# A2A Implementation Guide

This guide shows you how to build a complete Agent to Agent (A2A) system using the concepts from the [A2A Overview](overview). We'll create a banking customer service system with a main customer service agent and a loan specialist.

## Implementation Overview

We'll build a system with:

- **Customer Service Agent**: Voice-enabled interface agent using **RealTimePipeline** for low-latency voice interactions
- **Loan Specialist Agent**: Text-based domain expert using **CascadingPipeline** for efficient text processing
- **Intelligent Routing**: Automatic detection and forwarding of loan queries
- **Seamless Communication**: Users get expert responses without knowing about the routing

## Structure of the project

```js
A2A
├── agents/
│   ├── customer_agent.py     # CustomerServiceAgent definition
│   ├── loan_agent.py         # LoanAgent definition
│
├── session_manager.py        # Handles session creation, pipeline setup, meeting join/leave
└── main.py                   # Entry point: runs main() and starts agents
```

## Sequence Diagram

![A2A Architecture](https://cdn.videosdk.live/website-resources/docs-resources/a2a_sequence_diagram.png)

## Step 1: Create the Customer Service Agent

- **`Interface Agent`**: Creates `CustomerServiceAgent` as the main user-facing agent with voice capabilities and customer service instructions.
- **`Function Tool`**: Implements`@function_tool forward_to_specialist()`that uses A2A discovery to find and route queries to domain specialists.
- **`Response Relay`**: Includes `handle_specialist_response()` method that automatically receives and relays specialist responses back to users.

```python title="agents/customer_agent.py"
from videosdk.agents import Agent, AgentCard, A2AMessage, function_tool
import asyncio
from typing import Dict, Any

class CustomerServiceAgent(Agent):
    def __init__(self):
        super().__init__(
            agent_id="customer_service_1",
            instructions=(
                "You are a helpful bank customer service agent. "
                "For general banking queries (account balances, transactions, basic services), answer directly. "
                "For ANY loan-related queries, questions, or follow-ups, ALWAYS use the forward_to_specialist function "
                "with domain set to 'loan'. This includes initial loan questions AND all follow-up questions about loans. "
                "Do NOT attempt to answer loan questions yourself - always forward them to the specialist. "
                "After forwarding a loan query, stay engaged and automatically relay any response you receive from the specialist. "
                "When you receive responses from specialists, immediately relay them naturally to the customer."
            )
        )

    @function_tool
    async def forward_to_specialist(self, query: str, domain: str) -> Dict[str, Any]:
        """Forward queries to domain specialist agents using A2A discovery"""

        # Use A2A discovery to find specialists by domain
        specialists = self.a2a.registry.find_agents_by_domain(domain)
        id_of_target_agent = specialists[0] if specialists else None

        if not id_of_target_agent:
            return {"error": f"No specialist found for domain {domain}"}

        # Send A2A message to the specialist
        await self.a2a.send_message(
            to_agent=id_of_target_agent,
            message_type="specialist_query",
            content={"query": query}
        )

        return {
            "status": "forwarded",
            "specialist": id_of_target_agent,
            "message": "Let me get that information for you from our loan specialist..."
        }

    async def handle_specialist_response(self, message: A2AMessage) -> None:
        """Handle responses from specialist agents and relay to user"""
        response = message.content.get("response")
        if response:
            # Brief pause for natural conversation flow
            await asyncio.sleep(0.5)

            # Try multiple methods to relay the response to the user
            prompt = f"The loan specialist has responded: {response}"
            methods_to_try = [
                (self.session.pipeline.send_text_message, prompt),# While using Cascading as main agent, comment this
                (self.session.pipeline.model.send_message, response),# While using Cascading as main agent, comment this
                (self.session.say, response)
            ]

            for method, arg in methods_to_try:
                try:
                    await method(arg)
                    break
                except Exception as e:
                    print(f"Error with {method.__name__}: {e}")

    async def on_enter(self):
        # Register this agent with the A2A system
        await self.register_a2a(AgentCard(
            id="customer_service_1",
            name="Customer Service Agent",
            domain="customer_service",
            capabilities=["query_handling", "specialist_coordination"],
            description="Handles customer queries and coordinates with specialists"
        ))
        await self.session.say("Hello! I am your customer service agent. How can I help you?")

        # Set up message listener for specialist responses
        self.a2a.on_message("specialist_response", self.handle_specialist_response)

    async def on_exit(self):
        print("Customer agent left the meeting")
```

## Step 2: Create the Loan Specialist Agent

- **`Specialist Agent Setup`**: Creates `LoanAgent` class with specialized loan expertise instructions and agent_id `"specialist_1"`.
- **`Message Handlers`**: Implements` handle_specialist_query()` to process incoming queries and handle_model_response() to send responses back.
- **`Registration`**: Registers with A2A system using domain "loan" so it can be `discovered` by other agents needing loan expertise.

```python title="agents/loan_agent.py"
from videosdk.agents import Agent, AgentCard, A2AMessage

class LoanAgent(Agent):
    def __init__(self):
        super().__init__(
            agent_id="specialist_1",
            instructions=(
                "You are a specialized loan expert at a bank. "
                "Provide detailed, helpful information about loans including interest rates, terms, and requirements. "
                "Give complete answers with specific details when possible. "
                "You can discuss personal loans, car loans, home loans, and business loans. "
                "Provide helpful guidance and next steps for loan applications. "
                "Be friendly and professional in your responses. "
                "Keep responses concise within 5-7 lines and easily understandable."
            )
        )

    async def handle_specialist_query(self, message: A2AMessage):
        """Process incoming queries from customer service agent"""
        query = message.content.get("query")
        if query:
            # Send the query to our AI model for processing
            await self.session.pipeline.send_text_message(query)

    async def handle_model_response(self, message: A2AMessage):
        """Send processed responses back to requesting agent"""
        response = message.content.get("response")
        requesting_agent = message.to_agent
        if response and requesting_agent:
            # Send the specialist response back to the customer service agent
            await self.a2a.send_message(
                to_agent=requesting_agent,
                message_type="specialist_response",
                content={"response": response}
            )

    async def on_enter(self):
        await self.register_a2a(AgentCard(
            id="specialist_1",
            name="Loan Specialist Agent",
            domain="loan",
            capabilities=["loan_consultation", "loan_information", "interest_rates"],
            description="Handles loan queries"
        ))
        self.a2a.on_message("specialist_query", self.handle_specialist_query)
        self.a2a.on_message("model_response", self.handle_model_response)

    async def on_exit(self):
        print("LoanAgent Left")
```

## Step 3: Configure Session Management

- **`Pipeline Architecture`**: Uses **RealTimePipeline** for customer agent (audio-enabled Gemini for voice interaction) and **CascadingPipeline** for specialist agent (text-only OpenAI for efficient processing).
- **`Session Factory`**: Provides `create_pipeline()` and `create_session()` functions to properly configure agent sessions based on their roles.
- **`Modality Separation`**: Ensures customer agent can handle voice while specialist processes text in background.

```python title="session_manager.py"
from videosdk.agents import AgentSession, CascadingPipeline, RealTimePipeline, ConversationFlow
from videosdk.plugins.openai import OpenAILLM
from videosdk.plugins.google import GeminiRealtime, GeminiLiveConfig
import os

class MyConversationFlow(ConversationFlow):
    async def on_turn_start(self, transcript: str) -> None:
        pass

    async def on_turn_end(self) -> None:
        pass

def create_pipeline(agent_type: str):
    if agent_type == "customer":
        # Customer agent: RealTimePipeline for voice interaction
        return RealTimePipeline(
            model=GeminiRealtime(
                model="gemini-2.5-flash-native-audio-preview-12-2025",
                config=GeminiLiveConfig(
                    voice="Leda", 
                    response_modalities=["AUDIO"]
                )
            )
        )
    else:
        # Specialist agent: CascadingPipeline for text processing
        return CascadingPipeline(
            llm=OpenAILLM(api_key=os.getenv("OPENAI_API_KEY")),
        )

def create_session(agent, pipeline) -> AgentSession:
    return AgentSession(
        agent=agent,
        pipeline=pipeline,
        conversation_flow=MyConversationFlow(agent=agent),
    )
```
:::note
While setting up pipelines, make sure:
- The **customer agent** has **voice capabilities only** (via `RealTimePipeline`).
- The **specialist agent (Loan Agent)** operates in **text-only mode** (via `CascadingPipeline`).
:::

:::info
**Pipeline Support**: The VideoSDK AI Agents framework supports both **RealTimePipeline** and **CascadingPipeline**, enabling flexible configurations for voice and text processing with **A2A**. You can run a full `RealTimePipeline` or `CascadingPipeline` for both modalities, or create a hybrid setup that combines the two. This allows you to tailor the use of STT, TTS, and LLM to suit your specific use case, whether for low-latency interactions, complex processing flows, or a mix of both.
:::

## Step 4: Deploy A2A System on VideoSDK Platform

- **`Meeting Setup`**: Customer agent joins VideoSDK meeting for user interaction while specialist runs in background mode. Requires environment variables: `VIDEOSDK_AUTH_TOKEN`, `GOOGLE_API_KEY`, and `OPENAI_API_KEY`.
- **`System Orchestration`**: Uses `JobContext` and `WorkerJob` to manage the meeting lifecycle and agent coordination.
- **`Resource Management`**: Handles startup sequence, keeps system running, and provides clean shutdown with proper A2A unregistration

```python title="main.py"
import asyncio
from contextlib import suppress
from agents.customer_agent import CustomerServiceAgent
from agents.loan_agent import LoanAgent
from session_manager import create_pipeline, create_session
from videosdk.agents import JobContext, RoomOptions, WorkerJob

async def main(ctx: JobContext):
    specialist_agent = LoanAgent()
    specialist_pipeline = create_pipeline("specialist")
    specialist_session = create_session(specialist_agent, specialist_pipeline)

    customer_agent = CustomerServiceAgent()
    customer_pipeline = create_pipeline("customer")
    customer_session = create_session(customer_agent, customer_pipeline)

    specialist_task = asyncio.create_task(specialist_session.start())

    try:
        await ctx.connect()
        await customer_session.start()
        await asyncio.Event().wait()
    except (KeyboardInterrupt, asyncio.CancelledError):
        print("Shutting down...")
    finally:
        specialist_task.cancel()
        with suppress(asyncio.CancelledError):
            await specialist_task

        await specialist_session.close()
        await customer_session.close()
        
        await specialist_agent.unregister_a2a()
        await customer_agent.unregister_a2a()
        await ctx.shutdown()


def customer_agent_context() -> JobContext:
    room_options = RoomOptions(room_id="<meeting_id>", name="Customer Service Agent", playground=True)
    
    return JobContext(
        room_options=room_options
    )


if __name__ == "__main__":
    job = WorkerJob(entrypoint=main, jobctx=customer_agent_context)
    job.start()
```

:::note 
Ensure that the `JobContext` is created **only for the primary (main) agent**, i.e., the agent responsible for user-facing interaction (e.g., Customer Agent). 
The background agent (e.g., Loan Agent) should not have its own context or initiate a separate connection.
:::

#### Running the Application

Set the required environment variables:
```bash
export VIDEOSDK_AUTH_TOKEN="your_videosdk_token"
export GOOGLE_API_KEY="your_google_api_key"
export OPENAI_API_KEY="your_openai_api_key"
```

Replace `<meeting_id>` in the code with your actual meeting ID, then run:
```bash
cd A2A
python main.py
```

:::tip Quick Start

Get the complete working example at [A2A Quick Start Repository](https://github.com/videosdk-live/agents-quickstart/tree/main/A2A) with all the code ready to run.

:::


---

# Agent to Agent (A2A)

The Agent to Agent (A2A) protocol enables seamless collaboration between specialized AI agents, allowing them to communicate, share knowledge, and coordinate responses based on their unique capabilities and domain expertise. With VideoSDK's A2A implementation, you can create multi-agent systems where different agents work together to provide comprehensive solutions.

## How It Works

### Basic Flow

1. **Agent Registration**: Agents register themselves with an `AgentCard` that contains their capabilities and domain expertise
2. **Client Query**: Client sends a query to the main agent
3. **Agent Discovery**: Main agent discovers relevant specialist agents using agent cards
4. **Query Forwarding**: Main agent forwards specialized queries to appropriate agents
5. **Response Chain**: Specialist agents process queries and respond back to the main agent
6. **Client Response**: Main agent formats and delivers the final response to the client

![A2A Architecture](https://cdn.videosdk.live/website-resources/docs-resources/a2a_diagram.png)

### Example Scenario

```
Client → "Book a flight to New York and find a hotel"
   ↓
Travel Agent (Main) → Analyzes query
   ↓
Travel Agent → Discovers Flight Booking Agent & Hotel Booking Agent
   ↓
Travel Agent → Forwards flight query to Flight Booking Agent
Travel Agent → Forwards hotel query to Hotel Booking Agent
   ↓
Specialist Agents → Process queries and respond back (text format)
   ↓
Travel Agent → Combines responses and sends to client (audio format)
```

# Core Components

## 1. AgentCard

The `AgentCard` is how agents identify themselves and advertise their capabilities to other agents.

#### Structure

```python
AgentCard(
    id="agent_flight_001",
    name="Skymate",
    domain="flight",
    capabilities=[
        "search_flights",
        "modify_bookings",
        "show_flight_status"
    ],
    description="Handles all flight-related tasks"
)
```

#### Parameters

| Parameter      | Type   | Required | Description                          |
| -------------- | ------ | -------- | ------------------------------------ |
| `id`           | string | Yes      | Unique identifier for the agent      |
| `name`         | string | Yes      | Human-readable agent name            |
| `domain`       | string | Yes      | Primary expertise domain             |
| `capabilities` | list   | Yes      | List of specific capabilities        |
| `description`  | string | Yes      | Brief description of agent's purpose |
| `metadata`     | dict   | No       | Additional metadata for the agent    |

## 2. A2AMessage

`A2AMessage` is the standardized communication format between agents.

#### Structure

```python
message = A2AMessage(
    from_agent="travel_agent_1",
    to_agent="agent_flight_001",
    type="flight_status_query",
    content={"query": "What's the status of AI202?"},
    metadata={"client_id": "xyz123", "urgency": "medium"}
)
```

#### Parameters

| Parameter    | Type   | Required | Description                 |
| ------------ | ------ | -------- | --------------------------- |
| `from_agent` | string | Yes      | ID of the sending agent     |
| `to_agent`   | string | Yes      | ID of the receiving agent   |
| `type`       | string | Yes      | Message type/event name     |
| `content`    | dict   | Yes      | Message payload             |
| `metadata`   | dict   | No       | Additional message metadata |

## 3. Agent Registry

#### `register_a2a(agent_card)`

Register an agent with the A2A system.

```python
async def on_enter(self):
    await self.register_a2a(AgentCard(
        id="agent_flight_001",
        name="Skymate",
        domain="flight",
        capabilities=[
            "search_flights",
            "modify_bookings",
            "show_flight_status"
        ],
        description="Handles all flight-related tasks"
))
```

**What Registration Does:**

- Adds the agent to the global `AgentRegistry` singleton
- Makes the agent discoverable by other agents
- Stores both the `AgentCard` and agent instance
- Enables message routing to this agent

#### `unregister()`

Unregister an agent from the A2A system.

```python
await self.unregister_a2a()
```

## 4. A2AProtocol Class

The main class for managing agent-to-agent communication.

### Agent Discovery

#### `find_agents_by_domain(domain: str)`

Discover agents based on their domain expertise.

```python
agents = self.a2a.registry.find_agents_by_domain("hotel")
# Returns: ["agent_hotel_001"]
```

#### `find_agents_by_capability(cap: str)`

Find agents with specific skills.

```python
agents = await self.a2a.registry.find_agents_by_capability("modify_bookings")
# Returns: ["agent_flight_001"]
```

---

### Agent Communications

#### `send_message(to_agent, message_type, content, metadata=None)`

Send messages directly to other agents.

```python
await self.a2a.send_message(
    to_agent="agent_hotel_001",
    message_type="hotel_booking_query",  # Event name that the receiving agent listens for
    content={"query": "Find 3-star hotels in Delhi under $100"},
    metadata={"client_id": "xyz123"}     # Optional metadata
)
```

**Parameters:**

- `to_agent` (string): Target agent ID
- `message_type` (string): Event name the receiving agent listens for
- `content` (dict): Message payload
- `metadata` (dict, optional): Additional message metadata

#### `on_message(message_type, handler)`

Register message handlers for incoming messages.

```python
# Register a handler for specialist queries
self.a2a.on_message("hotel_booking_query", self.handle_specialist_query)

async def handle_specialist_query(self, message):
    # Process the incoming message
    query = message.content.get("query")
    # ... process query ...
    # Return response
    return {"response": "Current mortgage rates are 6.5%"}
```

## Next Steps

Now that you're familiar with the core A2A concepts, it's time to move from theory to practice:

👉 **[Explore the Full A2A Implementation](implementation)**
Dive into a complete, working example that demonstrates agent discovery, messaging, and collaboration in action.


---

# Agent Runtime Guide

AI voice agents are transforming how businesses interact with customers, providing natural, conversational experiences through voice interfaces. VideoSDK's **Agent Runtime** feature offers a powerful **no-code/low-code interface** that enables you to build sophisticated AI voice agents without extensive programming knowledge.

## Prerequisites

Before you begin, ensure you have:

- **VideoSDK Account:** Visit [VideoSDK Dashboard](https://app.videosdk.live) to sign up for a free account and access the AI Agent builder.



## Step-By-Step Guide

<div class="heading-toc-only">
### Step 1: Create a New Agent
</div>


1. In the dashboard, navigate to **AI Agent > Agents** or visit [Agents Dashboard](https://app.videosdk.live/agents/agents).
2. You'll see the `AI Agent > Agents` section in the dashboard.
3. To create a voice agent, click on **Agents** in the sidebar.

![Select Agents in Dashboard](https://strapi.videosdk.live/uploads/1_Select_Agents_in_Dashboard_1b6a6f6d0c.png)


<div class="heading-toc-only">
### Step 2: Click `Add New Agent`
</div>


This is where you'll start creating your voice agent. If no agent has been created yet, you'll see a **Add New Agent** button. If agents already exist, you'll see a list of all AI voice agents, and you can click the button in the top right corner to create a new agent.

![Click Create AI Voice Agent Button](https://strapi.videosdk.live/uploads/2_Click_Create_AI_Voice_Agent_Button_349f3799f2.png)


<div class="heading-toc-only">
### Step 3: Configure Agent Details
</div>


This is where you can define your AI voice agent's persona and behavior:

- **Agent Name:** Set a descriptive name for your agent (e.g., "AI Interviewer").
- **System Prompt:** Define the agent's role, personality, and behavior guidelines.
- **Welcome Message:** Set the message that plays when the agent joins a conversation.
- **Closing Message:** Set the message that plays when the agent leaves a conversation.

![Create Voice Agent Persona](https://strapi.videosdk.live/uploads/3_Create_Voice_Agent_Persona_6281a768ef.png)


<div class="heading-toc-only">
### Step 4: Configure the Pipeline
</div>


The pipeline is the core engine of your voice agent, processing audio through speech recognition, AI reasoning, and text-to-speech. VideoSDK offers two pipeline options: **Realtime Pipeline** and **Cascading Pipeline**.

**realtime:**

The **Realtime Pipeline** provides direct speech-to-speech processing with minimal latency, ideal for natural, conversational interactions. 

Example: Adding **Gemini Realtime Model**

1. Add your Gemini API key in the pipeline configuration or at [Realtime Integrations](https://app.videosdk.live/agents/integrations/realtime).
2. To get your API key, visit [Gemini API Keys](https://aistudio.google.com/api-keys).

![Gemini Add Your API Key](https://strapi.videosdk.live/uploads/4_Gemini_Add_Your_API_Key_bcf81a0f82.png)

**Available models:**

- `gemini-2.5-flash-native-audio-preview-12-2025`
- `gemini-2.0-flash`
- `gemini-2.5-flash-native-audio-preview-12-2025`
- `gemini-2.5-flash-native-audio`

---

**cascading:**

The **Cascading Pipeline** processes audio through distinct stages (STT → LLM → TTS), providing maximum control over each component.



Configure your providers for [STT Integrations](https://app.videosdk.live/agents/integrations/stt), [LLM Integrations](https://app.videosdk.live/agents/integrations/llm) and [TTS Integrations](https://app.videosdk.live/agents/integrations/tts).

![STT Providers](https://strapi.videosdk.live/uploads/stt_e2522d9ea2.png)





Example: Adding **Deepgram STT**

- Get API Key at: [Deepgram Console](https://console.deepgram.com/)

**Available models:**

- `flux-general-en`
- `nova-2` or `nova-2-general` (for non-English transcriptions)
- `nova-3` or `nova-3-general`
- `base`


<div class="heading-toc-only">
### Step 5: Knowledge Base Integration
</div>


Upload a knowledge base to provide context and domain expertise to your voice agent. This dramatically improves answer accuracy and enables your agent to handle specialized queries.

- Navigate to the **Knowledge Base** tab in your agent configuration.
- Upload documents, FAQs, or product sheets that contain relevant information.
- The agent will use this knowledge to provide more accurate and contextual responses.

![Add Knowledge Base in VideoSDK](https://strapi.videosdk.live/uploads/Add_Knowlodege_base_in_videosdk_363aaa82f3.png)


<div class="heading-toc-only">
### Step 6: Configure Telephony Settings
</div>


Configure telephony settings to enable your agent to handle phone calls:

- **Agent Type:** Set the type of agent (inbound, outbound, or both).
- **Inbound Gateways:** Set up gateways to receive incoming calls.
- **Outbound Gateways:** Set up gateways to make outbound calls.
- **Routing Rules:** Create rules to map phone numbers to your agent.
- **Calling Settings:** Configure call handling preferences and behavior.

![Telephony Configuration](https://strapi.videosdk.live/uploads/telephony_agents_dd2c2080ac.png)

This configuration is essential for **call center automation**, **platform integration**, and smooth **agent orchestration**.


<div class="heading-toc-only">
### Step 7: Test Your Voice Agent
</div>


You can interact with the agent directly from the dashboard before connecting it to production channels:

1. Visit [Agents Dashboard](https://app.videosdk.live/agents/agents).
2. Locate your agent in the list and click the **Test** button in the top-right corner.
3. Use the built-in simulator to speak with the agent in real time, view live transcripts, and fine-tune prompts based on the conversation.

![Test AI Voice Agent](https://strapi.videosdk.live/uploads/test_ai_voice_agent_30e0045af0.png)


<div class="heading-toc-only">
### Step 8: Connect Voice Agent
</div>


Once your agent is configured, you can connect it to various platforms and devices:

- **Web:** Integrate your agent into web applications.
- **Mobile:** Connect to iOS and Android mobile apps.
- **Telephony:** Deploy to phone systems for voice calls.
- **IoT Devices:** Connect to Internet of Things devices.

![Connect AI Voice Agent](https://strapi.videosdk.live/uploads/8_connect_ai_voice_agent_17fe428419.png)


## Next Steps

Congratulations! You've successfully created your AI voice agent. Here are the next steps:

- **Test Your Agent:** Use the built-in test simulator to verify your agent's behavior and responses.
- **Deploy to Production:** Connect your agent to production environments and real user interactions.
- **Monitor Performance:** Track agent performance, user satisfaction, and conversation quality.
- **Iterate and Improve:** Refine your agent's prompts, knowledge base, and configuration based on real-world usage.

Keep refining your agent's configuration to build a powerful voice AI solution tailored to your specific business needs.

### Integrations


- [Connect with JavaScript](/ai_agents/agent-runtime/connect-agent/web-integrations/with-javascript): Core language of the web
- [Connect with React](/ai_agents/agent-runtime/connect-agent/web-integrations/with-react): UI library for building interactive web apps.
- [Connect with React-Native](/ai_agents/agent-runtime/connect-agent/mobile-integrations/with-react-native): Cross-platform mobile app JS framework.
- [Connect with flutter](/ai_agents/agent-runtime/connect-agent/mobile-integrations/with-flutter): Cross-platform apps from one codebase.
- [Connect with iOS](/ai_agents/agent-runtime/connect-agent/mobile-integrations/with-ios): Mobile apps for Apple devices.


---

# Agent Runtime with Flutter

VideoSDK empowers you to seamlessly integrate AI agents with real-time voice interaction into your Flutter application within minutes. This guide shows you how to connect a Flutter frontend with an AI agent created and configured entirely from the VideoSDK dashboard.

## Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

- Video SDK Developer Account (Not having one, follow **[Video SDK Dashboard](https://app.videosdk.live/)**)
- Flutter installed on your device
- Familiarity with creating a no-code voice agent. If you're new to this, please follow our guide on how to **[Build a Custom Voice AI Agent in Minutes](/ai_agents/agent-runtime/build-agent)** first.

:::important

You need a VideoSDK account to generate a token and an agent from the dashboard.
Visit the VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate a token.

:::

## Project Structure

Your project structure should look like this:

```jsx title="Project Structure"
  root
   ├── android
   ├── ios
   ├── lib
   │    ├── api_call.dart
   │    ├── join_screen.dart
   │    ├── main.dart
   │    ├── meeting_controls.dart
   │    ├── meeting_screen.dart
   │    └── participant_tile.dart
   ├── macos
   ├── web
   └── windows
```

You will be working on the following files:

- `join_screen.dart`: Responsible for the user interface to join a meeting.
- `meeting_screen.dart`: Displays the meeting interface and handles meeting logic.
- `api_call.dart`: Handles API calls for creating meetings and dispatching agents.

## 1. Flutter Frontend

### Step 1: Getting Started


Follow these steps to create the environment necessary to add AI agent functionality to your app.

#### Create a New Flutter App

Create a new Flutter app using the following command:

```bash
$ flutter create videosdk_ai_agent_flutter_app
```

#### Install VideoSDK

Install the VideoSDK using the following Flutter command. Make sure you are in your Flutter app directory before you run this command.

```bash
$ flutter pub add videosdk
$ flutter pub add http
```


### Step 2: Configure Project


#### For Android

- Update the `/android/app/src/main/AndroidManifest.xml` for the permissions we will be using to implement the audio and video features.

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

- If necessary, in the `build.gradle` you will need to increase `minSdkVersion` of `defaultConfig` up to `23` (currently default Flutter generator set it to `16`).

#### For iOS

- Add the following entries which allow your app to access the camera and microphone to your `/ios/Runner/Info.plist` file :

```xml title="/ios/Runner/Info.plist"
<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) Camera Usage!</string>
<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) Microphone Usage!</string>
```

- Uncomment the following line to define a global platform for your project in `/ios/Podfile` :

```ruby title="/ios/Podfile"
platform :ios, '12.0'
```

#### For MacOS

- Add the following entries to your `/macos/Runner/Info.plist` file which allow your app to access the camera and microphone.

```xml title="/macos/Runner/Info.plist"
<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) Camera Usage!</string>
<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) Microphone Usage!</string>
```

- Add the following entries to your `/macos/Runner/DebugProfile.entitlements` file which allow your app to access the camera, microphone and open outgoing network connections.

```xml title="/macos/Runner/DebugProfile.entitleaments"
<key>com.apple.security.network.client</key>
<true/>
<key>com.apple.security.device.camera</key>
<true/>
<key>com.apple.security.device.microphone</key>
<true/>
```

- Add the following entries to your `/macos/Runner/Release.entitlements` file which allow your app to access the camera, microphone and open outgoing network connections.

```xml title="/macos/Runner/Release.entitlements"
<key>com.apple.security.network.server</key>
<true/>
<key>com.apple.security.network.client</key>
<true/>
<key>com.apple.security.device.camera</key>
<true/>
<key>com.apple.security.device.microphone</key>
<true/>
```



### Step 3: Configure Environment and Credentials


Create a meeting room using the VideoSDK API:

```bash
curl -X POST https://api.videosdk.live/v2/rooms \
  -H "Authorization: YOUR_JWT_TOKEN_HERE" \
  -H "Content-Type: application/json"
```

Copy the `roomId` from the response and configure it in `lib/api_call.dart` along with your agent credentials.

```dart title="lib/api_call.dart"
import 'dart:convert';
import 'package:http/http.dart' as http;

//Auth token we will use to generate a meeting and connect to it
const token = 'YOUR_VIDEOSDK_AUTH_TOKEN';
const agentId = 'YOUR_AGENT_ID';
const versionId = 'YOUR_VERSION_ID';

// API call to create meeting
Future<String> createMeeting() async {
  final http.Response httpResponse = await http.post(
    Uri.parse('https://api.videosdk.live/v2/rooms'),
    headers: {'Authorization': token},
  );

  //Destructuring the roomId from the response
  return json.decode(httpResponse.body)['roomId'];
}

// API call to connect agent
Future<void> connectAgent(String meetingId) async {
  final http.Response httpResponse = await http.post(
    Uri.parse('https://api.videosdk.live/v2/agent/general/dispatch'),
    headers: {
      'Authorization': token,
      'Content-Type': 'application/json',
    },
    body: json.encode({
      'agentId': agentId,
      'meetingId': meetingId,
      'versionId': versionId,
    }),
  );

  if (httpResponse.statusCode != 200) {
    throw Exception('Failed to connect agent');
  }
}
```



### Step 4: Design the User Interface (UI)


Update the UI files to add the "Connect Agent" button and connect the logic.

```dart title="lib/join_screen.dart"
import 'package:flutter/material.dart';
import 'api_call.dart';
import 'meeting_screen.dart';

class JoinScreen extends StatelessWidget {
  final _meetingIdController = TextEditingController();

  JoinScreen({super.key});

  void onJoinButtonPressed(BuildContext context) {
    // check meeting id is not null or invaild
    // if meeting id is vaild then navigate to MeetingScreen with meetingId,token
    Navigator.of(context).push(
      MaterialPageRoute(
        builder:
            (context) =>
                MeetingScreen(meetingId: "YOUR_MEETING_ID", token: token),
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('VideoSDK QuickStart')),
      body: Padding(
        padding: const EdgeInsets.all(12.0),
        child: Center(
          child: ElevatedButton(
            onPressed: () => onJoinButtonPressed(context),
            child: const Text('Join Meeting'),
          ),
        ),
      ),
    );
  }
}
```

```dart title="lib/meeting_screen.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
import 'participant_tile.dart';
import 'meeting_controls.dart';
import 'api_call.dart';

class MeetingScreen extends StatefulWidget {
  final String meetingId;
  final String token;

  const MeetingScreen({
    super.key,
    required this.meetingId,
    required this.token,
  });

  @override
  State<MeetingScreen> createState() => _MeetingScreenState();
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;
  var micEnabled = true;
  var camEnabled = true;
  bool _isAgentConnected = false;

  Map<String, Participant> participants = {};

  @override
  void initState() {
    // create room
    _room = VideoSDK.createRoom(
      roomId: widget.meetingId,
      token: widget.token,
      displayName: "John Doe",
      micEnabled: micEnabled,
      camEnabled: false,
      defaultCameraIndex:
          1, // Index of MediaDevices will be used to set default camera
    );

    setMeetingEventListener();

    // Join room
    _room.join();

    super.initState();
  }

  // listening to meeting events
  void setMeetingEventListener() {
    _room.on(Events.roomJoined, () {
      setState(() {
        participants.putIfAbsent(
          _room.localParticipant.id,
          () => _room.localParticipant,
        );
      });
    });

    _room.on(Events.participantJoined, (Participant participant) {
      setState(
        () => participants.putIfAbsent(participant.id, () => participant),
      );
    });

    _room.on(Events.participantLeft, (String participantId) {
      if (participants.containsKey(participantId)) {
        setState(() => participants.remove(participantId));
      }
    });

    _room.on(Events.roomLeft, () {
      participants.clear();
      Navigator.popUntil(context, ModalRoute.withName('/'));
    });
  }

  void _connectAgent() async {
    try {
      await connectAgent(widget.meetingId);
      setState(() {
        _isAgentConnected = true;
      });
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('Agent connected successfully!')),
      );
    } catch (e) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text('Failed to connect agent: ${e.toString()}')),
      );
    }
  }

  // onbackButton pressed leave the room
  Future<bool> _onWillPop() async {
    _room.leave();
    return true;
  }

  @override
  Widget build(BuildContext context) {
    return WillPopScope(
      onWillPop: () => _onWillPop(),
      child: Scaffold(
        appBar: AppBar(title: const Text('VideoSDK QuickStart')),
        body: Padding(
          padding: const EdgeInsets.all(8.0),
          child: Column(
            children: [
              Text(widget.meetingId),
              //render all participant
              Expanded(
                child: Padding(
                  padding: const EdgeInsets.all(8.0),
                  child: GridView.builder(
                    gridDelegate:
                        const SliverGridDelegateWithFixedCrossAxisCount(
                          crossAxisCount: 2,
                          crossAxisSpacing: 10,
                          mainAxisSpacing: 10,
                          mainAxisExtent: 300,
                        ),
                    itemBuilder: (context, index) {
                      return ParticipantTile(
                        key: Key(participants.values.elementAt(index).id),
                        participant: participants.values.elementAt(index),
                      );
                    },
                    itemCount: participants.length,
                  ),
                ),
              ),
              MeetingControls(
                onToggleMicButtonPressed: () {
                  micEnabled ? _room.muteMic() : _room.unmuteMic();
                  micEnabled = !micEnabled;
                },
                onLeaveButtonPressed: () => _room.leave(),
                onConnectAgentButtonPressed: _isAgentConnected ? null : _connectAgent,
              ),
            ],
          ),
        ),
      ),
    );
  }
}
```

```dart title="lib/meeting_controls.dart"
import 'package:flutter/material.dart';

class MeetingControls extends StatelessWidget {
  final void Function() onToggleMicButtonPressed;
  final void Function() onLeaveButtonPressed;
  final void Function()? onConnectAgentButtonPressed;

  const MeetingControls({
    super.key,
    required this.onToggleMicButtonPressed,
    required this.onLeaveButtonPressed,
    required this.onConnectAgentButtonPressed,
  });

  @override
  Widget build(BuildContext context) {
    return Row(
      mainAxisAlignment: MainAxisAlignment.spaceEvenly,
      children: [
        ElevatedButton(
          onPressed: onLeaveButtonPressed,
          child: const Text('Leave'),
        ),
        ElevatedButton(
          onPressed: onToggleMicButtonPressed,
          child: const Text('Toggle Mic'),
        ),
        ElevatedButton(
          onPressed: onConnectAgentButtonPressed,
          child: const Text('Connect Agent'),
        ),
      ],
    );
  }
}
```



## 2. Creating the AI Agent from Dashboard (No-Code)

You can create and configure a powerful AI agent directly from the VideoSDK dashboard.

### Step 1: Create Your Agent


First, follow our detailed guide to **[Build a Custom Voice AI Agent in Minutes](/ai_agents/agent-runtime/build-agent)**. This will walk you through creating the agent's persona, configuring its pipeline (Realtime or Cascading), and testing it directly from the dashboard.



### Step 2: Get Agent and Version ID


Once your agent is created, you need to get its `agentId` and `versionId` to connect it to your frontend application.

1.  After creating your agent, go to the agent's page and find the JSON editor on right side. Copy the `agentId`.

2.  To get the `versionId`, click on 3 dots besides Deploy button and click on "Version History" in it. Copy the version id via copy button of the version you want.

![Get agentId and versionId](https://strapi.videosdk.live/uploads/agent_version_id_0f8b59830a.png)



### Step 3: Configure IDs in Frontend


Now, update your `lib/api_call.dart` file with these IDs.

```dart title="lib/api_call.dart"
const token = 'your_videosdk_auth_token_here';
const agentId = 'paste_your_agent_id_here';
const versionId = 'paste_your_version_id_here';
```


## 3. Run the Application

### Step 1: Run the Frontend


Once you have completed all the steps mentioned above, start your Flutter application:

```bash
flutter run
```



### Step 2: Connect and Interact


1. **Join the meeting from the Flutter app:**
   - Click the "Join Meeting" button.
   - Allow microphone permissions when prompted.

2. **Connect the agent:**
   - Once you join, click the "Connect Agent" button.
   - You should see a confirmation that the agent was connected.
   - The AI agent will join the meeting and greet you.

3. **Start playing:**
   - Interact with your AI agent using your microphone.


## Troubleshooting

### Common Issues:

1. **Agent not joining:**
   - Check that the `roomId`, `agentId`, and `versionId` are correctly set.
   - Verify your VideoSDK token is valid and has the necessary permissions.

2. **Audio not working:**
   - Check device permissions for microphone access.

3. **"Failed to connect agent" error:**
   - Verify your `agentId` and `versionId` are correct.
   - Check the debug console for any network errors.

4. **Flutter build issues:**
   - Ensure your Flutter version is compatible.
   - Try cleaning the build: `flutter clean`.
   - Delete `pubspec.lock` and run `flutter pub get`.



---

# Agent Runtime with iOS

VideoSDK empowers you to integrate an AI voice agent into your iOS app within minutes. This guide shows you how to connect an iOS (SwiftUI) frontend with an AI agent created and configured entirely from the VideoSDK dashboard.

## Prerequisites

- macOS with Xcode 15.0+
- iOS 13.0+ deployment target
- Valid VideoSDK [Account](https://app.videosdk.live/)
- Familiarity with creating a no-code voice agent. If you're new to this, please follow our guide on how to **[Build a Custom Voice AI Agent in Minutes](/ai_agents/agent-runtime/build-agent)** first.

:::important
You need a VideoSDK account to generate a token and an agent from the dashboard.
:::

<div class="heading-toc-only">
### Step 1: Clone the sample project
</div>


Clone the repository to your local environment.

```bash
git clone https://github.com/videosdk-live/agents-quickstart.git
cd mobile-quickstarts/ios/
```


<div class="heading-toc-only">
### Step 2: Environment Configuration
</div>


### Create a Meeting Room

Create a meeting room using the VideoSDK API:

```bash
curl -X POST https://api.videosdk.live/v2/rooms \
  -H "Authorization: YOUR_VIDEOSDK_AUTH_TOKEN" \
  -H "Content-Type: application/json"
```

Use the returned `roomId` in your configuration files.

### Configuration Files

Update the following files with your credentials. The Agent and Version IDs will be retrieved in a later step.

**MeetingViewController.swift** (line 14):
```swift
var token = "YOUR_VIDEOSDK_AUTH_TOKEN" // Add Your token here
var agentId = "YOUR_AGENT_ID"
var versionId = "YOUR_VERSION_ID"
```

**JoinScreenView.swift** (line 13):
```swift
let meetingId: String = "YOUR_MEETING_ID"
```


<div class="heading-toc-only">
### Step 3: iOS Frontend Modifications
</div>


### Step 1: Add Connect Agent Button

In `MeetingView.swift`, add a button to connect the agent.

```swift title="MeetingView.swift"
// Add this button to your view hierarchy
Button(action: {
    meetingVC.connectAgent()
}) {
    Text("Connect Agent")
}
.disabled(meetingVC.isAgentConnected)
```

### Step 2: Implement Connect Logic

In `MeetingViewController.swift`, add the logic to call the dispatch API.

```swift title="MeetingViewController.swift"
// Add state to track if the agent is connected
@Published var isAgentConnected = false

// ...

func connectAgent() {
    guard let url = URL(string: "https://api.videosdk.live/v2/agent/general/dispatch") else { return }

    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.setValue(token, forHTTPHeaderField: "Authorization")

    let body: [String: Any] = [
        "agentId": agentId,
        "meetingId": room?.id ?? "",
        "versionId": versionId
    ]

    request.httpBody = try? JSONSerialization.data(withJSONObject: body)

    URLSession.shared.dataTask(with: request) { data, response, error in
        if let error = error {
            print("Connect error: \(error.localizedDescription)")
            return
        }
        if let httpResponse = response as? HTTPURLResponse, httpResponse.statusCode == 200 {
            DispatchQueue.main.async {
                self.isAgentConnected = true
                print("Agent connected successfully")
            }
        } else {
            print("Failed to connect agent")
        }
    }.resume()
}
```


<div class="heading-toc-only">
### Step 4: Creating the AI Agent from Dashboard (No-Code)
</div>


### Step 1: Create Your Agent

First, follow our detailed guide to **[Build a Custom Voice AI Agent in Minutes](/ai_agents/agent-runtime/build-agent)**. This will walk you through creating the agent's persona, configuring its pipeline (Realtime or Cascading), and testing it directly from the dashboard.

### Step 2: Get Agent and Version ID

Once your agent is created, you need to get its `agentId` and `versionId` to connect it to your frontend application.

1.  After creating your agent, go to the agent's page and find the JSON editor on right side. Copy the `agentId`.

2.  To get the `versionId`, click on 3 dots besides Deploy button and click on "Version History" in it. Copy the version id via copy button of the version you want.

![Get agentId and versionId](https://strapi.videosdk.live/uploads/agent_version_id_0f8b59830a.png)

### Step 3: Configure IDs in Frontend

Now, update your `MeetingViewController.swift` file with these IDs.

```swift title="MeetingViewController.swift"
var agentId = "paste_your_agent_id_here"
var versionId = "paste_your_version_id_here"
```


<div class="heading-toc-only">
### Step 5: Run the iOS Frontend
</div>


1. **Open Xcode:**
   ```bash
   open videosdk-agents-quickstart-ios.xcodeproj
   ```

2. **Configure your development team:**
   - Select the project in Xcode
   - Go to "Signing & Capabilities"
   - Select your development team

3. **Build and run:**
   - Select your target device or simulator
   - Press `Cmd + R` to build and run


<div class="heading-toc-only">
### Step 6: Connect and Interact
</div>


1. Join the meeting from the app and allow microphone permissions.
2. When you join, click the "Connect Agent" button to call the agent into the meeting.
3. Talk to the agent in real time.


## Troubleshooting

### Common Issues

1. **Build Errors:**
   - Ensure Xcode 15.0+ is installed
   - Check iOS deployment target (13.0+)
   - Verify VideoSDK package dependency

2. **Authentication Issues:**
   - Verify `VIDEOSDK_AUTH_TOKEN` in `MeetingViewController.swift`
   - Check token permissions include `allow_join`

3. **Meeting Connection Issues:**
   - Ensure `YOUR_MEETING_ID` is correct
   - Verify network connectivity
   - Check VideoSDK account status

4. **AI Agent Issues:**
   - Verify `agentId` and `versionId` are set correctly
   - Check for errors in the Xcode console when connecting the agent.


---

# Agent Runtime with React Native

VideoSDK empowers you to integrate an AI voice agent into your React Native app (Android/iOS) within minutes. This guide shows you how to connect a React Native frontend with an AI agent created and configured entirely from the VideoSDK dashboard.

## Prerequisites

- VideoSDK Developer Account (get token from the [dashboard](https://app.videosdk.live/api-keys))
- Node.js and a working React Native environment (Android Studio and/or Xcode)
- Familiarity with creating a no-code voice agent. If you're new to this, please follow our guide on how to **[Build a Custom Voice AI Agent in Minutes](/ai_agents/agent-runtime/build-agent)** first.

:::important
You need a VideoSDK token and an agent from the dashboard. Generate your VideoSDK token from the dashboard.
:::

## Project Structure

First, create an empty project using `mkdir folder_name` on your preferable location for the React Native Frontend. Your final project structure should look like this:

```jsx title="Directory Structure"
  root
   ├── android/
   ├── ios/
   ├── App.js
   ├── constants.js
   └── index.js
```

You will work on:
- `android/`: Contains the Android-specific project files.
- `ios/`: Contains the iOS-specific project files.
- `App.js`: The main React Native component, containing the UI and meeting logic.
- `constants.js`: To store token, meetingId, and agent credentials for the frontend.
- `index.js`: The entry point of the React Native application, where VideoSDK is registered.


## Building the React Native Frontend

### Step 1: Create App and Install SDKs


Create a React Native app and install the VideoSDK RN SDK:

```bash
npx react-native init videosdkAiAgentRN
cd videosdkAiAgentRN

# Install VideoSDK
npm install "@videosdk.live/react-native-sdk"
```


### Step 2: Configure the Project


#### Android Setup



```xml title="android/app/src/main/AndroidManifest.xml"
<manifest
  xmlns:android="http://schemas.android.com/apk/res/android"
>
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission
        android:name="android.permission.BLUETOOTH"
        android:maxSdkVersion="30" />
    <uses-permission
        android:name="android.permission.BLUETOOTH_ADMIN"
        android:maxSdkVersion="30" />

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

    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />
</manifest>
```





```java title="android/app/build.gradle"
  dependencies {
   implementation project(':rnwebrtc')
  }
```

```gradle title="android/settings.gradle"
include ':rnwebrtc'
project(':rnwebrtc').projectDir = new File(rootProject.projectDir, '../node_modules/@videosdk.live/react-native-webrtc/android')
```

```java title="MainApplication.kt"
import live.videosdk.rnwebrtc.WebRTCModulePackage

class MainApplication : Application(), ReactApplication {
  override val reactNativeHost: ReactNativeHost =
      object : DefaultReactNativeHost(this) {
        override fun getPackages(): List
    </TouchableOpacity>
  );
};

function ControlsContainer({ join, leave, toggleMic }) {
  const [connected, setConnected] = useState(false);

  const connectAgent = async () => {
    try {
      const response = await fetch("https://api.videosdk.live/v2/agent/general/dispatch", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: token,
        },
        body: JSON.stringify({ agentId: agentId, meetingId: meetingId, versionId: versionId }),
      });
      if (response.ok) {
        Alert.alert("Agent connected successfully!");
        setConnected(true);
      } else {
        Alert.alert("Failed to connect agent.");
      }
    } catch (error) {
      console.error("Error connecting agent:", error);
      Alert.alert("An error occurred while connecting the agent.");
    }
  };

  return (
    
      
      {!connected && (
        
      )}
      
    </View>
  );
}

function ParticipantView({ participantDisplayName }) {
  return (
    
    </View>
  );
}

function ParticipantList({ participants }) {
  return participants.length > 0 ? (
    ;
      }}
    />
  ) : (
    
    </View>
  );
}

function MeetingView() {
  const { join, leave, toggleMic, participants, meetingId } = useMeeting({});

  const participantsList = [...participants.values()].map(participant => ({
    displayName: participant.displayName,
  }));

  return (
    
      ) : null}
      
      
    </View>
  );
}

export default function App() {
  if (!meetingId || !token) {
    return (
      
        </View>
      </SafeAreaView>
    );
  }

  return (
    
      </MeetingProvider>
    </SafeAreaView>
  );
}
```


## Creating the AI Agent from Dashboard (No-Code)

You can create and configure a powerful AI agent directly from the VideoSDK dashboard.

### Step 1: Create Your Agent


First, follow our detailed guide to **[Build a Custom Voice AI Agent in Minutes](/ai_agents/agent-runtime/build-agent)**. This will walk you through creating the agent's persona, configuring its pipeline (Realtime or Cascading), and testing it directly from the dashboard.



### Step 2: Get Agent and Version ID


Once your agent is created, you need to get its `agentId` and `versionId` to connect it to your frontend application.

1.  After creating your agent, go to the agent's page and find the JSON editor on right side. Copy the `agentId`.

2.  To get the `versionId`, click on 3 dots besides Deploy button and click on "Version History" in it. Copy the version id via copy button of the version you want.

![Get agentId and versionId](https://strapi.videosdk.live/uploads/agent_version_id_0f8b59830a.png)



### Step 3: Configure IDs in Frontend


Now, update your `constants.js` file with these IDs.

```js title="constants.js"
export const token = "your_videosdk_auth_token_here";
export const meetingId = "YOUR_MEETING_ID";
export const name = "User Name";
export const agentId = "paste_your_agent_id_here";
export const versionId = "paste_your_version_id_here";
```


## Run the Application

### 1) Start the React Native app

```bash
npm install

# Android
npm run android

# iOS (macOS only)
cd ios && pod install && cd ..
npm run ios
```

### 2) Connect and interact

1. Join the meeting from the app and allow microphone permissions.
2. When you join, click the "Connect Agent" button to call the agent into the meeting.
3. Talk to the agent in real time.

## Troubleshooting

- Ensure the same `meetingId` is used and the `agentId` and `versionId` are correct in `constants.js`.
- Verify microphone permissions on the device/simulator.
- Confirm your VideoSDK token is valid.
- If audio is silent, check device output volume.



---

# Agent Runtime with JavaScript

VideoSDK empowers you to seamlessly integrate AI agents with real-time voice interaction into your JavaScript application within minutes. This guide shows you how to connect a JavaScript frontend with an AI agent created and configured entirely from the VideoSDK dashboard.

## Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

- Video SDK Developer Account (Not having one, follow **[Video SDK Dashboard](https://app.videosdk.live/)**)
- Node.js installed on your device
- Familiarity with creating a no-code voice agent. If you're new to this, please follow our guide on how to **[Build a Custom Voice AI Agent in Minutes](/ai_agents/agent-runtime/build-agent)** first.

:::important

You need a VideoSDK account to generate a token and an agent from the dashboard.
Visit the VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate a token.

:::

## Project Structure

First, create an empty project using `mkdir folder_name` on your preferable location for the JavaScript Frontend. Your final project structure should look like this:

```jsx title="Project Structure"
  root
   ├── index.html
   ├── config.js
   └── index.js
```

You will be working on the following files:

- `index.html`: Responsible for creating a basic UI for joining the meeting.
- `config.js`: Responsible for storing the token, room ID, and agent credentials.
- `index.js`: Responsible for rendering the meeting view and audio functionality.


## Building the JavaScript Frontend

### Step 1: Install VideoSDK


Import VideoSDK using the `<script>` tag or install it using npm/yarn.

**Tab:**

" label="<script>" default>

```html
<html>
  <head>

  </head>
  <body>

<script src="https://sdk.videosdk.live/js-sdk/0.3.6/videosdk.js"></script>
  </body>
</html>
```

---

**npm:**

```bash
npm install @videosdk.live/js-sdk
```

---

**yarn:**

```bash
yarn add @videosdk.live/js-sdk
```


### Step 2: Design the User Interface

Create an `index.html` file containing `join-screen` and `grid-screen` for audio-only interaction. The "Connect Agent" button will be used to call the AI agent into the meeting.

```html title="index.html"
<!DOCTYPE html>
<html>
<head> </head>
<body>
    <div id="join-screen">
        <button id="createMeetingBtn">Join Agent Meeting</button>
    </div>
    <div id="textDiv"></div>
    <div id="grid-screen" style="display: none">
        <h3 id="meetingIdHeading"></h3>
        <button id="leaveBtn">Leave</button>
        <button id="toggleMicBtn">Toggle Mic</button>
        <button id="connectAgentBtn">Connect Agent</button>
        <div id="audioContainer"></div>
    </div>
    <script src="https://sdk.videosdk.live/js-sdk/0.3.6/videosdk.js"></script>
    <script src="config.js"></script>
    <script src="index.js"></script>
</body>
</html>
```


### Step 3: Configure the Frontend

Create a meeting room using the VideoSDK API:

```bash
curl -X POST https://api.videosdk.live/v2/rooms \
  -H "Authorization: YOUR_JWT_TOKEN_HERE" \
  -H "Content-Type: application/json"
```

Copy the `roomId` from the response and configure it in `config.js`. You will get the Agent and Version IDs in the next section.

```js title="config.js"
TOKEN = "your_videosdk_auth_token_here";
ROOM_ID = "YOUR_MEETING_ID";
AGENT_ID = "YOUR_AGENT_ID";
VERSION_ID = "YOUR_VERSION_ID";
```


### Step 4: Implement Meeting Logic

In `index.js`, retrieve DOM elements, declare variables, and add the core meeting functionalities, including the logic to connect the agent.

```js title="index.js"
// getting Elements from Dom
const leaveButton = document.getElementById("leaveBtn");
const toggleMicButton = document.getElementById("toggleMicBtn");
const createButton = document.getElementById("createMeetingBtn");
const connectAgentButton = document.getElementById("connectAgentBtn");
const audioContainer = document.getElementById("audioContainer");
const textDiv = document.getElementById("textDiv");

// declare Variables
let meeting = null;
let meetingId = "";
let isMicOn = false;

// Join Agent Meeting Button Event Listener
createButton.addEventListener("click", async () => {
  document.getElementById("join-screen").style.display = "none";
  textDiv.textContent = "Please wait, we are joining the meeting";
  meetingId = ROOM_ID;
  initializeMeeting();
});

// Initialize meeting
function initializeMeeting() {
  window.VideoSDK.config(TOKEN);

  meeting = window.VideoSDK.initMeeting({
    meetingId: meetingId,
    name: "C.V.Raman",
    micEnabled: true,
    webcamEnabled: false,
  });

  meeting.join();

  meeting.localParticipant.on("stream-enabled", (stream) => {
    if (stream.kind === "audio") {
      setAudioTrack(stream, meeting.localParticipant, true);
    }
  });

  meeting.on("meeting-joined", () => {
    textDiv.textContent = null;
    document.getElementById("grid-screen").style.display = "block";
    document.getElementById("meetingIdHeading").textContent = `Meeting Id: ${meetingId}`;
  });

  meeting.on("meeting-left", () => {
    audioContainer.innerHTML = "";
  });

  meeting.on("participant-joined", (participant) => {
    let audioElement = createAudioElement(participant.id);
    participant.on("stream-enabled", (stream) => {
      if (stream.kind === "audio") {
        setAudioTrack(stream, participant, false);
        audioContainer.appendChild(audioElement);
      }
    });
  });

  meeting.on("participant-left", (participant) => {
    let aElement = document.getElementById(`a-${participant.id}`);
    if (aElement) aElement.remove();
  });
}

// Create audio elements for participants
function createAudioElement(pId) {
  let audioElement = document.createElement("audio");
  audioElement.setAttribute("autoPlay", "false");
  audioElement.setAttribute("playsInline", "true");
  audioElement.setAttribute("controls", "false");
  audioElement.setAttribute("id", `a-${pId}`);
  audioElement.style.display = "none";
  return audioElement;
}

// Set audio track
function setAudioTrack(stream, participant, isLocal) {
  if (stream.kind === "audio") {
    if (isLocal) {
      isMicOn = true;
    } else {
      const audioElement = document.getElementById(`a-${participant.id}`);
      if (audioElement) {
        const mediaStream = new MediaStream();
        mediaStream.addTrack(stream.track);
        audioElement.srcObject = mediaStream;
        audioElement.play().catch((err) => console.error("audioElem.play() failed", err));
      }
    }
  }
}

// Implement controls
leaveButton.addEventListener("click", async () => {
  meeting?.leave();
  document.getElementById("grid-screen").style.display = "none";
  document.getElementById("join-screen").style.display = "block";
});

toggleMicButton.addEventListener("click", async () => {
  if (isMicOn) meeting?.muteMic();
  else meeting?.unmuteMic();
  isMicOn = !isMicOn;
});

connectAgentButton.addEventListener("click", async () => {
  try {
    const response = await fetch("https://api.videosdk.live/v2/agent/general/dispatch", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: TOKEN,
      },
      body: JSON.stringify({ agentId: AGENT_ID, meetingId: ROOM_ID, versionId: VERSION_ID }),
    });
    if (response.ok) {
      alert("Agent connected successfully!");
      connectAgentButton.style.display = "none";
    } else {
      alert("Failed to connect agent.");
    }
  } catch (error) {
    console.error("Error connecting agent:", error);
    alert("An error occurred while connecting the agent.");
  }
});
```



## Creating the AI Agent from Dashboard (No-Code)

You can create and configure a powerful AI agent directly from the VideoSDK dashboard.

### Step 1: Create Your Agent


First, follow our detailed guide to **[Build a Custom Voice AI Agent in Minutes](/ai_agents/agent-runtime/build-agent)**. This will walk you through creating the agent's persona, configuring its pipeline (Realtime or Cascading), and testing it directly from the dashboard.



### Step 2: Get Agent and Version ID


Once your agent is created, you need to get its `agentId` and `versionId` to connect it to your frontend application.

1.  After creating your agent, go to the agent's page and find the JSON editor on right side. Copy the `agentId`.

2.  To get the `versionId`, click on 3 dots besides Deploy button and click on "Version History" in it. Copy the version id via copy button of the version you want.

![Get agentId and versionId](https://strapi.videosdk.live/uploads/agent_version_id_0f8b59830a.png)



### Step 3: Configure IDs in Frontend


Now, update your `config.js` file with these IDs.

```js title="config.js"
TOKEN = "your_videosdk_auth_token_here";
ROOM_ID = "YOUR_MEETING_ID";
AGENT_ID = "paste_your_agent_id_here";
VERSION_ID = "paste_your_version_id_here";
```


## Run the Application

### Step 1: Start the Frontend

Once you have completed all the steps, serve your frontend files:

```bash
# Using Python's built-in server
python3 -m http.server 8000

# Or using Node.js http-server
npx http-server -p 8000
```

Open `http://localhost:8000` in your web browser.


### Step 2: Connect and Interact

1. **Join the meeting from the frontend:**
   - Click the "Join Agent Meeting" button in your browser.
   - Allow microphone permissions when prompted.

2. **Connect the agent:**
   - Once you join, click the "Connect Agent" button.
   - You should see an alert confirming the agent was connected.
   - The AI agent will join the meeting and greet you.

3. **Start playing:**
   - Interact with your AI agent using your microphone.


## Final Output

You have completed the implementation of an AI agent with real-time voice interaction using VideoSDK and a no-code agent from the dashboard.



## Troubleshooting

### Common Issues:

1. **Agent not joining:**
   - Check that the `ROOM_ID`, `AGENT_ID`, and `VERSION_ID` are correctly set in `config.js`.
   - Verify your VideoSDK token is valid and has the necessary permissions.

2. **Audio not working:**
   - Check browser permissions for microphone access.

3. **"Failed to connect agent" error:**
   - Verify your `AGENT_ID` and `VERSION_ID` are correct.
   - Check the browser's developer console for any network errors.







---

# Agent Runtime with React

VideoSDK empowers you to seamlessly integrate AI agents with real-time voice interaction into your React application within minutes. This guide shows you how to connect a React frontend with an AI agent created and configured entirely from the VideoSDK dashboard.

## Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

- Video SDK Developer Account (Not having one, follow **[Video SDK Dashboard](https://app.videosdk.live/)**)
- Node.js installed on your device
- Familiarity with creating a no-code voice agent. If you're new to this, please follow our guide on how to **[Build a Custom Voice AI Agent in Minutes](/ai_agents/agent-runtime/build-agent)** first.

:::important

You need a VideoSDK account to generate a token and an agent from the dashboard.
Visit the VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate a token.

:::

## Project Structure

Your project structure should look like this.

```jsx title="Project Structure"
  root
   ├── node_modules
   ├── public
   ├── src
   │    ├── config.js
   │    ├── App.js
   │    └── index.js
   └── .env
```

You will be working on the following files:

- `App.js`: Responsible for creating a basic UI for joining the meeting
- `config.js`: Responsible for storing the token, room ID, and agent credentials
- `index.js`: This is the entry point of your React application.


## Part 1: React Frontend

### Step 1: Getting Started with the Code!


#### Create new React App

Create a new React App using the below command.

```bash
$ npx create-react-app videosdk-ai-agent-react-app
```

#### Install VideoSDK

Install the VideoSDK using the below-mentioned npm command. Make sure you are in your react app directory before you run this command.

```bash
$ npm install "@videosdk.live/react-sdk"
```


### Step 2: Configure Environment and Credentials


Create a meeting room using the VideoSDK API:

```bash
curl -X POST https://api.videosdk.live/v2/rooms \
  -H "Authorization: YOUR_JWT_TOKEN_HERE" \
  -H "Content-Type: application/json"
```

Copy the `roomId` from the response and configure it in `src/config.js`. You will get the Agent and Version IDs in the next section.

```js title="src/config.js"
export const TOKEN = "YOUR_VIDEOSDK_AUTH_TOKEN";
export const ROOM_ID = "YOUR_MEETING_ID";
export const AGENT_ID = "YOUR_AGENT_ID";
export const VERSION_ID = "YOUR_VERSION_ID";
```


### Step 3: Design the user interface (UI)


Create the main App component with audio-only interaction in `src/App.js`. This includes the "Connect Agent" button.

```js title="src/App.js"
import React, { useEffect, useRef, useState } from "react";


function ParticipantAudio({ participantId }) {
  const { micStream, micOn, isLocal, displayName } = useParticipant(participantId);
  const audioRef = useRef(null);

  useEffect(() => {
    if (!audioRef.current) return;
    if (micOn && micStream) {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(micStream.track);
      audioRef.current.srcObject = mediaStream;
      audioRef.current.play().catch(() => {});
    } else {
      audioRef.current.srcObject = null;
    }
  }, [micStream, micOn]);

  return (
    <div>
      <p>Participant: {displayName} | Mic: {micOn ? "ON" : "OFF"}</p>
      <audio ref={audioRef} autoPlay muted={isLocal} />
    </div>
  );
}

function Controls() {
  const { leave, toggleMic } = useMeeting();
  const [connected, setConnected] = useState(false);

  const connectAgent = async () => {
    try {
      const response = await fetch("https://api.videosdk.live/v2/agent/general/dispatch", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: TOKEN,
        },
        body: JSON.stringify({ agentId: AGENT_ID, meetingId: ROOM_ID, versionId: VERSION_ID }),
      });
      if (response.ok) {
        alert("Agent connected successfully!");
        setConnected(true);
      } else {
        alert("Failed to connect agent.");
      }
    } catch (error) {
      console.error("Error connecting agent:", error);
      alert("An error occurred while connecting the agent.");
    }
  };

  return (
    <div>
      <button onClick={() => leave()}>Leave</button>
      <button onClick={() => toggleMic()}>Toggle Mic</button>
      {!connected && <button onClick={connectAgent}>Connect Agent</button>}
    </div>
  );
}

function MeetingView({ meetingId, onMeetingLeave }) {
  const [joined, setJoined] = useState(null);
  const { join, participants } = useMeeting({
    onMeetingJoined: () => setJoined("JOINED"),
    onMeetingLeft: onMeetingLeave,
  });

  const joinMeeting = () => {
    setJoined("JOINING");
    join();
  };

  return (
    <div>
      <h3>Meeting Id: {meetingId}</h3>
      {joined === "JOINED" ? (
        <div>
          
          {[...participants.keys()].map((pid) => (
            
          ))}
        </div>
      ) : joined === "JOINING" ? (
        <p>Joining the meeting...</p>
      ) : (
        <button onClick={joinMeeting}>Join</button>
      )}
    </div>
  );
}

export default function App() {
  const [meetingId] = useState(ROOM_ID);

  const onMeetingLeave = () => {
    // no-op; simple sample
  };

  return (
    }
      </MeetingConsumer>
    </MeetingProvider>
  );
}
```



## Part 2: Creating the AI Agent from Dashboard (No-Code)

You can create and configure a powerful AI agent directly from the VideoSDK dashboard.

### Step 1: Create Your Agent


First, follow our detailed guide to **[Build a Custom Voice AI Agent in Minutes](/ai_agents/agent-runtime/build-agent)**. This will walk you through creating the agent's persona, configuring its pipeline (Realtime or Cascading), and testing it directly from the dashboard.



### Step 2: Get Agent and Version ID


Once your agent is created, you need to get its `agentId` and `versionId` to connect it to your frontend application.

1.  After creating your agent, go to the agent's page and find the JSON editor on right side. Copy the `agentId`.

2.  To get the `versionId`, click on 3 dots besides Deploy button and click on "Version History" in it. Copy the version id via copy button of the version you want.

![Get agentId and versionId](https://strapi.videosdk.live/uploads/agent_version_id_0f8b59830a.png)



### Step 3: Configure IDs in Frontend


Now, update your `src/config.js` file with these IDs.

```js title="src/config.js"
export const TOKEN = "your_videosdk_auth_token_here";
export const ROOM_ID = "YOUR_MEETING_ID";
export const AGENT_ID = "paste_your_agent_id_here";
export const VERSION_ID = "paste_your_version_id_here";
```


## Part 3: Run the Application

### Step 1: Run the Frontend


Once you have completed all the steps mentioned above, start your React application:

```bash
# Install dependencies
npm install

# Start the development server
npm start
```

Open `http://localhost:3000` in your web browser.



### Step 2: Connect and Interact


1. **Join the meeting from the React app:**
   - Click the "Join" button in your browser
   - Allow microphone permissions when prompted

2. **Connect the agent:**
   - Once you join, click the "Connect Agent" button.
   - You should see an alert confirming the agent was connected.
   - The AI agent will join the meeting and greet you.

3. **Start playing:**
   - Interact with your AI agent using your microphone.


## Final Output

You have completed the implementation of an AI agent with real-time voice interaction using VideoSDK and a no-code agent from the dashboard in React.



## Troubleshooting

### Common Issues:

1. **Agent not joining:**
   - Check that the `ROOM_ID`, `AGENT_ID`, and `VERSION_ID` are correctly set in `src/config.js`.
   - Verify your VideoSDK token is valid and has the necessary permissions.

2. **Audio not working:**
   - Check browser permissions for microphone access.

3. **"Failed to connect agent" error:**
   - Verify your `AGENT_ID` and `VERSION_ID` are correct.
   - Check the browser's developer console for any network errors.

4. **React build issues:**
   - Ensure Node.js version is compatible
   - Try clearing npm cache: `npm cache clean --force`
   - Delete `node_modules` and reinstall: `rm -rf node_modules && npm install`




---

VideoSDK empowers you to seamlessly integrate AI agents with real-time voice interaction into your Flutter application within minutes.

In this quickstart, you'll explore how to create an AI agent that joins a flutter meeting room and interacts with users through voice using Google Gemini Live API.

## Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

- Video SDK Developer Account (Not having one, follow **[Video SDK Dashboard](https://app.videosdk.live/)**)
- Flutter and Python 3.12+ installed on your device
- Google API Key with Gemini Live API access

:::important
You need a VideoSDK account to generate a token and a Google API key for the Gemini Live API.
Visit the VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate a token and the **[Google AI Studio](https://aistudio.google.com/api-keys)** for Google API key.
:::

## Project Structure

Your project structure should look like this:

```jsx title="Project Structure"
  root
   ├── android
   ├── ios
   ├── lib
   │    ├── api_call.dart
   │    ├── join_screen.dart
   │    ├── main.dart
   │    ├── meeting_controls.dart
   │    ├── meeting_screen.dart
   │    └── participant_tile.dart
   ├── macos
   ├── web
   ├── windows
   ├── agent-flutter.py
   └── .env
```

You will be working on the following files:

- `join_screen.dart`: Responsible for the user interface to join a meeting.
- `meeting_screen.dart`: Displays the meeting interface and handles meeting logic.
- `api_call.dart`: Handles API calls for creating meetings.
- `agent-flutter.py`: The Python AI agent backend using Google Gemini Live API.
- `.env`: For storing API keys.

## 1. Flutter Frontend

### Step 1: Getting Started


Follow these steps to create the environment necessary to add AI agent functionality to your app.

#### Create a New Flutter App

Create a new Flutter app using the following command:

```bash
$ flutter create videosdk_ai_agent_flutter_app
```

#### Install VideoSDK

Install the VideoSDK using the following Flutter command. Make sure you are in your Flutter app directory before you run this command.

```bash
$ flutter pub add videosdk
$ flutter pub add http
```


### Step 2: Configure Project


#### For Android

- Update the `/android/app/src/main/AndroidManifest.xml` for the permissions we will be using to implement the audio and video features.

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

- If necessary, in the `build.gradle` you will need to increase `minSdkVersion` of `defaultConfig` up to `23` (currently default Flutter generator set it to `16`).

#### For iOS

- Add the following entries which allow your app to access the camera and microphone to your `/ios/Runner/Info.plist` file :

```xml title="/ios/Runner/Info.plist"
<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) Camera Usage!</string>
<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) Microphone Usage!</string>
```

- Uncomment the following line to define a global platform for your project in `/ios/Podfile` :

```ruby title="/ios/Podfile"
platform :ios, '12.0'
```

#### For MacOS

- Add the following entries to your `/macos/Runner/Info.plist` file which allow your app to access the camera and microphone.

```xml title="/macos/Runner/Info.plist"
<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) Camera Usage!</string>
<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) Microphone Usage!</string>
```

- Add the following entries to your `/macos/Runner/DebugProfile.entitlements` file which allow your app to access the camera, microphone and open outgoing network connections.

```xml title="/macos/Runner/DebugProfile.entitleaments"
<key>com.apple.security.network.client</key>
<true/>
<key>com.apple.security.device.camera</key>
<true/>
<key>com.apple.security.device.microphone</key>
<true/>
```

- Add the following entries to your `/macos/Runner/Release.entitlements` file which allow your app to access the camera, microphone and open outgoing network connections.

```xml title="/macos/Runner/Release.entitlements"
<key>com.apple.security.network.server</key>
<true/>
<key>com.apple.security.network.client</key>
<true/>
<key>com.apple.security.device.camera</key>
<true/>
<key>com.apple.security.device.microphone</key>
<true/>
```



### Step 3: Configure Environment and Credentials


Create a meeting room using the VideoSDK API:

```bash
curl -X POST https://api.videosdk.live/v2/rooms \
  -H "Authorization: YOUR_JWT_TOKEN_HERE" \
  -H "Content-Type: application/json"
```

Copy the `roomId` from the response and configure it in `lib/join_screen.dart` and `lib/api_call.dart`.

```js title="lib/api_call.dart"
import 'dart:convert';
import 'package:http/http.dart' as http;

//Auth token we will use to generate a meeting and connect to it
const token =
    'YOUR_VIDEOSDK_AUTH_TOKEN';

// API call to create meeting
Future<String> createMeeting() async {
  final http.Response httpResponse = await http.post(
    Uri.parse('https://api.videosdk.live/v2/rooms'),
    headers: {'Authorization': token},
  );

  //Destructuring the roomId from the response
  return json.decode(httpResponse.body)['roomId'];
}
```

```js title="lib/join_screen.dart"
import 'package:flutter/material.dart';
import 'api_call.dart';
import 'meeting_screen.dart';

class JoinScreen extends StatelessWidget {
  final _meetingIdController = TextEditingController();

  JoinScreen({super.key});

  void onCreateButtonPressed(BuildContext context) async {
    // call api to create meeting and navigate to MeetingScreen with meetingId,token
    await createMeeting().then((meetingId) {
      if (!context.mounted) return;
      Navigator.of(context).push(
        MaterialPageRoute(
          builder:
              (context) => MeetingScreen(meetingId: meetingId, token: token),
        ),
      );
    });
  }

  void onJoinButtonPressed(BuildContext context) {
    // check meeting id is not null or invaild
    // if meeting id is vaild then navigate to MeetingScreen with meetingId,token
    Navigator.of(context).push(
      MaterialPageRoute(
        builder:
            (context) =>
                MeetingScreen(meetingId: "YOUR_MEETING_ID", token: token),
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('VideoSDK QuickStart')),
      body: Padding(
        padding: const EdgeInsets.all(12.0),
        child: Center(
          child: ElevatedButton(
            onPressed: () => onJoinButtonPressed(context),
            child: const Text('Join Meeting'),
          ),
        ),
      ),
    );
  }
}
```



### Step 4: Design the User Interface (UI)


Create the main `MeetingScreen` component with audio-only interaction in `lib/meeting_screen.dart`:

```js title="lib/meeting_screen.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
import 'participant_tile.dart';
import 'meeting_controls.dart';

class MeetingScreen extends StatefulWidget {
  final String meetingId;
  final String token;

  const MeetingScreen({
    super.key,
    required this.meetingId,
    required this.token,
  });

  @override
  State<MeetingScreen> createState() => _MeetingScreenState();
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;
  var micEnabled = true;
  var camEnabled = true;

  Map<String, Participant> participants = {};

  @override
  void initState() {
    // create room
    _room = VideoSDK.createRoom(
      roomId: widget.meetingId,
      token: widget.token,
      displayName: "John Doe",
      micEnabled: micEnabled,
      camEnabled: false,
      defaultCameraIndex:
          1, // Index of MediaDevices will be used to set default camera
    );

    setMeetingEventListener();

    // Join room
    _room.join();

    super.initState();
  }

  // listening to meeting events
  void setMeetingEventListener() {
    _room.on(Events.roomJoined, () {
      setState(() {
        participants.putIfAbsent(
          _room.localParticipant.id,
          () => _room.localParticipant,
        );
      });
    });

    _room.on(Events.participantJoined, (Participant participant) {
      setState(
        () => participants.putIfAbsent(participant.id, () => participant),
      );
    });

    _room.on(Events.participantLeft, (String participantId) {
      if (participants.containsKey(participantId)) {
        setState(() => participants.remove(participantId));
      }
    });

    _room.on(Events.roomLeft, () {
      participants.clear();
      Navigator.popUntil(context, ModalRoute.withName('/'));
    });
  }

  // onbackButton pressed leave the room
  Future<bool> _onWillPop() async {
    _room.leave();
    return true;
  }

  @override
  Widget build(BuildContext context) {
    return WillPopScope(
      onWillPop: () => _onWillPop(),
      child: Scaffold(
        appBar: AppBar(title: const Text('VideoSDK QuickStart')),
        body: Padding(
          padding: const EdgeInsets.all(8.0),
          child: Column(
            children: [
              Text(widget.meetingId),
              //render all participant
              Expanded(
                child: Padding(
                  padding: const EdgeInsets.all(8.0),
                  child: GridView.builder(
                    gridDelegate:
                        const SliverGridDelegateWithFixedCrossAxisCount(
                          crossAxisCount: 2,
                          crossAxisSpacing: 10,
                          mainAxisSpacing: 10,
                          mainAxisExtent: 300,
                        ),
                    itemBuilder: (context, index) {
                      return ParticipantTile(
                        key: Key(participants.values.elementAt(index).id),
                        participant: participants.values.elementAt(index),
                      );
                    },
                    itemCount: participants.length,
                  ),
                ),
              ),
              MeetingControls(
                onToggleMicButtonPressed: () {
                  micEnabled ? _room.muteMic() : _room.unmuteMic();
                  micEnabled = !micEnabled;
                },
                onLeaveButtonPressed: () => _room.leave(),
              ),
            ],
          ),
        ),
      ),
    );
  }
}
```

```js title="lib/participant_tile.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;
  const ParticipantTile({super.key, required this.participant});

  @override
  State<ParticipantTile> createState() => _ParticipantTileState();
}

class _ParticipantTileState extends State<ParticipantTile> {
  var pariticpantName;
  @override
  void initState() {
    pariticpantName = widget.participant.displayName;

    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return Padding(
      padding: const EdgeInsets.all(8.0),
      child: Container(
        color: Colors.grey.shade800,
        child: Center(
          child: Text(
            '$pariticpantName',
            style: TextStyle(color: Colors.white),
          ),
        ),
      ),
    );
  }
}
```

```js title="lib/meeting_controls.dart"
import 'package:flutter/material.dart';

class MeetingControls extends StatelessWidget {
  final void Function() onToggleMicButtonPressed;
  final void Function() onLeaveButtonPressed;

  const MeetingControls({
    super.key,
    required this.onToggleMicButtonPressed,
    required this.onLeaveButtonPressed,
  });

  @override
  Widget build(BuildContext context) {
    return Row(
      mainAxisAlignment: MainAxisAlignment.spaceEvenly,
      children: [
        ElevatedButton(
          onPressed: onLeaveButtonPressed,
          child: const Text('Leave'),
        ),
        ElevatedButton(
          onPressed: onToggleMicButtonPressed,
          child: const Text('Toggle Mic'),
        ),
      ],
    );
  }
}
```



## 2. Python AI Agent

### Step 1: Create Python AI Agent


Create a `.env` file to store your API keys securely for the Python agent:

```env title=".env"
# Google API Key for Gemini Live API
GOOGLE_API_KEY=your_google_api_key_here

# VideoSDK Authentication Token
VIDEOSDK_AUTH_TOKEN=your_videosdk_auth_token_here
```




Create the Python AI agent that will join the same meeting room and interact with users through voice.

```python title="agent-flutter.py"
from videosdk.agents import Agent, AgentSession, RealTimePipeline, JobContext, RoomOptions, WorkerJob
from videosdk.plugins.google import GeminiRealtime, GeminiLiveConfig
import logging

logging.getLogger().setLevel(logging.INFO)

class MyVoiceAgent(Agent): 
    def __init__(self):
        super().__init__(
            instructions="You are a high-energy game-show host guiding the caller to guess a secret number from 1 to 100 to win 1,000,000$.",
        )

    async def on_enter(self) -> None:
        await self.session.say("Welcome to the Videosdk's AI Agent game show! I'm your host, and we're about to play for 1,000,000$. Are you ready to play?")
    
    async def on_exit(self) -> None:
        await self.session.say("Goodbye!")

async def start_session(context: JobContext):
    agent = MyVoiceAgent()
    model = GeminiRealtime(
        model="gemini-2.5-flash-native-audio-preview-12-2025",
        # When GOOGLE_API_KEY is set in .env - DON'T pass api_key parameter
        # api_key="AIXXXXXXXXXXXXXXXXXXXX", 
        config=GeminiLiveConfig(
            voice="Leda", # Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus, and Zephyr.
            response_modalities=["AUDIO"]
        )
    )

    pipeline = RealTimePipeline(model=model)
    session = AgentSession(
        agent=agent,
        pipeline=pipeline
    )

    def on_transcription(data: dict):
        role = data.get("role")
        text = data.get("text")
        print(f"[TRANSCRIPT][{role}]: {text}")
    pipeline.on("realtime_model_transcription", on_transcription)

    await context.run_until_shutdown(session=session, wait_for_participant=True)

def make_context() -> JobContext:
    room_options = RoomOptions(
        # Static meeting ID - same as used in frontend
        room_id="YOUR_MEETING_ID", # Replace it with your actual room_id
        name="Gemini Agent",
        playground=True,
    )

    return JobContext(room_options=room_options)

if __name__ == "__main__":
    job = WorkerJob(entrypoint=start_session, jobctx=make_context)
    job.start()
```



## 3. Run the Application

### Step 1: Run the Frontend


Once you have completed all the steps mentioned above, start your Flutter application:

```bash
flutter run
```



### Step 2: Run the AI Agent


Open a new terminal and run the Python agent:

```bash
# Install Python dependencies
pip install "videosdk-plugins-google"
pip install videosdk-agents


# Run the AI agent
python agent-flutter.py
```



### Step 3: Connect and Interact


1. **Join the meeting from the Flutter app:**
   - Click the "Join Meeting" button.
   - Allow microphone permissions when prompted.

2. **Agent connection:**
   - Once you join, the Python agent will detect your participation.
   - You should see "Participant joined" in the terminal.
   - The AI agent will greet you and start the game.

3. **Start playing:**
   - The agent will guide you through a number guessing game (1-100).
   - Use your microphone to interact with the AI host.
   - The agent will provide hints and encouragement throughout the game.


## Troubleshooting

### Common Issues:

1. **"Waiting for participant..." but no connection:**
   - Ensure both the frontend and the agent are running.
   - Check that the room ID matches in both `lib/join_screen.dart` and `agent-flutter.py`.
   - Verify your VideoSDK token is valid.

2. **Audio not working:**
   - Check browser permissions for microphone access.
   - Ensure your Google API key has Gemini Live API access enabled.

3. **Agent not responding:**
   - Verify your Google API key is correctly set in the environment.
   - Check that the Gemini Live API is enabled in your Google Cloud Console.

4. **Flutter build issues:**
   - Ensure your Flutter version is compatible.
   - Try cleaning the build: `flutter clean`.
   - Delete `pubspec.lock` and run `flutter pub get`.

## Next Steps

Clone repo for quick implementation



- [Quickstart Example](https://github.com/videosdk-live/agents-quickstart/tree/main/mobile-quickstarts/flutter): Complete working example with source code


---

VideoSDK empowers you to integrate an AI voice agent into your iOS app within minutes. The agent joins the same meeting room and interacts over voice using the Google Gemini Live API.

## Prerequisites

- iOS 13.0+
- Xcode 13.0+
- Swift 5.0+
- VideoSDK Developer Account (get token from the [dashboard](https://app.videosdk.live/api-keys))
- Python 3.12+
- Google API Key with Gemini Live API access

:::important
You need a VideoSDK account to generate a token and a Google API key for the Gemini Live API.
Visit the VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate a token and the **[Google AI Studio](https://aistudio.google.com/api-keys)** for Google API key.
:::

## Project Structure

```jsx title="Directory Structure"
  .
  ├── videosdk-agents-quickstart-ios/
  │    ├── JoinScreenView.swift
  │    ├── MeetingView.swift
  │    ├── MeetingViewController.swift
  │    ├── RoomsStruct.swift
  │    └── videosdk_agents_quickstart_iosApp.swift
  ├── videosdk-agents-quickstart-ios.xcodeproj/
  ├── agent-ios.py
  └── .env
```

You will work on:
- `JoinScreenView.swift`: Join screen UI
- `MeetingView.swift`: Meeting interface with audio controls
- `MeetingViewController.swift`: Handles meeting logic and events
- `agent-ios.py`: Python AI agent (Gemini Live)
- `.env`: For storing API keys.

## 1. iOS Frontend

### Step 1: Create App and Install VideoSDK


Create a new iOS app in Xcode:

1. Create a new Xcode project
2. Choose **App** template
3. Add **Product Name** and save the project

Install VideoSDK using Swift Package Manager:

1. In Xcode, go to `File > Add Packages...`
2. Enter the repository URL: `https://github.com/videosdk-live/videosdk-rtc-ios-sdk.git`
3. Choose the latest version and click `Add Package`

Add permissions to `Info.plist`:

```xml title="Info.plist"
<key>NSCameraUsageDescription</key>
<string>Camera permission description</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone permission description</string>
```



### Step 2: Create Models and Views


Create Swift models and views for the meeting interface:

```swift title="RoomsStruct.swift"
struct RoomsStruct: Codable {
    let createdAt, updatedAt, roomID: String?
    let links: Links?
    let id: String?

    enum CodingKeys: String, CodingKey {
        case createdAt, updatedAt
        case roomID = "roomId"
        case links, id
    }
}

struct Links: Codable {
   let getRoom, getSession: String?

    enum CodingKeys: String, CodingKey {
        case getRoom = "get_room"
        case getSession = "get_session"
    }
}
```

```swift title="JoinScreenView.swift"
import SwiftUI

struct JoinScreenView: View {
    
    // State variables for
    let meetingId: String = "YOUR_MEETING_ID"
    @State var name: String
    
    var body: some View {
        NavigationView {
            VStack {
                Text("VideoSDK")
                    .font(.largeTitle)
                    .fontWeight(.bold)
                Text("AI Agent Quickstart")
                    .font(.largeTitle)
                    .fontWeight(.semibold)
                    .padding(.bottom)
                
                TextField("Enter Your Name", text: $name)
                    .foregroundColor(Color.black)
                    .autocorrectionDisabled()
                    .font(.headline)
                    .overlay(
                        Image(systemName: "xmark.circle.fill")
                            .padding()
                            .offset(x: 10)
                            .foregroundColor(Color.gray)
                            .opacity(name.isEmpty ? 0.0 : 1.0)
                            .onTapGesture {
                                UIApplication.shared.endEditing()
                                name = ""
                            }
                        , alignment: .trailing)
                    .padding()
                    .background(
                        RoundedRectangle(cornerRadius: 25)
                            .fill(Color.secondary.opacity(0.5))
                            .shadow(color: Color.gray.opacity(0.10), radius: 10))
                    .padding()
                
                NavigationLink(destination: MeetingView(meetingId: self.meetingId, userName: name ?? "Guest")
                    .navigationBarBackButtonHidden(true)) {
                        Text("Join Meeting")
                            .foregroundColor(Color.white)
                            .padding()
                            .background(
                                RoundedRectangle(cornerRadius: 25.0)
                                    .fill(Color.blue))
                    }
            }
        }
    }
}

extension UIApplication {
    
    func endEditing() {
        sendAction(#selector(UIResponder.resignFirstResponder), to: nil, from: nil, for: nil)
    }
}
```

```swift title="MeetingView.swift"
import SwiftUI
import VideoSDKRTC

struct MeetingView: View{

@Environment(\.presentationMode) var presentationMode

@ObservedObject var meetingViewController = MeetingViewController()
@State var meetingId: String?
@State var userName: String?
@State var isUnMute: Bool = true

var body: some View {
    VStack {
        if meetingViewController.participants.count == 0 {
            Text("Meeting Initializing")
        } else {
            VStack {
                VStack(spacing: 20) {
                    Text("Meeting ID: \(meetingViewController.meetingID)")
                        .padding(.vertical)
                    
                    List {
                        ForEach(meetingViewController.participants.indices, id: \.self) { index in
                            Text("Participant Name: \(meetingViewController.participants[index].displayName)")
                        }
                    }
                }
                
                VStack {
                    HStack(spacing: 15) {
                        // mic button
                        Button {
                            if isUnMute {
                                isUnMute = false
                                meetingViewController.meeting?.muteMic()
                            }
                            else {
                                isUnMute = true
                                meetingViewController.meeting?.unmuteMic()
                            }
                        } label: {
                            Text("Toggle Mic")
                                .foregroundStyle(Color.white)
                                .font(.caption)
                                .padding()
                                .background(
                                    RoundedRectangle(cornerRadius: 25)
                                        .fill(Color.blue))
                        }
                        // end meeting button
                        Button {
                            meetingViewController.meeting?.end()
                            presentationMode.wrappedValue.dismiss()
                        } label: {
                            Text("End Call")
                                .foregroundStyle(Color.white)
                                .font(.caption)
                                .padding()
                                .background(
                                    RoundedRectangle(cornerRadius: 25)
                                        .fill(Color.red))
                        }
                    }
                    .padding(.bottom)
                }
            }
        }
    }
    .onAppear() {
        /// MARK :- configuring the videoSDK
        VideoSDK.config(token: meetingViewController.token)
        print(meetingId)
        if meetingId?.isEmpty == false {
            print("i ff meeting isd is emty \(meetingId)")
            // join an existing meeting with provided meeting Id
            meetingViewController.joinMeeting(meetingId: meetingId!, userName: userName!)
        }
    }
}
}
```



### Step 3: Implement Meeting Logic


Create the main meeting view controller to handle events:

```swift title="MeetingViewController.swift"
import Foundation
import VideoSDKRTC

class MeetingViewController: ObservableObject {
    
    var token = "YOUR_VIDEOSDK_AUTH_TOKEN" // Add Your token here
    var meetingId: String = ""
    var name: String = ""
    
    @Published var meeting: Meeting? = nil
    @Published var participants: [Participant] = []
    @Published var meetingID: String = ""
    
    func initializeMeeting(meetingId: String, userName: String) {
        meeting = VideoSDK.initMeeting(
            meetingId: meetingId,
            participantName: userName,
            micEnabled: true,
            webcamEnabled: false
        )
        
        meeting?.addEventListener(self)
        meeting?.join()
    }
}

extension MeetingViewController: MeetingEventListener {
    
    func onMeetingJoined() {
        guard let localParticipant = self.meeting?.localParticipant else { return }
        
        // add to list
        participants.append(localParticipant)
        
        localParticipant.addEventListener(self)
        
    }
    
    func onParticipantJoined(_ participant: Participant) {
        participants.append(participant)
        
        // add listener
        participant.addEventListener(self)
        
    }
    
    func onParticipantLeft(_ participant: Participant) {
        participants = participants.filter({ $0.id != participant.id })
    }
    
    func onMeetingLeft() {
        meeting?.localParticipant.removeEventListener(self)
        meeting?.removeEventListener(self)
    }
    
    func onMeetingStateChanged(meetingState: MeetingState) {
        switch meetingState {
        case .DISCONNECTED:
            participants.removeAll()
        default:
            print("")
        }
    }
}

extension MeetingViewController: ParticipantEventListener {
    
}

extension MeetingViewController {
        
    func joinMeeting(meetingId: String, userName: String) {
        if !token.isEmpty {
            self.meetingID = meetingId
            self.initializeMeeting(meetingId: meetingId, userName: userName)
        }
        else {
            print("Auth token required")
        }
    }
}
```



### Step 4: App Entry Point


Configure the main app entry point:

```swift title="videosdk_agents_quickstart_iosApp.swift"
import SwiftUI

@main
struct videosdk_agents_quickstart_iosApp: App {
    var body: some Scene {
        WindowGroup {
            JoinScreenView(name: "")
        }
    }
}
```



## 2. Python AI Agent

### Step 1: Configure Environment


Create a `.env` file in the `mobile-quickstarts/ios` directory to store your API keys securely.

```env title=".env"
# Google API Key for Gemini Live API
GOOGLE_API_KEY=your_google_api_key_here

# VideoSDK Authentication Token
VIDEOSDK_AUTH_TOKEN=your_videosdk_auth_token_here
```



### 2. Create Python AI Agent


Create the Python AI agent that will join the same meeting room and interact with users through voice.

```python title="agent-ios.py"
from videosdk.agents import Agent, AgentSession, RealTimePipeline, JobContext, RoomOptions, WorkerJob
from videosdk.plugins.google import GeminiRealtime, GeminiLiveConfig
import logging

logging.getLogger().setLevel(logging.INFO)

class MyVoiceAgent(Agent): 
    def __init__(self):
        super().__init__(
            instructions="You are a high-energy game-show host guiding the caller to guess a secret number from 1 to 100 to win 1,000,000$.",
        )

    async def on_enter(self) -> None:
        await self.session.say("Welcome to the Videosdk's AI Agent game show! I'm your host, and we're about to play for 1,000,000$. Are you ready to play?")
    
    async def on_exit(self) -> None:
        await self.session.say("Goodbye!")

async def start_session(context: JobContext):
    agent = MyVoiceAgent()
    model = GeminiRealtime(
        model="gemini-2.5-flash-native-audio-preview-12-2025",
        # When GOOGLE_API_KEY is set in .env - DON'T pass api_key parameter
        # api_key="AIXXXXXXXXXXXXXXXXXXXX", 
        config=GeminiLiveConfig(
            voice="Leda", # Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus, and Zephyr.
            response_modalities=["AUDIO"]
        )
    )

    pipeline = RealTimePipeline(model=model)
    session = AgentSession(
        agent=agent,
        pipeline=pipeline
    )

    def on_transcription(data: dict):
        role = data.get("role")
        text = data.get("text")
        print(f"[TRANSCRIPT][{role}]: {text}")
    pipeline.on("realtime_model_transcription", on_transcription)

    await context.run_until_shutdown(session=session, wait_for_participant=True)

def make_context() -> JobContext:
    room_options = RoomOptions(
        # Static meeting ID - same as used in frontend
        room_id="YOUR_MEETING_ID", # Replace it with your actual room_id
        name="Gemini Agent",
        playground=True,
    )

    return JobContext(room_options=room_options)

if __name__ == "__main__":
    job = WorkerJob(entrypoint=start_session, jobctx=make_context)
    job.start()
```



## 3. Run the Application

### Step 1: Run the iOS App


Build and run the app from Xcode on a simulator or physical device.



### Step 2: Run the AI Agent


Open a new terminal and run the Python agent:

```bash
pip install videosdk-agents
pip install "videosdk-plugins-google"
python agent-ios.py
```


### Step 3: Connect and Interact


1. Run the iOS app on a simulator or device
2. Join the meeting and allow microphone permissions
3. When you join, the Python agent detects your participation and starts speaking
4. Talk to the agent in real time and play the number guessing game


## Troubleshooting

- Ensure the same `room_id` is set in both the iOS app and the agent's `RoomOptions`
- Verify microphone permissions in iOS Settings > Privacy & Security > Microphone
- Confirm your VideoSDK token is valid and Google API key is set
- For simulator issues, ensure you're using a physical device for microphone testing

## Next Steps

Clone repo for quick implementation



- [Quickstart Example](https://github.com/videosdk-live/agents-quickstart/tree/main/mobile-quickstarts/ios): Complete working example with source code


---

VideoSDK empowers you to seamlessly integrate AI agents with real-time voice interaction with your IoT device within minutes.

In this quickstart, you'll explore how to create an AI agent that connects with an IoT device and interacts with users through voice using Google Gemini Live API.


## Prerequisites

Before you begin, ensure you have the following:

- **ESP-IDF v5.3**: Installed and configured for your ESP32-S3 board.
- **Python**: Version 3.12 or higher.
- **VideoSDK Account**: If you don't have one, sign up at the [VideoSDK Dashboard](https://app.videosdk.live/).
- **Google API Key**: For using the Gemini Live API.

:::important
You need a VideoSDK account to generate a token and a Google API key for the Gemini Live API.
Visit the VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate a token and the **[Google AI Studio](https://aistudio.google.com/api-keys)** for Google API key.
:::

## Project Structure

```
IoT-quickstart/
├── main/
│   ├── ai-demo.c
│   ├── CMakeLists.txt
│   ├── idf_component.yml
│   └── Kconfig.projbuild
├── agent-iot.py
├── partitions.csv
├── sdkconfig.defaults
└── README.md
```

You will be working with the following files:
- **`main/ai-demo.c`**: Main application logic for the ESP32 firmware.
- **`agent-iot.py`**: The Python AI agent that joins the meeting.
- **Configuration Files**: `main/idf_component.yml`, `main/CMakeLists.txt`, `main/Kconfig.projbuild`, `partitions.csv`, and `sdkconfig.defaults` for project setup.

## 1. ESP32-S3 Firmware Setup

### Step 1: Create a Meeting Room


First, create a meeting room using the VideoSDK API. This will provide a static `roomId` that both the ESP32 device and the AI agent will use to connect.

```bash
curl -X POST https://api.videosdk.live/v2/rooms \
  -H "Authorization: YOUR_JWT_TOKEN_HERE" \
  -H "Content-Type: application/json"
```
Replace `YOUR_JWT_TOKEN_HERE` with your VideoSDK auth token. Copy the `roomId` from the response to use in the following steps.



### Step 2: Configure the Project


Update the configuration files to set up your project dependencies, build settings, and hardware specifics.

**Dependencies:**

```yaml title="main/idf_component.yml"
## IDF Component Manager Manifest File
dependencies:
  iot-sdk: 
 path: /path/to/your/IoTSdk # Replace with the absolute path to your cloned IoTSdk
  protocol_examples_common:
path: ${IDF_PATH}/examples/common_components/protocol_examples_common
  idf:
version: =5.3.0
  mdns: '*'
  espressif/esp_audio_codec: ~2.3.0
  espressif/esp_codec_dev: ~1.3.4
  espressif/esp_audio_effects: ~1.1.0
  sepfy/srtp: ^2.3.0
```

---

**CMake:**

```cmake title="main/CMakeLists.txt"
idf_component_register(SRCS
  "ai-demo.c"
  INCLUDE_DIRS "."
  REQUIRES mbedtls REQUIRES json  REQUIRES esp_netif  REQUIRES fatfs  REQUIRES vfs REQUIRES  esp_common REQUIRES esp_timer  REQUIRES esp_lcd  REQUIRES nvs_flash REQUIRES bt
)

target_compile_options(${COMPONENT_LIB} PRIVATE "-Wno-format")
```

---

**Hardware Config:**

```kconfig title="main/Kconfig.projbuild"
menu "SET Microcontroller"

choice AUDIO_BOARD
prompt "Audio hardware board"
default ESP32S3_XIAO
help
    Select an audio board to use

config ESP32_S3_KORVO_2_V3_0_BOARD
bool "ESP32-S3-Korvo-2"
depends on IDF_TARGET_ESP32S3
config ESP32S3_XIAO
bool "ESP32-S3-XIAO"
endchoice

endmenu
```

---

**Partitions:**

```csv title="partitions.csv"
# ESP-IDF Partition Table
# Name,   Type, SubType, Offset,  Size, Flags
nvs,      data, nvs,     0x9000,  0x6000,
phy_init, data, phy,     0xf000,  0x1000,
factory,  app,  factory, 0x10000, 4M,
```

---

**SDK Config:**

```ini title="sdkconfig.defaults"
# This file was generated using idf.py save-defconfig. It can be edited manually.
# Espressif IoT Development Framework (ESP-IDF) 5.2.2 Project Minimal Configuration
#
CONFIG_IDF_TARGET="esp32s3"
CONFIG_APP_RETRIEVE_LEN_ELF_SHA=16
CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
CONFIG_PARTITION_TABLE_CUSTOM=y
CONFIG_ESP32S3_XIAO_SENSE=y
CONFIG_EXAMPLE_WIFI_SSID="myssid"
CONFIG_EXAMPLE_WIFI_PASSWORD="mypassword"
CONFIG_EXAMPLE_CONNECT_IPV6=n
CONFIG_ESP_PHY_REDUCE_TX_POWER=y
CONFIG_SPIRAM=y
CONFIG_SPIRAM_MODE_OCT=y
CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_240=y
CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE=2048
CONFIG_ESP_MAIN_TASK_STACK_SIZE=4096
CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1=n
CONFIG_ESP_IPC_TASK_STACK_SIZE=2048
CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM=16
CONFIG_ESP_WIFI_STATIC_TX_BUFFER_NUM=32
CONFIG_ESP_WIFI_CACHE_TX_BUFFER_NUM=64
CONFIG_LWIP_IPV6_AUTOCONFIG=y
CONFIG_LWIP_IPV6_DHCP6=y
CONFIG_LWIP_TCP_SND_BUF_DEFAULT=5744
CONFIG_LWIP_TCP_WND_DEFAULT=5744
CONFIG_MBEDTLS_EXTERNAL_MEM_ALLOC=y
CONFIG_MBEDTLS_SSL_PROTO_DTLS=y
CONFIG_PTHREAD_TASK_STACK_SIZE_DEFAULT=8192
```


### Step 3: Implement the Firmware Logic


Update `main/ai-demo.c` with your VideoSDK token and the `roomId` you created.

```c title="main/ai-demo.c"
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <string.h>
#include <sys/param.h>
#include <sys/time.h>
#include "esp_event.h"
#include "esp_log.h"
#include "esp_mac.h"
#include "esp_netif.h"
#include "esp_partition.h"
#include "esp_system.h"
#include "freertos/FreeRTOS.h"
#include "nvs_flash.h"
#include "protocol_examples_common.h"
#include "videosdk.h"

static const char *TAG = "Videosdk";

const char *token = "YOUR_VIDEOSDK_AUTH_TOKEN"; // Replace with your VideoSDK auth token
static void meeting_task(void *pvParameters)
{

    create_meeting_result_t result = create_meeting(token);
    if (result.room_id)
    {
        ESP_LOGI(TAG, "Created meeting roomId = %s", result.room_id);
        free(result.room_id);
    }
    else
    {
        ESP_LOGE(TAG, "Failed to create meeting");
    }

    ESP_LOGI(TAG, "meeting_task finished, deleting self");
    vTaskDelete(NULL);
}

void app_main(void)
{
    static char deviceid[32] = {0};
    uint8_t mac[8] = {0};

    esp_log_level_set("*", ESP_LOG_INFO);
    esp_log_level_set("esp-tls", ESP_LOG_VERBOSE);
    esp_log_level_set("MQTT_CLIENT", ESP_LOG_VERBOSE);
    esp_log_level_set("MQTT_EXAMPLE", ESP_LOG_VERBOSE);
    esp_log_level_set("TRANSPORT_BASE", ESP_LOG_VERBOSE);
    esp_log_level_set("TRANSPORT", ESP_LOG_VERBOSE);
    esp_log_level_set("OUTBOX", ESP_LOG_VERBOSE);

    ESP_ERROR_CHECK(nvs_flash_init());
    ESP_ERROR_CHECK(esp_netif_init());
    ESP_ERROR_CHECK(esp_event_loop_create_default());
    ESP_ERROR_CHECK(example_connect());

    BaseType_t ok = xTaskCreate(meeting_task, "meeting_task", 16384, (void *)token, 5, NULL);
    if (ok != pdPASS)
    {
        ESP_LOGE(TAG, "Failed to create meeting_task");
    }
    init_config_t init_cfg = {
        .meetingID = "YOUR_MEETING_ID", // Replace with your meeting ID
        .token = token,
        .displayName = "ESP32-Device",
        .audioCodec = AUDIO_CODEC_OPUS,
    };

    result_t init_result = init(&init_cfg);
    printf("Result: %d\n", init_result);
    result_t result_publish = startPublishAudio("");
    result_t result_susbcribe = startSubscribeAudio("", NULL);
    printf("Result:%d\n", result_publish);

    while (1)
    {
        vTaskDelay(pdMS_TO_TICKS(10));
    }
}
```



## 2. Python AI Agent

### Step 1: Configure Environment and Credentials


Create a `.env` file in the `IoT-quickstart` directory to store your API keys securely.

```env title=".env"
# Google API Key for Gemini Live API
GOOGLE_API_KEY="your_google_api_key_here"

# VideoSDK Authentication Token
VIDEOSDK_AUTH_TOKEN="your_videosdk_auth_token_here"
```



### Step 2: Create the Python AI Agent


The Python agent joins the same meeting room and uses the Gemini Live API to interact with the user. Update `agent-iot.py` with the `roomId` you created earlier.

```python title="agent-iot.py"
from videosdk.agents import Agent, AgentSession, RealTimePipeline,JobContext, RoomOptions, WorkerJob
from videosdk.plugins.google import GeminiRealtime, GeminiLiveConfig
import logging
logging.getLogger().setLevel(logging.INFO)

class MyVoiceAgent(Agent): 
    def __init__(self):
        super().__init__(
            instructions="You are a high-energy game-show host guiding the caller to guess a secret number from 1 to 100 to win 1,000,000$.",
        )

    async def on_enter(self) -> None:
        await self.session.say("Welcome to the Videosdk's AI Agent game show! I'm your host, and we're about to play for 1,000,000$. Are you ready to play?")
    
    async def on_exit(self) -> None:
        await self.session.say("Goodbye!")

async def start_session(context: JobContext):
    agent = MyVoiceAgent()
    model = GeminiRealtime(
        model="gemini-2.5-flash-native-audio-preview-12-2025",
        # When GOOGLE_API_KEY is set in .env - DON'T pass api_key parameter
        # api_key="AIXXXXXXXXXXXXXXXXXXXX", 
        config=GeminiLiveConfig(
            voice="Leda", # Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus, and Zephyr.
            response_modalities=["AUDIO"]
        )
    )

    pipeline = RealTimePipeline(model=model)
    session = AgentSession(
        agent=agent,
        pipeline=pipeline
    )

    def on_transcription(data: dict):
        role = data.get("role")
        text = data.get("text")
        print(f"[TRANSCRIPT][{role}]: {text}")
    pipeline.on("realtime_model_transcription", on_transcription)

    await context.run_until_shutdown(session=session,wait_for_participant=True)

def make_context() -> JobContext:
    room_options = RoomOptions(
        # Static meeting ID - same as used in IoT
        room_id="YOUR_MEETING_ID", # Replace it with your actual room_id
        name="Gemini Agent",
        playground=True,
    )

    return JobContext(room_options=room_options)

if __name__ == "__main__":
    job = WorkerJob(entrypoint=start_session, jobctx=make_context)
    job.start()
```




## 3. Run the Application

### Step 1: Run the ESP32 Firmware


Configure, build, and flash the firmware onto your ESP32 board.

1.  **Set the target board:**
    ```bash
    idf.py set-target esp32s3
    ```
2.  **Run menuconfig to set WiFi and other board settings:**
    ```bash
    idf.py menuconfig
    ```
    Inside `menuconfig`, navigate to:
    - `Component config` -> `mbedtls` -> Enable `Support DTLS` and `Support TLS`.
    - `Example Connection Configuration` -> Set your `WIFI SSID` and `WIFI Password`.
    - `Partition table` -> Enable `Custom partition table CSV`.
    - `Serial flasher config` -> Adjust the flash size for your board.
    - `Set Microcontroller` -> Select your audio hardware board.

3.  **Build and flash the project:**
    ```bash
    idf.py build
    idf.py flash monitor
    ```



### Step 2: Run the Python AI Agent


Open a new terminal, navigate to the `IoT-quickstart` directory, and run the Python agent.

```bash
# Install Python dependencies
pip install videosdk-agents "videosdk-plugins-google"

# Run the AI agent
python agent-iot.py
```


Once the ESP32 device joins the meeting, the AI agent will detect it and begin the interactive game show.


## Next Steps

Clone repo for quick implementation



- [Quickstart Example](https://github.com/videosdk-live/agents-quickstart/tree/main/IoT-quickstart): Complete working example with source code



---

VideoSDK empowers you to seamlessly integrate AI agents with real-time voice interaction into your JavaScript application within minutes.

In this quickstart, you'll explore how to create an AI agent that joins a meeting room and interacts with users through voice using Google Gemini Live API.

## Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

- Video SDK Developer Account (Not having one, follow **[Video SDK Dashboard](https://app.videosdk.live/)**)
- Node.js and Python 3.12+ installed on your device
- Google API Key with Gemini Live API access

:::important
You need a VideoSDK account to generate a token and a Google API key for the Gemini Live API.
Visit the VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate a token and the **[Google AI Studio](https://aistudio.google.com/api-keys)** for Google API key.
:::

## Project Structure

First, create an empty project using `mkdir folder_name` on your preferable location for the JavaScript Frontend. Your final project structure should look like this:

```jsx title="Project Structure"
  root
   ├── index.html
   ├── config.js
   ├── index.js
   ├── agent-js.py
   └── .env
```

You will be working on the following files:

- `index.html`: Responsible for creating a basic UI for joining the meeting.
- `config.js`: Responsible for storing the token and room ID for the JavaScript frontend.
- `index.js`: Responsible for rendering the meeting view and audio functionality.
- `agent-js.py`: The Python agent using Google Gemini Live API.
- `.env`: Environment variables for the Python agent's API keys.


## 1. Building the JavaScript Frontend

### Step 1: Install VideoSDK


Import VideoSDK using the `<script>` tag or install it using npm/yarn.

**Tab:**

" label="<script>" default>

```html
<html>
  <head>

  </head>
  <body>

<script src="https://sdk.videosdk.live/js-sdk/0.3.6/videosdk.js"></script>
  </body>
</html>
```

---

**npm:**

```bash
npm install @videosdk.live/js-sdk
```

---

**yarn:**

```bash
yarn add @videosdk.live/js-sdk
```


### Step 2: Design the User Interface

Create an `index.html` file containing `join-screen` and `grid-screen` for audio-only interaction.

```html title="index.html"
<!DOCTYPE html>
<html>
<head> </head>
<body>
    <div id="join-screen">
        <button id="createMeetingBtn">Join Agent Meeting</button>
    </div>
    <div id="textDiv"></div>
    <div id="grid-screen" style="display: none">
        <h3 id="meetingIdHeading"></h3>
        <button id="leaveBtn">Leave</button>
        <button id="toggleMicBtn">Toggle Mic</button>
        <div id="audioContainer"></div>
    </div>
    <script src="https://sdk.videosdk.live/js-sdk/0.3.6/videosdk.js"></script>
    <script src="config.js"></script>
    <script src="index.js"></script>
</body>
</html>
```


### Step 3: Configure the Frontend

Create a meeting room using the VideoSDK API:

```bash
curl -X POST https://api.videosdk.live/v2/rooms \
  -H "Authorization: YOUR_JWT_TOKEN_HERE" \
  -H "Content-Type: application/json"
```

Copy the `roomId` from the response and configure it in `config.js` for the JavaScript frontend:

```js title="config.js"
TOKEN = "your_videosdk_auth_token_here";
ROOM_ID = "YOUR_MEETING_ID";  // Static room ID shared between frontend and agent
```


### Step 4: Implement Meeting Logic

In `index.js`, retrieve DOM elements, declare variables, and add the core meeting functionalities.

```js title="index.js"
// getting Elements from Dom
const leaveButton = document.getElementById("leaveBtn");
const toggleMicButton = document.getElementById("toggleMicBtn");
const createButton = document.getElementById("createMeetingBtn");
const audioContainer = document.getElementById("audioContainer");
const textDiv = document.getElementById("textDiv");

// declare Variables
let meeting = null;
let meetingId = "";
let isMicOn = false;

// Join Agent Meeting Button Event Listener
createButton.addEventListener("click", async () => {
  document.getElementById("join-screen").style.display = "none";
  textDiv.textContent = "Please wait, we are joining the meeting";
  meetingId = ROOM_ID;
  initializeMeeting();
});

// Initialize meeting
function initializeMeeting() {
  window.VideoSDK.config(TOKEN);

  meeting = window.VideoSDK.initMeeting({
    meetingId: meetingId,
    name: "C.V.Raman",
    micEnabled: true,
    webcamEnabled: false,
  });

  meeting.join();

  meeting.localParticipant.on("stream-enabled", (stream) => {
    if (stream.kind === "audio") {
      setAudioTrack(stream, meeting.localParticipant, true);
    }
  });

  meeting.on("meeting-joined", () => {
    textDiv.textContent = null;
    document.getElementById("grid-screen").style.display = "block";
    document.getElementById("meetingIdHeading").textContent = `Meeting Id: ${meetingId}`;
  });

  meeting.on("meeting-left", () => {
    audioContainer.innerHTML = "";
  });

  meeting.on("participant-joined", (participant) => {
    let audioElement = createAudioElement(participant.id);
    participant.on("stream-enabled", (stream) => {
      if (stream.kind === "audio") {
        setAudioTrack(stream, participant, false);
        audioContainer.appendChild(audioElement);
      }
    });
  });

  meeting.on("participant-left", (participant) => {
    let aElement = document.getElementById(`a-${participant.id}`);
    if (aElement) aElement.remove();
  });
}

// Create audio elements for participants
function createAudioElement(pId) {
  let audioElement = document.createElement("audio");
  audioElement.setAttribute("autoPlay", "false");
  audioElement.setAttribute("playsInline", "true");
  audioElement.setAttribute("controls", "false");
  audioElement.setAttribute("id", `a-${pId}`);
  audioElement.style.display = "none";
  return audioElement;
}

// Set audio track
function setAudioTrack(stream, participant, isLocal) {
  if (stream.kind === "audio") {
    if (isLocal) {
      isMicOn = true;
    } else {
      const audioElement = document.getElementById(`a-${participant.id}`);
      if (audioElement) {
        const mediaStream = new MediaStream();
        mediaStream.addTrack(stream.track);
        audioElement.srcObject = mediaStream;
        audioElement.play().catch((err) => console.error("audioElem.play() failed", err));
      }
    }
  }
}

// Implement controls
leaveButton.addEventListener("click", async () => {
  meeting?.leave();
  document.getElementById("grid-screen").style.display = "none";
  document.getElementById("join-screen").style.display = "block";
});

toggleMicButton.addEventListener("click", async () => {
  if (isMicOn) meeting?.muteMic();
  else meeting?.unmuteMic();
  isMicOn = !isMicOn;
});
```



## 2. Building the Python Agent

### Step 1: Configure the Agent

Create a `.env` file to store your API keys securely for the Python agent:

```env title=".env"
# Google API Key for Gemini Live API
GOOGLE_API_KEY=your_google_api_key_here

# VideoSDK Authentication Token
VIDEOSDK_AUTH_TOKEN=your_videosdk_auth_token_here
```


### Step 2: Create the Python Agent

Create the Python agent (`agent-js.py`) that will join the same meeting room and interact with users through voice.

```python title="agent-js.py"
from videosdk.agents import Agent, AgentSession, RealTimePipeline, JobContext, RoomOptions, WorkerJob
from videosdk.plugins.google import GeminiRealtime, GeminiLiveConfig
import logging

logging.getLogger().setLevel(logging.INFO)

class MyVoiceAgent(Agent): 
    def __init__(self):
        super().__init__(
            instructions="You are a high-energy game-show host guiding the caller to guess a secret number from 1 to 100 to win 1,000,000$.",
        )

    async def on_enter(self) -> None:
        await self.session.say("Welcome to the Videosdk's AI Agent game show! I'm your host, and we're about to play for 1,000,000$. Are you ready to play?")
    
    async def on_exit(self) -> None:
        await self.session.say("Goodbye!")

async def start_session(context: JobContext):
    agent = MyVoiceAgent()
    model = GeminiRealtime(
        model="gemini-2.5-flash-native-audio-preview-12-2025",
        # When GOOGLE_API_KEY is set in .env - DON'T pass api_key parameter
        # api_key="AIXXXXXXXXXXXXXXXXXXXX", 
        config=GeminiLiveConfig(
            voice="Leda", # Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus, and Zephyr.
            response_modalities=["AUDIO"]
        )
    )

    pipeline = RealTimePipeline(model=model)
    session = AgentSession(agent=agent, pipeline=pipeline)

    def on_transcription(data: dict):
        role = data.get("role")
        text = data.get("text")
        print(f"[TRANSCRIPT][{role}]: {text}")
    pipeline.on("realtime_model_transcription", on_transcription)

    await context.run_until_shutdown(session=session, wait_for_participant=True)

def make_context() -> JobContext:
    room_options = RoomOptions(
        room_id="YOUR_MEETING_ID", # Replace with your actual room_id
        name="Gemini Agent",
        playground=True,
    )
    return JobContext(room_options=room_options)

if __name__ == "__main__":
    job = WorkerJob(entrypoint=start_session, jobctx=make_context)
    job.start()
```


## 3. Run the Application

### Step 1: Start the Frontend

Once you have completed all the steps, serve your frontend files:

```bash
# Using Python's built-in server
python3 -m http.server 8000

# Or using Node.js http-server
npx http-server -p 8000
```

Open `http://localhost:8000` in your web browser.


### Step 2: Start the Python Agent

Open a new terminal and run the Python agent:

```bash
# Install Python dependencies
pip install "videosdk-plugins-google"
pip install videosdk-agents

# Run the Python agent (reads GOOGLE_API_KEY from .env file)
python agent-js.py
```


### Step 3: Connect and Interact

1. **Join the meeting from the frontend:**
   - Click the "Join Agent Meeting" button in your browser.
   - Allow microphone permissions when prompted.

2. **Agent connection:**
   - Once you join, the Python agent will detect your participation.
   - You should see "Participant joined" in the terminal.
   - The AI agent will greet you and initiate the game.

3. **Start playing:**
   - The agent will guide you through a number guessing game (1-100).
   - Use your microphone to interact with the AI host.


## Troubleshooting

### Common Issues:

1. **"Waiting for participant..." but no connection:**
   - Ensure both frontend and the agent are running.
   - Check that the `ROOM_ID` matches in `config.js` and `agent-js.py`.
   - Verify your VideoSDK token is valid.

2. **Audio not working:**
   - Check browser permissions for microphone access.
   - Ensure your Google API key has Gemini Live API access enabled.

3. **Agent not responding:**
   - Verify your `GOOGLE_API_KEY` is set in the `.env` file.
   - Check that the Gemini Live API is enabled in your Google Cloud Console.



## Next Steps

Clone repo for quick implementation



- [Quickstart Example](https://github.com/videosdk-live/agents-quickstart/tree/main/mobile-quickstarts/js): Complete working example with source code



---

VideoSDK empowers you to integrate an AI voice agent into your React Native app (Android/iOS) within minutes. The agent joins the same meeting room and interacts over voice using the Google Gemini Live API.

## Prerequisites

- VideoSDK Developer Account (get token from the [dashboard](https://app.videosdk.live/api-keys))
- Node.js and a working React Native environment (Android Studio and/or Xcode)
- Python 3.12+
- Google API Key with Gemini Live API access

:::important
You need a VideoSDK account to generate a token and a Google API key for the Gemini Live API.
Visit the VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate a token and the **[Google AI Studio](https://aistudio.google.com/api-keys)** for Google API key.
:::

## Project Structure

First, create an empty project using `mkdir folder_name` on your preferable location for the React Native Frontend. Your final project structure should look like this:

```jsx title="Directory Structure"
  root
   ├── android/
   ├── ios/
   ├── App.js
   ├── constants.js
   ├── index.js
   ├── agent-react-native.py
   └── .env
```

You will work on:
- `android/`: Contains the Android-specific project files.
- `ios/`: Contains the iOS-specific project files.
- `App.js`: The main React Native component, containing the UI and meeting logic.
- `constants.js`: To store token and meetingId for the frontend.
- `index.js`: The entry point of the React Native application, where VideoSDK is registered.
- `agent-react-native.py`: The Python agent that joins the meeting.
- `.env`: Environment variables file for the Python agent (stores API keys).

## 1. Building the React Native Frontend

### Step 1: Create App and Install SDKs


Create a React Native app and install the VideoSDK RN SDK:

```bash
npx react-native init videosdkAiAgentRN
cd videosdkAiAgentRN

# Install VideoSDK
npm install "@videosdk.live/react-native-sdk"
```


### Step 2: Configure the Project


#### Android Setup



```xml title="android/app/src/main/AndroidManifest.xml"
<manifest
  xmlns:android="http://schemas.android.com/apk/res/android"
>
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission
        android:name="android.permission.BLUETOOTH"
        android:maxSdkVersion="30" />
    <uses-permission
        android:name="android.permission.BLUETOOTH_ADMIN"
        android:maxSdkVersion="30" />

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

    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />
</manifest>
```





```java title="android/app/build.gradle"
  dependencies {
   implementation project(':rnwebrtc')
  }
```

```gradle title="android/settings.gradle"
include ':rnwebrtc'
project(':rnwebrtc').projectDir = new File(rootProject.projectDir, '../node_modules/@videosdk.live/react-native-webrtc/android')
```

```java title="MainApplication.kt"
import live.videosdk.rnwebrtc.WebRTCModulePackage

class MainApplication : Application(), ReactApplication {
  override val reactNativeHost: ReactNativeHost =
      object : DefaultReactNativeHost(this) {
        override fun getPackages(): List
    </TouchableOpacity>
  );
};

function ControlsContainer({ join, leave, toggleMic }) {
  return (
    
      
      
    </View>
  );
}

function ParticipantView({ participantDisplayName }) {
  return (
    
    </View>
  );
}

function ParticipantList({ participants }) {
  return participants.length > 0 ? (
    ;
      }}
    />
  ) : (
    
    </View>
  );
}

function MeetingView() {
  const { join, leave, toggleMic, participants, meetingId } = useMeeting({});

  const participantsList = [...participants.values()].map(participant => ({
    displayName: participant.displayName,
  }));

  return (
    
      ) : null}
      
      
    </View>
  );
}

export default function App() {
  if (!meetingId || !token) {
    return (
      
        </View>
      </SafeAreaView>
    );
  }

  return (
    
      </MeetingProvider>
    </SafeAreaView>
  );
}
```


## 2. Building the Python Agent

### Step 1: Configure the Agent

Create a `.env` file to store your API keys securely for the Python agent:

```env title=".env"
# Google API Key for Gemini Live API
GOOGLE_API_KEY=your_google_api_key_here

# VideoSDK Authentication Token
VIDEOSDK_AUTH_TOKEN=your_videosdk_auth_token_here
```


### Step 2: Create the Python Agent


```python title="agent-react-native.py"
from videosdk.agents import Agent, AgentSession, RealTimePipeline, JobContext, RoomOptions, WorkerJob
from videosdk.plugins.google import GeminiRealtime, GeminiLiveConfig
import logging

logging.getLogger().setLevel(logging.INFO)

class MyVoiceAgent(Agent): 
    def __init__(self):
        super().__init__(
            instructions="You are a high-energy game-show host guiding the caller to guess a secret number from 1 to 100 to win 1,000,000$.",
        )

    async def on_enter(self) -> None:
        await self.session.say("Welcome to the Videosdk's AI Agent game show! I'm your host, and we're about to play for 1,000,000$. Are you ready to play?")
    
    async def on_exit(self) -> None:
        await self.session.say("Goodbye!")

async def start_session(context: JobContext):
    agent = MyVoiceAgent()
    model = GeminiRealtime(
        model="gemini-2.5-flash-native-audio-preview-12-2025",
        # When GOOGLE_API_KEY is set in .env - DON'T pass api_key parameter
        # api_key="AIXXXXXXXXXXXXXXXXXXXX", 
        config=GeminiLiveConfig(
            voice="Leda", # Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus, and Zephyr.
            response_modalities=["AUDIO"]
        )
    )

    pipeline = RealTimePipeline(model=model)
    session = AgentSession(
        agent=agent,
        pipeline=pipeline
    )

    def on_transcription(data: dict):
        role = data.get("role")
        text = data.get("text")
        print(f"[TRANSCRIPT][{role}]: {text}")
    pipeline.on("realtime_model_transcription", on_transcription)

    await context.run_until_shutdown(session=session, wait_for_participant=True)

def make_context() -> JobContext:
    room_options = RoomOptions(
        # Static meeting ID - same as used in frontend
        room_id="YOUR_MEETING_ID", # Replace it with your actual room_id
        name="Gemini Agent",
        playground=True,
    )

    return JobContext(room_options=room_options)

if __name__ == "__main__":
    job = WorkerJob(entrypoint=start_session, jobctx=make_context)
    job.start()
```


## 3. Run the Application

### 1) Start the React Native app

```bash
npm install

# Android
npm run android

# iOS (macOS only)
cd ios && pod install && cd ..
npm run ios
```

### 2) Start the Python Agent

```bash
pip install videosdk-agents
pip install "videosdk-plugins-google"

python agent-react-native.py
```

### 3) Connect and interact

1. Join the meeting from the app and allow microphone permissions.
2. When you join, the Python agent detects your participation and starts speaking.
3. Talk to the agent in real time and play the number guessing game.

## Troubleshooting

- Ensure the same `room_id` is set in both the RN app (`constants.js`) and the agent's `RoomOptions`.
- Verify microphone and camera permissions on the device/simulator.
- Confirm your VideoSDK token is valid and Google API key is set.
- If audio is silent, check device output volume and that the agent is not in playground mode.


## Next Steps

Clone repo for quick implementation



- [Quickstart Example](https://github.com/videosdk-live/agents-quickstart/tree/main/mobile-quickstarts/react-native): Complete working example with source code



---

VideoSDK empowers you to seamlessly integrate AI agents with real-time voice interaction into your React application within minutes.

In this quickstart, you'll explore how to create an AI agent that joins a meeting room and interacts with users through voice using Google Gemini Live API.

## Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

- Video SDK Developer Account (Not having one, follow **[Video SDK Dashboard](https://app.videosdk.live/)**)
- Node.js and Python 3.12+ installed on your device
- Google API Key with Gemini Live API access

:::important
You need a VideoSDK account to generate a token and a Google API key for the Gemini Live API.
Visit the VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate a token and the **[Google AI Studio](https://aistudio.google.com/api-keys)** for Google API key.
:::

## Project Structure

Your project structure should look like this.

```jsx title="Project Structure"
  root
   ├── node_modules
   ├── public
   ├── src
   │    ├── config.js
   │    ├── App.js
   │    └── index.js
   ├── agent-react.py
   └── .env
```

You will be working on the following files:

- `App.js`: Responsible for creating a basic UI for joining the meeting
- `config.js`: Responsible for storing the token and room ID
- `index.js`: This is the entry point of your React application.
- `agent-react.py`: Python AI agent backend using Google Gemini Live API
- `.env`: Environment variables for API keys

## Part 1: React Frontend

### Step 1: Getting Started with the Code!


#### Create new React App

Create a new React App using the below command.

```bash
$ npx create-react-app videosdk-ai-agent-react-app
```

#### Install VideoSDK

Install the VideoSDK using the below-mentioned npm command. Make sure you are in your react app directory before you run this command.

```bash
$ npm install "@videosdk.live/react-sdk"
```


### Step 2: Configure Environment and Credentials


Create a meeting room using the VideoSDK API:

```bash
curl -X POST https://api.videosdk.live/v2/rooms \
  -H "Authorization: YOUR_JWT_TOKEN_HERE" \
  -H "Content-Type: application/json"
```

Copy the `roomId` from the response and configure it in `src/config.js`:

```js title="src/config.js"
export const TOKEN = "YOUR_VIDEOSDK_AUTH_TOKEN";
export const ROOM_ID = "YOUR_MEETING_ID"; // Create using VideoSDK API (curl -X POST https://api.videosdk.live/v2/rooms)
```


### Step 3: Design the user interface (UI)


Create the main App component with audio-only interaction in `src/App.js`:

```js title="src/App.js"
import React, { useEffect, useRef, useState } from "react";


function ParticipantAudio({ participantId }) {
  const { micStream, micOn, isLocal, displayName } = useParticipant(participantId);
  const audioRef = useRef(null);

  useEffect(() => {
    if (!audioRef.current) return;
    if (micOn && micStream) {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(micStream.track);
      audioRef.current.srcObject = mediaStream;
      audioRef.current.play().catch(() => {});
    } else {
      audioRef.current.srcObject = null;
    }
  }, [micStream, micOn]);

  return (
    <div>
      <p>Participant: {displayName} | Mic: {micOn ? "ON" : "OFF"}</p>
      <audio ref={audioRef} autoPlay muted={isLocal} />
    </div>
  );
}

function Controls() {
  const { leave, toggleMic } = useMeeting();
  return (
    <div>
      <button onClick={() => leave()}>Leave</button>
      <button onClick={() => toggleMic()}>Toggle Mic</button>
    </div>
  );
}

function MeetingView({ meetingId, onMeetingLeave }) {
  const [joined, setJoined] = useState(null);
  const { join, participants } = useMeeting({
    onMeetingJoined: () => setJoined("JOINED"),
    onMeetingLeft: onMeetingLeave,
  });

  const joinMeeting = () => {
    setJoined("JOINING");
    join();
  };

  return (
    <div>
      <h3>Meeting Id: {meetingId}</h3>
      {joined === "JOINED" ? (
        <div>
          
          {[...participants.keys()].map((pid) => (
            
          ))}
        </div>
      ) : joined === "JOINING" ? (
        <p>Joining the meeting...</p>
      ) : (
        <button onClick={joinMeeting}>Join</button>
      )}
    </div>
  );
}

export default function App() {
  const [meetingId] = useState(ROOM_ID);

  const onMeetingLeave = () => {
    // no-op; simple sample
  };

  return (
    }
      </MeetingConsumer>
    </MeetingProvider>
  );
}
```



## Part 2: Python AI Agent



### Step 1: Create AI Agent Backend


Create a `.env` file to store your API keys securely for the Python agent:

```env title=".env"
# Google API Key for Gemini Live API
GOOGLE_API_KEY=your_google_api_key_here

# VideoSDK Authentication Token
VIDEOSDK_AUTH_TOKEN=your_videosdk_auth_token_here
```




Create the Python AI agent that will join the same meeting room and interact with users through voice.

```python title="agent-react.py"
from videosdk.agents import Agent, AgentSession, RealTimePipeline, JobContext, RoomOptions, WorkerJob
from videosdk.plugins.google import GeminiRealtime, GeminiLiveConfig
import logging

logging.getLogger().setLevel(logging.INFO)

class MyVoiceAgent(Agent): 
    def __init__(self):
        super().__init__(
            instructions="You are a high-energy game-show host guiding the caller to guess a secret number from 1 to 100 to win 1,000,000$.",
        )

    async def on_enter(self) -> None:
        await self.session.say("Welcome to the Videosdk's AI Agent game show! I'm your host, and we're about to play for 1,000,000$. Are you ready to play?")
    
    async def on_exit(self) -> None:
        await self.session.say("Goodbye!")

async def start_session(context: JobContext):
    agent = MyVoiceAgent()
    model = GeminiRealtime(
        model="gemini-2.5-flash-native-audio-preview-12-2025",
        # When GOOGLE_API_KEY is set in .env - DON'T pass api_key parameter
        # api_key="AIXXXXXXXXXXXXXXXXXXXX", 
        config=GeminiLiveConfig(
            voice="Leda", # Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus, and Zephyr.
            response_modalities=["AUDIO"]
        )
    )

    pipeline = RealTimePipeline(model=model)
    session = AgentSession(
        agent=agent,
        pipeline=pipeline
    )

    def on_transcription(data: dict):
        role = data.get("role")
        text = data.get("text")
        print(f"[TRANSCRIPT][{role}]: {text}")
    pipeline.on("realtime_model_transcription", on_transcription)

    await context.run_until_shutdown(session=session, wait_for_participant=True)

def make_context() -> JobContext:
    room_options = RoomOptions(
        # Static meeting ID - same as used in frontend
        room_id="YOUR_MEETING_ID", # Replace it with your actual room_id
        name="Gemini Agent",
        playground=True,
    )

    return JobContext(room_options=room_options)

if __name__ == "__main__":
    job = WorkerJob(entrypoint=start_session, jobctx=make_context)
    job.start()
```


## Part 3: Run the Application

### Step 1: Run the Frontend


Once you have completed all the steps mentioned above, start your React application:

```bash
# Install dependencies
npm install

# Start the development server
npm start
```

Open `http://localhost:3000` in your web browser.



### Step 2: Run the AI Agent


Open a new terminal and run the Python agent:

```bash
# Install Python dependencies
pip install "videosdk-plugins-google"
pip install videosdk-agents

# Run the AI agent
python agent-react.py
```



### Step 3: Connect and Interact


1. **Join the meeting from the React app:**
   - Click the "Join" button in your browser
   - Allow microphone permissions when prompted

2. **Agent connection:**
   - Once you join, the Python backend will detect your participation
   - You should see "Participant joined" in the terminal
   - The AI agent will greet and initiate the game

3. **Start playing:**
   - The agent will guide you through a number guessing game (1-100)
   - Use your microphone to interact with the AI host
   - The agent will provide hints and encouragement throughout the game



## Troubleshooting

### Common Issues:

1. **"Waiting for participant..." but no connection:**
   - Ensure both frontend and backend are running
   - Check that the room ID matches in both `src/config.js` and `agent-react.py`
   - Verify your VideoSDK token is valid

2. **Audio not working:**
   - Check browser permissions for microphone access
   - Ensure your Google API key has Gemini Live API access enabled

3. **Agent not responding:**
   - Verify your Google API key is correctly set in the environment
   - Check that the Gemini Live API is enabled in your Google Cloud Console

4. **React build issues:**
   - Ensure Node.js version is compatible
   - Try clearing npm cache: `npm cache clean --force`
   - Delete `node_modules` and reinstall: `rm -rf node_modules && npm install`

## Next Steps

Clone repo for quick implementation



- [Quickstart Example](https://github.com/videosdk-live/agents-quickstart/tree/main/mobile-quickstarts/react): Complete working example with source code



---

This guide demonstrates how to integrate a real-time AI agent with a Unity application. The agent, powered by Google's Gemini Live API, acts as a high-energy game show host, guiding the user through a number-guessing game via voice.

## Prerequisites

Before you begin, ensure you have the following:
- **Unity 2022.3 LTS** or later.
- A **VideoSDK Account** for generating an auth token. If you don't have one, sign up at the [VideoSDK Dashboard](https://app.videosdk.live/).
- **Python 3.12+** for the AI agent.
- A **Google API Key** for the Gemini Live API.

:::important
You need a VideoSDK account to generate a token and a Google API key for the Gemini Live API.
Visit the VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate a token and the **[Google AI Studio](https://aistudio.google.com/api-keys)** for Google API key.
:::

## Project Structure

```
Unity-quickstart/
├── Unity/
│   ├── Assets/
│   │   └── Scripts/
│   │       └── GameManager.cs
│   ├── ProjectSettings/
│   └── Packages/
├── agent-unity.py
└── README.md
```

You will be working with the following files:
- **`Unity/Assets/Scripts/GameManager.cs`**: The main script for the Unity application, handling meeting logic and UI.
- **`agent-unity.py`**: The Python AI agent that joins the meeting.

## 1. Unity Frontend

### Step 1: Install VideoSDK Package


1. Open Unity’s **Package Manager** by selecting from the top bar: Window -> Package Manager.

2. Click the + button in the top left corner and select **Add package from git URL.**

3. Paste the following URL and click Add:

```js
https://github.com/videosdk-live/videosdk-rtc-unity-sdk.git
```

![Install VideoSDK Package](https://assets.videosdk.live/images/Project%20Manager.gif)

4. Add the `com.unity.nuget.newtonsoft-json` package by following the instructions provided [here](https://github.com/applejag/Newtonsoft.Json-for-Unity/wiki/Install-official-via-UPM).



### Step 2: Platform Setup


**Android Setup**

To integrate the VideoSDK into your Android project, follow these steps:

1. Add the following repository configuration to your `settingsTemplate.gradle` file:

```js title="settingsTemplate.gradle"
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        **ARTIFACTORYREPOSITORY**
        google()
        mavenCentral()
        jcenter()
        maven {
            url = uri("https://maven.aliyun.com/repository/jcenter")
        }
        flatDir {
            dirs "${project(':unityLibrary').projectDir}/libs"
        }
    }
}
```

2. Install Android SDK in `mainTemplate.gradle`

```js title="mainTemplate.gradle"
dependencies {
    implementation 'live.videosdk:rtc-android-sdk:0.3.1'
}
```

3. If your project has set `android.useAndroidX=true`, then set `android.enableJetifier=true` in the `gradleTemplate.properties` file to migrate your project to AndroidX and avoid duplicate class conflict.

```js title="gradleTemplate.gradle"
android.enableJetifier = true;
android.useAndroidX = true;
android.suppressUnsupportedCompileSdk = 34;
```

**Setting Up for iOS**

1. **Build for iOS**: In Unity, export the project for iOS.
2. **Open in Xcode**: Navigate to the generated Xcode project and open it.
3. **Configure Frameworks**:
   - Select the **Unity-iPhone** target.
   - Go to the **General** tab.
   - Under **Frameworks, Libraries, and Embedded Content**, add **VideoSDK** and its required frameworks.

![Unity iPhone](https://assets.videosdk.live/images/ios%20setup%201.png)
![Frameworks, Libraries, and Embedded Content](https://assets.videosdk.live/images/ios%20setup%202.png)



### Step 3: Create a Meeting Room


Create a static `roomId` using the VideoSDK API. Both the Unity app and the AI agent will use this ID to connect to the same meeting.

```bash
curl -X POST https://api.videosdk.live/v2/rooms \
  -H "Authorization: YOUR_JWT_TOKEN_HERE" \
  -H "Content-Type: application/json"
```
Replace `YOUR_JWT_TOKEN_HERE` with your VideoSDK auth token. Copy the `roomId` from the response for the next steps.



### Step 4: Configure Unity Project


Update `GameManager.cs` with your VideoSDK auth token and the `roomId` you just created.

```csharp title="Unity/Assets/Scripts/GameManager.cs"
// ... existing code ...
public class GameManager : MonoBehaviour
{
    // ... existing code ...
    private readonly string _token = "YOUR_VIDEOSDK_AUTH_TOKEN";
    private readonly string _staticMeetingId = "YOUR_MEETING_ID";
    // ... existing code ...
}
```



### Step 5: Set Up Platform-Specific Permissions


**For Android:**

Add the following permissions to your `AndroidManifest.xml` file:
```xml title="AndroidManifest.xml"
<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.permission.RECORD_AUDIO"/>
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>
```

**For iOS:**

Ensure your `Info.plist` includes descriptions for camera and microphone usage:
```xml title="Info.plist"
<key>NSCameraUsageDescription</key>
<string>Camera access is required for video calls.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone access is required for audio calls.</string>
```



## 2. Python AI Agent

### Step 1: Configure Environment and Credentials


Create a `.env` file in the `Unity-quickstart` directory to store your API keys.

```env title=".env"
# Google API Key for Gemini Live API
GOOGLE_API_KEY="your_google_api_key_here"

# VideoSDK Authentication Token
VIDEOSDK_AUTH_TOKEN="your_videosdk_auth_token_here"
```



### Step 2: Create the Python AI Agent


The Python agent joins the same meeting room to interact with the user. Update `agent-unity.py` with your `roomId`.

```python title="agent-unity.py"
from videosdk.agents import Agent, AgentSession, RealTimePipeline,JobContext, RoomOptions, WorkerJob
from videosdk.plugins.google import GeminiRealtime, GeminiLiveConfig
import logging
logging.getLogger().setLevel(logging.INFO)

class MyVoiceAgent(Agent): 
    def __init__(self):
        super().__init__(
            instructions="You are a high-energy game-show host guiding the caller to guess a secret number from 1 to 100 to win 1,000,000$.",
        )

    async def on_enter(self) -> None:
        await self.session.say("Welcome to the Videosdk's AI Agent game show! I'm your host, and we're about to play for 1,000,000$. Are you ready to play?")
    
    async def on_exit(self) -> None:
        await self.session.say("Goodbye!")

async def start_session(context: JobContext):
    agent = MyVoiceAgent()
    model = GeminiRealtime(
        model="gemini-2.5-flash-native-audio-preview-12-2025",
        config=GeminiLiveConfig(
            voice="Leda",
            response_modalities=["AUDIO"]
        )
    )

    pipeline = RealTimePipeline(model=model)
    session = AgentSession(
        agent=agent,
        pipeline=pipeline
    )

    def on_transcription(data: dict):
        role = data.get("role")
        text = data.get("text")
        print(f"[TRANSCRIPT][{role}]: {text}")
    pipeline.on("realtime_model_transcription", on_transcription)

    await context.run_until_shutdown(session=session,wait_for_participant=True)

def make_context() -> JobContext:
    room_options = RoomOptions(
        room_id="YOUR_MEETING_ID", # Replace with your actual room_id
        name="Gemini Agent",
        playground=True,
    )

    return JobContext(room_options=room_options)

if __name__ == "__main__":
    job = WorkerJob(entrypoint=start_session, jobctx=make_context)
    job.start()
```



## 3. Run the Application

### Step 1: Run the Python AI Agent


Open a terminal, navigate to the `Unity-quickstart` directory, and run the agent.

```bash
# Install Python dependencies
pip install videosdk-agents "videosdk-plugins-google"

# Run the AI agent
python agent-unity.py
```



### Step 2: Run the Unity Application


1.  Open the `Unity/` project in Unity Hub.
2.  Once the project is loaded, press the **Play** button in the Unity Editor to start the application.
3.  Click the **Join Meeting** button in the app to connect to the session.

Once you join the meeting, the AI agent will greet you and start the game.



- [Quickstart Example](https://github.com/videosdk-live/agents-quickstart/tree/main/Unity-quickstart): Complete working example with source code




---

This guide will walk you through creating a fully functional AI telephony agent using **[VideoSDK Agent SDK](https://github.com/videosdk-live/agents)**. You'll learn how to run the agent locally, connect it to the global telephone network using SIP, and enable it to handle both inbound and outbound phone calls. By the end, you'll have a working AI assistant that you can talk to from any phone.

## The Architecture

Before we dive in, let's look at the high-level architecture. A call from the phone network is directed by a [SIP provider](/telephony/integrations/twilio-sip-integration) (like Twilio) to VideoSDK's telephony infrastructure. A [Routing Rule](/telephony/call-routing/setting-up-routing-rules) then intelligently dispatches the call to your self-hosted AI agent, which processes the audio and responds in real-time.

![Architecture: Connecting a Voice Agent to the Telephony Network](https://strapi.videosdk.live/uploads/inbound_outbound_call_c70708607c.png)

## What You'll Build

We'll create a simple yet powerful project with the following structure:

```
├── main.py                 # The core logic for your AI voice agent
├── requirements.txt        # Python package dependencies
└── .env                    # Your secret credentials
```

## Prerequisites

To get started, you'll need a few things:

- **Python 3.12+**: Ensure you have a modern version of Python installed.
- **VideoSDK Account**: Sign up for a free [VideoSDK account](https://app.videosdk.live/api-keys) to get your `VIDEOSDK_TOKEN`. This token is used to authenticate your agent and manage telephony settings.

## Part 1: Build and Run the AI Agent Locally

First, let's get the AI agent running on your machine.

### Step 1: Set Up Your Project


1.  Create a `.env` file to store your secret keys. Add your credentials:

        **realtime-pipeline:**

```bash title=".env"
    VIDEOSDK_AUTH_TOKEN="your_videosdk_token_here"
    GOOGLE_API_KEY="your_google_api_key_here"
    ```

    > **API Keys** - Get API keys: [Google API Key ↗](https://aistudio.google.com/app/apikey) & Create your [VideoSDK Account ↗](https://app.videosdk.live/api-keys) and follow this guide to [generate videosdk token ](/ai_agents/authentication-and-token)

---

**cascading-pipeline:**

```bash title=".env"
    VIDEOSDK_AUTH_TOKEN="your_videosdk_token_here"
    DEEPGRAM_API_KEY="your_deepgram_api_key_here"
    OPENAI_API_KEY="your_openai_api_key_here"
    ELEVENLABS_API_KEY="your_elevenlabs_api_key_here"
    ```

    > **API Keys** - Get API keys: [Deepgram ↗](https://console.deepgram.com/), [OpenAI ↗](https://platform.openai.com/api-keys), [ElevenLabs ↗](https://elevenlabs.io/app/settings/api-keys) & Create your [VideoSDK Account ↗](https://app.videosdk.live/api-keys) and follow this guide to [generate videosdk token ](/ai_agents/authentication-and-token)

2.  Create a `requirements.txt` file and paste in the necessary dependencies:

        **realtime-pipeline:**

```text title="requirements.txt"
    videosdk-agents==0.0.45
    videosdk-plugins-google==0.0.45
    python-dotenv==1.1.1
    requests==2.31.0
    ```

---

**cascading-pipeline:**

```text title="requirements.txt"
    videosdk-agents[deepgram,openai,elevenlabs,silero,turn_detector]==0.0.45
    python-dotenv==1.1.1
    requests==2.31.0
    ```

        > **Latest Version**: Check the latest [videosdk-agents version on PyPI](https://pypi.org/project/videosdk-agents/) for the most recent release.

3.  Finally, create the `main.py` file. This script defines your agent's personality and handles the connection to VideoSDK.

        **realtime-pipeline:**

```python title="main.py"
    import asyncio
    import traceback
    from videosdk.agents import Agent, AgentSession, RealTimePipeline, JobContext, RoomOptions, WorkerJob, Options
    from videosdk.plugins.google import GeminiRealtime, GeminiLiveConfig
    from dotenv import load_dotenv
    import os
    import logging
    logging.basicConfig(level=logging.INFO)

    load_dotenv()

    # Define the agent's behavior and personality
    class MyVoiceAgent(Agent):
        def __init__(self):
            super().__init__(
                instructions="You are a helpful AI assistant that answers phone calls. Keep your responses concise and friendly.",
            )

        async def on_enter(self) -> None:
            await self.session.say("Hello! I'm your real-time assistant. How can I help you today?")

        async def on_exit(self) -> None:
            await self.session.say("Goodbye! It was great talking with you!")

    async def start_session(context: JobContext):
        # Configure the Gemini model for real-time voice
        model = GeminiRealtime(
            model="gemini-2.5-flash-native-audio-preview-12-2025",
            api_key=os.getenv("GOOGLE_API_KEY"),
            config=GeminiLiveConfig(
                voice="Leda",
                response_modalities=["AUDIO"]
            )
        )
        pipeline = RealTimePipeline(model=model)
        session = AgentSession(agent=MyVoiceAgent(), pipeline=pipeline)

        try:
            await context.connect()
            await session.start()
            await asyncio.Event().wait()
        finally:
            await session.close()
            await context.shutdown()

    def make_context() -> JobContext:
        room_options = RoomOptions()
        return JobContext(room_options=room_options)

    if __name__ == "__main__":
        try:
            # Register the agent with a unique ID
            options = Options(
                agent_id="MyTelephonyAgent",  # CRITICAL: Unique identifier for routing
                register=True,               # REQUIRED: Register with VideoSDK for telephony
                max_processes=10,            # Concurrent calls to handle
                host="localhost",
                port=8081,
                )            
            job = WorkerJob(entrypoint=start_session, jobctx=make_context, options=options)
            job.start()
        except Exception as e:
            traceback.print_exc()
    ```

---

**cascading-pipeline:**

```python title="main.py"
    import asyncio
    import traceback
    from videosdk.agents import Agent, AgentSession, CascadingPipeline, JobContext, RoomOptions, WorkerJob, Options, ConversationFlow
    from videosdk.plugins.silero import SileroVAD
    from videosdk.plugins.turn_detector import TurnDetector, pre_download_model
    from videosdk.plugins.deepgram import DeepgramSTT
    from videosdk.plugins.openai import OpenAILLM
    from videosdk.plugins.elevenlabs import ElevenLabsTTS
    from dotenv import load_dotenv
    import os
    import logging
    logging.basicConfig(level=logging.INFO)

    load_dotenv()

    # Pre-downloading the Turn Detector model
    pre_download_model()

    # Define the agent's behavior and personality
    class MyVoiceAgent(Agent):
        def __init__(self):
            super().__init__(
                instructions="You are a helpful AI assistant that answers phone calls. Keep your responses concise and friendly.",
            )

        async def on_enter(self) -> None:
            await self.session.say("Hello! I'm your AI telephony assistant. How can I help you today?")

        async def on_exit(self) -> None:
            await self.session.say("Goodbye! It was great talking with you!")

    async def start_session(context: JobContext):
        # Create agent and conversation flow
        agent = MyVoiceAgent()
        conversation_flow = ConversationFlow(agent)

        # Create pipeline
        pipeline = CascadingPipeline(
            stt=DeepgramSTT(model="nova-2", language="en"),
            llm=OpenAILLM(model="gpt-4o"),
            tts=ElevenLabsTTS(model="eleven_flash_v2_5"),
            vad=SileroVAD(threshold=0.35),
            turn_detector=TurnDetector(threshold=0.8)
        )

        session = AgentSession(
            agent=agent,
            pipeline=pipeline,
            conversation_flow=conversation_flow
        )

        try:
            await context.connect()
            await session.start()
            await asyncio.Event().wait()
        finally:
            await session.close()
            await context.shutdown()
    def make_context() -> JobContext:
        room_options = RoomOptions()
        return JobContext(room_options=room_options)

    if __name__ == "__main__":
        try:
            # Register the agent with a unique ID
            options = Options(
                agent_id="MyTelephonyAgent",  # CRITICAL: Unique identifier for routing
                register=True,               # REQUIRED: Register with VideoSDK for telephony
                max_processes=10,            # Concurrent calls to handle
                host="localhost",
                port=8081,
                )
            job = WorkerJob(entrypoint=start_session, jobctx=make_context, options=options)
            job.start()
        except Exception as e:
            traceback.print_exc()
    ```



### Step 2: Set Up Your Environment and Install Dependencies


Create and activate a virtual environment to keep your project dependencies isolated.

```bash
# Create the virtual environment
python3 -m venv .venv

# Activate it (macOS/Linux)
source .venv/bin/activate
# On Windows, use: .venv\Scripts\activate

# Install the required packages
pip install -r requirements.txt
```



### Step 3: Run the Agent


Now, start your agent by running the Python script.

```bash
python main.py
```

Your terminal will show that the agent is running and has registered itself with VideoSDK using the ID `MyTelephonyAgent`. This ID is crucial for routing calls to it later.

![Running AI Agent Locally](https://strapi.videosdk.live/uploads/run_local_agent_327c1b161c.gif)

**Important:** Keep this terminal window open. Your agent must remain running to accept connections.



## Part 2: Connect Your Agent to the Phone Network

With your agent running locally, it's time to connect it to the outside world. This involves setting up [gateways and routing rules](/telephony/introduction) in your VideoSDK dashboard.

### Step 1: Configure an Inbound Gateway


An **[Inbound Gateway](/telephony/managing-calls/receiving-inbound-calls)** is the entry point for calls coming into VideoSDK.

**dashboard:**

- Navigate to **Telephony > Inbound Gateways** in the [VideoSDK Dashboard](https://app.videosdk.live/telephony/inbound-gateways) and click **Add**.
- Give your gateway a name and enter the phone number you purchased from your SIP provider (e.g., Twilio, Vonage, Telnyx, Plivo, Exotel).
- After creating it, copy the **Inbound Gateway URL**.
- In your SIP provider's dashboard, paste this URL into the **Origination SIP URI** field for your phone number. This tells your provider to forward all incoming calls to VideoSDK.

<div style={{ textAlign: "center" }}>
  
</div>

---

**api:**

```bash
curl --request POST \
  --url https://api.videosdk.live/v2/sip/inbound-gateways \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
"name": "My Inbound Gateway",
"numbers": ["+1234567890"]
  }'
```

> **API Reference**: [Create Inbound Gateway](/api-reference/realtime-communication/sip/inbound-gateway/create-inbound-gateway)



### Step 2: Configure an Outbound Gateway


An **[Outbound Gateway](/telephony/managing-calls/making-outbound-calls)** is the exit point for calls your agent makes to the phone network.

**dashboard:**

- Go to **Telephony > Outbound Gateways** in the dashboard and click **Add**.
- Give it a name and paste the **Termination SIP URI** and credentials from your SIP provider into the required fields.


<div style={{ textAlign: "center" }}>
  
</div>

---

**api:**

```bash
curl --request POST \
  --url https://api.videosdk.live/v2/sip/outbound-gateways \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
"name": "My Outbound Gateway",
"numbers": ["+12065551234"],
"address": "sip.myprovider.com",
"transport": "udp",
"auth": {
  "username": "your-username",
  "password": "your-password"
}
  }'
```

> **API Reference**: [Create Outbound Gateway](/api-reference/realtime-communication/sip/outbound-gateway/create-outbound-gateway)



### Step 3: Create a Routing Rule


A **[Routing Rule](/telephony/call-routing/setting-up-routing-rules)** acts as a switchboard, connecting your gateways to your agent. This is where the magic happens.

**dashboard:**

- Go to **Telephony > Routing Rules** and click **Add**.
- Configure the rule:
  - **Gateway**: Select the Inbound Gateway you just created.
  - **Numbers**: Add the phone number associated with the gateway.
  - **Dispatch**: Choose **Agent**.
  - **Agent Type**: Set to `Self Hosted`.
  - **Agent ID**: Enter `MyTelephonyAgent`. This **must match** the `agent_id` in your `main.py` file.
- Click **Create** to save the rule.

![Setting Up Routing Rules for an AI Agent](https://assets.videosdk.live/images/routing-rules.gif)

---

**api:**

```bash
curl --request POST \
  --url https://api.videosdk.live/v2/sip/routing-rules \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
"gatewayId": "gateway_in_123456789",
"name": "Support Line Rule",
"numbers": ["+1234567890"],
"dispatch": "agent",
"agentType": "self_hosted",
"agentId": "MyTelephonyAgent"
  }'
```

> **API Reference**: [Create Routing Rule](/api-reference/realtime-communication/sip/routing-rules/create-routing-rule) 


You have now successfully instructed VideoSDK to route all inbound calls from your phone number directly to your running Python agent.

## Part 3: Time to Talk! Make and Receive Calls

Your setup is complete! Let's test it out.

:::tip **Keep Your Agent Running**

Make sure your AI agent is running locally before configuring the telephony settings. The agent must be active to receive incoming calls.

:::

### Making an Inbound Call

- Using any phone, dial the SIP number you configured.
- Your local Python agent will automatically answer.
- You'll hear the greeting: "Hello! I'm your real-time assistant. How can I help you today?"
- Start talking! The agent will listen and respond in real-time.

### Making an Outbound Call

You can trigger an outbound call from your agent using a simple API request.

Use `curl` or any API client to make a `POST` request to the VideoSDK API. Replace `YOUR_VIDEOSDK_TOKEN` and the `gatewayId` with your own.

```bash
curl --request POST \
  --url https://api.videosdk.live/v2/sip/call \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "gatewayId": "gw_123456789",
    "sipCallTo": "+14155550123"
  }'
```

This will command your `MyTelephonyAgent` to dial the specified number and start a conversation.

:::tip **Geographic Optimization**

For optimal performance, run your agent in the same geographic region as your SIP provider (e.g., US East for Twilio, US West for Telnyx, Europe for Plivo). This reduces latency and improves call quality.

:::

## Next Steps

Congratulations! You've built and deployed a sophisticated AI telephony agent. You've seen how to run it locally and connect it to the global phone network for both inbound and outbound communication.

- [Deploy Your Agent](/ai_agents/deployments/introduction): Learn how to deploy your AI agent to production
- [Explore Telephony Docs](/telephony/introduction): Comprehensive telephony documentation and guides
- [Provider Integrations](/telephony/integrations/twilio-sip-integration): SIP provider setup guides (Twilio, Vonage, etc.)




---

# Why we are using JWT based Token ?

Token based authentication allows users to verify their identity by providing generated API key and secret.

We use JWT token for the authentication purpose because Token-based authentication is **widely used** in modern web applications and APIs because it offers several benefits over traditional authentication. For example, it can **reduce the risk of the credentials being misused**, and it allows for **more fine-grained control** over access to resources. Additionally, tokens can be easily revoked or expired, making it easier to manage access rights.

## How to generate Token ?

To manage secured communication, every participant that connects to the meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key` which you can get from [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

### 1. Generating token from Dashboard

If you are looking to do **testing or for development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for getting token includes generating it from your backend server which will help in **keeping your credentials safe**.
:::

### 2. Generating token in your backend

- Your server will generate access token using your API key and secret.
  - While generating a token, you can provide **expiration time, permissions and roles** which are discussed later in this section.
- Your client obtains token from your backend server.
- For token validation, client will pass this token to VideoSDK server.
- VideoSDK server will only allow entry in the meeting if the token is valid.

![img2.png](/img/authentication-and-token.png)




Follow our official example repositories to setup token API [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)

### Payload while generating token

For AI Agent authentication, the payload is simplified to include only the essential parameters:

```js
{
 apikey: API_KEY, //MANDATORY
 permissions: [`allow_join`], //MANDATORY
}
```

- **`apikey`(Mandatory)**: This must be the API Key generated from the VideoSDK Dashboard. You can get it from [here](https://app.videosdk.live/api-keys).

- **`permissions`(Mandatory)**: For AI agents, typically use `allow_join` to enable the agent to join meetings directly.

  Available permissions for AI agents:

  - **`allow_join`**: The AI agent is **allowed to join** the meeting directly.
  - **`ask_join`**: The AI agent is required to **ask for permission to join** the meeting.

Then, you have to sign this payload with your **`SECRET KEY`** and `jwt` options using the **`HS256 algorithm`**.

### Expiration time

You can set any expiration time to the token. But in the **production environment**, it is recommended to generate a token with **short expiration time** because by any chance if someone gets hold of the token, it won't be valid for a longer period of time.

### What happens if token is expired?

If your token is expired, the user won't be able to join the meeting and all the API calls will give error with message `Token is invalid or expired`.

:::note
Token is validated only once while joining the meeting, so if a person joins the meeting and the token gets expired after that, there won't be any issue in the current meeting.
:::

## How to check validity of token?

1. After generating the token, visit [jwt.io](https://jwt.io) and paste your token in the given area.
2. You will be able to see the payload you passed while generating the token and also be able to see the expiration time and token creation time.

![img1.png](/img/validate-token.png)

## API Settings & Controls

The VideoSDK Dashboard provides a powerful [API Settings](https://app.videosdk.live/api-keys) section where you can configure various services and controls for your meetings. These settings allow you to customize the behavior of different features directly from the dashboard without requiring code changes.

## Audio/Video Configurations

:::note
Runtime configuration from the dashboard has higher precedence than static SDK configurations.
If a value is modified in the dashboard, it will override any previously defined SDK settings for that session.

Example:
Code: Video = HD → Dashboard: Video = Full HD → Applied: Full HD
:::

### Maximum Send Bitrate Per Participant

Control the maximum total upload bandwidth for all media streams from a single participant.

![Maximum Send Bitrate](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.00.11%E2%80%AFPM.png)

**Available Options:**
- **Auto**: Removes the upload bitrate limit (recommended for best quality)
- **SD (800kbps)**: Standard definition bitrate
- **HD (1500kbps)**: High definition bitrate
- **Full HD (3000kbps)**: Full high definition bitrate

:::tip
Setting this to **Auto** provides the best video quality as it removes upload bitrate constraints, allowing adaptive streaming based on network conditions.
:::

## Recording & Streaming Configuration

:::note
Recording and HLS follow a precedence-based configuration model:

API/SDK configuration → Highest priority
Dashboard configuration → Used only when no API values are defined

Any parameters explicitly set via the API will not be overridden by dashboard changes.
:::

### Recording Configuration

Configure recording settings for your meetings including layout, quality, and auto-start options.

![Recording Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.01.00%E2%80%AFPM.png)

**Recording Controls:**
- **Enabled**: Toggle to enable/disable recording functionality
- **Enabled Modes**: Choose between Video & Audio or Audio Only recording
- **Start Recording Automatically**: Auto-start recording when meeting begins
- **Layout Style**: Select Grid layout for recording composition
- **Maximum Tiles In Grid**: Set the number of participants visible in grid (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme for recordings
- **Video Orientation**: Choose between Landscape or Portrait mode
- **Recording Quality**: Select quality level (e.g., HD Medium)
- **Recording Mode**: Choose between Video & Audio or Audio Only

### HLS Streaming Configuration

Configure HTTP Live Streaming (HLS) settings for broadcasting your meetings.

![HLS Streaming Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.02.18%E2%80%AFPM.png)

**HLS Streaming Controls:**
- **Enabled**: Toggle to enable/disable HLS streaming
- **Enabled Modes**: Choose between Video & Audio or Audio Only streaming
- **Auto Start HLS**: Automatically start HLS when meeting begins
- **Record HLS Stream**: Enable recording of the HLS stream
- **Layout Style**: Select Grid layout for stream composition
- **Maximum Tiles In Grid**: Set the number of participants visible (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme
- **HLS Orientation**: Choose between Landscape or Portrait mode
- **HLS Quality**: Select streaming quality (e.g., HD Medium)
- **HLS Streaming Mode**: Choose between Video & Audio or Audio Only

### Additional Service Controls

Enable or disable additional services for your API key.

![Service Controls](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.08%E2%80%AFPM.png)

**Available Services:**
- **RTMP Output**: Enable RTMP streaming to external platforms
- **SIP Integration**: Enable SIP (Session Initiation Protocol) integration for telephony
- **Realtime Translation**: Enable real-time language translation in meetings

### Transcription & Summary

Configure transcription and domain whitelisting for your API key.

![Transcription Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.50%E2%80%AFPM.png)

**Transcription Controls:**
- **Enabled**: Toggle to enable/disable transcription and summary features
- **Whitelist Domain**: Add domain restrictions for API key usage
  - Enter domain names in the format `https://domain.name`
  - Click "Add Domain" to whitelist specific domains
  - Only whitelisted domains can use this API key
  - When no domains are whitelisted, the API key can be used from any domain


---

# Console Mode for AI Agents

Console mode allows you to interact with your AI agent directly through the terminal without joining a VideoSDK meeting room. This is particularly useful for:

- Quick testing of agent functionality
- Local development and debugging
- Testing function tools and MCP integrations
- Validating pipeline configurations

## How It Works

When running your agent script in console mode:
1. The agent runs in a terminal-based environment
2. Your microphone input is captured directly through the terminal
3. Agent responses are played through your system audio
4.Run the full `Cascading Pipeline` and `RealTime Pipeline` locally without connecting to a meeting. This makes it easier to verify that audio flows, agent logic, and response generation are working correctly before deploying into a live session.
1. Function tools, MCP integrations, and other features remain fully functional

## Using Console Mode

To use console mode, simply add the `console` argument when running your agent script:

```bash
python main.py console
```


<div style={{textAlign: 'center'}}>



</div>

The console will display:
- Agent speech output
- User speech input
- Various latency metrics (STT, TTS, LLM,EOU)
- Pipeline processing information

This flexibility allows you to use the same agent code for both development and production environments.


---

# Agent Session

The `AgentSession` is the central orchestrator that integrates the `Agent`, `Pipeline`, and optional `ConversationFlow` into a cohesive workflow. It manages the complete lifecycle of an agent's interaction within a VideoSDK meeting, handling initialization, execution, and cleanup.

![Agent Session](https://cdn.videosdk.live/website-resources/docs-resources/build_agent_section_agent_session.png)

## Core Features

- **Component Orchestration:** Unifies agent, pipeline, and conversation flow components.
- **Lifecycle Management:** Handles session start, execution, and cleanup
  
## State Management  
  
The `AgentSession` provides comprehensive state tracking for both users and agents, automatically emitting state change events for real-time monitoring.  

:::tip Version Requirement  
The state management features and enhanced methods (`reply()`, `interrupt()`) are available in versions above v0.0.35.  
:::  
    
### User States  
  
- **IDLE** - User is not actively speaking or listening  
- **SPEAKING** - User is currently speaking    
- **LISTENING** - User is actively listening to the agent  
  
### Agent States  
  
- **STARTING** - Agent is initializing  
- **IDLE** - Agent is ready and waiting  
- **SPEAKING** - Agent is currently generating speech  
- **LISTENING** - Agent is processing user input  
- **THINKING** - Agent is processing and generating response  
- **CLOSING** - Agent is shutting down  
  
### State Event Monitoring  
  
State changes are automatically emitted as events that you can listen to:  
  
```python title="main.py"  
def on_user_state_changed(data):  
    print("User state:", data)  
  
def on_agent_state_changed(data):  
    print("Agent state:", data)  
  
session.on("user_state_changed", on_user_state_changed)  
session.on("agent_state_changed", on_agent_state_changed)
```

## Constructor Parameters

```python
AgentSession(
    agent: Agent,
    pipeline: Pipeline,
    conversation_flow: Optional[ConversationFlow] = None,
    wake_up: Optional[int] = None
)
```



- [Agent](/ai_agents/core-components/agent): Your custom agent implementation
- [Pipeline](/ai_agents/core-components/conversation-flow): Optional conversation state management
  


### Wake-Up Call

Wake-up call automatically triggers actions when users are inactive for a specified period of time, helping maintain engagement.

```python title="main.py"
# Configure wake-up timer  
session = AgentSession(  
    agent=MyAgent(),  
    pipeline=pipeline,  
    wake_up=10  # Trigger after 10 seconds of inactivity  
)  
  
# Set callback function  
async def on_wake_up():  
    await session.say("Are you still there? How can I help?")  
  
session.on_wake_up = on_wake_up
```

:::note
Important: If a `wake_up` time is provided, you must set a callback function before starting the session. If no `wake_up` time is specified, no timer or callback will be activated.
:::


## Basic Usage

To get an agent running, you initialize an `AgentSession` with your custom
`Agent` and a configured `Pipeline`. The session handles the underlying
connection and data flow.

### Example Implementation:



**Real-time Pipeline:**

```python title="main.py"
from videosdk.agents import AgentSession, Agent, WorkerJob, JobContext, RoomOptions
from videosdk.plugins.openai import OpenAIRealtime
from videosdk.agents import RealTimePipeline

class MyAgent(Agent):  
def __init__(self):  
    super().__init__(instructions="You are a helpful meeting assistant.")  
  
async def on_enter(self):  
    await self.session.say("Hello! How can I help you today?")  
  
def setup_state_monitoring(self):  
    def on_user_state_changed(data):  
        print(f"User state changed to: {data['state']}")  
      
    def on_agent_state_changed(data):  
        print(f"Agent state changed to: {data['state']}")  
      
    self.session.on("user_state_changed", on_user_state_changed)  
    self.session.on("agent_state_changed", on_agent_state_changed)

async def start_session(ctx: JobContext):
model = OpenAIRealtime(model="gpt-4o-realtime-preview")
pipeline = RealTimePipeline(model=model)

session = AgentSession(
    agent=MyAgent(),
    pipeline=pipeline
)

await ctx.connect()
await session.start()
# Session runs until manually stopped or meeting ends

def make_context():
return JobContext(
    room_options=RoomOptions(
        room_id="your-room-id",
        auth_token="your-auth-token",
        name="Assistant Bot"
    )
)

if __name__ == "__main__":
job = WorkerJob(entrypoint=start_session, jobctx=make_context)
job.start()
```

---

**Cascading Pipeline:**

```python title="main.py"
from videosdk.agents import AgentSession, Agent, WorkerJob, JobContext, RoomOptions
from videosdk.plugins.openai import OpenAISTT, OpenAITTS, OpenAILLM
from videosdk.agents import CascadingPipeline

class MyAgent(Agent):  
def __init__(self):  
    super().__init__(instructions="You are a helpful meeting assistant.")  
  
async def on_enter(self):  
    await self.session.say("Hello! How can I help you today?")  
  
def setup_state_monitoring(self):  
    def on_user_state_changed(data):  
        print(f"User state changed to: {data['state']}")  
      
    def on_agent_state_changed(data):  
        print(f"Agent state changed to: {data['state']}")  
      
    self.session.on("user_state_changed", on_user_state_changed)  
    self.session.on("agent_state_changed", on_agent_state_changed)

async def start_session(ctx: JobContext):
# Configure individual components
stt = OpenAISTT(model="whisper-1")
llm = OpenAILLM(model="gpt-4")
tts = OpenAITTS(model="tts-1", voice="alloy")

pipeline = CascadingPipeline(
    stt=stt,
    llm=llm,
    tts=tts
)

session = AgentSession(
    agent=MyAgent(),
    pipeline=pipeline
)

await ctx.connect()
await session.start()
# Session runs until manually stopped or meeting ends

def make_context():
return JobContext(
    room_options=RoomOptions(
        room_id="your-room-id",
        auth_token="your-auth-token",
        name="Assistant Bot"
    )
)

if __name__ == "__main__":
job = WorkerJob(entrypoint=start_session, jobctx=make_context)
job.start()
```


## Development and Testing Features  
  
The `AgentSession` supports several modes for development, testing, and user engagement:  
  
### Playground Mode  

Playground mode provides a web-based interface for testing your agent without building a separate client application.  

#### Usage

To activate playground mode, simply set `playground: True` in your RoomOptions for JobContext.


```python title="main.py"
from videosdk.agents import RoomOptions, JobContext, WorkerJob

async def entrypoint(ctx: JobContext):
    # Your agent implementation here
    # This is where you create your pipeline, agent, and session
    pass

def make_context() -> JobContext:
    room_options = RoomOptions(
        room_id="<meeting_id>", 
        name="Test Agent", 
        playground=True  # Enable playground mode
    )
    
    return JobContext(room_options=room_options)

if __name__ == "__main__":
    from videosdk.agents import WorkerJob
    job = WorkerJob(entrypoint=entrypoint, jobctx=make_context)
    job.start()
```

When enabled, the playground URL is automatically displayed in your terminal for easy access.

:::note
Note: Playground mode is designed for development and testing purposes. For production deployments, ensure playground mode is disabled to maintain security and performance.
:::

### Console Mode

Console mode allows you to test your agent directly in the terminal using your microphone and speakers, without joining a VideoSDK meeting.

#### Usage

To use console mode, simply add the console argument when running your agent script:

```bash
python main.py console
```


<div style={{textAlign: 'center'}}>



</div>

The console will display:
- Agent speech output
- User speech input
- Various latency metrics (STT, TTS, LLM,EOU)
- Pipeline processing information

This flexibility allows you to use the same agent code for both development and production environments.



## Session Lifecycle Management

The `AgentSession` provides methods to control the agent's presence and behavior in the meeting.

- [start(**kwargs)](https://docs.videosdk.live/agent-sdk-reference/agents/agent_session#:~:text=to%20the%20agent.-,async%20def%20start,self%2C%20**kwargs%3A%C2%A0Any)%20%E2%80%91%3E%C2%A0None,-EXPAND%20SOURCE%20CODE): Initializes and starts the agent session. Sets up MCP tools, metrics collection, pipeline, and calls agent's on_enter() hook.
- [say(message: str)](https://docs.videosdk.live/agent-sdk-reference/agents/agent_session#:~:text=the%20agent%20session.-,async%20def%20say,self%2C%20message%3A%C2%A0str)%20%E2%80%91%3E%C2%A0None,-EXPAND%20SOURCE%20CODE): Sends a message from the agent to the meeting participants. Allows the agent to communicate with users in the meeting.
- [close()](https://docs.videosdk.live/agent-sdk-reference/agents/agent_session#:~:text=Methods-,async%20def%20close,self)%20%E2%80%91%3E%C2%A0None,-EXPAND%20SOURCE%20CODE): Gracefully shuts down the session. Finalizes metrics collection, cancels wake-up timer, and calls agent's on_exit() hook.
- [leave()](https://docs.videosdk.live/agent-sdk-reference/agents/agent_session#:~:text=the%20agent%20session.-,async%20def%20leave,self)%20%E2%80%91%3E%C2%A0None,-EXPAND%20SOURCE%20CODE): Leaves the meeting without full session cleanup. Provides a quick exit option while maintaining session state.
- [reply(instructions, wait_for_playback)](https://docs.videosdk.live/agent-sdk-reference/agents/agent_session#:~:text=the%20agent%20session.-,async%20def%20reply,self%2C%20instructions%3A%C2%A0str%2C%20wait_for_playback%3A%C2%A0bool%C2%A0%3D%C2%A0True)%20%E2%80%91%3E%C2%A0None,-EXPAND%20SOURCE%20CODE): Generate agent responses using instructions and current chat context. Includes playback control and prevents concurrent calls.
- [interrupt()](https://docs.videosdk.live/agent-sdk-reference/agents/agent_session#:~:text=the%20agent%20session.-,async%20def%20interrupt,self)%20%E2%80%91%3E%C2%A0None,-EXPAND%20SOURCE%20CODE): Immediately interrupt the agent's current operation, stopping speech generation and LLM processing for emergency stops or user interruptions.


### Example of Managing the Lifecycle:

```python title="main.py"
import asyncio
from videosdk.agents import AgentSession, Agent, WorkerJob, JobContext, RoomOptions
from videosdk.plugins.openai import OpenAIRealtime
from videosdk.agents import RealTimePipeline

class MyAgent(Agent):
    def __init__(self):
        super().__init__(instructions="You are a helpful meeting assistant.")

    # LIFECYCLE: Agent entry point - called when session starts
    async def on_enter(self):
        await self.session.say("Hello! How can I help you today?")

    # LIFECYCLE: Agent exit point - called when session ends
    async def on_exit(self):
        print("Agent is leaving the session")

    @function_tool  
    async def provide_summary(self) -> str:  
        """Provide a conversation summary using the new reply method"""  
        await self.session.reply("Let me summarize our conversation so far...")  
        return "Summary provided"  
      
    @function_tool    
    async def stop_speaking(self) -> str:  
        """Emergency stop functionality"""  
        await self.session.interrupt()  
        return "Agent stopped successfully"

async def run_agent_session(ctx: JobContext):
    # LIFECYCLE STAGE 1: Session Creation
    model = OpenAIRealtime(model="gpt-4o-realtime-preview")
    pipeline = RealTimePipeline(model=model)

    session = AgentSession(agent=MyAgent(), pipeline=pipeline)

    try:
        # LIFECYCLE STAGE 2: Connection Establishment
        await ctx.connect()

        # LIFECYCLE STAGE 3: Session Start
        await session.start()

        # LIFECYCLE STAGE 4: Session Running
        await asyncio.Event().wait()

    finally:
        # LIFECYCLE STAGE 5: Session Cleanup
        await session.close()

        # LIFECYCLE STAGE 6: Context Shutdown
        await ctx.shutdown()

# LIFECYCLE STAGE 0: Context Creation
def make_context() -> JobContext:
    room_options = RoomOptions(room_id="your-room-id", auth_token="your-token")
    return JobContext(room_options=room_options)

if __name__ == "__main__":
    # LIFECYCLE ORCHESTRATION: Worker Job Management
    # Creates and starts the worker job that manages the entire lifecycle
    job = WorkerJob(entrypoint=run_agent_session, jobctx=make_context)
    job.start()
```

## Examples - Try Out Yourself

We have examples to get you started. Go ahead, try out, talk to agent, understand and customize according to your needs.

- [Wakeup call Example](https://github.com/videosdk-live/agents/blob/main/examples/wakeup_call.py): Agent Session with wakeup call
- [Agent to agent Example](https://github.com/videosdk-live/agents/tree/main/examples/a2a): Agent Session with Customer and Loan agent







---

# Agent

The `Agent` class is the base class for defining AI agent behavior and capabilities. It provides the foundation for creating intelligent conversational agents with support for function tools, MCP servers, and advanced lifecycle management.

![Agent](https://cdn.videosdk.live/website-resources/docs-resources/build_agent_section_agent.png)

## Basic Usage

### Simple Agent

This is how you can initialize a simple agent with the `Agent` class, where `instructions` defines how the agent should behave.

```python title="main.py"
from videosdk.agents import Agent

class MyAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are a helpful assistant."
        )
```

## Agent with Function Tools

Function tools allow your agent to perform actions and interact with external services, extending its capabilities beyond simple conversation. You can register tools that are defined either outside or inside your agent class.

### External Tools

External tools are defined as standalone functions and are passed into the agent's constructor via the tools list. This is useful for sharing common tools across multiple agents.

```python title="main.py"
from videosdk.agents import Agent, function_tool

# External tool defined outside the class
@function_tool(description="Get weather information")
def get_weather(location: str) -> str:
    """Get weather information for a specific location."""
    # Weather logic here
    return f"Weather in {location}: Sunny, 72°F"

class WeatherAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are a weather assistant.",
            tools=[get_weather]  # Register the external tool
        )
```

### Internal Tools

Internal tools are defined as methods within your agent class and are decorated with `@function_tool`. This is useful for logic that is specific to the agent and needs access to its internal state (`self`).

```python title="main.py"
from videosdk.agents import Agent, function_tool

class FinanceAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are a helpful financial assistant."
        )
        self.portfolio = {"AAPL": 10, "GOOG": 5}

    @function_tool
    def get_portfolio_value(self) -> dict:
        """Get the current value of the user's stock portfolio."""
        # In a real scenario, you'd fetch live stock prices
        # This is a simplified example
        return {"total_value": 5000, "holdings": self.portfolio}
```

## Agent with MCP Server

`MCPServerStdio` enables your agent to communicate with external processes via standard input/output streams. This is ideal for integrating complex, standalone Python scripts or other local executables as tools.

```python title="main.py"
import sys
from pathlib import Path
from videosdk.agents import Agent, MCPServerStdio

# Path to your external Python script that runs the MCP server
mcp_server_path = Path(__file__).parent / "mcp_server_script.py"

class MCPAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are an assistant that can leverage external tools via MCP.",
            mcp_servers=[
                MCPServerStdio(
                    executable_path=sys.executable,
                    process_arguments=[str(mcp_server_path)],
                    session_timeout=30
                )
            ]
        )
```

## Agent Lifecycle and Methods

The `Agent` class provides lifecycle hooks and methods to manage state and behavior at critical points in the agent's session.

### Lifecycle Hooks

These methods are designed to be overridden in your custom agent class to implement specific behaviors.

- `async def on_enter(self) -> None`:
  Called once when the agent successfully joins the meeting. This is the ideal place for introductions or initial actions, such as greeting participants.
- `async def on_exit(self) -> None`:
  Called when the agent is about to exit the meeting. Use this for cleanup tasks or for saying goodbye.

```python title="main.py"
from videosdk.agents import Agent

class LifecycleAgent(Agent):
    async def on_enter(self):
        print("Agent has entered the meeting.")
        await self.session.say("Hello everyone! I'm here to help.")

    async def on_exit(self):
        print("Agent is exiting the meeting.")
        await self.session.say("It was a pleasure assisting you. Goodbye!")
```


## Human in the Loop (HITL)  

Human in the Loop enables AI agents to escalate specific queries to human operators for review and approval. This implementation uses Discord as the human interface through an MCP server, allowing seamless handoffs between AI automation and human oversight.  

### Use Cases  

- **Discount Requests**: AI escalates pricing queries to human sales agents  
- **Complex Support**: Technical issues requiring human expertise    
- **Policy Decisions**: Requests that need human approval or clarification  
- **Escalation Scenarios**: Situations where AI confidence is low  

### Implementation  

The HITL pattern combines the Agent's MCP server capability with a Discord-based human interface:  
  
**Agent Configuration:**

```python title="main.py"
from videosdk.agents import Agent, MCPServerStdio, CascadingPipeline, AgentSession, JobContext, RoomOptions, WorkerJob  
from videosdk.plugins.deepgram import DeepgramSTT  
from videosdk.plugins.anthropic import AnthropicLLM  
from videosdk.plugins.google import GoogleTTS  
from videosdk.plugins.silero import SileroVAD  
from videosdk.plugins.turn_detector import TurnDetector  
import pathlib  
import sys  
import os  
from typing import Optional  
  
class CustomerAgent(Agent):  
def __init__(self, ctx: Optional[JobContext] = None):  
    current_dir = pathlib.Path(__file__).parent  
    discord_mcp_server_path = current_dir / "discord_mcp_server.py"  
  
    super().__init__(  
        instructions="You are a customer-facing agent for VideoSDK. You have access to various tools to assist with customer inquiries, provide support, and handle tasks. When a user asks for a discount percentage, always use the appropriate tool to retrieve and provide the accurate answer from your superior human agent.",  
        mcp_servers=[  
            MCPServerStdio(  
                executable_path=sys.executable,  
                process_arguments=[str(discord_mcp_server_path)],  
                session_timeout=30  
            ),  
        ]  
    )  
    self.ctx = ctx  
  
async def on_enter(self) -> None:  
    """Called when the agent first joins the meeting"""  
    await self.session.say("Hi! I'm your VideoSDK customer support agent. How can I help you today?")  
  
async def on_exit(self) -> None:  
    """Called when the agent exits the meeting"""  
    await self.session.say("Thank you for contacting VideoSDK support. Have a great day!")  
  
# Pipeline configuration integrated into the main setup  
def create_pipeline() -> CascadingPipeline:  
"""Create and configure the cascading pipeline with all components"""  
return CascadingPipeline(  
    stt=DeepgramSTT(api_key=os.getenv("DEEPGRAM_API_KEY")),    
    llm=AnthropicLLM(api_key=os.getenv("ANTHROPIC_API_KEY")),  
    tts=GoogleTTS(api_key=os.getenv("GOOGLE_API_KEY")),  
    vad=SileroVAD(),  
    turn_detector=TurnDetector(threshold=0.8)  
)  
  
async def start_session(ctx: JobContext):  
"""Main entry point that creates agent, pipeline, and starts the session"""  
# Create the pipeline  
pipeline = create_pipeline()  
  
# Create the agent with context  
agent = CustomerAgent(ctx=ctx)  
  
# Create the agent session  
session = AgentSession(  
    agent=agent,  
    pipeline=pipeline  
)  
  
try:  
    # Connect to the room  
    await ctx.connect()  
      
    # Start the agent session  
    await session.start()  
      
    # Keep running until interrupted  
    import asyncio  
    await asyncio.Event().wait()  
      
finally:  
    # Clean up resources  
    await session.close()  
    await ctx.shutdown()  
  
def make_context() -> JobContext:  
"""Create the job context with room configuration"""  
room_options = RoomOptions(  
    room_id=os.getenv("VIDEOSDK_ROOM_ID", "your-room-id"),  
    auth_token=os.getenv("VIDEOSDK_AUTH_TOKEN"),  
    name="VideoSDK Customer Agent",  
    playground=True  
)  
  
return JobContext(room_options=room_options)  
  
if __name__ == "__main__":  
job = WorkerJob(entrypoint=start_session, jobctx=make_context)  
job.start()
```

---

**Discord MCP Server:**

```python title="discord_mcp_server.py"
import asyncio  
import os  
from mcp.server.fastmcp import FastMCP  
import discord  
from discord.ext import commands  
  
class DiscordHuman:  
def __init__(self, user_id: int, channel_id: int, bot_token: str):  
    self.user_id = user_id  
    self.channel_id = channel_id  
    self.bot_token = bot_token  
    self.bot = commands.Bot(command_prefix="!", intents=discord.Intents.all())  
    self.response_future = None  
    self.setup_bot_events()  
  
def setup_bot_events(self):  
    @self.bot.event  
    async def on_ready():  
        print(f'{self.bot.user} has connected to Discord!')  
  
    @self.bot.event  
    async def on_message(message):  
        if (message.author.id == self.user_id and   
            message.channel.id in [thread.id for thread in self.bot.get_all_channels() if hasattr(thread, 'parent')] and  
            self.response_future and not self.response_future.done()):  
            self.response_future.set_result(message.content)  
  
async def start_bot(self):  
    """Start the Discord bot"""  
    await self.bot.start(self.bot_token)  
  
async def ask(self, question: str) -> str:  
    if not self.bot.is_ready():  
        return "❌ Discord bot is not ready"  
          
    try:  
        channel = self.bot.get_channel(self.channel_id)  
        if not channel:  
            return "❌ Channel not found"  
              
        thread = await channel.create_thread(  
            name=question[:100],  
            type=discord.ChannelType.public_thread  
        )  
        await thread.send(f"<@{self.user_id}> {question}")  
  
        self.response_future = asyncio.get_event_loop().create_future()  
        try:  
            response = await asyncio.wait_for(self.response_future, timeout=600)  
            return response  
        except asyncio.TimeoutError:  
            return "⏱️ Timed out waiting for a human response"  
    except Exception as e:  
        return f"❌ Error: {str(e)}"  
  
# Initialize Discord human instance  
discord_human = DiscordHuman(  
user_id=int(os.getenv("DISCORD_USER_ID")),  
channel_id=int(os.getenv("DISCORD_CHANNEL_ID")),  
bot_token=os.getenv("DISCORD_TOKEN")  
)  
  
# MCP Server Setup  
mcp = FastMCP("HumanInTheLoopServer")  
  
@mcp.tool(description="Ask a human agent via Discord for a specific user query such as discount percentage, etc.")  
async def ask_human(question: str) -> str:  
"""Ask a human agent via Discord for assistance"""  
return await discord_human.ask(question)  
  
async def main():  
"""Main function to start both the Discord bot and MCP server"""  
# Start Discord bot in background  
bot_task = asyncio.create_task(discord_human.start_bot())  
  
# Wait a moment for bot to initialize  
await asyncio.sleep(2)  
  
# Start MCP server  
await mcp.run()  
  
if __name__ == "__main__":  
asyncio.run(main())
```

---

**Environment Variables:**

Set the following environment variables:

```bash title=".env"
DISCORD_TOKEN=your_discord_bot_token  
DISCORD_USER_ID=human_operator_user_id  
DISCORD_CHANNEL_ID=channel_id_for_escalations  
DEEPGRAM_API_KEY=your_deepgram_key  
ANTHROPIC_API_KEY=your_anthropic_key  
GOOGLE_API_KEY=your_google_key  
VIDEOSDK_AUTH_TOKEN=your_videosdk_token  
VIDEOSDK_ROOM_ID=your_room_id
```

The Discord MCP server provides the `ask_human` tool that creates Discord threads for human operator responses. This leverages the same MCP integration pattern shown in the previous section.

Complete implementation with full source code, setup instructions, and configuration examples available in the [VideoSDK Agents GitHub repository](https://github.com/videosdk-live/agents/tree/main/examples/human_in_the_loop). -->



## Examples - Try Out Yourself

Checkout the examples of function tool usage and MCP server.

- [Function Tool ](https://github.com/videosdk-live/agents/blob/main/examples/test_cascading_pipeline.py): Implement agent with internal and external tool
- [MCP Server](https://github.com/videosdk-live/agents/blob/main/examples/mcp_example.py): Implement agent with MCP server integration
- [Human in the Loop](https://github.com/videosdk-live/agents/tree/main/examples/human_in_the_loop): Escalate queries to human operators via Discord



---

# Avatar

Avatars add a visual, human-like presence to your AI agents, creating more engaging and natural interactions. The VideoSDK Agents framework supports virtual avatars through the Simli integration, providing lifelike video representations that sync with your agent's speech.

![Avatar](https://cdn.videosdk.live/website-resources/docs-resources/voice_agent_avatar.png)

## Overview

Avatar functionality enables your AI agents to:

- **Visual Presence**: Display a human-like avatar that represents your agent
- **Lip Sync**: Automatically synchronize avatar mouth movements with speech
- **Real-time Rendering**: Generate avatar video in real-time during conversations
- **Customizable Appearance**: Choose from different avatar faces and styles
- **Seamless Integration**: Works with both CascadingPipeline and RealTimePipeline

## What Avatars Enable

With avatar capabilities, your agents can:

- Provide a more human and approachable interface
- Increase user engagement through visual interaction
- Create branded agent personalities with custom appearances
- Enhance accessibility through visual communication cues
- Build trust through consistent visual representation

## Simli Avatar Integration

### Basic Setup

The Simli avatar integration provides high-quality virtual avatars with real-time lip synchronization.

```python title="main.py"
from videosdk.plugins.simli import SimliAvatar, SimliConfig

# Configure your avatar
avatar_config = SimliConfig(
    apiKey="your-simli-api-key",
    faceId="0c2b8b04-5274-41f1-a21c-d5c98322efa9",  # Default face
    syncAudio=True,
    handleSilence=True
)

avatar = SimliAvatar(config=avatar_config)
```

### Avatar Configuration Options

Customize your avatar's behavior and appearance:

```python title="main.py"
from videosdk.plugins.simli import SimliConfig

config = SimliConfig(
    apiKey="your-simli-api-key",
    faceId="your-custom-face-id",     # Choose avatar appearance
    syncAudio=True,                   # Enable lip sync
    handleSilence=True,               # Manage silent periods
    maxSessionLength=1800,            # 30 minutes max session
    maxIdleTime=300                   # 5 minutes idle timeout
)
```

## Pipeline Integration

**Cascading Pipeline:**

Add avatar to your cascading pipeline setup:

```python title="main.py"
from videosdk.agents import CascadingPipeline, AgentSession
from videosdk.plugins.simli import SimliAvatar, SimliConfig

# Configure avatar
avatar_config = SimliConfig(apiKey="your-simli-api-key")
avatar = SimliAvatar(config=avatar_config)

# Create pipeline with avatar
pipeline = CascadingPipeline(
stt=your_stt_provider,
llm=your_llm_provider,
tts=your_tts_provider,
avatar=avatar  # Add avatar to pipeline
)
```

---

**Real-time Pipeline:**

Integrate avatar with real-time models:

```python title="main.py"
from videosdk.agents import RealTimePipeline
from videosdk.plugins.simli import SimliAvatar, SimliConfig
from videosdk.plugins.openai import OpenAIRealtime

# Configure avatar
avatar = SimliAvatar(config=SimliConfig(apiKey="your-api-key"))

# Configure real-time model
model = OpenAIRealtime(model="gpt-4o-realtime-preview")

# Create pipeline with avatar
pipeline = RealTimePipeline(
model=model,
avatar=avatar
)
```

:::info
You can also specify the avatar in your room configuration:

```python title="main.py"
from videosdk.agents import JobContext, RoomOptions

def make_context():
    avatar = SimliAvatar(config=SimliConfig(apiKey="your-api-key"))

    return JobContext(
        room_options=RoomOptions(
            room_id="your-room-id",
            auth_token="your-auth-token",
            name="Avatar Agent",
            avatar=avatar  # Specify avatar in room options
        )
    )
```

:::

## Example - Try Out Yourself


- [AI Avatar Example](https://github.com/videosdk-live/agents/tree/main/examples/avatar): Complete avatar implementation with weather assistant functionality



---

# Background Audio

The Background Audio feature enables voice agents to play audio during conversations, enhancing user experience with ambient sounds and processing feedback. 
There are two ways to set the audio:
1. **Thinking Audio:** Plays automatically during agent processing (e.g., keyboard typing sounds)
2. **Background Audio:** Plays on-demand for ambient music or soundscapes


**Thinking Audio:**

![Thinking Audio](https://assets.videosdk.live/images/thinking_audio.png)

---

**Background Audio:**

![Background Audio](https://assets.videosdk.live/images/background-audio.png)

## Getting Started

### Enable Background Audio

```python
from videosdk.agents import RoomOptions, JobContext  
  
room_options = RoomOptions(  
    room_id="your-room-id",  
    name="My Agent",  
    # highlight-start
    background_audio=True  # Enable background audio support  
    #highlight-end
)  
  
context = JobContext(room_options=room_options)
```

### Agent Methods

**1. Set Thinking Audio**

`set_thinking_audio()`: Configures audio that plays automatically while the agent processes responses.

**Parameters:** 
- `file (str, optional)`: Path to custom WAV audio file. If not provided, uses built-in `agent_keyboard.wav`
- `volume (float, optional)`: Volume of the audio. Default: `0.3`

**Example:**
```python
class MyAgent(Agent):  
    def __init__(self):  
        super().__init__(instructions="...")  
        # highlight-start
        # Use default keyboard sound  
        self.set_thinking_audio()  
        # Or use custom audio  
        # self.set_thinking_audio(file="path/to/custom.wav")
        # highlight-end
```

**2.  Play Background Audio**

`play_background_audio()`: Starts playing background audio during the conversation.

**Parameters:** 
- `file (str, optional)`: Path to custom WAV audio file. If not provided, uses built-in `classical.wav`
- `looping (bool, optional)`: Whether to loop the audio. Default: `False`
- `override_thinking (bool, optional)`: Whether to stop thinking audio when background audio starts. Default: `True`
- `volume (float, optional)`: Volume of the audio. Default: `1.0`

**Example:**
```python
@function_tool  
async def play_music(self):  
    """Plays background music"""  
    # highlight-start
    await self.play_background_audio(  
        looping=True,  
        override_thinking=False  
    )  
    # highlight-end
    return "Music started"
```

**3. Stop Background Audio**

`stop_background_audio()`: Stops currently playing background audio.

**Example:**
```python
@function_tool  
async def stop_music(self):  
    """Stops background music"""  
    # highlight-start
    await self.stop_background_audio()  
    # highlight-end
    return "Music stopped"
```

## Complete Example

```python title="main.py"
from videosdk.agents import (  
    Agent, AgentSession, CascadingPipeline,   
    WorkerJob, ConversationFlow, JobContext,   
    RoomOptions, function_tool  
)  
from videosdk.plugins.openai import OpenAILLM, OpenAITTS  
from videosdk.plugins.deepgram import DeepgramSTT  
from videosdk.plugins.silero import SileroVAD  
from videosdk.plugins.turn_detector import TurnDetector  
  
class MusicAgent(Agent):  
    def __init__(self):  
        super().__init__(  
            instructions="You are a helpful assistant. Use control_music to play or stop background music."  
        )  
        #highlight-start
        # Enable thinking audio with default keyboard sound  
        self.set_thinking_audio()  
        #highlight-end
      
    async def on_enter(self):  
        await self.session.say("Hello! Ask me to play music.")
    
    async def on_exit(self):
        await self.session.say("Goodbye! Hope you enjoyed the music.")
      
    @function_tool  
    async def control_music(self, action: str):  
        """  
        Controls background music.  
        :param action: 'play' to start music, 'stop' to end it  
        """  
        if action == "play":  
            #highlight-start
            await self.play_background_audio(  
                override_thinking=True,  
                looping=True  
            )  
            #highlight-end
            return "Music started"  
        elif action == "stop":  
            #highlight-start
            await self.stop_background_audio()  
            #highlight-end
            return "Music stopped"  
        return "Invalid action"  
  
async def entrypoint(ctx: JobContext):  
    agent = MusicAgent()  
      
    pipeline = CascadingPipeline(  
        stt=DeepgramSTT(),  
        llm=OpenAILLM(),  
        tts=OpenAITTS(),  
        vad=SileroVAD(),  
        turn_detector=TurnDetector()  
    )  
      
    session = AgentSession(  
        agent=agent,  
        pipeline=pipeline,  
        conversation_flow=ConversationFlow(agent)  
    )  
      
    await ctx.run_until_shutdown(session=session)  
  
def make_context():  
    return JobContext(  
        room_options=RoomOptions(  
            room_id="<room_id>",  
            name="Music Agent",  
            #highlight-start
            background_audio=True  # Required!  
            #highlight-end
        )  
    )  
  
if __name__ == "__main__":  
    job = WorkerJob(entrypoint=entrypoint, jobctx=make_context)  
    job.start()
```

## Pipeline Support

Background audio works with both pipeline types:

### Cascading Pipeline

- Thinking audio plays automatically during LLM processing
- Background audio can be controlled via agent methods
- Audio stops automatically when agent speaks

### RealTime Pipeline

- Full background audio support with streaming models
- Automatic lifecycle management during conversation turns

## Audio Behavior

| Feature | Thinking Audio | Background Audio |  
|---------|---------------|------------------|  
| **Trigger** | Automatic during processing | Manual via `play_background_audio()` |  
| **Default File** | `agent_keyboard.wav` | `classical.wav` |  
| **Typical Duration** | Short (during LLM call) | Long/continuous |  
| **Looping** | Optional | Recommended (`looping=True`) |  
| **User Control** | No | Yes (via function tools) |  
| **Stops When** | Agent speaks | Agent speaks or `stop_background_audio()` |

## Audio File Requirements

- **Format:** WAV (`.wav`)
- **Recommended:** 16-bit PCM, 16kHz sample rate, mono channel
- **Built-in files:**
    - `agent_keyboard.wav`: Default thinking sound
    - `classical.wav`: Default background music

## Best Practices

1. **Always enable in RoomOptions:** Set `background_audio=True` before using audio methods
2. **Use `override_thinking=True`:** When playing music to avoid overlapping sounds
3. **Loop background audio:** Set `looping=True` for continuous ambient sounds
4. **Control via function tools:** Let users control music through natural language
5. **Clean audio files:** Use high-quality WAV files to avoid distortion

## Common Use Cases

- **Music player agent:** Control playback through conversation
- **Ambient soundscapes:** Create atmosphere during interactions
- **Processing feedback:** Custom thinking sounds for different agent personalities
- **Hold music:** Play audio while agent performs long operations

## Example - Try It Yourself

- [Background Audio example](https://github.com/videosdk-live/agents/blob/main/examples/background_audio.py): Implement and experience the background audio functionality yourself


## FAQs

### Troubleshooting

| Issue | Solution |
|--------|-----------|
| Audio not playing | Verify `background_audio=True` in `RoomOptions` |
| Audio quality issues | Use WAV format with 16-bit PCM encoding |
| Audio doesn't stop | Ensure `stop_background_audio()` is called properly |
| Overlapping sounds | Use `override_thinking=True` when playing background audio |

---

Call Transfer lets your AI Agent move an ongoing SIP call to another phone number without ending the current session. Instead of making the caller hang up and dial a new number, the agent can automatically route the call.

## How Call Transfer Works

- The agent evaluates the user’s intent to determine when a call transfer is required and then triggers the function tool.
- When the function tool is triggered, it tells the system to move the call to another phone number.
- The ongoing SIP call is forwarded to the new number instantly, without disconnecting or redialing.

## Trigger Call Transfer

To set up incoming call handling, outbound calling, and routing rules, check out the [Quick Start Example](https://docs.videosdk.live/telephony/ai-telephony-agent-quick-start#part-2-connect-your-agent-to-the-phone-network).

```python title="main.py"

from videosdk.agents import Agent, function_tool, 

class CallTransferAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are the Call Transfer Agent Which Help and provide to transfer on going call to new number. use transfer_call tool to transfer the call to new number.",
        )

    async def on_enter(self) -> None:
        await self.session.say("Hello Buddy, How can I help you today?")

    async def on_exit(self) -> None:
        await self.session.say("Goodbye Buddy, Thank you for calling!")

    @function_tool
    async def transfer_call(self) -> None:
        """Transfer the call to Provided number"""
        token = os.getenv("VIDEOSDK_AUTH_TOKEN")
        transfer_to = os.getenv("CALL_TRANSFER_TO") 
        return await self.session.call_transfer(token,transfer_to)
```

## Example - Try It Yourself

- [Call Transfer Example](https://github.com/videosdk-live/agents/blob/main/examples/call_transfer.py): Check out and implement the Call Transfer example from GitHub.


---

# Cascading Pipeline

The `Cascading Pipeline` component provides a flexible, modular approach to building AI agents by allowing you to mix and match different components for Speech-to-Text (STT), Large Language Models (LLM), Text-to-Speech (TTS), Voice Activity Detection (VAD), and Turn Detection.

## Core Architecture

The pipeline is composed of five key stages that work in sequence to handle a conversation:

- **VAD (Voice Activity Detection)** - Detects the presence of human speech in the audio stream to know when to start processing.
- **STT (Speech-to-Text)** - Converts the detected speech from audio into a text transcript.
- **LLM (Large Language Model)** - Takes the text transcript as input, processes it, and generates a meaningful response.
- **TTS (Text-to-Speech)** - Converts the LLM's text response back into audible speech.
- **Turn Detection** - Manages the back-and-forth of the conversation, determining when one speaker has finished and another can begin.

![Cascading Pipeline Architecture](https://cdn.videosdk.live/website-resources/docs-resources/videosdk_casading_pipeline.png)

## Basic Usage

### Simple Pipeline

Here is the most basic setup, combining STT, LLM, and TTS components. The SDK will use default configurations if no specific settings are provided.

```python title="main.py"
from videosdk.agents import CascadingPipeline
from videosdk.plugins.deepgram import DeepgramSTT
from videosdk.plugins.openai import OpenAILLM
from videosdk.plugins.elevenlabs import ElevenLabsTTS
from videosdk.plugins.silero import SileroVAD
from videosdk.plugins.turn_detector import TurnDetector

pipeline = CascadingPipeline(
    stt=DeepgramSTT(),
    llm=OpenAILLM(),
    tts=ElevenLabsTTS(),
    vad=SileroVAD(),
    turn_detector=TurnDetector()
)
```

## Key Features:

- **Modular Component Selection** - Choose different providers for each component
- **Flexible Configuration** - Mix and match STT, LLM, TTS, VAD, and Turn Detection
- **Custom Processing** - Add custom processing for STT and LLM outputs
- **Provider Agnostic** - Support for multiple AI service providers
- **Advanced Control** - Fine-tune each component independently

## Advance Configuration

You can fine-tune the behavior of each component by passing specific parameters during initialization.

```python title="main.py"
from videosdk.agents import CascadingPipeline
from videosdk.plugins.openai import OpenAILLM
from videosdk.plugins.deepgram import DeepgramSTT
from videosdk.plugins.silero import SileroVAD
from videosdk.plugins.turn_detector import TurnDetector

stt=DeepgramSTT(
    model="nova-2",
    language="en",
    punctuate=True,
    diarize=True
),
llm=OpenAILLM(
    model="gpt-4o",
    temperature=0.7,
    max_tokens=1000
),
tts=ElevenLabsTTS(
    model="eleven_flash_v2_5",
    voice_id="21m00Tcm4TlvDq8ikWAM"
),
vad=SileroVAD(
    threshold=0.35,
    min_silence_duration=0.5
),
turn_detector=TurnDetector(
    threshold=0.8,
    min_turn_duration=1.0
)

pipeline = CascadingPipeline(stt=stt, llm=llm, tts=tts, vad=vad, turn_detector=turn_detector)
```

## Dynamic Component Changes

The pipeline supports runtime component swapping

```python
# Change components during runtime
await pipeline.change_component(
    stt=new_stt_provider,
    llm=new_llm_provider,
    tts=new_tts_provider
)
```

## Plugin Ecosystem

There are multiple plugins available for STT, LLM, & TTS. Checkout here:


- [STT](https://docs.videosdk.live/ai_agents/plugins/llm/openai): Learn more about other STT plugins





## Plugin Development

### Creating Custom Plugins

To create custom plugins, follow the [plugin development guide ↗](https://github.com/videosdk-live/agents/blob/main/BUILD_YOUR_OWN_PLUGIN.md).

Key requirements include:

- Inherit from the correct base class (`STT`, `LLM`, or `TTS`)
- Implement all abstract methods
- Handle errors consistently using `self.emit("error", message)`
- Clean up resources in the `aclose()` method

## Plugin Installation

Install additional plugins as needed:

```python
# Install specific provider plugins
pip install videosdk-plugins-openai
pip install videosdk-plugins-elevenlabs
pip install videosdk-plugins-deepgram
```

## Best Practices

1. **Component Selection:** Choose providers based on your specific requirements (latency, quality, cost)
2. **Error Handling:** Implement proper error handling and fallback strategies
3. **Resource Management:** Use the `cleanup()` method to properly close components.
4. **Configuration Monitoring:** Use `get_component_configs()` for debugging and monitoring
5. **Audio Format:** Ensure your custom plugins handle the 48kHz audio format correctly

## Key Benefits

The Cascading Pipeline offers several advantages over integrated solutions:

- **Multi-language Support** - Use specialized STT for different languages
- **Cost Optimization** - Mix premium and cost-effective services
- **Custom Voice Processing** - Add domain-specific processing logic
- **Performance Optimization** - Choose fastest providers for each component
- **Compliance Requirements** - Use specific providers for regulatory compliance

## Comparison with Realtime Pipeline

| Feature       | Cascading Pipeline                  | Realtime Pipeline             |
| ------------- | ----------------------------------- | ----------------------------- |
| Control       | Maximum control over each component | Integrated model control      |
| Flexibility   | Mix different providers             | Single model provider         |
| Latency       | Higher due to sequential processing | Lower with streaming          |
| Customization | Extensive customization options     | Limited to model capabilities |
| Complexity    | More complex configuration          | Simpler setup                 |

The `Cascading Pipeline` is ideal when you need maximum flexibility and control over each processing stage, while the `Realtime Pipeline` is better for low-latency applications with integrated model providers.

## Examples - Try Out Yourself

We have examples to get you started. Go ahead, try out, talk to agent, understand and customize according to your needs.

- [Basic Implementation](https://github.com/videosdk-live/agents/blob/main/examples/test_cascading_pipeline.py): Checkout the cascading pipeline implementation



---

# Conversation Flow

The `Conversation Flow` component manages the turn-taking logic in AI agent conversations, ensuring smooth and natural interactions. It is an inheritable class that allows you to inject custom logic into the `Cascading Pipeline`, enabling advanced capabilities like context preservation, dynamic adaptation, and Retrieval-Augmented Generation (RAG) before the final LLM call.

![Conversation Flow](https://cdn.videosdk.live/website-resources/docs-resources/build_agent_section_conversation_flow.png)

:::note
Conversation Flow is a powerful feature that currently works exclusively with the [Cascading Pipeline ↗](https://docs.videosdk.live/ai_agents/core-components/cascading-pipeline).
:::

## Core Features

The key methods allow you to inject custom logic at different stages of the conversation flow, enabling sophisticated AI agent behaviors while maintaining clean separation of concerns:

### **Core Capabilities**

- **Turn-taking Management:** Control the flow and timing of agent and user turns
- **Context Preservation:** Maintain conversation history and user data across turns (handled automatically)
- **Advanced Flow Control:** Build stateful conversations that can adapt to user input
- **Performance Optimization:** Fine-tune conversation processing for speed and efficiency
- **Error Handling:** Implement robust error recovery and fallback mechanisms

### **Advanced Use Cases**

- **RAG Implementation:** Retrieve relevant documents and context before LLM processing
- **Memory Management:** Store and recall conversation history across sessions
- **Content Filtering:** Apply safety checks and content moderation on input/output
- **Analytics & Logging:** Track conversation metrics and user behavior patterns (built-in metrics integration)
- **Business Logic Integration:** Add domain-specific processing and validation rules
- **Multi-step Workflows:** Implement complex conversation flows with state management
- **Function Tool Execution:** Automatic execution of function tools when requested by the LLM.

## Basic Usage

### Complete Setup with CascadingPipeline

The recommended approach is to use `ConversationFlow` with a `CascadingPipeline`, which handles component configuration automatically:

```python title="main.py"
from videosdk.agents import ConversationFlow, Agent, CascadingPipeline

# First, define your agent
class MyAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are a helpful assistant."
        )

    async def on_enter(self):
        # Initialize agent state
        pass

    async def on_exit(self):
        # Cleanup resources
        pass

# Create pipeline and conversation flow
pipeline = CascadingPipeline(stt=my_stt, llm=my_llm, tts=my_tts)
conversation_flow = ConversationFlow(MyAgent())

# Pipeline automatically configures all components
pipeline.set_conversation_flow(conversation_flow)
```

### Constructor Parameters

The ConversationFlow constructor accepts comprehensive configuration options:

```python
ConversationFlow(
    agent: Agent,
    stt: STT | None = None,
    llm: LLM | None = None,
    tts: TTS | None = None,
    vad: VAD | None = None,
    turn_detector: EOU | None = None,
    denoise: Denoise | None = None
)
```

To add custom behavior, you inherit from `ConversationFlow` and override its methods.

## Built-in Methods

### Core Processing Methods

- `process_with_llm()`: Processes the current chat context with the LLM and handles function tool execution automatically.
- `say(message: str)`: Direct TTS synthesis for agent responses.
- `process_text_input(text: str)`: Handle text input for A2A communication, bypassing STT.

### Lifecycle Hooks

Override these methods to add custom behavior at specific conversation points:

```python
class CustomFlow(ConversationFlow):
    async def on_turn_start(self, transcript: str) -> None:
        """Called when a user turn begins."""
        print(f"User said: {transcript}")

    async def on_turn_end(self) -> None:
        """Called when a user turn ends."""
        print("Turn completed")

```

## Automatic Features

- **Context Management**: The conversation flow automatically manages the agent's chat context. Do not manually add user messages as this will create duplicates.
- **Audio Processing**: Audio data is automatically processed through send_audio_delta(), handling denoising, STT, and VAD processing.
- **Interruption Handling**: The system includes sophisticated interruption logic that gracefully handles user interruptions during agent responses.



## Custom Conversation Flows

### RAG (Retrieval-Augmented Generation) Integration

Enhance your agent's knowledge by integrating RAG to retrieve relevant information from external documents and databases.

**Benefits:**

- Access external documents and FAQs
- Reduce hallucinations with real data
- Dynamic context retrieval

```python title="rag_example.py"
class RAGConversationFlow(ConversationFlow):
    async def run(self, transcript: str) -> AsyncIterator[str]:
        # Retrieve relevant context
        context = await self.agent.retrieve_relevant_documents(transcript)

        # Add context to conversation
        if context:
            self.agent.chat_context.add_message(
                role="system",
                content=f"Use this information: {context}"
            )

        # Generate response with enhanced context
        async for response in self.process_with_llm():
            yield response
```

See our [RAG Integration Documentation](../core-components/rag) for complete implementation.

### Implementing Custom Flows

You can create a custom flow by inheriting from `ConversationFlow` and overriding the `run` method. This allows you to intercept the user's transcript, modify it, manage state, and even change the response from the LLM.

```python title="main.py"
from typing import AsyncIterator
from videosdk.agents import ConversationFlow, Agent

class CustomConversationFlow(ConversationFlow):
    def __init__(self, agent):
        super().__init__(agent)
        self.turn_count = 0

    async def run(self, transcript: str) -> AsyncIterator[str]:
        """Override the main conversation loop to add custom logic."""
        self.turn_count += 1

        # You can access and add to the agent's chat context before calling the LLM
        self.agent.chat_context.add_message(role=ChatRole.USER, content=transcript)

        # Process with the standard LLM call
        async for response_chunk in self.process_with_llm():
            # Apply custom processing to the response
            processed_chunk = await self.apply_custom_processing(response_chunk)
            yield processed_chunk

    async def apply_custom_processing(self, chunk: str) -> str:
        """A helper method to modify the LLM's output."""
        if self.turn_count == 1:
            # Prepend a greeting on the first turn
            return f"Hello! {chunk}"
        elif self.turn_count > 5:
            # Offer to summarize after many turns
            return f"This is an interesting topic. To summarize: {chunk}"
        else:
            return chunk
```

### Advanced Turn-Taking Logic

For more complex interactions, you can implement a state machine within your conversation flow to manage different states of the conversation.

```python title="main.py"
class AdvancedTurnTakingFlow(ConversationFlow):
    def __init__(self, agent):
        super().__init__(agent)
        self.conversation_state = "listening"  # Initial state

    async def run(self, transcript: str) -> AsyncIterator[str]:
        """A state-driven conversation loop."""
        if self.conversation_state == "listening":
            # If we were listening, we now process the user's input
            # and transition to the responding state.
            await self.process_user_input(transcript)
            self.conversation_state = "responding"

            async for response_chunk in self.process_with_llm():
                yield response_chunk

            # Once done responding, go back to listening
            self.conversation_state = "listening"

        elif self.conversation_state == "waiting_for_confirmation":
            # Handle a confirmation state
            if "yes" in transcript.lower():
                yield "Great! Proceeding."
                self.conversation_state = "listening"
            else:
                yield "Okay, cancelling."
                self.conversation_state = "listening"

    async def process_user_input(self, transcript: str):
        """Custom logic for processing user input."""
        print(f"Processing user input in state: {self.conversation_state}")
        # Add logic here, e.g., check if the user is asking a question that needs confirmation
        if "delete my account" in transcript.lower():
            self.conversation_state = "waiting_for_confirmation"
```

### Context-Aware Conversations

Maintain conversation history and user preferences to create a personalized and context-aware experience.

```python title="main.py"
import time

class ContextAwareFlow(ConversationFlow):
    def __init__(self, agent):
        super().__init__(agent)
        self.conversation_history = []
        self.current_topic = "general"

    async def run(self, transcript: str) -> AsyncIterator[str]:
        # First, update the context with the new transcript
        await self.update_context(transcript)

        # The agent's chat_context (automatically managed) will be
        # used by process_with_llm() to generate a context-aware response.
        async for response_chunk in self.process_with_llm():
            yield response_chunk

    async def update_context(self, transcript: str):
        """Update history and identify the topic before calling the LLM."""
        self.conversation_history.append({
            'role': 'user',
            'content': transcript,
            'timestamp': time.time()
        })
        await self.identify_topic(transcript)

        # Add topic-specific context (system messages are safe to add)
        if hasattr(self, 'current_topic'):
            self.agent.chat_context.add_message(
                role=ChatRole.SYSTEM,
                content=f"System note: The user is asking about {self.current_topic}."
            )

    async def identify_topic(self, transcript: str):
        """A simple topic identification logic."""
        if "weather" in transcript.lower():
            self.current_topic = "weather"
        elif "finance" in transcript.lower():
            self.current_topic = "finance"
```

## Performance Optimization

To ensure the best user experience, consider the following optimization strategies:

- **Efficient Context**: Keep the context provided to the LLM concise. Summarize earlier parts of the conversation to reduce token count and improve LLM response time.

- **Asynchronous Operations**: When performing RAG or calling external APIs for data, ensure the operations are fully asynchronous (async/await) to avoid blocking the event loop.

- **Caching**: Cache frequently accessed data (e.g., from a database or RAG store) to reduce lookup latency on subsequent turns.

- **Streaming**: The run method returns an `AsyncIterator`. Process and yield response chunks as soon as they are available from the LLM to minimize perceived latency for the user.

## Examples - Try Out Yourself

We have examples to get you started. Go ahead, try out, talk to agent, understand and customize according to your needs.

- [Understand conversation flow](https://youtu.be/ZGqmIu-tE18?feature=shared): Youtube video explaining conversation flow





---

# Conversational Graph

The **Conversational Graph** is a powerful tool that allows you to define complex, structured conversation flows for your AI agents. Instead of relying solely on an LLM's inherent reasoning, which can sometimes be unpredictable, you can use a graph-based approach to guide the conversation through specific states and transitions.

## Installation

To use the Conversational Graph, you need to install the `videosdk-conversational-graph` package.

```bash
pip install videosdk-conversational-graph
```

:::note
Check out the latest version of [videosdk-conversational-graph](https://pypi.org/project/videosdk-conversational-graph/) on PyPI.
:::

## Core Concepts

The Conversational Graph is built around a few key concepts:

1.  **ConversationalGraph**: The main object that manages the states and transitions.
2.  **State**: A specific point in the conversation (e.g., "Greeting", "Asking for Name"). Each state has instructions for the agent.
3.  **Transition**: Logic that dictates how the agent moves from one state to another based on user input or collected data.

## Example: Loan Application

Let's walk through a complete example of building a Loan Application agent. This agent will guide the user through selecting a loan type (Personal, Home, or Car) and collecting the necessary details.

![Conversational Graph Loan Application](https://assets.videosdk.live/images/conversational-Graph.png)

### Step 1: Define the Data Model


First, define the data you want to collect using `ConversationalDataModel`. This ensures the agent knows exactly what information to extract.

```python title="main.py"
from pydantic import Field
from conversational_graph import ConversationalGraph,ConversationalDataModel

class LoanFlow(ConversationalDataModel):
    loan_type: str = Field(None, description="Type of loan: personal, home, car")
    annual_income: int = Field(None, description="Annual income of the applicant in INR")
    credit_score: int = Field(None, description="Credit score of the applicant. Must be between 300 and 850")
    property_value: int = Field(None, description="Value of the property for home loan in INR")
    vehicle_price: int = Field(None, description="Price of the vehicle for car loan in INR")
    loan_amount: int = Field(None, description="Desired loan amount in INR. MUST be greater than ₹11 lakh for approval")
```



### Step 2: Initialize the Graph


Create an instance of `ConversationalGraph` and pass your data model.

```python title="main.py"
loan_application = ConversationalGraph(
    name="Loan Application",
    DataModel=LoanFlow,
    off_topic_threshold=5
)
```



### Step 3: Define States


Define the various states of your conversation. Each state has a `name` and `instruction` that tells the agent what to do in that state. You can also define specific `tools` available to the agent within that state.

```python title="main.py"
# Start Greeting
q0 = loan_application.state(
    name="Greeting",
    instruction="Welcome user and start the conversation about loan application. Ask if they are ready to apply for a loan.",
)

# Loan Type Selection
q1 = loan_application.state(
    name="Loan Type Selection",
    instruction="Ask user to select loan type. We only offer personal loan, home loan, and car loan at the moment.",
)


# highlight-start
# Tool for state q2
submit_loan_application = PreDefinedTool().http_tool(HttpToolRequest(
        name="submit_loan_application",
        description="Called when loan request is approved and sumitted.",
        url="https://videosdk.free.beeceptor.com/apply",
        method="POST"
    )
)

q2 = loan_application.state(
    name="Review and Confirm",
    instruction="Review all loan details with the user and get confirmation.",
    tool=submit_loan_application
)
# highlight-end

# Master / Off-topic handler
q_master = loan_application.state(
    name="Off-topic Handler",
    instruction="Handle off-topic or inappropriate inputs respectfully and end the call politely",
    master=True
)
```



### Step 4: Define Transitions


Now, link the states together using transitions. You specify the `from_state`, `to_state`, and a `condition` that must be met to trigger the transition.

```python title="main.py"
# Greeting → Loan Type Selection
loan_application.transition(
    from_state=q0,
    to_state=q1,
    condition="User ready to apply for loan"
)

# Branch from Loan Type Selection
loan_application.transition(
    from_state=q1,
    to_state=q1a,
    condition="User wants personal loan"
)

# Merge all branches → Loan Amount Collection
loan_application.transition(
    from_state=q1a,
    to_state=q2,
    condition="Personal loan details collected and verified"
)
# ... More Transitions ...
```



### Step 5: Integrate with the Agent Pipeline


Finally, pass the `conversational_graph` to your `CascadingPipeline`.

```python title="main.py"
class VoiceAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are a helpful voice assistant that can assist you with your loan applications")
        
    async def on_enter(self) -> None:
        await self.session.say("Hello, I am here to help with your loan application. How can I help you today?", interruptible=False)
    
    async def on_exit(self) -> None:
        await self.session.say("Goodbye!")
  
async def entrypoint(ctx: JobContext):
    
    agent = VoiceAgent()
    conversation_flow = ConversationFlow(agent)

    # highlight-start
    pipeline = CascadingPipeline(
        stt= DeepgramSTT(),
        llm=OpenAILLM(),
        tts=GoogleTTS(),
        vad=SileroVAD(),
        turn_detector=TurnDetector(),
        conversational_graph = loan_application
    )
    # highlight-end
    
    session = AgentSession(
        agent=agent, 
        pipeline=pipeline,
        conversation_flow=conversation_flow
    )

    await session.start(wait_for_participant=True, run_until_shutdown=True)

def make_context() -> JobContext:
    room_options = RoomOptions(room_id="<room_id>", name="Workflow Agent", playground=True)
    
    return JobContext(room_options=room_options)

if __name__ == "__main__":
    job = WorkerJob(entrypoint=entrypoint, jobctx=make_context)
    job.start()
```





## Working Example

- [Conversational Graph Example](https://github.com/videosdk-live/agents/blob/main/examples/test_workflow_pipeline.py): Check out the complete working example of a Loan Application agent using Conversational Graph.



---

# De-noise  
  
De-noise improves audio quality in your AI agent conversations by filtering out background noise. This creates more professional and engaging interactions, especially in noisy environments.  
  
## Overview  
  
The VideoSDK Agents framework provides real-time audio denoising capabilities via `RNNoise` plugin that:  
  
- **Remove Background Noise**: Filters out ambient sounds, keyboard typing, air conditioning, and other distractions  
- **Enhance Voice Clarity**: Improves speech intelligibility and quality  
- **Work in Real-time**: Processes audio with minimal latency during live conversations  
- **Integrate Seamlessly**: Works with both `CascadingPipeline` and `RealTimePipeline` architectures  
  
## What De-noise Solves  
  
Without noise removal, your agents may struggle with:  
- Poor audio quality affecting transcription accuracy  
- Background noise interfering with conversation flow  
- Unprofessional sound quality in business applications  
- Difficulty understanding users in noisy environments  
  
With De-noise, you get:  
- Crystal clear audio for better user experience  
- Improved speech-to-text accuracy  
- Professional-grade audio quality  
- Better performance in various acoustic environments  
  
## RNNoise Implementation  
  
`RNNoise` is a real-time noise suppression library that uses deep learning to distinguish between speech and noise, providing effective background noise removal.  
  
### Key Features  
  
- **Real-time Processing**: Low-latency noise removal suitable for live conversations  
- **Adaptive Filtering**: Automatically adjusts to different types of background noise  
- **Speech Preservation**: Maintains voice quality while removing unwanted sounds  
- **Lightweight**: Efficient processing with minimal computational overhead  
  
### Basic Setup  
  
```python  
from videosdk.plugins.rnnoise import RNNoise  
  
# Initialize noise removal 
denoise = RNNoise()
```

## Pipeline Integration

**Cascading Pipeline:**

Add noise removal to your cascading pipeline:

```python title="main.py"
from videosdk.agents import Agent, CascadingPipeline, AgentSession  
# highlight-start
from videosdk.plugins.rnnoise import RNNoise  
# highlight-end
# Add your preferred providers  
from videosdk.plugins.deepgram import DeepgramSTT  
from videosdk.plugins.openai import OpenAILLM  
from videosdk.plugins.elevenlabs import ElevenLabsTTS  
from videosdk.plugins.silero import SileroVAD  
  
class EnhancedVoiceAgent(Agent):  
def __init__(self):  
    super().__init__(  
        instructions="You are a professional assistant with crystal-clear audio quality. Help users with their questions while maintaining excellent conversation flow."  
    )  
  
async def on_enter(self):  
    await self.session.say("Hello! I'm here with enhanced audio quality for our conversation.")  
  
async def on_exit(self):  
    await self.session.say("Goodbye! It was great talking with you.")  
  
# Set up pipeline with noise removal  
pipeline = CascadingPipeline(  
stt=DeepgramSTT(api_key="your-deepgram-key"),  
llm=OpenAILLM(api_key="your-openai-key", model="gpt-4"),  
tts=ElevenLabsTTS(api_key="your-elevenlabs-key", voice_id="your-voice-id"),  
vad=SileroVAD(),  
# highlight-start
denoise=RNNoise()  # Enable noise removal  
# highlight-end
)  
  
# Create and start session  
async def main():  
session = AgentSession(agent=EnhancedVoiceAgent(), pipeline=pipeline)  
await session.start()  
  
if __name__ == "__main__":  
import asyncio  
asyncio.run(main())
```

---

**Real-time Pipeline:**

Integrate with real-time models:

```python title="main.py"
from videosdk.agents import Agent, RealTimePipeline, AgentSession
# highlight-start  
from videosdk.plugins.rnnoise import RNNoise  
# highlight-end
from videosdk.plugins.openai import OpenAIRealtime  
  
class EnhancedRealtimeAgent(Agent):  
def __init__(self):  
    super().__init__(  
        instructions="You are a professional assistant with crystal-clear audio quality. Engage in natural, real-time conversations while providing helpful responses."  
    )  
  
async def on_enter(self):  
    await self.session.say("Hello! I'm ready for a real-time conversation with enhanced audio quality.")  
  
async def on_exit(self):  
    await self.session.say("Thank you for the conversation! Take care.")  
  
# Set up real-time model  
model = OpenAIRealtime(  
model="gpt-4o-realtime-preview",  
api_key="your-openai-key",  
voice="alloy"  # Choose from: alloy, echo, fable, onyx, nova, shimmer  
)  
  
# Set up pipeline with noise removal  
pipeline = RealTimePipeline(  
model=model,  
# highlight-start
denoise=RNNoise()  # Enable noise removal  
# highlight-end
)  
  
# Create and start session  
async def main():  
session = AgentSession(agent=EnhancedRealtimeAgent(), pipeline=pipeline)  
await session.start()  
  
if __name__ == "__main__":  
import asyncio  
asyncio.run(main())
```



## Audio Processing Flow

When noise removal is enabled, audio processing follows this flow:

1. **Raw Audio Input:** Microphone captures audio with background noise
2. **Noise Removal:** `RNNoise` filters out unwanted sounds
3. **Enhanced Audio:** Clean audio is passed to speech processing
4. **Improved Results:** Better transcription and conversation quality






## Example - Try Out Yourself

- [Enhanced Pronounciation Example](https://github.com/videosdk-live/agents/blob/main/examples/enhanced_pronounciation.py): Checkout example with enhanced voice and noise removal



---

DTMF (Dual-Tone Multi-Frequency) events happen when a caller presses keys (0–9, *, #) on their phone or SIP device during a call.
AI agents can listen for these events to capture user input, run specific actions, or respond to the caller based on the key they pressed. DTMF provides a simple and reliable way for users to interact with the agent during a call.

## How It Works

- **DTMF Event Detection**: The agent detects key presses (0–9, *, #) from the caller during a call session.
- **Real-Time Processing**: Each key press generates a DTMF event that is delivered to the agent immediately.
- **Callback Integration**: A user-defined callback function handles incoming DTMF events.
- **Action Execution**: The agent executes actions or triggers workflows based on the received DTMF input like building IVR flows, collecting user input, or triggering actions in your application.

## How to enable DTMF Events

### Step 1 : Activate DTMF Detection

DTMF event detection can be enabled in two ways:

**dashboard:**

When creating an Inbound SIP gateway in the VideoSDK dashboard, enable the `DTMF` option.

![dtmf-event](https://assets.videosdk.live/images/DTMF-events.png)

---

**api:**

Set the `enableDtmf` parameter to `true` when creating or updating a SIP gateway using the API.
  ```bash
  curl 	-H 'Authorization: $YOUR_TOKEN' \ 
	-H 'Content-Type: application/json' \ 
	-d '{
		"name" : "Twilio Inbound Gateway",
  "enableDtmf" : "true",
		"numbers" : ["+0123456789"]

	}' \ 
	-XPOST https://api.videosdk.live/v2/sip/inbound-gateways
```

### Step 2 : Implementation

To set up inbound calls, outbound calls, and routing rules check out the [Quick Start Example](https://docs.videosdk.live/telephony/managing-calls/making-outbound-calls).

```python title="main.py"
from videosdk.agents import AgentSession, DTMFHandler

async def entrypoint(ctx: JobContext):
  
    async def dtmf_callback(digit: int):
        if digit == 1:
            agent.instructions = "You are a Sales Representative. Your goal is to sell our products"
            await agent.session.say(
                "Routing you to Sales. Hi, I'm from Sales. How can I help you today?"
            )
        elif digit == 2:
            agent.instructions = "You are a Support Specialist. Your goal is to help customers with technical issues."
            await agent.session.say(
                "Routing you to Support. Hi, I'm from Support. What issue are you facing?"
            )
        else:
            await agent.session.say(
                "Invalid input. Press 1 for Sales or 2 for Support."
            )

    #highlight-start
    dtmf_handler = DTMFHandler(dtmf_callback)
    #highlight-end

    session = AgentSession(
        #highlight-start
        dtmf_handler = dtmf_handler,
        #highlight-end
    )
```
## Example - Try It Yourself

- [DTMF Event Example](https://github.com/videosdk-live/agents-quickstart/blob/main/DTMF%20Handler/dtmf_handler.py): Check out full working example of the DTMF Event Example


---

# Fallback Adapter

The `Fallback Adapter` provides automatic failover between multiple STT, LLM, or TTS providers.
If a provider becomes unavailable, the system automatically switches to the next configured provider without interrupting the session.

## Features

- **Automatic Fallback**: Switches to lower-priority providers if the primary provider fails.
- **Cooldown-based Retry**: Implements a cooldown period before retrying a failed provider, preventing immediate repeated failures.
- **Auto-Recovery**: Automatically switches back to a higher-priority provider once it becomes healthy again.
- **Permanent Disable**: Permanently disables a provider after a configured number of failed recovery attempts.

## Example Usage

Here is how you can implement fallback providers for STT, LLM, and TTS in your agent configuration.

```python
from videosdk.agents import FallbackSTT, FallbackLLM, FallbackTTS
from videosdk.plugins.openai import OpenAISTT, OpenAILLM, OpenAITTS
from videosdk.plugins.deepgram import DeepgramSTT
from videosdk.plugins.cerebras import CerebrasLLM
from videosdk.plugins.cartesia import CartesiaTTS

# Configure Fallback STT
stt_provider = FallbackSTT(
    [OpenAISTT(), DeepgramSTT()],
    temporary_disable_sec=30.0,
    permanent_disable_after_attempts=3
)

# Configure Fallback LLM
llm_provider = FallbackLLM(
    [OpenAILLM(model="gpt-4o-mini"), CerebrasLLM()],
    temporary_disable_sec=30.0,
    permanent_disable_after_attempts=3
)

# Configure Fallback TTS
tts_provider = FallbackTTS(
    [OpenAITTS(voice="alloy"), CartesiaTTS()],
    temporary_disable_sec=30.0,
    permanent_disable_after_attempts=3
)
```

## Configuration Options

You can configure the fallback behavior using the following parameters:

| Parameter | Description |
| :--- | :--- |
| `temporary_disable_sec` | The duration (in seconds) to wait before retrying a failed provider. |
| `permanent_disable_after_attempts` | The maximum number of recovery attempts allowed before a provider is permanently disabled. |

## Examples - Try Out Yourself

- [Fallback Adapter](https://github.com/videosdk-live/agents/blob/main/examples/fallback_recovery.py): Checkout the full implementation on github


---

# Memory

Give your AI agents the ability to remember past interactions and user preferences. By integrating a memory provider, your agent can move beyond the limits of its immediate context window to deliver truly personalized and context-aware conversations.

## How Memory Enhances Conversations

A standard LLM's memory is limited to its context window. A dedicated memory provider solves this by creating a persistent, intelligent storage layer that recalls information across different sessions.

![Memory-enabled Conversation Flow](https://assets.videosdk.live/images/voice-agent-memory-manager.png)

As the diagram shows, the agent intelligently stores key facts and retrieves them in later conversations to provide a personalized, efficient interaction.

## Implementation with Mem0

This guide demonstrates how to implement long-term memory using [**Mem0**](https://mem0.ai/), an open-source platform designed to give AI agents a persistent memory layer.

This example creates a "Concierge Agent" that remembers returning users. We will break down the implementation into logical steps.

:::note
The following sections outline the steps you might follow. For a complete working example, see the GitHub repository:

- https://github.com/videosdk-live/agents-quickstart/tree/main/Memory
  :::

### Prerequisites

- A Mem0 API key, available from the [Mem0 dashboard](https://app.mem0.ai/).
- Ensure your agent environment is set up per the [AI Voice Agent Quickstart](/ai_agents/voice-agent-quick-start). This is the baseline app where we'll implement the memory features in the steps below.

### Step 1: Create a Dedicated Memory Manager


Start by creating a memory manager class that abstracts your chosen memory provider's API. This class should handle three core operations: storing memories, retrieving memories, and deciding what to remember.

The key is to implement a `should_store` method that intelligently determines which conversations are worth remembering based on keywords, user intent, or other criteria you define.

```python title="memory_utils.py"
from mem0.client.main import AsyncMemoryClient

class Mem0MemoryManager:
    """Handles all interactions with the Mem0 API."""
    def __init__(self, api_key: str, user_id: str):
        self.user_id = user_id
        self._client = AsyncMemoryClient(api_key=api_key)

    async def fetch_recent_memories(self, limit: int = 5) -> list[str]:
        """Retrieves the most recent memories for the user."""
        try:
            response = await self._client.get_all(filters={"user_id": self.user_id}, limit=limit)
            return [entry.get("memory", "") for entry in response]
        except Exception as e:
            print(f"Error fetching memories: {e}")
            return []

    def should_store(self, user_message: str) -> bool:
        """Determines if a message contains keywords indicating a fact to remember."""
        keywords = ("remember", "preference", "my name is", "likes", "dislike")
        return any(keyword in user_message.lower() for keyword in keywords)

    async def record_memory(self, user_message: str, assistant_message: str | None = None):
        """Stores a conversational turn in Mem0."""
        # ... implementation to call self._client.add()
```



### Step 2: Accessing Memory to Personalize the Agent


Implement memory retrieval at session startup to personalize your agent's behavior. Create a function that fetches relevant user memories and injects them into your agent's system prompt or context.

Consider how you want to use retrieved memories: for personalized greetings, context-aware responses, or maintaining conversation continuity across sessions.

```python title="main.py"
class MemoryAgent(Agent):
    def __init__(self, instructions: str, remembered_facts: list[str] | None = None):
        self._remembered_facts = remembered_facts or []
        super().__init__(instructions=instructions)

    async def on_enter(self):
        # Use the retrieved facts for a personalized greeting
        if self._remembered_facts:
            top_fact = "; ".join(self._remembered_facts[:2])
            await self.session.say(f"Welcome back! I remember that {top_fact}. What can I help you with?")
        else:
            await self.session.say("Hello! How can I help today?")

# This helper function runs at the start of the session
async def build_agent_instructions(memory_manager: Mem0MemoryManager | None) -> tuple[str, list[str]]:
    base_instructions = "You are a helpful voice concierge..."
    if not memory_manager:
        return base_instructions, []

    # Fetches memories and adds them to the system prompt
    remembered_facts = await memory_manager.fetch_recent_memories()
    if not remembered_facts:
        return base_instructions, []

    memory_lines = "\n".join(f"- {fact}" for fact in remembered_facts)
    enriched_instructions = f"{base_instructions}\n\nKnown details about this caller:\n{memory_lines}"
    return enriched_instructions, remembered_facts
```



### Step 3: Storing New Memories with a Custom Conversation Flow


Extend your conversation flow to capture and store new memories during interactions. If you are new to flows, review the core concepts in the [Conversation Flow](./conversation-flow.md) guide. Override the conversation flow's main processing method to evaluate each user message after the agent responds.

The goal is to identify valuable information (user preferences, personal details, important facts) and store it without impacting response latency. You can implement this as a post-processing step or integrate it into your existing conversation handling logic.

:::tip
Want a deeper dive or to run this locally?

- Review core concepts in the [Conversation Flow](./conversation-flow.md) guide.
- To run your agent, follow the [AI Voice Agent Quickstart](/ai_agents/voice-agent-quick-start).
  :::

```python title="memory_utils.py"
from videosdk.agents import ConversationFlow

class Mem0ConversationFlow(ConversationFlow):
    """A custom flow that records memories after each turn."""
    def __init__(self, agent: Agent, memory_manager: Mem0MemoryManager, **kwargs):
        super().__init__(agent=agent, **kwargs)
        self._memory_manager = memory_manager
        self._pending_user_message: str | None = None

    async def run(self, transcript: str):
        self._pending_user_message = transcript
        # First, let the standard conversation turn happen
        full_response = "".join([chunk async for chunk in super().run(transcript)])

        # After the response, decide if the turn should be stored in memory
        if self._pending_user_message and self._memory_manager.should_store(self._pending_user_message):
            await self._memory_manager.record_memory(self._pending_user_message, full_response or None)

        self._pending_user_message = None
```



### Step 4: Assembling the Agent Session


Integrate all components in your main application entry point. Initialize your memory manager, use it to build personalized agent instructions, and configure your session with the enhanced conversation flow.

This is where you connect the memory system to your agent's lifecycle, ensuring memories are loaded at startup and new information is captured during conversations.

```python title="main.py"
async def start_session(context: JobContext):
    # 1. Setup memory manager
    memory_manager = Mem0MemoryManager(api_key=os.getenv("MEM0_API_KEY"), user_id="demo-user")

    # 2. Build agent with personalized instructions
    instructions, facts = await build_agent_instructions(memory_manager)
    agent = MemoryAgent(instructions=instructions, remembered_facts=facts)

    # 3. Setup conversation flow with memory capabilities
    conversation_flow = Mem0ConversationFlow(agent=agent, memory_manager=memory_manager, ...)

    # 4. Create the session with the custom flow
    session = AgentSession(
        agent=agent,
        pipeline=pipeline, # your pipeline
        conversation_flow=conversation_flow
    )

    # ... rest of your session and job context setup
```

This creates a powerful feedback loop where each interaction enriches the agent's knowledge, leading to smarter and more personalized conversations over time.


### Step 5: Run the Agent


Start your worker process and connect the agent to a room using a `JobContext`. This boots your agent and keeps it running.

```python title="main.py"
from videosdk.agents import WorkerJob, JobContext, RoomOptions

def make_context() -> JobContext:
    return JobContext(room_options=RoomOptions(name="Concierge Agent", playground=True))

if __name__ == "__main__":
    WorkerJob(entrypoint=start_session, jobctx=make_context).start()
```

This will initialize the session using your `start_session` function from Step 4 and keep the worker alive.



## Example - Try It Yourself

Explore our complete, runnable example on GitHub to see how to integrate a memory provider into a VideoSDK AI Agent.

- [Memory Agent Example](https://github.com/videosdk-live/agents-quickstart/tree/main/Memory): A complete example demonstrating how to use Mem0 to give your AI agent long-term memory.



---

Multi agent switching allows you to break a complex workflow into multiple specialized agents, each responsible for a specific domain or task. Instead of relying on a single agent to manage every tool and decision, you can coordinate smaller agents that operate independently.

### Context Inheritance

When switching agents, you can control whether the new agent should be aware of the previous conversation using the `inherit_context` flag.

- **`inherit_context=True`**: The new agent receives the full chat context. This is ideal for maintaining continuity, so the user doesn't have to repeat information.
- **`inherit_context=False`** (Default): The new agent starts with a fresh state. This is useful when switching to a completely unrelated task.

## How It Works

- The primary VideoSDK agent identifies whether specialized assistance is needed based on the users intent.
- It invokes a `function tool` to switch to the appropriate specialized agent.
- Control automatically shifts to the new agent and has access to the previous chat context as `inherit_context=True` was passed.
- The specialized agent handles the user’s request, and complete the interaction.

### Implementation

```python title="main.py"
from videosdk.agents import Agent, function_tool, 

class TravelAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="""You are a travel assistant. Help users with general travel inquiries and guide them to booking when needed.""",
        )

    async def on_enter(self) -> None:
        await self.session.reply(instructions="Greet the user and ask how you can help with their travel plans.")

    async def on_exit(self) -> None:
        await self.session.say("Safe travels!")

    @function_tool()
    async def transfer_to_booking(self) -> Agent:
        """Transfer the user to a booking specialist for reservations and scheduling."""
        return BookingAgent(inherit_context=True)

class BookingAgent(Agent):
    def __init__(self, inherit_context: bool = False):
        super().__init__(
            instructions="""You are a booking specialist. Help users book or modify flights, hotels, and travel reservations.""",
            inherit_context=inherit_context
        )

    async def on_enter(self) -> None:
        await self.session.say("I'm a booking specialist. What would you like to book or modify today?")

    async def on_exit(self) -> None:
        await self.session.say("Your booking request is complete. Have a great trip!")

```

## Example - Try It Yourself

- [Travel Agent Example](https://github.com/videosdk-live/agents-quickstart/tree/main/Multi%20Agent%20Switch/Travel%20Agent): Check out full working implementation of the Travel Agent Example
- [Health Care Agent Example](https://github.com/videosdk-live/agents-quickstart/blob/main/Multi%20Agent%20Switch/Health%20Care%20agent/): Implement Health Care Agent Example


---

The VideoSDK AI Agent SDK provides a powerful framework for building AI agents that can participate in real-time conversations. This guide explains the core components and demonstrates how to create a complete agentic workflow. The SDK serves as a real-time bridge between AI models and your users, facilitating seamless voice and media interactions.

## Architecture

The Agent Session orchestrates the entire workflow, combining the Agent with a Pipeline for real-time communication. You can use a direct Realtime Pipeline for speech-to-speech, or a Cascading Pipeline with a Conversation Flow for modular STT-LLM-TTS control.

![Overview](https://cdn.videosdk.live/website-resources/docs-resources/build_agent_section_overview.png)

1. **Agent** - This is the base class for defining your agent's identity and behavior. Here, you can configure custom instructions, manage its state, and register function tools.
2. **Pipeline** - This component manages the real-time flow of audio and data between the user and the AI models. The SDK offers two types of pipelines:
   - **Realtime Pipeline** - A speech to speech pipeline where there is no need for converting speech to text or text to speech and no llm to configure in between.
   - **Cascading Pipleine** - The traditional STT-LLM-TTS pipeline which allows flexibility to mix and match different providers for Speech-to-Text (STT), Large Language Models (LLM), and Text-to-Speech (TTS).
3. **Agent Session** - This component brings together the agent, pipeline, and conversation flow to manage the agent's lifecycle within a VideoSDK meeting.
4. **Conversation Flow** - This inheritable class works with the CascadingPipeline to let you define custom turn-taking logic and preprocess transcripts.

## Supporting Components

These components work behind the scenes to support the core functionality of the AI Agent SDK:

- Execution & Lifecycle Management

  - **JobContext** - Provides the execution environment and lifecycle management for AI agents. It encapsulates the context in which an agent job is running.

  - **WorkerJob** - Manages the execution of jobs and worker processes using Python's multiprocessing, allowing for concurrent agent operations.

- Configuration & Settings

  - **RoomOptions** - This allows you to configure the behavior of the session, including room settings and other advanced features for the agent's interaction within a meeting.

  - **Options** - This is used to configure the behavior of the worker, including logging and other execution settings.

- External Integration

  - **MCP Servers** - These enable the integration of external tools through either stdio or HTTP transport.
    - **MCPServerStdio** - Facilitates direct process communication for local Python scripts.
    - **MCPServerHTTP** - Enables HTTP-based communication for remote servers and services.

## Advanced Features

The AI Agent SDK includes a range of advanced features to build sophisticated conversational agents:


- [Session Management](https://docs.videosdk.live/ai_agents/core-components/agent-session): Control session timeouts and configure agents to auto-end conversations
- [Playground Mode](https://docs.videosdk.live/ai_agents/core-components/agent-session#playground-mode): A testing environment to experiment with different agent configurations
- [Vision Integration](https://docs.videosdk.live/ai_agents/core-components/vision-and-multi-modality): Enable agents to receive and process video input from the meeting
- [Recording Capabilities](https://docs.videosdk.live/ai_agents/core-components/recording): Record agent sessions for analysis and quality assurance
- [A2A Communication](https://docs.videosdk.live/ai_agents/a2a/overview): Allows for seamless collaboration between specialized AI agents
- [MCP Server Integration](https://docs.videosdk.live/ai_agents/mcp-integration): Connect agents to external tools and data sources


## Examples - Try Out Yourself

We have examples to get you started. Go ahead, try out, talk to agent and customize according to your needs.

- [Avatar Integration](https://github.com/videosdk-live/agents/tree/main/examples/avatar): Enhance user experience with realistic, lip-synced virtual avatars
- [Human in the loop](https://github.com/videosdk-live/agents/tree/main/examples/human_in_the_loop): Implement human intervention capabilities in AI agent conversations for better control and oversight
- [Enhanced Pronounciation](https://github.com/videosdk-live/agents/blob/main/examples/enhanced_pronounciation.py): Improve speech quality and pronunciation accuracy for better user experience and communication clarity
- [PubSub Messaging](https://github.com/videosdk-live/agents/blob/main/examples/pubsub_example.py): Facilitates real-time messaging between agent and client



---

# Preemptive Response

Preemptive Response is a feature that allows the Speech-to-Text (STT) engine to produce **partial, low-latency text output** while the user is still speaking. This is crucial for building highly responsive conversational AI agents.

By enabling preemptive response, your agent can begin processing the user's intent and formulating a response before the full utterance is completed, significantly reducing the perceived latency.

## How It Works

![preemtive-response](https://assets.videosdk.live/images/preemptive-response.png)

- User audio is streamed to the STT, which generates partial transcripts.
- These partial transcripts are immediately sent to the LLM to enable preemptive (early) responses.
- The LLM output is then passed to the TTS to generate the spoken response.


## Prerequisites

Ensure you have the required packages installed:

```text
pip install "videosdk-agents[deepgram,openai,elevenlabs,silero,turn_detector]"
```
:::tip
Currently, preemptive response generation is limited to Deepgram’s STT implementation and is available only in the Flux model.
:::

## Enabling Preemptive Generation

To enable this feature, set the `enable_preemptive_generation` flag to `True` when initializing your STT plugin (e.g., `DeepgramSTTV2`).

```python
from videosdk.plugins.deepgram import DeepgramSTTV2

stt = DeepgramSTTV2(
    enable_preemptive_generation=True
)
```


## Full Working Example

The following example demonstrates how to build a voice agent with preemptive transcription enabled. This setup uses Deepgram for STT, OpenAI for LLM, and ElevenLabs for TTS.

```python
import asyncio
import os
from videosdk.agents import Agent, AgentSession, CascadingPipeline, JobContext, RoomOptions, WorkerJob, ConversationFlow
from videosdk.plugins.silero import SileroVAD
from videosdk.plugins.turn_detector import TurnDetector, pre_download_model
from videosdk.plugins.deepgram import DeepgramSTTV2
from videosdk.plugins.openai import OpenAILLM
from videosdk.plugins.elevenlabs import ElevenLabsTTS

# Pre-download the Turn Detector model to avoid delays during startup
pre_download_model()

class MyVoiceAgent(Agent):
    def __init__(self):
        super().__init__(instructions="You are a helpful voice assistant that can answer questions and help with tasks.")

    async def on_enter(self):
        await self.session.say("Hello! How can I help you today?")

    async def on_exit(self):
        await self.session.say("Goodbye!")

async def start_session(context: JobContext):
    # 1. Create the agent and conversation flow
    agent = MyVoiceAgent()
    conversation_flow = ConversationFlow(agent)

    # 2. Define the pipeline with Preemptive Generation enabled
    pipeline = CascadingPipeline(
        stt=DeepgramSTTV2(
            model="flux-general-en",
            enable_preemptive_generation=True  # Enable low-latency partials
        ),
        llm=OpenAILLM(model="gpt-4o"),
        tts=ElevenLabsTTS(model="eleven_flash_v2_5"),
        vad=SileroVAD(threshold=0.35),
        turn_detector=TurnDetector(threshold=0.8)
    )

    # 3. Initialize the session
    session = AgentSession(
        agent=agent,
        pipeline=pipeline,
        conversation_flow=conversation_flow
    )

    try:
        await context.connect()
        await session.start()
        # Keep the session running
        await asyncio.Event().wait()
    finally:
        # Clean up resources
        await session.close()
        await context.shutdown()

def make_context() -> JobContext:
    room_options = RoomOptions(
        name="VideoSDK Cascaded Agent",
        playground=True
    )
    return JobContext(room_options=room_options)

if __name__ == "__main__":
    job = WorkerJob(entrypoint=start_session, jobctx=make_context)
    job.start()
```


---

# Pub/Sub Messaging

Pub/Sub (Publish/Subscribe) messaging enables real-time, bidirectional communication between your AI agent and client applications within a VideoSDK meeting. This allows you to build interactive experiences where the client can send commands or data to the agent, and the agent can push updates or notifications back to the client, all without relying on voice.

![Pub/Sub Architecture Diagram](https://strapi.videosdk.live/uploads/user_agent_pubsub_chat_e62ce8f209.png)

## Key Features

- **Send Messages**: Agents can publish messages to any specified Pub/Sub topic, which can be received by any participant (including client applications) subscribed to that topic.
- **Receive Messages**: Agents can subscribe to topics to receive messages published by client applications or other participants.
- **Bidirectional Flow**: Communication is not one-way. Both the agent and the client can publish and subscribe, enabling a fully interactive loop.
- **Decoupled Communication**: The client and agent do not need to know about each other's existence directly. They communicate through shared topics, which simplifies the architecture.

## Implementation

Implementing Pub/Sub involves two main parts: subscribing to topics to receive messages and publishing messages. Subscribing is typically the first step on both the agent and client side.



Use the tabs below to see how to subscribe to a Pub/Sub topic across the AI Agent and client SDKs.

**ai-agent:**

```python title="Subscribe on Room Context"
from videosdk import PubSubSubscribeConfig

def on_client_message(message):
print(f"Received: {message}")

await ctx.room.subscribe_to_pubsub(PubSubSubscribeConfig(
topic="CHAT",
cb=on_client_message
))
```

---

**javascript:**

```js title="Subscribe on meeting join"
// Subscribe to CHAT
meeting.on("meeting-joined", () => {
  meeting.pubSub.subscribe("CHAT", (data) => {
const { message, senderId, senderName, timestamp } = data;
console.log("Client command:", message);
  });
});
```

---

**react:**

```js title="usePubSub hook"

function ClientCommands() {
  usePubSub("CHAT", {
onMessageReceived: ({ message, senderId }) => {
  console.log("Client command:", message);
},
  });
  return null;
}
```

---

**react-native:**

```js title="usePubSub hook"

function ClientCommands() {
  const { messages } = usePubSub("CHAT", {
onMessageReceived: (message) => {
  console.log("Client command:", message.message);
},
  });
  return null;
}
```

---

**ios:**

```swift title="Subscribe with listener"
class ClientCommandsListener: PubSubMessageListener {
  func onMessageReceived(message: PubSubMessage) {
print("Client command: \(message.message)")
  }
}
let listener = ClientCommandsListener()
meeting?.pubsub.subscribe(topic: "CHAT", forListener: listener)
```

---

**android:**

```kotlin title="Subscribe with listener"
val listener = PubSubMessageListener { message ->
  Log.d("PubSub", "Client command: ${message.message}")
}
meeting?.pubSub?.subscribe("CHAT", listener)
```

---

**flutter:**

```dart title="Subscribe with handler"
void messageHandler(PubSubMessage message) {
  print("Client command: ${message.message}");
}
final messages = await room.pubSub.subscribe(
  "CHAT",
  messageHandler,
);
```





The most effective way for an agent to publish messages is by exposing a `function_tool`. This allows the LLM to decide when to send a message based on the conversation.

To publish, you use `PubSubPublishConfig` and call the `publish_to_pubsub` method on the `JobContext` room object.

```python
from videosdk import PubSubPublishConfig
from videosdk.agents import Agent, function_tool, JobContext

class MyPubSubAgent(Agent):
    def __init__(self, ctx: JobContext):
        super().__init__(
            instructions="You can send messages to the client using the send_message tool."
        )
        self.ctx = ctx

    @function_tool
    async def send_message_to_client(self, message: str):
        """Sends a text message to the client application on the 'CHAT' topic."""
        publish_config = PubSubPublishConfig(
            topic="CHAT",
            message=message
        )
        await self.ctx.room.publish_to_pubsub(publish_config)
        return f"Message '{message}' sent to client."
```





To receive messages, the agent must subscribe to a topic using `PubSubSubscribeConfig` and the `subscribe_to_pubsub` method, which registers a callback function to handle incoming messages. This setup is typically done in your main `entrypoint` function after connecting to the room.

```python
import asyncio
from videosdk import PubSubSubscribeConfig
from videosdk.agents import JobContext

# Define the callback function that will process incoming messages
def on_client_message(message):
    print(f"Received message from client: {message}")
    # Add your logic here to process the message.
    # For example, you could pass it to the agent's pipeline.

async def entrypoint(ctx: JobContext):
    # ... (agent and session setup)

    try:
        await ctx.connect()
        await ctx.room.wait_for_participant()

        # Configure the subscription
        subscribe_config = PubSubSubscribeConfig(
            topic="CHAT",
            cb=on_client_message
        )
        # Subscribe to the topic
        await ctx.room.subscribe_to_pubsub(subscribe_config)

        # Start the agent session
        await session.start()
        await asyncio.Event().wait()

    finally:
        await session.close()
        await ctx.shutdown()
```



## Best Practices

- **Topic Naming Conventions**: Use clear and consistent topic names (e.g., `CHAT`, `AGENT_STATUS`) to keep your application organized.
- **Structured Data**: Use JSON for your message payloads. This makes messages easy to parse and allows for sending complex data structures.
- **Error Handling**: Your callback function should gracefully handle malformed or unexpected messages to prevent crashes.
- **Asynchronous Callbacks**: If your callback function performs long-running tasks, make sure it is `async` and consider running tasks in the background with `asyncio.create_task()` to avoid blocking the main event loop.

## Example - Try Out Yourself

Check out our quickstart repository for a complete, runnable example of an agent using Pub/Sub.

- [Pub/Sub Example](https://github.com/videosdk-live/agents-quickstart/tree/main/Pubsub): A complete, runnable example demonstrating how to send and receive Pub/Sub messages with an AI agent.



---

# RAG (Retrieval-Augmented Generation) integration

**RAG** helps your AI agent find relevant information from documents to give better answers. It searches through your knowledge base and uses that context to respond more accurately.

## Architecture

![RAG](https://cdn.videosdk.live/website-resources/docs-resources/voice_agent_rag.png)

The RAG pipeline flow:

1.  **Voice Input** → Deepgram STT converts speech to text
2.  **Retrieval** → Query embeddings fetch relevant documents from ChromaDB
3.  **Augmentation** → Retrieved context is injected into the prompt
4.  **Generation** → OpenAI LLM generates a grounded response
5.  **Voice Output** → ElevenLabs TTS converts response to speech

## Managed RAG
With Managed RAG, you can upload knowledge bases from the VideoSDK dashboard and attach them to your agent to enhance responses using retrieval-augmented generation.

#### Step 1 : Upload Knowledge Base on the dashboard



#### Step 2 : Configure it in Cascading Pipeline

After uploading, the Knowledge Base is assigned a unique ID(as shown in Step 1), which you can use to load it, enabling the agent to fetch relevant information during conversations.

```python title="main.py"
import os
from videosdk.agents import KnowledgeBase, KnowledgeBaseConfig

# Initialize Knowledge Base with ID from Dashboard
kb_id = os.getenv("KNOWLEDGE_BASE_ID")
config = KnowledgeBaseConfig(id=kb_id, top_k=3)

# Load Knowledge Base and pass it to the agent
agent = VoiceAgent(
    knowledge_base=KnowledgeBase(config)
)
```

## Custom RAG

### Prerequisites

- Install VideoSDK agents with all dependencies:

  ```bash
  pip install "videosdk-agents[deepgram,openai,elevenlabs,silero,turn_detector]"
  pip install chromadb openai numpy
  ```

- Set API keys in envrionment:

  ```shell title=".env"
  DEEPGRAM_API_KEY = "Your Deepgram API Key"
  OPENAI_API_KEY = "Your OpenAI API Key"
  ELEVENLABS_API_KEY = "Your ElevenLabs API Key"
  VIDEOSDK_AUTH_TOKEN = "VideoSDK Auth token"
  ```

:::tip
For a complete working example with all the code integrated together, check out our GitHub repository: [RAG Implementation Example](https://github.com/videosdk-live/agents-quickstart/blob/main/RAG/rag.py)
:::

## Implementation

### Step 1: Custom Voice Agent with RAG

Create a custom agent class that extends `Agent` and adds retrieval capabilities:

```python title="main.py"
class VoiceAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="""You are a helpful voice assistant that answers questions
            based on provided context. Use the retrieved documents to ground your answers.
            If no relevant context is found, say so. Be concise and conversational."""
        )

        # Initialize OpenAI client for embeddings
        self.openai_client = AsyncOpenAI(api_key=os.getenv("OPENAI_API_KEY"))

        # Define your knowledge base
        self.documents = [
            "What is VideoSDK? VideoSDK is a comprehensive video calling and live streaming platform...",
            "How do I authenticate with VideoSDK? Use JWT tokens generated with your API key...",
            # Add more documents
        ]

        # Set up ChromaDB
        self.chroma_client = chromadb.Client()  # In-memory
        # For persistence: chromadb.PersistentClient(path="./chroma_db")
        self.collection = self.chroma_client.create_collection(
            name="videosdk_faq_collection"
        )

        # Generate embeddings and populate database
        self._initialize_knowledge_base()

    def _initialize_knowledge_base(self):
        """Generate embeddings and store documents."""
        embeddings = [self._get_embedding_sync(doc) for doc in self.documents]
        self.collection.add(
            documents=self.documents,
            embeddings=embeddings,
            ids=[f"doc_{i}" for i in range(len(self.documents))]
        )
```

### Step 2: Embedding Generation

Implement both synchronous (for initialization) and asynchronous (for runtime) embedding methods:

```python title="main.py"
    def _get_embedding_sync(self, text: str) -> list[float]:
        """Synchronous embedding for initialization."""
        import openai
        client = openai.OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
        response = client.embeddings.create(
            input=text,
            model="text-embedding-ada-002"
        )
        return response.data[0].embedding

    async def get_embedding(self, text: str) -> list[float]:
        """Async embedding for runtime queries."""
        response = await self.openai_client.embeddings.create(
            input=text,
            model="text-embedding-ada-002"
        )
        return response.data[0].embedding
```

### Step 3: Retrieval Method

Add semantic search capability:

```python title="main.py"
    async def retrieve(self, query: str, k: int = 2) -> list[str]:
        """Retrieve top-k most relevant documents from vector database."""
        # Generate query embedding
        query_embedding = await self.get_embedding(query)

        # Query ChromaDB
        results = self.collection.query(
            query_embeddings=[query_embedding],
            n_results=k
        )

        # Return matching documents
        return results["documents"][0] if results["documents"] else []
```

### Step 4: Agent Lifecycle Hooks

Define agent behavior on entry and exit:

```python title="main.py"
    async def on_enter(self) -> None:
        """Called when agent session starts."""
        await self.session.say("Hello! I'm your VideoSDK assistant. How can I help you today?")

    async def on_exit(self) -> None:
        """Called when agent session ends."""
        await self.session.say("Thank you for using VideoSDK. Goodbye!")
```

### Step 5: Custom Conversation Flow

Override the conversation flow to inject retrieved context:

```python title="main.py"
class RAGConversationFlow(ConversationFlow):
    async def run(self, transcript: str) -> AsyncIterator[str]:
        """
        Process user input with RAG pipeline.
        Args:
            transcript: User's speech transcribed to text
        Yields:
            Generated response chunks
        """
        # Step 1: Retrieve relevant documents
        context_docs = await self.agent.retrieve(transcript)

        # Step 2: Format context
        if context_docs:
            context_str = "\n\n".join([f"Document {i+1}: {doc}"
                                      for i, doc in enumerate(context_docs)])
        else:
            context_str = "No relevant context found."

        # Step 3: Inject context into conversation
        self.agent.chat_context.add_message(
            role="system",
            content=f"Retrieved Context:\n{context_str}\n\nUse this context to answer the user's question."
        )

        # Step 4: Generate response with LLM
        async for response_chunk in self.process_with_llm():
            yield response_chunk
```

### Step 6: Session and Pipeline Setup

Configure the agent session and start the job:

```python title="main.py"
async def entrypoint(ctx: JobContext):
    agent = VoiceAgent()

    conversation_flow = RAGConversationFlow(
        agent=agent,
    )

    session = AgentSession(
        agent=agent,
        pipeline=CascadingPipeline(
            stt=DeepgramSTT(),
            llm=OpenAILLM(),
            tts=ElevenLabsTTS(),
            vad=SileroVAD(),
            turn_detector=TurnDetector()
        ),
        conversation_flow=conversation_flow,
    )

    # Register cleanup
    ctx.add_shutdown_callback(lambda: session.close())

    # Start agent
    try:
        await ctx.connect()
        print("Waiting for participant...")
        await ctx.room.wait_for_participant()
        print("Participant joined - starting session")
        await session.start()
        await asyncio.Event().wait()
    except KeyboardInterrupt:
        print("\nShutting down gracefully...")
    finally:
        await session.close()
        await ctx.shutdown()

def make_context() -> JobContext:
    room_options = RoomOptions(name="RAG Voice Assistant", playground=True)
    return JobContext(room_options=room_options)

if __name__ == "__main__":
    job = WorkerJob(entrypoint=entrypoint, jobctx=make_context)
    job.start()
```

## Advanced Features

### Dynamic Document Updates

Add documents at runtime:

```python title="main.py"
async def add_document(self, document: str, metadata: dict = None):
    """Add a new document to the knowledge base."""
    doc_id = f"doc_{len(self.documents)}"
    embedding = await self.get_embedding(document)
    self.collection.add(
        documents=[document],
        embeddings=[embedding],
        ids=[doc_id],
        metadatas=[metadata] if metadata else None
    )
    self.documents.append(document)
```

### Document Chunking

Split large documents for better retrieval:

```python title="main.py"
def chunk_document(self, document: str, chunk_size: int = 500, overlap: int = 50) -> list[str]:
    """Split document into overlapping chunks."""
    words = document.split()
    chunks = []
    for i in range(0, len(words), chunk_size - overlap):
        chunk = " ".join(words[i:i + chunk_size])
        chunks.append(chunk)
    return chunks

# Use when adding documents
for doc in large_documents:
    chunks = self.chunk_document(doc)
    for chunk in chunks:
        self.documents.append(chunk)
```

#### Best Practices

1. Document Quality: Use clear, well-structured documents with specific information
2. Chunk Size: Keep chunks between 300-800 words for optimal retrieval
3. Retrieval Count: Start with k=2-3, adjust based on response quality and latency
4. Context Window: Ensure retrieved context fits within LLM token limits
5. Persistent Storage: Use PersistentClient in production to save embeddings
6. Error Handling: Always handle retrieval failures gracefully
7. Testing: Test with diverse queries to ensure good coverage

#### Common Issues

| Issue              | Solution                                                                      |
| ------------------ | ----------------------------------------------------------------------------- |
| Slow responses     | Reduce retrieval count (k), use faster embedding model, or cache embeddings   |
| Irrelevant results | Improve document quality, adjust chunking strategy, or use metadata filtering |
| Out of memory      | Use PersistentClient instead of in-memory Client                              |


---

# RealTime Pipeline

The `Realtime Pipeline` provides direct speech-to-speech processing with minimal latency. It uses unified models that handle the entire audio processing pipeline in a single step, offering the fastest possible response times for conversational AI.

![Realtime Pipeline Architecture](https://cdn.videosdk.live/website-resources/docs-resources/videosdk_realtime_pipeline.png)

:::tip
The `RealTimePipeline` is specifically designed for real-time AI models that provide end-to-end speech processing which is better for conversational agent. For use cases requiring more granular control over individual components (STT, LLM, TTS) for context support and response control, the [CascadingPipeline ↗](https://docs.videosdk.live/ai_agents/core-components/cascading-pipeline) would be more appropriate.
:::



## Basic Usage

Setting up a `RealTimePipeline` is straightforward. You simply need to initialize your chosen real-time model and pass it to the pipeline's constructor.

```python title="main.py"
from videosdk.agents import RealTimePipeline
from videosdk.plugins.openai import OpenAIRealtime, OpenAIRealtimeConfig

# Initialize the desired real-time model
model = OpenAIRealtime(
    model="gpt-4o-realtime-preview",
    config=OpenAIRealtimeConfig(
        voice="alloy",
        response_modalities=["AUDIO"]
    )
)

# Create the pipeline with the model
pipeline = RealTimePipeline(model=model)
```

In addition to [OpenAI ↗](https://docs.videosdk.live/ai_agents/plugins/realtime/openai), the Realtime Pipeline also supports other advanced models like [Google Gemini (Live API) ↗](https://docs.videosdk.live/ai_agents/plugins/realtime/google-live-api) and [AWS Nova Sonic ↗](https://docs.videosdk.live/ai_agents/plugins/realtime/aws-nova-sonic), each offering unique features for building high-performance conversational agents, you can check their pages for advance configuration options.


- [OpenAI](https://docs.videosdk.live/ai_agents/plugins/realtime/openai): More about OpenAI Realtime Plugin
- [Google Gemini](https://docs.videosdk.live/ai_agents/plugins/realtime/google-live-api): More about Gemini Realtime Plugin
- [AWS Nova Sonic](https://docs.videosdk.live/ai_agents/plugins/realtime/aws-nova-sonic): More about AWSNovaSonic Realtime Plugin




<div style={{marginTop: '2rem'}}></div>

:::tip

- Choose a model based on its optimal audio sample rate (OpenAI/Nova Sonic: 16kHz, Gemini: 24kHz) to best fit your needs.

- For cloud providers like AWS, select the server region closest to your users to minimize network latency.

:::

## Custom Model Integration

To integrate a custom real-time model, you need to implement the `RealtimeBaseModel` interface, which requires implementing methods like `connect()`, `handle_audio_input()`, `send_message()`, and `interrupt()`.

```python title="main.py"
from videosdk.agents import RealtimeBaseModel, Agent, CustomAudioStreamTrack
from typing import Literal, Optional
import asyncio

class CustomRealtime(RealtimeBaseModel[Literal["user_speech_started", "error"]]):
    """Custom real-time AI model implementation"""

    def __init__(self, model_name: str, api_key: str):
        super().__init__()
        self.model_name = model_name
        self.api_key = api_key
        self.audio_track: Optional[CustomAudioStreamTrack] = None
        self._instructions = ""
        self._tools = []
        self._connected = False

    def set_agent(self, agent: Agent) -> None:
        """Set agent instructions and tools"""
        self._instructions = agent.instructions
        self._tools = agent.tools

    async def connect(self) -> None:
        """Initialize connection to your AI service"""
        # Your connection logic here
        self._connected = True
        print(f"Connected to {self.model_name}")

    async def handle_audio_input(self, audio_data: bytes) -> None:
        """Process incoming audio from user"""
        if not self._connected:
            return

        # Process audio and generate response
        # Your audio processing logic here

        # Emit user speech detection
        self.emit("user_speech_started", {"type": "detected"})

        # Generate and play response audio
        if self.audio_track:
            response_audio = b"your_generated_audio_bytes"
            await self.audio_track.add_new_bytes(response_audio)

    async def send_message(self, message: str) -> None:
        """Send text message to model"""
        # Your text processing logic here
        pass

    async def interrupt(self) -> None:
        """Interrupt current response"""
        if self.audio_track:
            self.audio_track.interrupt()

    async def aclose(self) -> None:
        """Cleanup resources"""
        self._connected = False
        if self.audio_track:
            await self.audio_track.cleanup()
```

## Comparison with Cascading Pipeline

The key architectural difference is that `RealTimePipeline` uses integrated models that handle the entire speech-to-speech pipeline internally, while cascading pipelines coordinate separate STT, LLM, and TTS components.

| Feature         | Realtime Pipeline                                                                   | Cascading Pipeline                                                                                |
| :-------------- | :---------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ |
| **Latency**     | Significantly lower latency, ideal for highly interactive, real-time conversations. | Higher latency due to coordinating separate STT, LLM, and TTS components.                         |
| **Control**     | Less granular control; tools are handled directly by the integrated model.          | Granular control over each step (STT, LLM, TTS), allowing for more complex logic.                 |
| **Flexibility** | Limited to the capabilities of the single, chosen real-time model.                  | Allows mixing and matching different providers for each component (e.g., Google STT, OpenAI LLM). |
| **Complexity**  | Simpler to configure as it involves a single, unified model.                        | More complex to set up due to the coordination of multiple separate components.                   |
| **Cost**        | Varies depending on the chosen real-time model and usage patterns.                  | Varies depending on the combination of providers and usage for each component.                    |

## Examples - Try Out Yourself

We have examples to get you started. Go ahead, try out, talk to agent, understand and customize according to your needs.

- [Basic Implementation](https://github.com/videosdk-live/agents/blob/main/examples/test_realtime_pipeline.py): Checkout the realtime pipeline implementation
- [OpenAI](https://github.com/videosdk-live/agents-quickstart/tree/main/OpenAI): Implement with OpenAI
- [Google Gemini (LiveAPI)](https://github.com/videosdk-live/agents-quickstart/tree/main/Google%20Gemini%20(LiveAPI)): Implement with Google Gemini (LiveAPI)
- [AWS Nova Sonic](https://github.com/videosdk-live/agents-quickstart/tree/main/AWS%20Nova%20Sonic): Implement with AWS Nova Sonic



---

# Recording  
  
Recording capabilities in VideoSDK Agents allow you to capture and store meeting conversations, enabling features like conversation analysis, compliance documentation, and quality assurance. VideoSDK provides three distinct recording approaches, each suited for different use cases and requirements.
 
  
## Recording Types Overview
VideoSDK offers three types of recording functionality:

1. **Participant Recording** - Built-in automatic recording managed by the agent framework
2. **Track Recording** - Individual audio/video track recording with granular control
3. **Meeting Recording** - Complete meeting session recording with composite output


## 1. Participant Recording (Built-in)

Participant recording is the simplest approach, automatically managed by the VideoSDK Agents framework when you enable the `recording` parameter.

### How It Works

When recording=True is set in RoomOptions, the system automatically:

- Starts recording when the agent joins the meeting.
- Starts recording for each participant as they join.
- Stops and merges recordings when the session ends.

### Basic Setup

```python title="main.py"
from videosdk.agents import JobContext, RoomOptions  
  
def make_context():  
    return JobContext(  
        room_options=RoomOptions(  
            room_id="your-room-id",  
            auth_token="your-auth-token",   
            name="Recording Agent",  
            #highlight-start
            recording=True  # Enable automatic participant recording  
            #highlight-end
        )  
    )
```


## 2. Track Recording

Track recording provides granular control over individual audio and video tracks, allowing you to record specific streams with custom configurations.

### When to Use Track Recording

- Need to record specific audio/video tracks separately
- Require custom recording configurations per track
- Want to control recording start/stop timing manually
- Need different quality settings for different tracks

### Key Features

- **Individual Control**: Start/stop recording for specific tracks
- **Custom Configuration**: Set different recording parameters per track
- **Flexible Output**: Choose output formats and quality settings
- **Manual Management**: Full control over recording lifecycle

### API References for Track Recording

- [Start Track Recording](https://docs.videosdk.live/api-reference/realtime-communication/start-track-recording): This API lets you record a track of participant of your room by passing roomId, participantId and kind as body parameters.
- [Stop Track Recording](https://docs.videosdk.live/api-reference/realtime-communication/stop-track-recording): This API lets you stop recording of track of participant of your room by passing roomId, participantId and kind as a body parameter.
- [Fetch a Track Recording](https://docs.videosdk.live/api-reference/realtime-communication/fetch-a-track-recording): This API lets you fetch a particular track recording info by passing trackRecordingId as parameter.
- [Fetch All Track Recordings](https://docs.videosdk.live/api-reference/realtime-communication/fetch-all-track-recordings): This API lets you fetch details of your track recording by passing roomId, sessionId and participantId as query parameters.
- [Delete A Track Recording](https://docs.videosdk.live/api-reference/realtime-communication/delete-track-recording): This API lets you delete a particular track recording by passing trackRecordingId as parameter.




## 3. Meeting Recording

Meeting recording captures the entire meeting session as a single composite recording, including all participants and their interactions.

### When to Use Meeting Recording

- Need a single recording file for the entire meeting
- Want automatic mixing of all audio/video streams
- Require meeting-level recording controls
- Need simplified post-processing workflow

### Key Features

- **Composite Output**: Single recording file with all participants
- **Automatic Mixing**: Audio/video streams automatically combined
- **Meeting-level Control**: Start/stop recording for entire meeting
- **Simplified Management**: One recording per meeting session


### API References for Meeting Recording

- [Start Recording](https://docs.videosdk.live/api-reference/realtime-communication/start-recording): This API lets you record your room by passing roomId and config object as body parameters.
- [Stop Recording](https://docs.videosdk.live/api-reference/realtime-communication/stop-recording): This API lets you stop recording of your room by passing roomId as a body parameter.
- [Fetch Recordings](https://docs.videosdk.live/api-reference/realtime-communication/fetch-recordings): This API lets you fetch details of your recording by passing roomId and sessionId as query parameters.
- [List all Recordings](https://docs.videosdk.live/api-reference/realtime-communication/fetch-recording-using-recordingId): This API lets you fetch a particular recording info by passing recording Id as parameter.
- [Delete a Recording](https://docs.videosdk.live/api-reference/realtime-communication/delete-recording): This API lets you delete a particular recording by passing recording Id as parameter.


## Choosing the Right Recording Type

| Use Case | Recommended Type | Reason |
| :--- | :--- | :--- |
| Agent conversations with automatic management | Participant Recording | Built-in automation and channel separation |
| Custom recording workflows | Track Recording | Granular control over individual streams |
| Simple meeting archival | Meeting Recording | Single composite file for entire meeting |
| Compliance and audit trails | Participant Recording | Automatic lifecycle management |
| Advanced post-processing | Track Recording | Individual track access and control |


## Best Practices

### Recording Management

- Choose the appropriate recording type based on your use case
- Ensure proper authentication tokens for recording API access
- Monitor recording status and handle errors gracefully
- Plan for adequate storage capacity

### Privacy and Compliance

- Inform participants that sessions are being recorded
- Implement proper data retention and deletion policies
- Ensure compliance with local privacy regulations
- Use appropriate recording type for your compliance requirements





---

---  
id: room-options  
title: RoomOptions  
hide_title: false  
hide_table_of_contents: false  
description: "Learn how to configure RoomOptions for VideoSDK AI Agents to customize meeting connection, agent behavior, and session management."  
pagination_label: "RoomOptions"  
keywords:  
  - RoomOptions  
  - AI Agents Configuration  
  - Meeting Connection  
  - Agent Settings  
  - VideoSDK Agents  
  - Session Management  
  - Python SDK  
  - Agent Identity  
  - Playground Mode  
image: img/videosdklive-thumbnail.jpg  
sidebar_position: 12  
sidebar_label: RoomOptions  
slug: room-options  
---  
  
# RoomOptions  
  
`RoomOptions` is a configuration class that defines how an AI agent connects to and behaves within a VideoSDK meeting room. It serves as the primary interface for customizing agent behavior, meeting connection parameters, and session management settings.  
  
## Introduction  
  
The `RoomOptions` class is the central configuration point for VideoSDK AI agents, providing comprehensive control over how agents join meetings, interact with participants, and manage their sessions. This configuration is passed to the `JobContext` during agent initialization and influences all aspects of the agent's behavior within the meeting environment.  
  
## Core Features  
  
- **Meeting Connection**: Configure room ID and authentication for VideoSDK meetings  
- **Agent Identity**: Set display name and visual representation  
- **Session Management**: Control automatic session termination and timeouts  
- **Media Capabilities**: Enable vision processing and meeting recording  
- **Development Tools**: Playground mode for testing and development  
- **Error Handling**: Custom error handling callbacks  
- **Avatar Integration**: Support for virtual avatars  
  
## Basic Example  
  
```python title="main.py"
from videosdk.agents import RoomOptions, JobContext  
  
# Basic configuration  
room_options = RoomOptions(  
    room_id="your-meeting-id",  
    name="My AI Agent",  
    playground=True  
)  
  
# Create job context 
context = JobContext(room_options=room_options)
```

## Parameters

Parameters that you can pass with `RoomOptions`:

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `room_id` | Optional[str] | None | Unique identifier for the VideoSDK meeting |
| `auth_token` | Optional[str] | None | VideoSDK authentication token |
| `name` | Optional[str] | "Agent" | Display name of the agent in the meeting |
| `playground` | bool | True | Enable playground mode for easy testing |
| `vision` | bool | False | Enable video processing capabilities |
| `recording` | bool | False | Enable meeting recording |
| `avatar` | Optional[Any] | None | Virtual avatar for visual representation |
| `join_meeting` | Optional[bool] | True | Whether agent should join the meeting |
| `on_room_error` | Optional[Callable] | None | Error handling callback function |
| `auto_end_session` | bool | True | Automatically end session when participants leave |
| `session_timeout_seconds` | Optional[int] | 30 | Timeout for automatic session termination |
| `signaling_base_url` | Optional[str] | None | Custom VideoSDK signaling server URL |


## Additional Resources


- [Playground Mode](https://docs.videosdk.live/ai_agents/core-components/agent-session#playground-mode): A testing environment to experiment with different agent configurations
- [Vision Integration](https://docs.videosdk.live/ai_agents/core-components/vision-and-multi-modality): Enable agents to receive and process video input from the meeting
- [Recording Capabilities](https://docs.videosdk.live/ai_agents/core-components/recording): Record agent sessions for analysis and quality assurance
- [Avatar](https://docs.videosdk.live/ai_agents/core-components/avatar): Use Avatar for visually engaging AI Voice Agent



---

# Speech Handle

Speech control in VideoSDK agents operates through two complementary layers: **session-level** methods for initiating speech and **utterance-level** handles for managing speech lifecycle. This document covers both aspects of controlling agent speech output.

## Session-Level Speech Control

The `AgentSession` provides three primary methods for controlling agent speech output

**1. Say**

`say(message: str, interruptible: bool = True)`: 
Sends a direct message from the agent to meeting participants with interruption control.

**Parameters:**

- `message`: The message to be spoken.
- `interruptible`: When `True`, the agent’s speech can be interrupted. When `False`, the agent will continue speaking until the message is fully delivered. Default is `True`.

```python
# Basic usage  
# highlight-start
await session.say("Critical update!", interruptible=False)  
# highlight-end
  
# In agent lifecycle hooks  
class MyAgent(Agent):  
    async def on_enter(self):  
        # highlight-start
        await self.session.say("Welcome to the meeting!")
        # highlight-end
```

**2. Reply**

`reply(instructions: str, wait_for_playback: bool = True, interruptible: bool = True)`: 
Generates agent responses dynamically using custom instructions with interruption control.

**Parameters:**

- `instructions`: Custom instructions for generating the response
- `wait_for_playback`: When `True`, prevents user interruptions until playback completes
- `interruptible`: When `True`, the agent’s response can be interrupted. When `False`, the agent will continue speaking without interruption. Default is `True`.

```python
# Generate immediate response  
# highlight-start
await session.reply(instructions="Please summarize the conversation so far", interruptible=False)  
# highlight-end
  
# Wait for complete playback before allowing new inputs  
# highlight-start
await session.reply(  
    instructions="Explain the next steps",   
    wait_for_playback=True  
)  
# highlight-end
  
# Practical example in function tools  
class MyAgent(Agent):  
    @function_tool  
    async def get_summary(self) -> str:  
        #highlight-start
        await self.session.reply(  
            instructions="Based on our conversation, let me provide a summary..."  
        )  
        #highlight-end
        return "Summary generated"
```

**3. Interrupt**

`interrupt()`: 
Immediately stops the agent's current speech operation.

```python
# Emergency stop during agent response  
# highlight-start
session.interrupt()
# highlight-end  

# User interruption handling  
class InteractiveAgent(Agent):  
    async def handle_user_input(self, user_input: str):  
        if "stop" in user_input.lower():  
            #highlight-start
            self.session.interrupt()  
            #highlight-end
            await self.session.reply(instructions="How can I help you instead?")  
      
    @function_tool  
    async def emergency_stop(self) -> str:  
        """Stop current agent operation immediately"""  
        # highlight-start
        self.session.interrupt()  
        # highlight-end
        return "Agent stopped successfully"
```

## Utterance-Level Management

`UtteranceHandle` manages individual agent utterances, preventing overlapping speech and enabling graceful interruption handling.


### Core Concepts

- **Lifecycle Management**
    - Each `UtteranceHandle` tracks a single utterance from creation through completion.

- **Completion States**

    An utterance can complete in two ways:
    1. **Natural Completion:** The TTS finishes playing the audio
    2. **User Interruption:** The user starts speaking during playback

- **Awaitable Pattern**
    - The handle supports Python's async/await syntax for sequential speech control.

### API Reference

| Property/Method | Return Type | Description |
|------------------|--------------|--------------|
| `id` | `str` | Unique identifier for the utterance |
| `done()` | `bool` | Returns `True` if utterance is complete |
| `interrupted` | `bool` | Returns `True` if user interrupted |
| `interrupt()` | `None` | Manually marks utterance as interrupted |
| `__await__()` | `Generator` | Enables awaiting the handle |

### Usage Patterns

- **Sequential Speech**

    To prevent overlapping TTS, await each handle before starting the next utterance:

    ```python
    # Correct approach  
    handle1 = self.session.say(f"The current temperature is {temperature}°C.")  
    await handle1  # Wait for first utterance to complete  
    
    handle2 = self.session.say("Do you live in this city?")  
    await handle2  # Wait for second utterance to complete
    ```

- **Checking Interruption Status**

    Access the current utterance handle via `self.session.current_utterance` to detect interruptions:

    ```python
    utterance: UtteranceHandle | None = self.session.current_utterance  
    
    # In long-running operations, check periodically  
    for i in range(10):  
        if utterance and utterance.interrupted:  
            logger.info("Task was interrupted by the user.")  
            return "The task was cancelled because you interrupted me."  
        
        await asyncio.sleep(1)
    ```

### Best Practices

- **Sequential Speech:** Always await handles when you need sequential speech to prevent audio overlap
- **Interruption Handling:** Check `interrupted` status in long-running operations to enable graceful cancellation
- **Handle References:** Store handle references if you need to check status later in your function
- **Avoid Concurrent Tasks:** Don't use `create_task()` for speech that should play sequentially

### Common Use Cases

- **Multi-part responses:** When function tools need to speak multiple sentences in sequence
- **Long-running operations:** Tasks that should be cancellable when users interrupt
- **Conversational flows:** Scenarios requiring precise timing between utterances

## Example - Try It Yourself

- [Utterence handle example](https://github.com/videosdk-live/agents/blob/main/examples/utterance_handle_agent.py): Checkout the interruption handle implementation via the utterence handle functionality


## FAQs

### Troubleshooting

| Issue | Solution |
|--------|-----------|
| Overlapping speech | Use `await` on handles instead of `create_task()` |
| Tasks not cancelling on interruption | Check `utterance.interrupted` in loops |
| Handle is None | Only available during function tool execution via `session.current_utterance` |

### Correct Usage Pattern

#### ✅ Correct: Sequential Speech
Await each handle to prevent overlapping TTS.
```python
handle1 = session.say("First")
await handle1
handle2 = session.say("Second")
await handle2
```
---
#### ❌ Incorrect: Concurrent Speech
Using `create_task()` causes audio overlap.
```python
asyncio.create_task(session.say("First"))
asyncio.create_task(session.say("Second"))
```

---

# Testing and Evaluation

The VideoSDK Agent SDK provides a structured evaluation framework that allows you to run controlled tests on individual agent components: Speech-to-Text (STT), Large Language Models (LLM), and Text-to-Speech (TTS) and collect performance metrics such as latency, accuracy, and stability.

## Evaluation Components

To test your agent, use the `Evaluation` class. This allows you to define different scenarios (called "turns") and run them to see how your agent performs.

Key components include:
- **`Evaluation`**: Runs all your test scenarios.
- **`EvalTurn`**: Represents a single conversational turn, one complete exchange where the user gives input and the agent processes it to provide a response.
- **`EvalMetric`**: Measurements like `STT_LATENCY`, `LLM_LATENCY`, etc.
- **`LLMAsJudge`**: Uses an LLM to "judge" the quality of your agent's response.

These are the criteria the Judge can use to evaluate the agent:

| Metric | Description |
| :--- | :--- |
| **REASONING** | Explains *why* the agent responded in a certain way. Useful for debugging logic. |
| **RELEVANCE** | Checks if the response actually answers the user's question. |
| **CLARITY** | Checks if the response is easy to understand. |
| **SCORE** | Gives a numerical rating (0-10) for the quality of the response. |

## Implementation

The following steps explain how to set up a test for your agent.

### 1. Import Libraries

First, import the necessary modules from the SDK.

```python
import logging
import aiohttp
from videosdk.agents import (
    Evaluation, EvalTurn, EvalMetric, LLMAsJudgeMetric, 
    LLMAsJudge, STTEvalConfig, LLMEvalConfig, TTSEvalConfig, 
    STTComponent, LLMComponent, TTSComponent, function_tool
)

# Set up logging to see the output
logging.basicConfig(level=logging.INFO)
```

### 2. Define Tools

If your agent uses tools (like checking the weather), you need to define them here so the evaluation can use them.

```python
@function_tool
async def get_weather(
    latitude: str,
    longitude: str,
):
    """
    Called when the user asks about the weather. Returns the weather for the given location.
    
    Args:
        latitude: The latitude of the location
        longitude: The longitude of the location
    """
    print("### Getting weather for", latitude, longitude)
    url = f"https://api.open-meteo.com/v1/forecast?latitude={latitude}&longitude={longitude}&current=temperature_2m"
    weather_data = {}
    try:
        async with aiohttp.ClientSession() as session:
            async with session.get(url) as response:
                if response.status == 200:
                    data = await response.json()
                    print("Weather data", data)
                    weather_data = {
                        "temperature": data["current"]["temperature_2m"],
                        "temperature_unit": "Celsius",
                    }
                else:
                    print(f"Failed to get weather data, status code: {response.status}")
                    raise Exception(f"Failed to get weather data, status code: {response.status}")
    except Exception as e:
        print(f"Exception in get_weather tool: {e}")
        raise e

    return weather_data
```

### 3. Setup Evaluation

Create an `Evaluation` instance. You can specify which metrics you want to track.

```python
eval = Evaluation(
    name="basic-agent-eval",
    include_context=False,
    metrics=[
        EvalMetric.STT_LATENCY,
        EvalMetric.LLM_LATENCY,
        EvalMetric.TTS_LATENCY,
        EvalMetric.END_TO_END_LATENCY
    ],
    output_dir="./reports"
)
```

**Parameters:**

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `name` | `str` | Name of the evaluation suite. |
| `include_context` | `bool` | Whether to include conversation context. |
| `metrics` | `list` | List of metrics to calculate (e.g., `EvalMetric.STT_LATENCY`). |
| `output_dir` | `str` | Directory to save the evaluation reports. |


### 4. Add Test Scenarios (Turns)

Add "turns" to your evaluation. A turn simulates a single complete interaction loop (Input -> Processing -> Response) between the user and the agent. You can mix and match mock inputs (text) and real inputs (audio files).

#### Scenario 1: Complex Interaction
Here, we test the full pipeline:
1.  **STT**: Transcribes an audio file (`sample.wav`).
2.  **LLM**: Receives a mock text input (overriding the STT output for this test) and uses the `get_weather` tool.
3.  **TTS**: Generates speech from a mock text string.
4.  **Judge**: An LLM reviews the answer to see if it is relevant.

:::warning Note
Only `.wav` files are supported for STT evaluation. Please ensure your audio files are in this format.
:::

```python
eval.add_turn(
    EvalTurn(
        stt=STTComponent.deepgram(
            STTEvalConfig(file_path="./sample.wav") 
        ),
        llm=LLMComponent.google(
            LLMEvalConfig(
                model="gemini-2.5-flash-lite",
                use_stt_output=False, 
                mock_input="write one paragraph about Water and get weather of Delhi",
                tools=[get_weather]
            )
        ),
        tts=TTSComponent.google(
            TTSEvalConfig(
                model="en-US-Standard-A",
                use_llm_output=False,
                mock_input="Peter Piper picked a peck of pickled peppers"  
            )
        ),
        judge=LLMAsJudge.google(
            model="gemini-2.5-flash-lite",
            prompt="Can you evaluate the agent's response based on the following criteria: Is it relevant to the user input?",
            checks=[LLMAsJudgeMetric.REASONING, LLMAsJudgeMetric.SCORE]
        )
    )
)
```

**Configuration Parameters:**

**STTEvalConfig:**

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `file_path` | `str` | Path to the audio file. **Note:** Only `.wav` files are supported. |

---

**LLMEvalConfig:**

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `model` | `str` | The LLM model to use (e.g., `gemini-2.5-flash-lite`). |
| `use_stt_output` | `bool` | If `True`, uses the output from the STT stage as input. |
| `mock_input` | `str` | Text input to use if `use_stt_output` is `False`. |
| `tools` | `list` | List of tool functions available to the LLM. |

---

**TTSEvalConfig:**

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `model` | `str` | The TTS model to use. |
| `use_llm_output` | `bool` | If `True`, uses the output from the LLM stage as input. |
| `mock_input` | `str` | Text input to use if `use_llm_output` is `False`. |

---

**LLMAsJudge:**

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `model` | `str` | The LLM model to use for judging. |
| `prompt` | `str` | The prompt/criteria for the judge. |
| `checks` | `list` | List of metrics to check (e.g., `LLMAsJudgeMetric.REASONING`, `LLMAsJudgeMetric.SCORE`). |


#### Scenario 2: End-to-End Flow
This scenario uses the output from one step as the input for the next. The STT output is fed into the LLM, and the LLM output is fed into the TTS.

```python
eval.add_turn(
    EvalTurn(
        stt=STTComponent.deepgram(
            STTEvalConfig(file_path="./Sports.wav") 
        ),
        llm=LLMComponent.google(
            LLMEvalConfig(
                model="gemini-2.5-flash-lite",
                use_stt_output=True, # Use the text from STT
            )
        ),
        tts=TTSComponent.google(
            TTSEvalConfig(
                model="en-US-Standard-A",
                use_llm_output=True # Use the text from LLM
            )
        ),
        judge=LLMAsJudge.google(
            model="gemini-2.5-flash-lite",
            prompt="Is the response relevant?",
            checks=[LLMAsJudgeMetric.REASONING, LLMAsJudgeMetric.SCORE]
        )
    )
)
```

#### Scenario 3: Individual Component Testing
You can also test components in isolation.

**STT Only:**

```python
eval.add_turn(
EvalTurn(
    stt=STTComponent.deepgram(
        STTEvalConfig(file_path="./Sports.wav") 
    )
)
)
```

---

**LLM Only:**

```python
eval.add_turn(
EvalTurn(
    llm=LLMComponent.google(
        LLMEvalConfig(
            model="gemini-2.5-flash-lite",
            use_stt_output=False, 
            mock_input="write one paragraph about trees",
        )
    ),
)
)
```

---

**TTS Only:**

```python
eval.add_turn(
EvalTurn(
     tts=TTSComponent.google(
        TTSEvalConfig(
            model="en-US-Standard-A",
            use_llm_output=False,
            mock_input="A big black bug bit a big black bear, made the big black bear bleed blood."
        )
    )
)
)
```

### 5. Run and Save Results

Finally, run the evaluation and save the report. The report will be saved to the `output_dir`.

```python
results = eval.run()
results.save()
```

## Examples - Try It Out Yourself

- [Evaluation Example](https://github.com/videosdk-live/agents/blob/main/examples/eval.py): A complete example of setting up and running evaluations for your agent.


---

# Turn Detection and Voice Activity Detection

In conversational AI, timing is everything. Traditional voice agents rely on simple silence-based timers (Voice Activity Detection or VAD) to guess when a user has finished speaking. This often leads to awkward interruptions or unnatural pauses.

To solve this, VideoSDK created **Namo-v1**: an open-source, high-performance turn-detection model that understands the _meaning_ of the conversation, not just the silence.

![Namo Turn Detection](https://strapi.videosdk.live/uploads/namo_v1_turn_detection_12e042c6ec.png)

## From Silence Detection to Speech Understanding

Namo shifts from basic audio analysis to sophisticated Natural Language Understanding (NLU), allowing your agent to know when a user is truly finished speaking versus just pausing to think.

| Traditional VAD (Silence-Based)                 | Namo Turn Detector (Semantic-Based)                      |
| :---------------------------------------------- | :------------------------------------------------------- |
| **Listens for silence.**                        | **Understands words and context.**                       |
| Relies on a fixed timer (e.g., 800ms).          | Uses a transformer model to predict intent.              |
| Often interrupts or lags.                       | Knows when to wait and when to respond instantly.        |
| Struggles with natural pauses and filler words. | Distinguishes between a brief pause and a true endpoint. |

This semantic understanding enables AI agents to respond quicker and more naturally, creating a fluid, human-like conversational experience.

:::tip Learn More
For a deep dive into Namo's architecture, performance benchmarks, and how to use it as a standalone model, check out the dedicated [**Namo Turn Detector plugin page**](/ai_agents/plugins/namo-turn-detector).
:::

## Implementation

For the most robust setup, you can use VAD and Namo together. VAD acts as a basic speech detector, while Namo intelligently decides if the turn is over.

### 1. Voice Activity Detection (VAD)

First, configure VAD to detect the presence of speech. This helps manage interruptions and acts as a first-pass filter.

```python
from videosdk.plugins.silero import SileroVAD

# Configure VAD to detect speech activity
vad = SileroVAD(
    threshold=0.5,                    # Sensitivity to speech (0.3-0.8)
    min_speech_duration=0.1,          # Ignore very brief sounds
    min_silence_duration=0.75         # Wait time before considering speech ended
)
```

### 2. Namo Turn Detection

Next, add the `NamoTurnDetectorV1` plugin to analyze the content of the speech and predict the user's intent.

#### Multilingual Model

If your agent needs to support multiple languages, use the default multilingual model. It's a single, powerful model that works across more than 20 languages.

```python
from videosdk.plugins.turn_detector import NamoTurnDetectorV1, pre_download_namo_turn_v1_model

# Pre-download the multilingual model to avoid runtime delays
pre_download_namo_turn_v1_model()

# Initialize the multilingual Turn Detector
turn_detector = NamoTurnDetectorV1(
    threshold=0.7  # Confidence level for triggering a response
)
```

The table below lists all supported languages with their performance metrics and language codes.



#### Language-Specific Models

For maximum performance and accuracy in a single language, use a specialized model. These models are faster and have a smaller memory footprint.

```python
from videosdk.plugins.turn_detector import NamoTurnDetectorV1, pre_download_namo_turn_v1_model

# Pre-download a specific language model (e.g., German)
pre_download_namo_turn_v1_model(language="de")

# Initialize the Turn Detector for German
turn_detector = NamoTurnDetectorV1(
  language="de",
  threshold=0.7
)
```



:::note
To see all available models for different languages, along with their benchmarks and accuracy, please visit our [Hugging Face models page](https://huggingface.co/videosdk-live/models).
:::

### 3. Adaptive End-of-Utterance (EOU) Handling

The **Adaptive EOU** mode dynamically adjusts the speech-wait timeout based on the confidence scores. This ensures that the agent waits longer when the user is hesitant and responds faster when the user's intent is clear, creating a more natural conversational flow.

You can configure this by setting the `eou_config` in your pipeline options:

```python
pipeline = CascadingPipeline(
    # ... other config
    eou_config=EOUConfig(
        mode='ADAPTIVE', # or 'DEFAULT'
        min_max_speech_wait_timeout=[0.5, 0.8] # Min 0.5s, Max 0.8s wait
    )
)
```

#### Configuration Parameters

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `mode` | `str` | • **DEFAULT**: Uses a fixed timeout value.<br /> • **ADAPTIVE**: Dynamically adjusts timeout based on confidence scores.|
| `min_max_speech_wait_timeout` | `list[float]` | Defines the minimum and maximum wait time (in seconds)|

##### Example

| User Input | Agent Reaction | Wait Time | Example |
|------------|----------------|-----------|---------|
| **Mode = DEFAULT**<br/>Speaks clearly | Responds immediately | ~0.5s | `“Book a meeting for tomorrow at 10.”` |
| **Mode = DEFAULT**<br/>Pauses or hesitates mid-sentence | Waits slightly longer | ~0.8s | `“Book a meeting for… um… tomorrow…”` |
| **Mode = ADAPTIVE** | Adjusts based on speech clarity | Scaled between min/max | `“Remind me to call… uh… John later.”` |


### 4. Interruption Detection (VAD + STT)

Interruption Detection controls when the system should treat user speech as an intentional interruption.
It evaluates both voice activity and recognized speech content to avoid triggering interruptions from short noises, filler words, or background audio. The agent only stops or responds when the user clearly intends to speak.

#### Configuration Example (HYBRID mode)

```python
pipeline = CascadingPipeline(
    # ... other config
    interrupt_config=InterruptConfig(
        mode="HYBRID",               
        interrupt_min_duration=0.2,  # 200ms of continuous speech
        interrupt_min_words=2,       # At least 2 words recognized
    )
)
```
#### VAD_ONLY mode

```python
pipeline = CascadingPipeline(
    # ... other config
    interrupt_config=InterruptConfig(
        mode="VAD_ONLY",               
        interrupt_min_duration=0.2,  # 200ms of continuous speech
    )
)
```

#### STT_ONLY mode

```python
pipeline = CascadingPipeline(
    # ... other config
    interrupt_config=InterruptConfig(
        mode="STT_ONLY",               
        interrupt_min_words=2,       # At least 2 words recognized
    )
)
```

#### Configuration Parameters

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `mode` | `str` |• **HYBRID** : Combines VAD and STT. Requires both audio detection and recognized words to trigger an interruption.<br />• **VAD_ONLY** : Uses only raw speech activity detection. Faster but may be triggered by background noise.<br />• **STT_ONLY** : Relies only on recognized words from the transcript. Slower but ensures speech is intelligible. |
| `interrupt_min_duration` | `float` | Minimum duration (in seconds) of continuous speech required to trigger interruption. |
| `interrupt_min_words` | `int` | Minimum number of words that must be recognized (used in `HYBRID` and `STT_ONLY` modes). |

### 5. False-Interruption Recovery

The **False-Interruption Recovery** feature detects accidental or brief user noises and allows the agent to automatically resume speaking when interruptions are not genuine. 

#### Configuration Example

```python
pipeline = CascadingPipeline(
    # ... other config
    interrupt_config=InterruptConfig(
        false_interrupt_pause_duration=2.0,  # Wait 2 seconds to confirm interruption
        resume_on_false_interrupt=True,      # Auto-resume if interruption is brief
    )
)
```

#### Configuration Parameters

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `false_interrupt_pause_duration` | `float` | Duration (in seconds) to wait after detecting an interruption before considering it false. If the user doesn't continue speaking within this time, the interruption is considered accidental and the agent resumes. |
| `resume_on_false_interrupt` | `bool` | If `True`, the agent will automatically resume speaking after detecting a false interruption. If `False`, the agent will remain paused even after brief interruptions. |

## Pipeline Integration

Combine VAD and Namo in your `CascadingPipeline` to bring it all together.

```python
from videosdk.agents import CascadingPipeline
from videosdk.plugins.silero import SileroVAD
from videosdk.plugins.turn_detector import NamoTurnDetectorV1, pre_download_namo_turn_v1_model

# Pre-download the model you intend to use
pre_download_namo_turn_v1_model(language="en")

pipeline = CascadingPipeline(
    stt=your_stt_provider,
    llm=your_llm_provider,
    tts=your_tts_provider,
    # highlight-start
    vad=SileroVAD(threshold=0.5),
    turn_detector=NamoTurnDetectorV1(language="en", threshold=0.7)
    # highlight-end
)
```

:::tip
The `RealTimePipeline` for providers like OpenAI includes built-in turn detection, so external VAD and Turn Detector components are not required.
:::

## Example Implementation

Here’s a complete example showing Namo in a conversational agent.

```python title="main.py"
from videosdk.agents import Agent, CascadingPipeline, AgentSession
from videosdk.plugins.silero import SileroVAD
from videosdk.plugins.turn_detector import NamoTurnDetectorV1, pre_download_namo_turn_v1_model
from your_providers import your_stt_provider, your_llm_provider, your_tts_provider

class ConversationalAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are a helpful assistant that waits for users to finish speaking before responding."
        )

    async def on_enter(self):
        await self.session.say("Hello! I'm listening and will respond when you're ready.")

# 1. Pre-download the model to ensure fast startup
pre_download_namo_turn_v1_model(language="en")

# 2. Set up the pipeline with Namo for intelligent turn detection
pipeline = CascadingPipeline(
    stt=your_stt_provider,
    llm=your_llm_provider,
    tts=your_tts_provider,
    # highlight-start
    vad=SileroVAD(threshold=0.5),
    turn_detector=NamoTurnDetectorV1(language="en", threshold=0.7)
    # highlight-end
)

# 3. Create and start the session
session = AgentSession(agent=ConversationalAgent(), pipeline=pipeline)
# ... connect to your call transport
```

## Examples - Try It Yourself

- [Namo Quickstart](https://github.com/videosdk-live/agents-quickstart/tree/main/Namo%20Turn%20Detector): A quickstart guide to get you started with Namo Turn Detector.
- [Cascading Pipleine](https://github.com/videosdk-live/agents/blob/main/examples/test_cascading_pipeline.py): Turn-Detection and VAD with cascading pipeline



---

# Utterence Handle

`UtteranceHandle` is a lifecycle management class for agent utterances in the videosdk-agents framework. It solves two critical problems: 
    - preventing overlapping text-to-speech (TTS) output
    - enabling graceful interruption handling when users speak during agent responses. 
This is essential for creating natural conversational experiences where agents can generate multiple sequential speech outputs without audio overlap.

## Core Concepts

### Lifecycle Management

Each `UtteranceHandle` instance tracks a single utterance from creation through completion. The handle manages state transitions automatically as the conversation progresses.

### Completion States

An utterance can complete in two ways:

1. **Natural Completion:** The TTS finishes playing the audio to completion
2. **User Interruption:** The user starts speaking, triggering an interruption

### Awaitable Pattern

The handle is compatible with Python's async/await syntax. This allows you to write sequential speech code that waits for each utterance to complete before starting the next one.

## API Reference

### Properties

| Property/Method | Return Type | Description |  
|----------------|-------------|-------------|  
| id | str | Unique identifier for the utterance |  
| done() | bool | Returns True if utterance is complete |  
| interrupted | bool | Returns True if user interrupted |  
| interrupt() | None | Manually marks utterance as interrupted |  
| __await__() | Generator | Enables awaiting the handle |

### Methods

- `interrupt()`: Manually marks the utterance as interrupted
- `__await__()`: Enables awaiting the handle to wait for completion

## Usage Patterns

### Sequential Speech 

To prevent overlapping TTS, await each handle before starting the next utterance:

```python
# Correct approach  
handle1 = self.session.say(f"The current temperature is {temperature}°C.")  
await handle1  # Wait for first utterance to complete  
  
handle2 = self.session.say("Do you live in this city?")  
await handle2  # Wait for second utterance to complete
```

### Checking Interruption Status

Access the current utterance handle via `self.session.current_utterance` in function tools to detect interruptions:

```python
utterance: UtteranceHandle | None = self.session.current_utterance  
  
# In long-running operations, check periodically  
for i in range(10):  
    if utterance and utterance.interrupted:  
        logger.info("Task was interrupted by the user.")  
        return "The task was cancelled because you interrupted me."  
      
    await asyncio.sleep(1)
```

## Anti-Pattern: Concurrent Speech

Never use `asyncio.create_task()` for speech that should be sequential, as this causes overlapping audio:

```python
# INCORRECT - causes overlapping speech  
asyncio.create_task(self.session.say(f"The current temperature is {temperature}°C."))  
asyncio.create_task(self.session.say("Do you live in this city?"))
```

## Integration with AgentSession

The `session.say()` method returns an `UtteranceHandle` instance. During function tool execution, the current utterance is accessible via `self.session.current_utterance`. The handle's lifecycle is managed automatically by the session, with completion and interruption states updated as the conversation progresses.

### Complete Example

```python
@function_tool  
async def get_weather(self, latitude: str, longitude: str) -> dict:  
    utterance: UtteranceHandle | None = self.session.current_utterance  
      
    # Fetch weather data  
    temperature = await fetch_temperature(latitude, longitude)  
      
    # Sequential speech with await  
    handle1 = self.session.say(f"The current temperature is {temperature}°C.")  
    await handle1  
      
    handle2 = self.session.say("Do you live in this city?")  
    await handle2  
      
    # Check if user interrupted  
    if utterance and utterance.interrupted:  
        return {"response": "Weather request cancelled due to user interruption."}  
      
    return {"response": f"The temperature is {temperature}°C."}
```

## Best Practices

1. Always await handles when you need sequential speech to prevent audio overlap
2. Check `interrupted` status in long-running operations to enable graceful cancellation
3. Store handle references if you need to check status later in your function
4. Avoid `create_task()` for speech that should play sequentially

## Common Use Cases

- **Multi-part responses:** When function tools need to speak multiple sentences in sequence
- **Long-running operations:** Tasks that should be cancellable when users interrupt
- **Conversational flows:** Scenarios requiring precise timing between utterances

## Example - Try It Yourself

- [Utterence handle example](https://github.com/videosdk-live/agents/blob/main/examples/utterance_handle_agent.py): Checkout the interruption handle implementation via the utterence handle functionality


## FAQs

### Troubleshooting

| Issue | Solution |
|--------|-----------|
| Overlapping speech | Use `await` on handles instead of `create_task()` |
| Tasks not cancelling on interruption | Check `utterance.interrupted` in loops |
| Handle is None | Only available during function tool execution via `session.current_utterance` |

### Correct Usage Pattern

#### ✅ Correct: Sequential Speech
Await each handle to prevent overlapping TTS.
```python
handle1 = session.say("First")
await handle1
handle2 = session.say("Second")
await handle2
```
---
#### ❌ Incorrect: Concurrent Speech
Using `create_task()` causes audio overlap.
```python
asyncio.create_task(session.say("First"))
asyncio.create_task(session.say("Second"))
```



---

# Vision & Multi-modality

Vision and multi-modal capabilities enable your AI agents to process and understand visual content alongside text and audio. This creates richer, more interactive experiences where agents can analyze images, respond to visual cues, and engage in conversations about what they see.

The VideoSDK Agents framework supports vision capabilities through two distinct pipeline architectures, each with different capabilities and use cases.

## Pipeline Architecture Overview

The framework provides two pipeline types with different vision support:

| Pipeline Type | Vision Capabilities | Supported Models | Use Cases |
|---|---|---|---|
| CascadingPipeline | Live frame capture & static images | OpenAI, Anthropic, Google | On-demand frame analysis, document analysis, visual Q&A |
| RealTimePipeline | Continuous live video streaming | Google Gemini Live only | Real-time visual interactions, live video commentary |  


## Cascading Pipeline Vision

The CascadingPipeline supports vision through two approaches: capturing live video frames from participants, or processing static images. This works with all supported LLM providers (OpenAI, Anthropic, Google).

### Enabling Vision

Enable vision capabilities by setting `vision=True` in RoomOptions:

```python
from videosdk.agents import JobContext, RoomOptions  
  
room_options = RoomOptions(  
    room_id="your-room-id",  
    name="Vision Agent",  
    #highlight-start
    vision=True  # Enable vision capabilities  
    #highlight-end
)  
  
job_context = JobContext(room_options=room_options)
```

### Live Frame Capture

Capture video frames from meeting participants on-demand using `agent.capture_frames()`:

```python
from videosdk.agents import Agent, AgentSession, CascadingPipeline  
from videosdk.plugins.deepgram import DeepgramSTT  
from videosdk.plugins.elevenlabs import ElevenLabsTTS  
from videosdk.plugins.google import GoogleLLM  
  
class VisionAgent(Agent):  
    def __init__(self):  
        super().__init__(  
            instructions="You are a helpful assistant that can analyze images."  
        )  
  
async def entrypoint(ctx: JobContext):
    
    agent = VisionAgent(ctx)
    conversation_flow = ConversationFlow(agent)

    pipeline = CascadingPipeline(
        stt=DeepgramSTT(),
        llm=GoogleLLM(),
        tts=ElevenLabsTTS(),
        vad=SileroVAD(),
        turn_detector=TurnDetector()
    )
    session = AgentSession(
        agent=agent, 
        pipeline=pipeline,
        conversation_flow=conversation_flow,
    )

    shutdown_event = asyncio.Event()
    #highlight-start
    async def on_pubsub_message(message):
        print("Pubsub message received:", message)
        if isinstance(message, dict) and message.get("message") == "capture_frames":
            print("Capturing frame....")
            try:
                frames = agent.capture_frames(num_of_frames=1)
                if frames:
                    print(f"Captured {len(frames)} frame(s)")
                    await session.reply(
                        "Please analyze this frame and describe what you see in details within one line.",
                        frames=frames
                    )
                else:
                    print("No frames available. Make sure vision is enabled in RoomOptions.")
            except ValueError as e:
                print(f"Error: {e}")

    def on_pubsub_message_wrapper(message):
        asyncio.create_task(on_pubsub_message(message))
    #highlight-end
#rest of the code..
```
:::tip
The `capture_frames` function returns an array and the max number of frames you can input is 5 (`num_of_frames <=5`)
:::


**Key Features:**

- **On-Demand Capture:** Capture frames only when needed, triggered by events or user requests
- **Event-Driven:** Use PubSub or other triggers to capture frames at the right moment
- **Flexible Analysis:** Send custom instructions along with frames for specific analysis tasks

### Silent Capture (Saving Captured Frames)
  
You can save captured video frames to disk for later analysis or debugging. The frames returned by `agent.capture_frames()` are `av.VideoFrame` objects that can be converted to JPEG images.  
(Silent capture - as it doesn't invoke any agent speech saying the image is being captured unless explicity set to do so)
  
```python title="main.py"  
import io  
from av import VideoFrame  
from PIL import Image  
  
def save_frame_as_jpeg(frame: VideoFrame, filename: str) -> None:  
    """Save a video frame as a JPEG file."""  
    img = frame.to_image()  # Convert to PIL Image  
    img.save(filename, format="JPEG")  
  
# In your agent code  
frames = agent.capture_frames(num_of_frames=1)  
if frames:  
    # Save the first frame  
    save_frame_as_jpeg(frames[0], "captured_frame.jpg")  
      
    # Or save as bytes for uploading/processing  
    buffer = io.BytesIO()  
    frames[0].to_image().save(buffer, format="JPEG")  
    jpeg_bytes = buffer.getvalue()
```

**Use Cases:**

- **Debugging:** Save frames to verify what the agent is seeing
- **Logging:** Archive frames for audit trails or quality assurance
- **Preprocessing:** Save frames before sending to external vision APIs
- **Thumbnails:** Generate preview images for user interfaces

### Static Image Processing

For pre-existing images or URLs, use the `ImageContent` class:

```python
from videosdk.agents import ChatRole, ImageContent  
  
# Add image from URL  
agent.chat_context.add_message(  
    role=ChatRole.USER,  
    content=[ImageContent(image="https://example.com/image.jpg")]  
)  
  
# Add image with custom settings  
image_content = ImageContent(  
    image="https://example.com/document.png",  
    inference_detail="high"  # "auto", "high", or "low"  
)  
  
agent.chat_context.add_message(  
    role=ChatRole.USER,  
    content=[image_content]  
)
```

### Provider Support

All major LLM providers support vision in `CascadingPipeline`:

| Provider | Vision Models | Capabilities |
|-----------|----------------|---------------|
| OpenAI | GPT-4 Vision models | Configurable detail levels, URL & base64 support |
| Anthropic | Claude 3 models | Advanced image understanding, document analysis |
| Google | Gemini models | Comprehensive visual analysis, multi-image support |

### Best Practices

- **Frame Timing:** Capture frames at meaningful moments (e.g., when user asks "what do you see?")
- **Error Handling:** Always check if frames are available before processing
- **Vision Enablement:** Ensure `vision=True` is set in `RoomOptions` for frame capture
- **Image Quality:** Use appropriate resolutions for your use case (1024x1024 recommended for detailed analysis)

*Here is the example you can try out : [Cascading Pipeline Vision Example](https://github.com/videosdk-live/agents/blob/main/examples/vision_cascading_pipeline.py)*

---

## RealTime Pipeline Vision

The `RealTimePipeline` enables continuous live video processing for real-time visual interactions. Video frames are automatically streamed to the model as they arrive.

### Live Video Processing

Live video input is enabled through the `vision` parameter in `RoomOptions` and requires Google's Gemini Live model.

```python title="main.py"
from videosdk.agents import Agent, AgentSession, RealTimePipeline,WorkerJob, JobContext, RoomOptions
from videosdk.plugins.google import GeminiRealtime, GeminiLiveConfig  
  
async def start_session(context: JobContext):  
    # Initialize Gemini with vision capabilities  
    model = GeminiRealtime(  
        model="gemini-2.5-flash-native-audio-preview-12-2025",  
        config=GeminiLiveConfig(  
            voice="Leda",  
            response_modalities=["AUDIO"]  
        )  
    )  
  
    pipeline = RealTimePipeline(model=model)
    agent = VisionAgent()
    
    session = AgentSession(
        agent=agent,
        pipeline=pipeline,
    )

    await session.start(wait_for_participant=True, run_until_shutdown=True)

# Enable live video processing  
def make_context() -> JobContext:
    room_options = RoomOptions(room_id="<room_id>", 
                               name="Sandbox Agent", 
                               playground=True,
                               #highlight-start
                               vision=True
                               #highlight-end
                               ) 
    return JobContext(
        room_options=room_options
        )
```

### Video Processing Flow

When vision is enabled, the system automatically does following:

1. **Continuous Capture**: Captures video frames from meeting participants
2. **Frame Processing**: Processes frames at optimal intervals (throttled to 0.5 seconds)
3. **Model Integration**: Sends visual data to the Gemini Live model
4. **Context Integration**: Integrates visual understanding with conversation context



### RealTimePipeline Limitations

- **Model Restriction**: Only works with `GeminiRealtime` model
- **Network Requirements**: Requires stable network connections for optimal performance
- **Frame Rate**: Automatically throttled to prevent overwhelming the model


*Here is the example you can try out : [**Realtime Pipeline Vision Example**](https://github.com/charu1603/test-realtime-vision)*


## Choosing the Right Approach

| Use Case | Recommended Pipeline | Why |
|-----------|----------------------|-----|
| On-demand frame analysis | CascadingPipeline | Capture frames only when needed, works with all LLM providers |
| Document/image Q&A | CascadingPipeline | Process static images with custom instructions |
| Real-time video commentary | RealTimePipeline | Continuous streaming for live visual interactions |
| Multi-provider support | CascadingPipeline | Works with OpenAI, Anthropic, and Google |
| Lowest latency | RealTimePipeline | Direct streaming to Gemini Live model |


## Examples - Try Out Yourself

Checkout examples of using Realtime and Cascading Vision functionality


- [Cascading Pipeline Vision](https://github.com/videosdk-live/agents/blob/main/examples/vision_cascading_pipeline.py): On-demand frame capture and static image processing
- [Realtime Pipeline Vision](https://github.com/charu1603/test-realtime-vision): Continuous video streaming with Gemini Realtime API


## Frequently Asked Questions

### Can I use vision with any LLM provider?

CascadingPipeline vision works with OpenAI, Anthropic, and Google LLMs. RealTimePipeline vision only works with Google's Gemini Live model.

### How do I capture frames at specific moments?

Use event-driven triggers like PubSub messages or user speech to call `agent.capture_frames()` at the right time. See the example code above for implementation details.

### What's the difference between frame capture and continuous streaming?

Frame capture (CascadingPipeline) captures frames on-demand when you call `capture_frames()`. Continuous streaming (RealTimePipeline) automatically sends video frames to the model in real-time.















---

# Voice Mail Detection

Voice Mail Detection allows you to automatically handle voicemail scenarios when making outbound calls with a VideoSDK AI agent.
When an outbound call is forwaded to a voicemail system, the detector triggers a callback so your agent can take the action such as leaving a voicemail message or ending the call.

## What Problem This Solves

In outbound calling workflows, unanswered calls are often routed to voicemail systems. Without detection, agents may continue speaking or wait unnecessarily.

Voice Mail Detection lets you:

- Detect voicemail systems automatically
- Control how your agent responds
- End calls cleanly after voicemail handling

:::info
To set up an outbound calling, and routing rules check out the [Quick Start Example](https://docs.videosdk.live/telephony/managing-calls/making-outbound-calls).
:::

## Enabling Voice Mail Detection

To use voicemail detection, import and add `VoiceMailDetector` to your agent configuration and register a callback that defines how voicemail should be handled.

```python
from videosdk.agents import VoiceMailDetector
from videosdk.plugins.openai import OpenAILLM

async def voice_mail_callback(message):
    print("Voice Mail message received:", message)

# highlight-start
voicemail = VoiceMailDetector(
    llm=OpenAILLM(),
    duration=5,
    callback=custom_callback_voicemail,
)
# highlight-end

session = AgentSession(
    # highlight-start
    voice_mail_detector=voicemail
    # highlight-end
)
```

## Parameters

| Parameter | Description |
|----------|-------------|
| `llm` | LLM to process the detected voicemail. |
| `duration` | The minimum period of silence (in seconds) that triggers voicemail detection. |
| `callback` | A function that is called whenever a voicemail is detected, allowing for custom actions like hanging up or leaving a message. |


## Example - Try It Yourself

- [Voice Mail Detection](https://github.com/videosdk-live/agents-quickstart/blob/main/Voice%20Mail%20Detector/voice_mail_detector.py): Check out full working example of the Voice Mail Detection


---

# Worker

This document covers the `worker` and `job` execution system that manages `agent` processes, handles backend registration, and coordinates job assignment and execution. This system provides the foundation for running VideoSDK agents either locally or as part of a distributed backend infrastructure.

## Architecture Overview

The `worker` and `job` system consists of three primary components that work together to execute agent code:

- **WorkerJob**: The main entry point that configures and starts agent execution
- **Worker**: Manages process pools, backend communication, and job lifecycle
- **JobContext**: Provides runtime context and resources to agent entrypoint functions

![Worker](https://cdn.videosdk.live/website-resources/docs-resources/build_agent_section_worker.png)

## Core Components

### Worker Class

The `Worker` class manages the complete lifecycle of agent execution, including process management, backend communication, and job coordination.

**Core Responsibilities:**

- Process pool management and lifecycle
- Backend registry communication
- Job assignment and execution coordination
- Resource monitoring and cleanup
- Error handling and recovery

### WorkerJob

The `WorkerJob` class serves as the primary entry point for creating and running agents. It accepts an `entrypoint function` and `configuration options`, then delegates to the Worker class for execution.

```python
from videosdk.agents import WorkerJob, Options, JobContext, RoomOptions

# Configure worker options
options = Options(
    agent_id="MyAgent",
    max_processes=5,
    register=True,   # Registers worker with backend for job scheduling
)

# Set up room configuration
room_options = RoomOptions(
    name="My Agent",
)

# Create job context
job_context = JobContext(room_options=room_options)

# Define your agent entrypoint
async def your_agent_function(ctx: JobContext):
    # Your agent logic here
    await ctx.connect()
    # Agent implementation...

# Create and start the worker job
# highlight-start
job = WorkerJob(
    entrypoint=your_agent_function,
    jobctx=lambda: job_context,
    options=options,
)

job.start()
# highlight-end
```

- **Entrypoint:** An async function that serves as your agent's main execution logic. This function receives a `JobContext` parameter and contains your agent implementation.

- **JobContext:** Provides the runtime environment for your agent, managing room connections and VideoSDK integration. It handles room setup, authentication, and cleanup operations.

- **Options:** Configuration settings for worker execution including process management, authentication, and backend registration. You can find worker options [here ↗](https://docs.videosdk.live/ai_agents/deployments/self-hosting/worker-configuration#worker-options-explained).

**Key Methods:**

- `start()`: Initiates worker execution based on configuration

## Deployments

Choose how to deploy your VideoSDK agents based on your infrastructure needs and requirements.

- [Agent Cloud](https://docs.videosdk.live/ai_agents/deployments/agent-cloud): Deploy your agents to VideoSDK's managed cloud infrastructure
- [Self Hosting with Worker](https://docs.videosdk.live/ai_agents/deployments/self-hosting/understanding-worker): Learn how to deploy workers for self-hosted agent infrastructure


## Examples - Try Out Yourself

We have examples to get you started. Go ahead, try out, talk to agent, understand and customize according to your needs.

- [Worker Example](https://github.com/videosdk-live/agents/blob/main/examples/new_worker.py): Checkout worker implementation



---

# Deploy Your Agents
This guide shows you how to deploy AI Agents with the [videosdk-agents](https://pypi.org/project/videosdk-agents/) python package.
Once your AI Agent is ready to use, you need to create an AI Deployment. The AI Deployment is responsible for running your AI Agent.
Before proceeding, ensure you have completed the steps under **Prerequisites**.

## Prerequisites
To deploy your AI Deployment, make sure you have:
- Created an AI Deployment using the [Create AI Deployment API](/api-reference/agent-cloud/create-deployment).
- A VideoSDK authentication token (generate from [VideoSDK Dashboard](https://app.videosdk.live))

## YAML Configuration
Create a `videosdk.yaml` file with the following structure: 
```
version: "1.0"
deployment:
  id: your_ai_deployment_id
  entry:
    path: entry_point_for_deployment
env: # Optional to run your agent locally
  path: "./.env"
secrets:
  VIDEOSDK_AUTH_TOKEN: your_auth_token
deploy:
  cloud: true
```

### Field Descriptions
| Field                         | Description                                                                                    |
| ----------------------------- | ---------------------------------------------------------------------------------------------- |
| `deployment.id`                   | The `deploymentId` obtained from the [Create AI Deployment API](/api-reference/agent-cloud/create-deployment) |
| `deployment.entry.path`           | Path to the entry point script for your AI Deployment.                                             |
| `env.path`                    | Path to your `.env` file, used only when running the agent locally.                            |
| `secrets.VIDEOSDK_AUTH_TOKEN` | Your VideoSDK auth token (required for deployment).                     |
| `deploy.cloud`                | Set to `true` to allow deploying the deployment to VideoSDK Cloud, when using the deploy command. Use `false` to avoid accidental deploys. |


## CLI Commands

- ###### Run the AI Deployment locally for Testing.
```
videosdk run 
```

- ###### Deploy the AI Deployment.
```
videosdk deploy
```  
## Next Steps

After deploying your AI Deployment, you can start using it by:

1. Creating a new session using the [Start Session API](/api-reference/agent-cloud/start-session)
2. Ending the session using the [End Session API](/api-reference/agent-cloud/end-session)

---

# Agent Cloud

This guide shows you how to deploy AI Agents with the [videosdk-agents](https://pypi.org/project/videosdk-agents/) python package.
Once your AI Agent is ready to use, you need to create an AI Deployment. The AI Deployment is responsible for running your AI Agent.
Before proceeding, ensure you have completed the steps under **Prerequisites**.

## Prerequisites

To deploy your AI Deployment, make sure you have:

- Created an AI Deployment using the [Create AI Deployment API](/api-reference/agent-cloud/create-deployment).
- A VideoSDK authentication token (generate from [VideoSDK Dashboard](https://app.videosdk.live))

## YAML Configuration

Create a `videosdk.yaml` file with the following structure:

```
version: "1.0"
deployment:
  id: your_ai_deployment_id
  entry:
    path: entry_point_for_deployment
env: # Optional to run your agent locally
  path: "./.env"
secrets:
  VIDEOSDK_AUTH_TOKEN: your_auth_token
deploy:
  cloud: true
```

### Field Descriptions

| Field                         | Description                                                                                                                                |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `deployment.id`               | The `deploymentId` obtained from the [Create AI Deployment API](/api-reference/agent-cloud/create-deployment)                              |
| `deployment.entry.path`       | Path to the entry point script for your AI Deployment.                                                                                     |
| `env.path`                    | Path to your `.env` file, used only when running the agent locally.                                                                        |
| `secrets.VIDEOSDK_AUTH_TOKEN` | Your VideoSDK auth token (required for deployment).                                                                                        |
| `deploy.cloud`                | Set to `true` to allow deploying the deployment to VideoSDK Cloud, when using the deploy command. Use `false` to avoid accidental deploys. |

## CLI Commands

- ###### Run the AI Deployment locally for Testing.

```
videosdk run
```

- ###### Deploy the AI Deployment.

```
videosdk deploy
```

## Next Steps

After deploying your AI Deployment, you can start using it by:

1. Creating a new session using the [Start Session API](/api-reference/agent-cloud/start-session)
2. Ending the session using the [End Session API](/api-reference/agent-cloud/end-session)


---

# Deployments

### Overview

The VideoSDK Agents framework provides multiple deployment options to run your AI agents in production environments. Understanding these options helps you choose the right deployment strategy for your specific use case.

VideoSDK Agents supports two primary deployment modes:

1. **Agent Cloud (Managed)** - Fully managed deployment hosted on VideoSDK infrastructure
2. **Self-Hosting** - Self-managed deployment on your own infrastructure (EC2, Docker, Kubernetes, etc.)

### [Agent Cloud (Hosted on Our Infrastructure)](./agent-cloud.md)

Agent Cloud is a fully managed service that handles the deployment, scaling, and maintenance of your AI agents. When you deploy to Agent Cloud:

- **Zero Infrastructure Management**: No need to manage servers, containers, or scaling
- **Automatic Scaling**: Built-in load balancing and auto-scaling capabilities
- **High Availability**: Redundant infrastructure with automatic failover
- **Managed Updates**: Automatic security patches and framework updates
- **Global Distribution**: Agents deployed across multiple regions for low latency
- **Built-in Monitoring**: Integrated metrics, logging, and health monitoring

**Best for**: Teams that want to focus on agent development rather than infrastructure management, or applications with variable traffic patterns.

### [Self-Hosting (EC2, Docker, or Custom Infrastructure)](./self-hosting/understanding-worker.md)

Self-hosting gives you complete control over your deployment environment and infrastructure. When self-hosting:

- **Full Control**: Complete control over hardware, networking, and configuration
- **Custom Integrations**: Ability to integrate with existing infrastructure and tools
- **Cost Optimization**: Potential cost savings for high-volume, predictable workloads
- **Compliance**: Meet specific security, compliance, or data residency requirements
- **Custom Scaling**: Implement your own scaling strategies and resource management

**Best for**: Organizations with existing infrastructure, specific compliance requirements, or predictable high-volume workloads.

### When to Choose Agent Cloud vs Self-Hosting

#### Choose Agent Cloud when:

- You want to get started quickly without infrastructure setup
- You have variable or unpredictable traffic patterns
- You need global distribution and low latency
- You want automatic scaling and high availability
- You prefer a managed service with built-in monitoring

#### Choose Self-Hosting when:

- You need to meet specific compliance or security requirements
- You have predictable, high-volume workloads where cost optimization is important
- You require custom integrations with existing systems
- You need complete control over the deployment environment

### Common Terminology

Understanding these key terms will help you navigate the deployment documentation:

| Term                    | Definition                                                                                                                                                                             |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Agent**               | Your AI application built using the VideoSDK Agents framework. An agent can handle voice conversations, process audio, and respond with synthesized speech.                            |
| **Worker**              | A runtime component that executes your agent code. Workers can run in different environments (Agent Cloud or self-hosted) and handle job assignments from the backend registry system. |
| **Backend Registry**    | The central service that manages worker registration, job assignment, and load balancing. Workers connect to this registry to receive job assignments and report their status.         |
| **Job**                 | A single execution instance of your agent. When a user starts a conversation, the backend registry assigns a job to an available worker.                                               |
| **JobContext**          | The execution context for a job, containing room configuration, pipeline setup, and session management. This is the main interface your agent code interacts with.                     |
| **Worker Registration** | The process by which self-hosted workers register themselves with the VideoSDK backend registry to receive job assignments.                                                            |
| **Load Threshold**      | A configuration parameter that determines when a worker is considered "at capacity" and should not receive new job assignments.                                                        |
| **Health Check**        | Regular monitoring of worker status to ensure they're available and functioning correctly. Workers provide health endpoints for monitoring.                                            |
| **Resource Management** | The system for managing worker resources including process/thread allocation, memory limits, and concurrent job handling.                                                              |
| **Session Management**  | Handles the lifecycle of agent sessions including automatic session ending, timeouts, and cleanup.                                                                                     |
| **Horizontal Scaling**  | The manual process of deploying additional worker instances to handle increased load (requires manual deployment of new worker instances).                                             |
| **Vertical Scaling**    | The automatic scaling within a single worker up to its configured maximum capacity (`max_processes`).                                                                                  |
| **Dispatch API**        | A REST API endpoint that allows you to dynamically dispatch agents to meetings on-demand.                                                                                              |
| **AI Deployment**       | The deployment configuration that runs your AI agent, either in Agent Cloud or self-hosted environments.                                                                               |

This terminology will be referenced throughout the deployment documentation as we explore specific deployment scenarios and configurations.


---

# Dispatch Agents

Dynamically assign your AI agents to meetings using the VideoSDK dispatch API. This API supports dispatching for both self-hosted agents created with the Agents SDK and agents managed through the VideoSDK dashboard (Agent Runtime).

## How It Works

1. **Your app** calls the dispatch API
2. **VideoSDK backend** finds an available server
3. **Server spawns a job/process** to join the meeting
4. **Agent starts** and begins processing in the meeting

## API Usage

### Endpoint

```bash
POST https://api.videosdk.live/v2/agent/dispatch
```

### Request Body Parameters

| Parameter   | Type   | Required | Description                                                                                                                              |
| :---------- | :----- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| meetingId | string | Yes      | The ID of the meeting to which the agent should be dispatched.                                                                           |
| agentId   | string | Yes      | The ID of the agent to dispatch.                                                                                                         |
| metadata  | object | No       | Optional metadata to pass to the agent, such as variables.                                                                               |
| versionId | string | No       | The specific version of a dashboard-managed agent to dispatch. If omitted, the latest deployed version is used. Not for self-hosted agents. |

### Example Request 

```bash
curl -X POST "https://api.videosdk.live/v2/agent/dispatch" \
  -H "Authorization: YOUR_VIDEOSDK_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "meetingId": "xxxx-xxxx-xxxx",
    "agentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "metadata": {
        "variables":[
            {
                "name":"fname",
                "value":"ankit"
            }
        ]
    },
    "versionId":"abcd-abcd-abcd-abcd"
  }'
```



### Responses

**On Success**

A successful request will return a confirmation that the dispatch has been initiated.

```json
{
    "message": "Agent dispatch requested successfully.",
    "data": {
        "success": true,
        "status": "assigned",
        "roomId": "xxxx-xxxx-xxxx",
        "agentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
}
```

**On Error**

If the dispatch fails, you will receive one of the following error messages:

**no-workers:**

This error occurs when no servers and agents are configured to handle the request.

```json
{
"message": "No workers available"
}
```

---

**no-workers-registered:**

This error is specific to **self-hosted (Agents SDK) agents**. It means that while the `agentId` is valid, no server has been configured for the specific `agentId`.

```json
{
"message": "No workers have registered with agentId 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'"
}
```

---

**agent-not-deployed:**

This error is specific to **dashboard-managed agents**. It indicates that the agent exists but has no deployed versions available for dispatch or the specific version user wants to dispatch is not deployed .

```json
{
"message": "No agent is deployed with agentId 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'"
}
```

## Dispatching Your Agent

The prerequisites for dispatching an agent depend on how it was created.

### For Self-Hosted Agents (Agents SDK)

If you created your agent using the Python Agents SDK, you are responsible for hosting it. Your server must be:

1.  **Registered**: The server must be configured with `register=True`.
2.  **Connected**: The server must be running and connected to the VideoSDK backend.
3.  **Available**: The server must have the capacity to handle new jobs.

The `versionId` parameter is not applicable in this scenario.

**Server Configuration Example**

```python
from videosdk.agents import Options

options = Options(
    agent_id="MyAgent",        # Must match agentId in API call
    register=True,             # Required for dispatch
    max_processes=10,
    load_threshold=0.75,
)
```

### For Dashboard-Managed Agents (Agent Runtime)

If you created your agent using the dashboard interface, VideoSDK manages the hosting for you. The only prerequisite is that your agent must be **deployed**.

-   You can deploy your agent via the dashboard.
-   You can use the optional `versionId` parameter in your dispatch request to specify which deployed version of the agent to use.
-   If `versionId` is not provided, the **latest deployed version** will be dispatched by default.

## Code Examples

**python:**

```python
import requests

def dispatch_agent(auth_token, meeting_id, agent_id, metadata=None, version_id=None):
url = "https://api.videosdk.live/v2/agent/dispatch"
headers = {
    "Authorization": auth_token,
    "Content-Type": "application/json"
}
payload = {
    "meetingId": meeting_id,
    "agentId": agent_id,
}
if metadata:
    payload["metadata"] = metadata
if version_id:
    payload["versionId"] = version_id

response = requests.post(url, headers=headers, json=payload)
return response.json()

# Usage
result = dispatch_agent("your-token", "room-123", "MyAgent")
```

---

**javascript:**

```javascript
async function dispatchAgent(authToken, meetingId, agentId, metadata, versionId) {
  const url = "https://api.videosdk.live/v2/agent/dispatch";
  const headers = {
Authorization: authToken,
"Content-Type": "application/json",
  };
  
  const body = {
meetingId,
agentId,
  };

  if (metadata) {
body.metadata = metadata;
  }
  if (versionId) {
body.versionId = versionId;
  }

  const response = await fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
  });

  return response.json();
}

// Usage
dispatchAgent("your-token", "room-123", "MyAgent");
```



---

# AWS EC2

Deploy your VideoSDK AI Agent Worker on AWS EC2 instances.

## Prerequisites

- AWS account
- SSH key pair
- VideoSDK authentication token

## Quick Setup

### 1. Launch EC2 Instance

```bash
aws ec2 run-instances \
  --image-id ami-0c02fb55956c7d316 \
  --instance-type t3.medium \
  --key-name your-key-pair \
  --security-group-ids sg-xxxxxxxxx \
  --user-data file://user-data.sh
```

### 2. User Data Script

```bash
#!/bin/bash
yum update -y
yum install -y python3 python3-pip git

# Clone private repository with token
git clone https://YOUR_TOKEN@github.com/your-org/your-agent.git /opt/agent
cd /opt/agent

# Install dependencies
pip3 install -r requirements.txt

# Create systemd service
cat > /etc/systemd/system/agent-worker.service << EOF
[Unit]
Description=VideoSDK Agent Worker
After=network.target

[Service]
Type=simple
User=ec2-user
WorkingDirectory=/opt/agent
Environment=VIDEOSDK_AUTH_TOKEN=your_auth_token
ExecStart=/usr/bin/python3 main.py
Restart=always

[Install]
WantedBy=multi-user.target
EOF

# Start the service
systemctl enable agent-worker
systemctl start agent-worker
```

### 3. Security Group

Configure your security group with these rules:

- **SSH (22)**: Your IP
- **Custom TCP (8081)**: Your IP (for health checks)
- **HTTPS (443)**: 0.0.0.0/0 (for VideoSDK API)

## Deploy Updates

```bash
# Connect to your instance
ssh -i your-key.pem ec2-user@your-instance-ip

# Update your agent
cd /opt/agent
git pull
systemctl restart agent-worker
```

## Monitor

```bash
# Check service status
systemctl status agent-worker

# View logs
journalctl -u agent-worker -f
```

## Scaling

> To support more concurrent agents, you can spin up additional EC2 instances using the same process. Each instance will register with the VideoSDK backend registry and automatically receive job assignments. The backend will distribute the load across all available workers.

**To add more instances:**

1. Use the same user data script
2. Launch additional EC2 instances
3. Each instance will automatically join the worker pool
4. The VideoSDK backend will handle load balancing

**Example:**

```bash
# Launch multiple instances
aws ec2 run-instances \
  --image-id ami-0c02fb55956c7d316 \
  --instance-type t3.medium \
  --key-name your-key-pair \
  --security-group-ids sg-xxxxxxxxx \
  --user-data file://user-data.sh \
  --count 3
```


---

# Docker

Deploy your VideoSDK AI Agent Worker using Docker containers.

## Prerequisites

- Docker installed
- VideoSDK authentication token

## Quick Setup

### 1. Create Dockerfile

```dockerfile
FROM python:3.11-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# Copy requirements and install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Expose debug port
EXPOSE 8081

# Run the worker
CMD ["python", "main.py"]
```

### 2. Build and Run

```bash
# Build the image
docker build -t my-agent-worker .

# Run the container
docker run -d \
  --name my-agent-worker \
  -p 8081:8081 \
  -e VIDEOSDK_AUTH_TOKEN="your_auth_token" \
  my-agent-worker
```

### 3. Docker Compose (Optional)

Create `docker-compose.yml`:

```yaml title="docker-compose.yml"
version: "3.8"

services:
  agent-worker:
    build: .
    ports:
      - "8081:8081"
    environment:
      - VIDEOSDK_AUTH_TOKEN=${VIDEOSDK_AUTH_TOKEN}
    restart: unless-stopped
```

Run with:

```bash
docker-compose up -d
```

## Deploy Updates

```bash
# Stop container
docker stop my-agent-worker

# Remove old container
docker rm my-agent-worker

# Build new image
docker build -t my-agent-worker .

# Run new container
docker run -d \
  --name my-agent-worker \
  -p 8081:8081 \
  -e VIDEOSDK_AUTH_TOKEN="your_auth_token" \
  my-agent-worker
```

## Monitor

```bash
# Check container status
docker ps

# View logs
docker logs my-agent-worker

# Execute commands in container
docker exec -it my-agent-worker bash
```

## Scaling

> To support more concurrent agents, you can run multiple containers using the same image. Each container will register with the VideoSDK backend registry and automatically receive job assignments.

**Run multiple containers:**

```bash
# Run additional containers
docker run -d \
  --name my-agent-worker-2 \
  -p 8082:8081 \
  -e VIDEOSDK_AUTH_TOKEN="your_auth_token" \
  my-agent-worker

docker run -d \
  --name my-agent-worker-3 \
  -p 8083:8081 \
  -e VIDEOSDK_AUTH_TOKEN="your_auth_token" \
  my-agent-worker
```

**Or scale with Docker Compose:**

```bash
docker-compose up -d --scale agent-worker=3
```


---

# Kubernetes

Deploy your VideoSDK AI Agent Worker on Kubernetes clusters.

## Prerequisites

- Kubernetes cluster (EKS, GKE, or self-hosted)
- kubectl configured
- Docker image of your agent

## Quick Setup

### 1. Create Namespace

```bash
kubectl create namespace agent-workers
```

### 2. Create Secret

```bash
kubectl create secret generic agent-secrets \
  --from-literal=VIDEOSDK_AUTH_TOKEN=your_auth_token \
  --namespace agent-workers
```

### 3. Deploy Agent

```yaml title="deployment.yaml"
apiVersion: apps/v1
kind: Deployment
metadata:
  name: agent-worker
  namespace: agent-workers
spec:
  replicas: 3
  selector:
    matchLabels:
      app: agent-worker
  template:
    metadata:
      labels:
        app: agent-worker
    spec:
      containers:
        - name: agent-worker
          image: your-registry/agent-worker:latest
          ports:
            - containerPort: 8081
          env:
            - name: VIDEOSDK_AUTH_TOKEN
              valueFrom:
                secretKeyRef:
                  name: agent-secrets
                  key: VIDEOSDK_AUTH_TOKEN
          resources:
            requests:
              memory: "512Mi"
              cpu: "250m"
            limits:
              memory: "1Gi"
              cpu: "500m"
```

Apply the deployment:

```bash
kubectl apply -f deployment.yaml
```

## Monitor

```bash
# Check deployment status
kubectl get deployments -n agent-workers

# Check pods
kubectl get pods -n agent-workers

# View logs
kubectl logs -f deployment/agent-worker -n agent-workers
```

## Deploy Updates

```bash
# Update image
kubectl set image deployment/agent-worker agent-worker=your-registry/agent-worker:latest -n agent-workers

# Check rollout status
kubectl rollout status deployment/agent-worker -n agent-workers
```

## Scaling

> To support more concurrent agents, you can scale the deployment by increasing the number of replicas. Each pod will register with the VideoSDK backend registry and automatically receive job assignments.

**Scale the deployment:**

```bash
# Scale to 5 replicas
kubectl scale deployment agent-worker --replicas=5 -n agent-workers

# Or use HPA for automatic scaling
kubectl autoscale deployment agent-worker --cpu-percent=70 --min=2 --max=10 -n agent-workers
```

**Check scaling:**

```bash
# View current replicas
kubectl get deployment agent-worker -n agent-workers

# View HPA status
kubectl get hpa -n agent-workers
```

## Cleanup

```bash
# Delete deployment
kubectl delete deployment agent-worker -n agent-workers

# Delete namespace (removes everything)
kubectl delete namespace agent-workers
```


---

# Monitoring APIs

Monitor your worker status and performance using HTTP endpoints. All endpoints are available at `http://localhost:8081`.

## Available Endpoints

- **`/health`** - Basic health check
- **`/worker`** - Worker status
- **`/stats`** - Detailed statistics
- **`/debug`** - Configuration info
- **`/`** - Web dashboard

## Quick Health Check

```bash
curl http://localhost:8081/health
```

**Response:**

```
OK
```

## Worker Status

```bash
curl http://localhost:8081/worker
```

**Response:**

```json
{
  "agent_id": "MyAgent",
  "active_jobs": 3,
  "connected": true,
  "worker_id": "worker-123",
  "worker_load": 0.3
}
```

## Detailed Statistics

```bash
curl http://localhost:8081/stats
```

**Response:**

```json
{
  "worker_load": 0.3,
  "current_jobs": 3,
  "max_processes": 10,
  "agent_id": "MyAgent",
  "backend_connected": true,
  "resource_stats": {
    "total_resources": 10,
    "available_resources": 7,
    "active_resources": 3
  }
}
```

## Web Dashboard

Open `http://localhost:8081/` in your browser for a visual interface showing:

- Real-time worker status
- Resource utilization
- Active jobs
- Performance metrics

## Integration Examples

**python:**

```python
import requests

def check_worker_health():
response = requests.get("http://localhost:8081/health")
return response.status_code == 200

def get_worker_stats():
response = requests.get("http://localhost:8081/stats")
return response.json()

# Usage
if check_worker_health():
stats = get_worker_stats()
print(f"Active jobs: {stats['current_jobs']}")
```

---

**javascript:**

```javascript
async function checkWorkerHealth() {
  const response = await fetch("http://localhost:8081/health");
  return response.ok;
}

async function getWorkerStats() {
  const response = await fetch("http://localhost:8081/stats");
  return response.json();
}

// Usage
if (await checkWorkerHealth()) {
  const stats = await getWorkerStats();
  console.log(`Active jobs: ${stats.current_jobs}`);
}
```

## Common Use Cases

- **Health monitoring**: Use `/health` for load balancer checks
- **Performance tracking**: Use `/stats` for resource monitoring
- **Debugging**: Use `/debug` to verify configuration
- **Visual monitoring**: Use web dashboard for real-time overview


---

# Understanding the Worker

The **Worker** is the runtime engine that executes your AI agents in production. Think of it as the "server" that runs your agent code and handles multiple conversations simultaneously.

![AI Agent Worker](https://cdn.videosdk.live/website-resources/docs-resources/ai_agent_worker.png)

## What the Worker Does

The Worker manages the lifecycle of your AI agents by:

- **Executing** your agent code when users start conversations
- **Managing** multiple concurrent conversations efficiently
- **Connecting** to VideoSDK's backend to receive job assignments
- **Monitoring** health and performance automatically
- **Scaling** up or down based on demand

## Why Use the Built-in Worker?

The VideoSDK Agents framework includes a production-ready Worker that handles all the complex infrastructure concerns, so you can focus on building your AI agent logic.

**Key Benefits:**

- **Production-Ready**: Built for real-world workloads with proper error handling
- **Auto-Scaling**: Automatically handles multiple conversations within a single worker
- **Health Monitoring**: Built-in health checks and status reporting
- **Zero-Downtime**: Graceful shutdown and deployment capabilities


---

# Worker Configuration

Workers are the execution engines that run your **AI Agent jobs**.
Think of them as the bridge between your **agent logic** and the **VideoSDK runtime**.

This guide walks you through how to configure and tune a Worker for different environments — from local dev to production.

## Quick Start: Minimal Worker

Here’s the simplest Worker setup to get going:

```python
from videosdk.agents import WorkerJob, Options, JobContext, RoomOptions

options = Options(
    agent_id="MyAgent",
    max_processes=5,
    register=True,   # Registers worker with the backend for job scheduling
)

room_options = RoomOptions(
    name="My Agent",
)

job_context = JobContext(room_options=room_options)

job = WorkerJob(
    entrypoint=your_agent_function,
    jobctx=lambda: job_context,
    options=options,
)

job.start()
```

That’s enough to start processing jobs locally or in staging.

## Worker Options Explained

The `Options` class gives you fine-grained control over Worker behavior:

| Option               | Purpose                                     | Example                         |
| -------------------- | ------------------------------------------- | ------------------------------- |
| `agent_id`           | Unique identifier for your agent            | `"SupportBot01"`                |
| `max_processes`      | Maximum concurrent jobs                     | `10`                            |
| `num_idle_processes` | Pre-warmed processes for faster startup     | `2`                             |
| `load_threshold`     | Max CPU/Load tolerance before refusing jobs | `0.75`                          |
| `register`           | Whether to register with backend            | `True` (prod) / `False` (local) |
| `log_level`          | Logging verbosity                           | `"DEBUG"`, `"INFO"`, `"ERROR"`  |
| `host`, `port`       | Bind address for health/status endpoints    | `"0.0.0.0"`, `8081`             |
| `memory_warn_mb`     | Trigger warning logs at this usage          | `500.0`                         |
| `memory_limit_mb`    | Hard memory cap (`0` = unlimited)           | `1000.0`                        |
| `ping_interval`      | Heartbeat interval in seconds               | `30.0`                          |
| `max_retry`          | Max connection retries before giving up     | `16`                            |

## Example Configurations

**standard-production:**

**Standard Production** configuration for typical deployments:

```python
options = Options(
agent_id="StandardAgent",
max_processes=5,
register=True,
log_level="INFO",
)
```

This configuration is suitable for:

- Standard production deployments
- Moderate traffic loads
- Most business applications

---

**high-scale-production:**

**High-Scale Production** configuration for enterprise workloads:

```python
options = Options(
agent_id="EnterpriseAgent",
max_processes=20,
num_idle_processes=5,
load_threshold=0.8,
memory_limit_mb=2000.0,
register=True,
log_level="DEBUG",
)
```

This configuration is optimized for:

- Enterprise-scale deployments
- High concurrent user loads
- Advanced monitoring requirements

---

**local-development:**

**Local Development** configuration for development:

```python
options = Options(
agent_id="DevAgent",
max_processes=1,
register=False,   # Don't register with backend
log_level="DEBUG",
host="localhost",
port=8081,
)
```

This configuration is ideal for:

- Local development and testing
- Debugging agent behavior
- Isolated development environments

## Hosting Environments



## Scaling Your Workers

Workers can scale both **vertically** (more power per instance) and **horizontally** (more instances).

- **Vertical Scaling** → Increase `max_processes` to run more jobs per worker.
- **Horizontal Scaling** → Deploy multiple workers; the backend registry will balance load.
- **Idle Processes** → Use `num_idle_processes` to reduce cold start latency.
- **Load Threshold** → Tune `load_threshold` (default `0.75`) to prevent overload.
- **Memory Safety** → Use `memory_warn_mb` and `memory_limit_mb` to keep processes healthy.

## Pro Tips

- **Start small** → Begin with `max_processes=5` and adjust as you observe metrics.
- **Log smart** → Use `DEBUG` in dev, but `INFO` or `WARN` in prod to reduce noise.
- **Monitor & Auto-Scale** → Pair with metrics (Prometheus, Grafana, CloudWatch, etc.) to auto-scale horizontally.
- **Keep processes warm** → Set at least `num_idle_processes=1` in production for faster first-response times.


---

# Function Tools

Function tools allow your AI agent to perform actions and interact with external services, extending its capabilities beyond simple conversation. By registering function tools, you enable your agent to execute custom logic, call APIs, access databases, and perform various tasks based on user requests.

## Overview

Function tools are Python functions decorated with `@function_tool` that your agent can call during conversations. The LLM automatically decides when to use these tools based on the user's request and the tool's description.

## External Tools

External tools are defined as standalone functions and passed into the agent's constructor via the `tools` parameter. This approach is useful for sharing common tools across multiple agents.

```python title="main.py"
from videosdk.agents import Agent, function_tool

# External tool defined outside the class
@function_tool(description="Get weather information for a location")
def get_weather(location: str) -> str:
    """Get weather information for a specific location."""
    # Weather logic here
    return f"Weather in {location}: Sunny, 72°F"

class WeatherAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are a weather assistant.",
            tools=[get_weather]  # Register the external tool
        )
```

## Internal Tools

Internal tools are defined as methods within your agent class and decorated with `@function_tool`. This approach is useful for logic that is specific to the agent and needs access to its internal state (`self`).

```python title="main.py"
from videosdk.agents import Agent, function_tool

class FinanceAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are a helpful financial assistant."
        )
        self.portfolio = {"AAPL": 10, "GOOG": 5}

    @function_tool
    def get_portfolio_value(self) -> dict:
        """Get the current value of the user's stock portfolio."""
        # Access agent state via self
        return {"total_value": 5000, "holdings": self.portfolio}
```

## Async Function Tools

Function tools can be asynchronous, which is essential for making HTTP requests, performing I/O operations, or integrating with async VideoSDK features.

```python title="main.py"
import aiohttp
from videosdk.agents import Agent, function_tool

class WeatherAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are a weather assistant that can fetch real-time weather data."
        )

    @function_tool
    async def get_weather_async(self, location: str) -> dict:
        """Fetch real-time weather data from an API."""
        async with aiohttp.ClientSession() as session:
            async with session.get(f"https://api.weather.com/{location}") as response:
                data = await response.json()
                return {
                    "location": location,
                    "temperature": data.get("temp"),
                    "condition": data.get("condition")
                }
```

:::note **Sarvam AI LLM**: When using Sarvam AI as the LLM option, function tool calls and MCP tools will not work. Consider using alternative LLM providers if you need function tool support.
:::

## Examples - Try Out Yourself

- [Function Tool Example](https://github.com/videosdk-live/agents/blob/main/examples/test_cascading_pipeline.py): Complete example demonstrating internal and external function tools
- [Real-life Usecase](https://github.com/videosdk-live/agents/blob/ee3ced912078c3be9dd62c7576c95c1bbe227bae/examples/a2a/agents/customer_agent.py#L22): Complete example demonstrating internal and external function tools



---

# Human in the Loop

Human in the Loop (HITL) enables AI agents to escalate specific queries to human operators for review and approval. This implementation uses Discord as the human interface, allowing seamless handoffs between AI automation and human oversight.

## Overview

The HITL system allows AI agents to:
- Handle routine customer inquiries autonomously
- Escalate specific queries (like discount requests) to human operators via Discord
- Receive human responses and relay them back to customers
- Maintain conversation flow while waiting for human input

## Use Cases

- **Discount Requests**: AI escalates pricing queries to human sales agents
- **Complex Support**: Technical issues requiring human expertise
- **Policy Decisions**: Requests that need human approval or clarification
- **Escalation Scenarios**: Situations where AI confidence is low

## Example Overview

The implementation consists of two main components:

1. **Customer Agent**: VideoSDK AI agent that handles customer interactions and escalates specific queries
2. **Discord MCP Server**: MCP server that creates Discord threads for human operator responses

## Example Implementation

### Customer Agent Setup

```python
from videosdk.agents import Agent, MCPServerStdio
import pathlib
import sys

class CustomerAgent(Agent):
    def __init__(self, ctx: Optional[JobContext] = None):
        current_dir = pathlib.Path(__file__).parent
        discord_mcp_server_path = current_dir / "discord_mcp_server.py"

        super().__init__(
            instructions="You are a customer-facing agent for VideoSDK. You have access to various tools to assist with customer inquiries, provide support, and handle tasks. When a user asks for a discount percentage, always use the appropriate tool to retrieve and provide the accurate answer from your superior human agent.",
            mcp_servers=[
                MCPServerStdio(
                    executable_path=sys.executable,
                    process_arguments=[str(discord_mcp_server_path)],
                    session_timeout=30
                ),
            ]
        )
        self.ctx = ctx
```

### Discord MCP Server

```python
from mcp.server.fastmcp import FastMCP
import discord
from discord.ext import commands

class DiscordHuman:
    def __init__(self, user_id: int, channel_id: int):
        self.user_id = user_id
        self.channel_id = channel_id
        self.bot = commands.Bot(command_prefix="!", intents=discord.Intents.all())
        self.response_future = None

    async def ask(self, question: str) -> str:
        channel = self.bot.get_channel(self.channel_id)
        thread = await channel.create_thread(
            name=question[:100],
            type=discord.ChannelType.public_thread
        )
        await thread.send(f"<@{self.user_id}> {question}")

        self.response_future = self.loop.create_future()
        try:
            return await asyncio.wait_for(self.response_future, timeout=600)
        except asyncio.TimeoutError:
            return "⏱️ Timed out waiting for a human response"

# MCP Server Setup
mcp = FastMCP("HumanInTheLoopServer")

@mcp.tool(description="Ask a human agent via Discord for a specific user query such as discount percentage, etc.")
async def ask_human(question: str) -> str:
    return await discord_human.ask(question)
```

### Pipeline Configuration

```python
pipeline = CascadingPipeline(
    stt=DeepgramSTT(api_key=os.getenv("DEEPGRAM_API_KEY")),  
    llm=AnthropicLLM(api_key=os.getenv("ANTHROPIC_API_KEY")),
    tts=GoogleTTS(api_key=os.getenv("GOOGLE_API_KEY")),
    vad=SileroVAD(),
    turn_detector=TurnDetector(threshold=0.8)
)
```

### Environment Variables

Set the following environment variables:

```bash
DISCORD_TOKEN=your_discord_bot_token
DISCORD_USER_ID=human_operator_user_id
DISCORD_CHANNEL_ID=channel_id_for_escalations
DEEPGRAM_API_KEY=your_deepgram_key
ANTHROPIC_API_KEY=your_anthropic_key
GOOGLE_API_KEY=your_google_key
```

### Example Link

Complete implementation with full source code, setup instructions, and configuration examples available in the [VideoSDK Agents GitHub repository](https://github.com/videosdk-live/agents/tree/main/examples/human_in_the_loop).


---

# AI Voice Agents

The VideoSDK AI Agent SDK is a powerful Python framework for developers to seamlessly integrate intelligent, real-time voice agents into any application. Bridge the gap between advanced AI models and human interaction, creating natural, engaging, and responsive conversational experiences.





- [AI Voice Agent Quickstart](/ai_agents/voice-agent-quick-start): Build an AI Voice Agent in less than 10 minutes
- [AI Telephony Agent Quickstart](/ai_agents/ai-phone-agent-quick-start): Build an AI Telephony Agent in less than 10 minutes
- [Github Repository](https://github.com/videosdk-live/agents): The videosdk agent code and examples
- [SDK Reference](https://docs.videosdk.live/agent-sdk-reference/agents/): Reference docs for agents framework


## The Architecture

The VideoSDK AI Agents framework connects four key components to enable seamless AI voice interactions:

- Your **Infrastructure** hosts the agent management system
- The **Agent Worker** creates and manages AI sessions
- The **VideoSDK Room** handles real-time meeting operations
- **User Devices** connect through web, mobile apps, or phone calls to interact with intelligent agents that can listen, understand, and respond naturally in real-time conversations.



![Introduction](https://assets.videosdk.live/images/agent-architecture.png)



## Use Cases

Here are some real-world applications where VideoSDK AI Agents can be deployed to create intelligent, voice-enabled experiences across different industries and scenarios. You can use this, or refer this to create your customized agent.

- [Multi-Agent System](https://github.com/videosdk-live/agents/tree/main/examples/a2a): See the Agent-to-Agent Protocol in action, where there is a general customer care agent that transfers queries to Loan Specialist Agent for Loan related queries.
- [Agent with MCP Server](https://github.com/videosdk-live/agents-quickstart/blob/main/MCP/mcp_stdio_server.py): Integrate MCP (Model Context Protocol) Server with VideoSDK Agents.
- [RAG Agent](https://github.com/videosdk-live/agents-quickstart/tree/main/RAG): An example of Retrieval-Augmented Generation (RAG) based agent for knowledge-grounded conversations.
- [Translator Agent](https://github.com/videosdk-live/agents/blob/main/examples/translator_agent.py): A translator assistant that can speak to user in their language.
- [Whatsapp Call Agent](https://docs.videosdk.live/ai_agents/whatsapp-voice-agent-quick-start): Streamline your business with whatsapp ai call agent that you can use for inbound queries or for outbound calls.
- [Agent with Wakeup Call](https://github.com/videosdk-live/agents-quickstart/tree/main/Wakeup%20Call): An agent that maintains engagement by triggering automatically after specified period of inactivity.
- [Virtual Avatar Agent](https://github.com/videosdk-live/agents-quickstart/tree/main/Virtual%20Avatar): Bring your AI agent to life with a virtual avatar that can interact visually during conversations.


## The Building Blocks

Our SDK is built on four primary, modular components that work together to create powerful and customizable agents. Understand these concepts, and you're ready to build.

- [Agent Capabilities](/ai_agents/core-components/overview): Build sophisticated agents with function tools, vision, human-in-the-loop, and agent-to-agent(A2A) communication.
- [Deployment Options](/ai_agents/deployments/introduction): Deploy your agent on cloud or self-host it on your own infrastructure
- [Observability](/ai_agents/tracing-observability/session-analytics): Monitor and debug with confidence using our built-in session analytics, latency tracking, and detailed traces.
- [Plugin Ecosystem](/ai_agents/plugins/realtime/openai): Integrate with dozens of providers like OpenAI, Google, Anthropic, and Elevenlabs for STT, LLM, and TTS.


## Need Help?

If you have any queries, please feel free to reach out to us using one of the following methods:

- [Discord](https://discord.com/invite/Gpmj6eCq5u): Join our Discord Community.
- [GitHub](https://github.com/videosdk-live/agents/issues): Ask your questions on GitHub.
- [Support](https://www.videosdk.live/contact): Talk to an expert, book demo or talk to sales.




## Frequently Asked Questions

### What programming language and version are required?

The AI Agent SDK is built in Python. You'll need Python 3.12 or higher to use the SDK.

### Can my agent answer phone calls?

Yes. By integrating with our SIP/telephony services, your AI agent can join a room initiated by a standard phone call. This allows you to build powerful IVR systems, automated appointment schedulers, AI-powered call centers, and more.

### What AI models are supported?

The SDK supports various AI models including:
- **Real-time Models**: OpenAI, Google Gemini, AWS Nova Sonic
- **LLM Providers**: OpenAI, Google Gemini, Anthropic Claude, Sarvam AI, Cerebras
- **TTS Providers**: ElevenLabs, OpenAI, Google, AWS Polly, Cartesia, and many more
- **STT Providers**: OpenAI Whisper, Deepgram, Google, AssemblyAI, and others

### Can I use my own custom models?

Absolutely! The SDK's modular architecture allows you to create custom plugins for any AI provider. Check our [plugin development guide](https://github.com/videosdk-live/agents/blob/main/BUILD_YOUR_OWN_PLUGIN.md) for detailed instructions.

### How is pricing handled for the AI Agent SDK?

VideoSDK offers a free tier with limited usage. The AI Agent SDK itself is open-source, but you'll need API keys for the AI services you choose to use (OpenAI, Google, etc.). Check the [pricing page](https://www.videosdk.live/pricing) for VideoSDK usage limits.

### Can agents handle more than just voice?

Absolutely! Agents support multimodal interactions including vision processing, data messages, and real-time video streams. They can also use function tools to interact with external systems and APIs.

### Is the SDK production-ready?

Yes, the AI Agent SDK is stable and production-ready. It is designed to be self-hosted on your own infrastructure for full control and scalability, from a single server to a Kubernetes cluster. It includes comprehensive error handling, metrics collection, and deployment flexibility.

<div style={{marginTop: '1.5rem'}}></div>










---

The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to data sources and tools. With VideoSDK's AI Agents, you can seamlessly integrate MCP servers to extend your agent's capabilities with external services or applications, databases, and APIs.
## MCP Server Types
VideoSDK supports two transport methods for MCP servers:

### 1. STDIO Transport
- Direct process communication
- Local Python scripts
- Best for custom tools and functions
- Ideal for server-side integrations

### 2. HTTP Transport (Streamable HTTP or SSE)
- Network-based communication
- External MCP services
- Best for third-party integrations
- Supports remote MCP servers

## How It Works with VideoSDK's AI Agent

MCP tools are automatically discovered and made available to your agent. Agent will intelligently choose which tools to use based on user requests. When a user asks for information that requires external data, the agent will:

- Identify the need for external data based on the user's request
- Select appropriate tools from available MCP servers
- Execute the tools with relevant parameters
- Process the results and provide a natural language response

This seamless integration allows your voice agent to access real-time data and external services while maintaining a natural conversational flow.


## Creating an MCP Server

# Basic MCP Server Structure

A simple MCP server using STDIO to return the current time. First, install the required package:

```bash
pip install fastmcp
```

```python title="mcp_stdio_example.py"
from mcp.server.fastmcp import FastMCP
import datetime

# Create the MCP server
mcp = FastMCP("CurrentTimeServer")

@mcp.tool()
def get_current_time() -> str:
    """Get the current time in the user's location"""

    # Get current time
    now = datetime.datetime.now()
    
    # Return formatted time string
    return f"The current time is {now.strftime('%H:%M:%S')} on {now.strftime('%Y-%m-%d')}"

if __name__ == "__main__":
    # Run the server with STDIO transport
    mcp.run(transport="stdio")
```

## Integrating MCP with VideoSDK Agent

Now we'll see how to integrate MCP servers with your VideoSDK AI Agent:

```python title="main.py"
import asyncio
import pathlib
import sys
from videosdk.agents import Agent, AgentSession, RealTimePipeline,MCPServerStdio, MCPServerHTTP
from videosdk.plugins.google import GeminiRealtime, GeminiLiveConfig

class MyVoiceAgent(Agent):
    def __init__(self):
        # Define paths to your MCP servers
        mcp_script = Path(__file__).parent.parent / "MCP_Example" / "mcp_stdio_example.py"
        super().__init__(
            instructions="""You are a helpful assistant with access to real-time data. 
            You can provide current time information. 
            Always be conversational and helpful in your responses.""",
            mcp_servers=[
                # STDIO MCP Server (Local Python script for time)
                MCPServerStdio(
                    executable_path=sys.executable,  # Use current Python interpreter
                    process_arguments=[str(mcp_script)],
                    session_timeout=30
                ),
                # HTTP MCP Server (External service example e.g Zapier)
                MCPServerHTTP(
                    endpoint_url="https://your-mcp-service.com/api/mcp",
                    session_timeout=30
                )
            ]
        )

    async def on_enter(self) -> None:
        await self.session.say("Hi there! How can I help you today?")

    async def on_exit(self) -> None:
        await self.session.say("Thank you for using the assistant. Goodbye!")

async def main(context: dict):
    
    # Configure Gemini Realtime model
    model = GeminiRealtime(
        model="gemini-2.5-flash-native-audio-preview-12-2025",
        config=GeminiLiveConfig(
            voice="Leda",  # Available voices: Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus, Zephyr
            response_modalities=["AUDIO"]
        )
    )

    pipeline = RealTimePipeline(model=model)
    agent = MyVoiceAgent()

    session = AgentSession(
        agent=agent,
        pipeline=pipeline,
        context=context
    )

    try:
        # Start the session
        await session.start()
        # Keep the session running until manually terminated
        await asyncio.Event().wait()
    finally:
        # Clean up resources when done
        await session.close()

if __name__ == "__main__":
    def make_context():
        # When VIDEOSDK_AUTH_TOKEN is set in .env - DON'T include videosdk_auth
        return {
        "meetingId": "your_actual_meeting_id_here",  # Replace with actual meeting ID
        "name": "AI Voice Agent", 
        "videosdk_auth": "your_videosdk_auth_token_here"  # Replace with actual token
    }

```

:::tip

Get started quickly with the [Quick Start Example](https://github.com/videosdk-live/agents-quickstart/tree/main/MCP) for the VideoSDK AI Agent SDK With MCP — everything you need to build your first AI agent fast.

:::


---

# Agents Playground

The Agents Playground provides an interactive testing environment where you can directly communicate with your AI agents during development. This feature enables rapid prototyping, testing, and debugging of your voice AI implementations without needing a separate client application.

## Overview

Playground mode creates a web-based interface that connects directly to your agent session, allowing you to:
- Test agent in real-time
- Demonstrate agent capabilities to stakeholders

## Enabling Playground Mode

To activate playground mode, simply set `playground: True` in your RoomOptions for JobContext.

### Basic Implementation

```python
from videosdk.agents import RoomOptions, JobContext, WorkerJob

async def entrypoint(ctx: JobContext):
    # Your agent implementation here
    # This is where you create your pipeline, agent, and session
    pass

def make_context() -> JobContext:
    room_options = RoomOptions(
        room_id="<meeting_id>", 
        name="Test Agent", 
        playground=True  # Enable playground mode
    )
    
    return JobContext(room_options=room_options)

if __name__ == "__main__":
    from videosdk.agents import WorkerJob
    job = WorkerJob(entrypoint=entrypoint, jobctx=make_context)
    job.start()
```

## Accessing the Playground

Once your agent session starts, the playground URL will be displayed in your terminal:

```
Agent started in playground mode
Interact with agent here at:
https://playground.videosdk.live?token={auth_token}&meetingId={meeting_id}
```

### URL Structure

The playground URL follows this format:
```
https://playground.videosdk.live?token={auth_token}&meetingId={meeting_id}
```

Where:
- `auth_token`: videosdk_auth that is provided in session context or in env file.
- `meeting_id`: The meeting ID specified in session context.

**Note**: Playground mode is designed for development and testing purposes. For production deployments, ensure playground mode is disabled to maintain security and performance.


---

# Simli Avatar

The Simli Avatar plugin allows you to integrate a real-time, lip-synced AI avatar into your VideoSDK agent. This creates a more engaging and interactive experience for users by providing a visual representation of the AI agent.

Simli offers two avatar types: Legacy (30 FPS) and Trinity (25 FPS). When creating a SimliAvatar, set is_trinity_avatar=True if you're using a Trinity avatar (default is False). Always select the correct faceID from the Simli dashboard.

## Installation

Install the Simli-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-simli"
```

## Authentication

The Simli plugin requires an [Simli API key](https://app.simli.com/apikey).

Set `SIMLI_API_KEY` in your `.env` file.

## Importing

```python
from videosdk.plugins.simli import SimliAvatar, SimliConfig
```

## Setup Credentials

To use Simli, you need an API key. You can get one from the [Simli Dashboard](https://app.simli.com/profile).

Set up your credentials by exporting them as an environment variable:

```bash
export SIMLI_API_KEY="YOUR_SIMLI_API_KEY"
```

You can also provide a `faceId` if you have a custom one.

```bash
export SIMLI_FACE_ID="YOUR_FACE_ID"
```

## Example Usage

Here's how you can integrate the Simli Avatar with both `CascadingPipeline` and `RealTimePipeline`.

### Cascading Pipeline

This example shows how to add the Simli Avatar to a `CascadingPipeline`.

```python
import os
from videosdk.agents import CascadingPipeline
from videosdk.plugins.simli import SimliAvatar, SimliConfig
# Import other necessary components like STT, LLM, TTS

# 1. Initialize SimliConfig
simli_config = SimliConfig(
    apiKey=os.getenv("SIMLI_API_KEY"),
    faceId=os.getenv("SIMLI_FACE_ID"), # This is optional and has a default value
)

# 2. Create a SimliAvatar instance
# For Legacy avatars (default)
simli_avatar = SimliAvatar(config=simli_config)

# For Trinity avatars
# simli_avatar = SimliAvatar(
#     config=simli_config,
#     is_trinity_avatar=True,
# )

# 3. Add the avatar to the pipeline
pipeline = CascadingPipeline(
    # ... stt=stt, llm=llm, tts=tts
    avatar=simli_avatar
)
```

### Real-time Pipeline

This example shows how to add the Simli Avatar to a `RealTimePipeline`.

```python
import os
from videosdk.agents import RealTimePipeline
from videosdk.plugins.simli import SimliAvatar, SimliConfig
# from videosdk.plugins.google import GeminiRealtime # Example model

# 1. Initialize SimliConfig
simli_config = SimliConfig(
    apiKey=os.getenv("SIMLI_API_KEY"),
)

# 2. Create a SimliAvatar instance
# For Legacy avatars (default)
simli_avatar = SimliAvatar(config=simli_config)

# For Trinity avatars
# simli_avatar = SimliAvatar(
#     config=simli_config,
#     is_trinity_avatar=True,
# )

# 3. Add the avatar to the pipeline
pipeline = RealTimePipeline(
    model=your_realtime_model, # e.g., GeminiRealtime()
    avatar=simli_avatar
)
```

:::note
When using an environment variable for credentials, you should still load it in your code using `os.getenv("SIMLI_API_KEY")` and pass it to `SimliConfig`.
:::

## Configuration Options

You can customize the avatar's behavior using the `SimliConfig` and `SimliAvatar` classes.

### `SimliConfig`

- `faceId`: (str, optional) The ID for the avatar face. You can find available faces in the [Simli Docs](https://docs.simli.com/api-reference/available-faces) or create your own. Defaults to `"0c2b8b04-5274-41f1-a21c-d5c98322efa9"`.
- `maxSessionLength`: (int, optional) A hard time limit in seconds after which the session will disconnect. Defaults to `1800` (30 minutes).
- `maxIdleTime`: (int, optional) A soft time limit in seconds that disconnects the session after a period of not sending data. Defaults to `300` (5 minutes).

### `SimliAvatar`

- `config`: (`SimliConfig`) A `SimliConfig` object with your desired settings.
- `is_trinity_avatar`: (bool, optional) Set to `True` when using Trinity avatars. Defaults to `False` for Legacy avatars.

## Additional Resources

The following resources provide more information about using Simli with VideoSDK Agents SDK.

- **[Simli docs](https://docs.simli.com/overview)**: Simli docs.





---

# Denoise

The RNNoise plugin enhances audio quality by removing background noise from your audio input, resulting in improved speech-to-text (STT) accuracy and better overall audio processing performance.

RNNoise is a real-time noise suppression library powered by a recurrent neural network that intelligently filters out environmental noise such as air conditioning, computer fans, and other stationary background sounds while preserving the clarity and quality of speech.

## Installation

Install the RNNoise plugin for denoising in VideoSDK Agents package:

```bash
pip install "videosdk-plugins-rnnoise"
```

## Importing

```python
from videosdk.plugins.rnnoise import RNNoise
```

## Example Usage

```python
from videosdk.plugins.rnnoise import RNNoise
from videosdk.agents import CascadingPipeline

# Initialize the RNNoise Plugin
rnnoise = RNNoise()

# Add Denoise Plugin to cascading pipeline
pipeline = CascadingPipeline(denoise=rnnoise)
```

It also works with [`RealTimePipeline`](/ai_agents/core-components/realtime-pipeline.md).

## Example Usage in RealTime Pipeline

```python
from videosdk.plugins.rnnoise import RNNoise
from videosdk.agents import RealTimePipeline

# Initialize the RNNoise Plugin
rnnoise = RNNoise()

# Add Denoise Plugin to realtime pipeline
pipeline = RealTimePipeline(denoise=rnnoise)
```

## Benefits

- **Enhanced STT Accuracy**: Cleaner audio input leads to more accurate speech-to-text transcription
- **Real-time Processing**: Processes audio streams with minimal latency for seamless user experience
- **Intelligent Noise Reduction**: Effectively removes background noise while preserving speech clarity

## Additional Resources

The following resources provide more information about using RNNoise with VideoSDK Agents SDK.

- **[RNNoise project](https://github.com/xiph/rnnoise)**: The open source RNNoise library that powers the VideoSDK RNNoise plugin.





---

# Cerebras LLM

The Cerebras AI LLM provider enables your agent to use Cerebras AI's language models for text-based conversations and processing.

## Installation

Install the Cerebras-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-cerebras"
```

## Importing

```python
from videosdk.plugins.cerebras import CerebrasLLM
```

## Authentication

The Cerebras plugin requires an [Cerebras API key](https://cloud.cerebras.ai/).

Set `CARTESIA_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.cerebras import CerebrasLLM
from videosdk.agents import CascadingPipeline

# Initialize the Cerebras LLM model
llm = CerebrasLLM(
    model="llama3.3-70b",
    temperature=0.7,
    max_tokens=1024,
)

#  Add llm to cascading pipeline
pipeline = CascadingPipeline(llm=llm)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit `api_key` and other credential parameters from your code.
:::

## Configuration Options

- `model`: (str) The Cerebras model to use (default: `"llama3.3-70b"`). Supported models include: `llama3.3-70b`, `llama3.1-8b`, `llama-4-scout-17b-16e-instruct`, `qwen-3-32b`, `deepseek-r1-distill-llama-70b` (private preview)
- `api_key`: (str) Your Cerebras API key. Can also be set via the `CEREBRAS_API_KEY` environment variable.
- `temperature`: (float) Sampling temperature for response randomness (default: `0.7`).
- `tool_choice`: (ToolChoice) Tool selection mode (`"auto"`, `"required"`, `"none"`) (default: `"auto"`).
- `max_completion_tokens`: (int) Maximum number of tokens to generate in the response (optional).
- `top_p`: (float) Nucleus sampling probability (optional).
- `seed`: (int) Random seed for reproducible completions (optional).
- `stop`: (str) Stop sequence that halts generation when encountered (optional).
- `user`: (str) Identifier for the end user triggering the request (optional).

## Additional Resources

The following resources provide more information about using Cerebras with VideoSDK Agents SDK.

- **[Cerebras docs](https://inference-docs.cerebras.ai/introduction)**: Cerebras documentation.





---

# Anthropic LLM

The Anthropic AI LLM provider enables your agent to use Anthropic AI's language models for text-based conversations and processing. It also supports vision input capabilities, allowing your agent to analyze and respond to images alongside text with the [supported](https://docs.anthropic.com/en/docs/about-claude/models/overview) models.

## Installation

Install the Anthropic-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-anthropic"
```

## Importing

```python
from videosdk.plugins.anthropic import AnthropicLLM
```

## Authentication

The Anthropic plugin requires an [Anthropic API key](https://console.anthropic.com/dashboard).

Set `ANTHROPIC_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.anthropic import AnthropicLLM
from videosdk.agents import CascadingPipeline

# Initialize the Anthropic LLM model
llm = AnthropicLLM(
    model="claude-sonnet-4-20250514",
    temperature=0.7,
    max_tokens=1024,
)

#  Add llm to cascading pipeline
pipeline = CascadingPipeline(llm=llm)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit `api_key` and other credential parameters from your code.
:::

## Configuration Options

- `model`: (str) The Anthropic model to use (default: `"claude-sonnet-4-20250514"`).
- `api_key`: (str) Your Anthropic API key. Can also be set via the `ANTHROPIC_API_KEY` environment variable.
- `base_url`: (str) Optional custom base URL for Claude API (default: `None`).
- `temperature`: (float) Sampling temperature for response randomness (default: `0.7`).
- `tool_choice`: (ToolChoice) Tool selection mode (`"auto"`, `"required"`, `"none"`) (default: `"auto"`).
- `max_tokens`: (int) Maximum number of tokens in the response (default: `1024`).
- `top_p`: (float) Nucleus sampling probability (optional).
- `top_k`: (int) Top-k sampling parameter (optional).

## Additional Resources

The following resources provide more information about using Anthropic with VideoSDK Agents SDK.

- **[Anthropic docs](https://docs.anthropic.com/en/docs/intro)**: Anthropic documentation.





---

# Azure OpenAI LLM

The Azure OpenAI LLM provider enables your agent to use Azure OpenAI's language models (like GPT-4o) for text-based conversations and processing. It also supports vision input capabilities, allowing your agent to analyze and respond to images alongside text with the [supported](https://platform.openai.com/docs/models) models.

## Installation

Install the Azure OpenAI-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-openai"
```

## Importing

```python
from videosdk.plugins.openai import OpenAILLM
```

## Authentication

The Azure OpenAI plugin requires either an [Azure OpenAI API key](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/create-resource?pivots=web-portal).

Set `AZURE_OPENAI_API_KEY` , `AZURE_OPENAI_ENDPOINT` and `OPENAI_API_VERSION` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.openai import OpenAILLM
from videosdk.agents import CascadingPipeline

# Initialize the Azure OpenAI LLM model
llm = OpenAILLM.azure(
    azure_deployment="gpt-4o",
    temperature=0.7,
)

#  Add llm to cascading pipeline
pipeline = CascadingPipeline(llm=llm)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit api_key, videosdk_auth, and other credential parameters from your code.
:::

## Configuration Options

- `azure_deployment`: The OpenAI deployment ID to use (by default it is model name: e.g., `"gpt-4o"`, `"gpt-4o-mini"`)
- `api_key`: Your Azure OpenAI API key (can also be set via environment variable)
- `azure_endpoint`: Your Azure OpenAI Deployment Endpoint URL (can also be set via environment variable)
- `api_version`: Your Azure OpenAI API version (can also be set via environment variable)
- `temperature`: (float) Sampling temperature for response randomness (0.0 to 2.0, default: 0.7)
- `tool_choice`: Tool selection mode (e.g., `"auto"`, `"none"`, or specific tool)
- `max_completion_tokens`: (int) Maximum number of tokens in the completion response

## Additional Resources

The following resources provide more information about using OpenAI with VideoSDK Agents SDK.





---

# Google LLM

The Google LLM provider enables your agent to use Google's Gemini family of language models for text-based conversations and processing. It also supports vision input capabilities, allowing your agent to analyze and respond to images alongside text with the [supported](https://ai.google.dev/gemini-api/docs/models) models.

## Installation

Install the Google-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-google"
```

## Importing

```python
from videosdk.plugins.google import GoogleLLM
```

## Authentication

The Google plugin requires an [Gemini API key](https://aistudio.google.com/apikey).

Set `GOOGLE_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.google import GoogleLLM
from videosdk.agents import CascadingPipeline

# Initialize the Google LLM model
llm = GoogleLLM(
    model="gemini-3-flash-preview",
    # When GOOGLE_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-google-api-key",
    temperature=0.7,
    tool_choice="auto",
    max_output_tokens=1000
)

#  Add llm to cascading pipeline
pipeline = CascadingPipeline(llm=llm)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit `api_key` and other credential parameters from your code.
:::

## Vertex AI Integration

You can also use Google's Gemini models through Vertex AI. This requires a different authentication and configuration setup.

### Authentication for Vertex AI

For Vertex AI, you need to set up Google Cloud credentials. Create a service account, download the JSON key file, and set the path to this file in your environment.

```bash
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"
```

You should also configure your project ID and location. These can be set as environment variables or directly in the code. If not set, the `project_id` is inferred from the credentials file and the `location` defaults to `us-central1`.

```bash
export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"
export GOOGLE_CLOUD_LOCATION="your-gcp-location"
```

### Example Usage with Vertex AI

To use Vertex AI, set `vertexai=True` when initializing `GoogleLLM`. You can configure the project and location using `VertexAIConfig`, which will take precedence over environment variables.

```python
from videosdk.plugins.google import GoogleLLM, VertexAIConfig
from videosdk.agents import CascadingPipeline
# Import other necessary components like STT and TTS
# from videosdk.plugins.deepgram import DeepgramSTT
# from videosdk.plugins.elevenlabs import ElevenLabsTTS

# Initialize GoogleLLM with Vertex AI configuration
llm = GoogleLLM(
    vertexai=True,
    vertexai_config=VertexAIConfig(
        project_id="videosdk",
        location="us-central1"
    )
)

# Add llm to a cascading pipeline
pipeline = CascadingPipeline(
    stt=DeepgramSTT(), # Example STT
    llm=llm,
    tts=ElevenLabsTTS() # Example TTS
)
```

## Configuration Options

- `model`: (str) The Google model to use (e.g., `"gemini-3-flash-preview"`, `"gemini-3-pro-preview"`, `"gemini-2.0-flash-001"`,) (default: `"gemini-2.0-flash-001"`).
- `api_key`: (str) Your Google API key. Can also be set via the `GOOGLE_API_KEY` environment variable.
- `temperature`: (float) Sampling temperature for response randomness (default: `0.7`).
- `tool_choice`: (ToolChoice) Tool selection mode (`"auto"`, `"required"`, `"none"`) (default: `"auto"`).
- `max_output_tokens`: (int) Maximum number of tokens in the completion response (optional).
- `top_p`: (float) The nucleus sampling probability (optional).
- `top_k`: (int) The top-k sampling parameter (optional).
- `presence_penalty`: (float) Penalizes new tokens based on whether they appear in the text so far (optional).
- `frequency_penalty`: (float) Penalizes new tokens based on their existing frequency in the text so far (optional).

## Additional Resources

The following resources provide more information about using Google with VideoSDK Agents SDK.

- **[Gemini docs](https://ai.google.dev/gemini-api/docs/models)**: Google Gemini documentation.





---

# OpenAI LLM

The OpenAI LLM provider enables your agent to use OpenAI's language models (like GPT-4o) for text-based conversations and processing. It also supports vision input capabilities, allowing your agent to analyze and respond to images alongside text with the [supported](https://platform.openai.com/docs/models) models.

## Installation

Install the OpenAI-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-openai"
```

## Importing

```python
from videosdk.plugins.openai import OpenAILLM
```

## Authentication

The OpenAI plugin requires an [OpenAI API key](https://platform.openai.com/api-keys).

Set `OPENAI_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.openai import OpenAILLM
from videosdk.agents import CascadingPipeline

# Initialize the OpenAI LLM model
llm = OpenAILLM(
    model="gpt-4o",
    # When OPENAI_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-openai-api-key",
    temperature=0.7,
    tool_choice="auto",
    max_completion_tokens=1000
)

#  Add llm to cascading pipeline
pipeline = CascadingPipeline(llm=llm)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit api_key, videosdk_auth, and other credential parameters from your code.
:::

## Configuration Options

- `model`: The OpenAI model to use (e.g., `"gpt-4o"`, `"gpt-4o-mini"`, `"gpt-3.5-turbo"`)
- `api_key`: Your OpenAI API key (can also be set via environment variable)
- `base_url`: Custom base URL for OpenAI API (optional)
- `temperature`: (float) Sampling temperature for response randomness (0.0 to 2.0, default: 0.7)
- `tool_choice`: Tool selection mode (e.g., `"auto"`, `"none"`, or specific tool)
- `max_completion_tokens`: (int) Maximum number of tokens in the completion response

## Additional Resources

The following resources provide more information about using OpenAI with VideoSDK Agents SDK.

- **[OpenAI docs](https://platform.openai.com/docs/)**: OpenAI documentation.





---

# Sarvam AI LLM

The Sarvam AI LLM provider enables your agent to use Sarvam AI's language models for text-based conversations and processing.

## Installation

Install the Sarvam AI-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-sarvamai"
```

## Importing

```python
from videosdk.plugins.sarvamai import SarvamAILLM
```

:::note
When using Sarvam AI as the LLM option, the function tool calls and MCP tool will not work.
:::

## Authentication

The Sarvam plugin requires a [Sarvam API key](https://dashboard.sarvam.ai/key-management).

Set `SARVAM_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.sarvamai import SarvamAILLM
from videosdk.agents import CascadingPipeline

# Initialize the Sarvam AI LLM model
llm = SarvamAILLM(
    model="sarvam-m",
    # When SARVAMAI_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-sarvam-ai-api-key",
    temperature=0.7,
    tool_choice="auto",
    max_completion_tokens=1000
)

#  Add llm to cascading pipeline
pipeline = CascadingPipeline(llm=llm)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit `api_key` and other credential parameters from your code.
:::

## Configuration Options

- `model`: (str) The Sarvam AI model to use (default: `"sarvam-m"`).
- `api_key`: (str) Your Sarvam AI API key. Can also be set via the `SARVAMAI_API_KEY` environment variable.
- `temperature`: (float) Sampling temperature for response randomness (default: `0.7`).
- `tool_choice`: (ToolChoice) Tool selection mode (default: `"auto"`).
- `max_completion_tokens`: (int) Maximum number of tokens in the completion response (optional).

## Additional Resources

The following resources provide more information about using Sarvam AI with VideoSDK Agents SDK.

- **[Sarvam docs](https://docs.sarvam.ai/)**: Sarvam's full docs site.





---

# Namo Turn Detector

The Namo Turn Detector v1 utilizes a custom fine-tuned model from VideoSDK to accurately determine whether a user has finished speaking. This allows for precise management of conversation flow, especially in cascading pipeline setups. It can operate as a multilingual model or be configured for a specific language for optimized performance.

## Installation

Install the Turn Detector-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-turn-detector"
```

## Importing

```python
from videosdk.plugins.turn_detector import NamoTurnDetectorV1
```

## Example Usage

**1. For a specific language (e.g., English):**

```python
from videosdk.plugins.turn_detector import NamoTurnDetectorV1, pre_download_namo_turn_v1_model
from videosdk.agents import CascadingPipeline

# Pre-download the English model to avoid delays
pre_download_namo_turn_v1_model(language="en")

# Initialize the Turn Detector for English
turn_detector = NamoTurnDetectorV1(
  language="en",
  threshold=0.7
)

# Add the Turn Detector to a cascading pipeline
pipeline = CascadingPipeline(turn_detector=turn_detector)
```

**2. For multilingual support:**

If you don't specify a language, the detector will default to the multilingual model, which can handle various languages.

```python
from videosdk.plugins.turn_detector import NamoTurnDetectorV1, pre_download_namo_turn_v1_model
from videosdk.agents import CascadingPipeline

# Pre-download the multilingual model
pre_download_namo_turn_v1_model()

# Initialize the multilingual Turn Detector
turn_detector = NamoTurnDetectorV1(
    threshold=0.7
)

# Add the Turn Detector to a cascading pipeline
pipeline = CascadingPipeline(turn_detector=turn_detector)
```

## Configuration Options

- `language`: (Optional, `str`): Specifies the language for the turn detection model. If left as `None` (the default), it loads a multilingual model capable of handling all supported languages.

- `threshold`: (float) Confidence threshold for turn completion detection (0.0 to 1.0, default: `0.7`)

## Supported Languages

The `NamoTurnDetectorV1` supports a wide range of languages when you specify the corresponding language code. If no language is specified, the multilingual model will be used.

Here is a list of the supported languages and their codes:

| Language | Code |
| :--- | :--- |
| Arabic | `ar` |
| Bengali | `bn` |
| Chinese | `zh` |
| Danish | `da` |
| Dutch | `nl` |
| English | `en` |
| Finnish | `fi` |
| French | `fr` |
| German | `de` |
| Hindi | `hi` |
| Indonesian |`id` |
| Italian | `it` |
| Japanese | `ja` |
| Korean | `ko` |
| Marathi | `mr` |
| Norwegian | `no` |
| Polish | `pl` |
| Portuguese | `pt` |
| Russian | `ru` |
| Spanish | `es` |
| Turkish | `tr` |
| Ukrainian | `uk` |
| Vietnamese |`vi` |

## Pre-downloading Model

To avoid delays during agent initialization, you can pre-download the Hugging Face model:

You can pre-download a specific language model:

```python
from videosdk.plugins.turn_detector import pre_download_namo_turn_v1_model

# Download the English model before the agent runs
pre_download_namo_turn_v1_model(language="en")
```

Or pre-download the multilingual model:

```python
from videosdk.plugins.turn_detector import pre_download_namo_turn_v1_model

# Download the multilingual model
pre_download_namo_turn_v1_model()
```

## Additional Resources

The following resources provide more information about VideoSDK Turn Detector plugin for AI Agents SDK.








---

# AWS Nova Sonic

The AWS Nova Sonic provider enables your agent to use Amazon's Nova Sonic model for real-time, speech-to-speech AI interactions.

### Prerequisites

Before Start Using AWS Nova Sonic with the VideoSDK AI Agent, ensure the following:

- `AWS Account`: You have an active AWS account with permissions to access Amazon Bedrock.
- `Model Access`: You've requested and obtained access to the Amazon Nova models (Nova Lite and Nova Canvas) via the Amazon Bedrock console.
- `Region Selection`: You're operating in the US East (N. Virginia) (us-east-1) region, as model access is region-specific.
- `AWS Credentials`: Your AWS credentials (aws_access_key_id and aws_secret_access_key) are configured, either through environment variables or your preferred credential management method.

## Installation

Install the Gemini-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-aws"
```

## Authentication

The Amazon Nova Sonic plugin requires an [AWS API key](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html).

Set the following environment variables in your `.env` file:

```shell
AWS_ACCESS_KEY_ID=<aws-access-key-id>
AWS_SECRET_ACCESS_KEY=<aws-secret-access-key>
AWS_DEFAULT_REGION=<aws-deployment-region>

```

## Importing

```python
from videosdk.plugins.aws import NovaSonicRealtime, NovaSonicConfig
```

## Example Usage

```python
from videosdk.plugins.aws import NovaSonicRealtime, NovaSonicConfig
from videosdk.agents import RealTimePipeline

# Initialize the Nova Sonic real-time model
    model = NovaSonicRealtime(
        model="amazon.nova-sonic-v1:0",
        # When AWS credentials and region are set in .env - DON'T pass credential parameters
        region="us-east-1",  # Currently, only "us-east-1" is supported for Amazon Nova Sonic.
        aws_access_key_id="YOUR_ACCESS_KEY",
        aws_secret_access_key="YOUR_SECRET_KEY",
        config=NovaSonicConfig(
            voice="tiffany", #  "tiffany","matthew", "amy"
            temperature=0.7,
            top_p=0.9,
            max_tokens=1024
        )
    )

# Create the pipeline with the model
pipeline = RealTimePipeline(model=model)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit api_key, videosdk_auth, and other credential parameters from your code.
:::

:::note
To initiate a conversation with Amazon Nova Sonic, the user must speak first. The model listens for user input to begin the interaction.
:::

## See it in Action

Explore a complete, end-to-end implementation of an agent using this provider in our [AI Agent Quickstart Guide](https://docs.videosdk.live/ai_agents/voice-agent-quick-start).

## Configuration Options

- `model`: The Amazon Nova Sonic model to use (e.g., "amazon.nova-sonic-v1:0").
- `region`: AWS region where the model is hosted (e.g., "us-east-1").
- `aws_access_key_id`: Your AWS access key ID.
- `aws_secret_access_key`: Your AWS secret access key.
- `config`: A NovaSonicConfig object for advanced options:
  - `voice`: (str or None) The voice to use for audio output (e.g., "matthew", "tiffany", "amy").
  - `temperature`: (float or None) Sampling temperature for response randomness.
  - `top_p`: (float or None) Nucleus sampling probability.
  - `max_tokens`: (int or None) Maximum number of tokens in the output

## Additional Resources

The following resources provide more information about using AWS Nova Sonic with VideoSDK Agents SDK.

- **[Plugin quickstart](https://github.com/videosdk-live/agents-quickstart/blob/main/Realtime%20Pipeline/AWS%20Nova%20Sonic/aws_novasonic_agent_quickstart.py)**: Quickstart for the AWS Nova Sonic API plugin.

- **[AWS Nova Sonic docs](https://docs.aws.amazon.com/nova/latest/userguide/speech.html)**: AWS Nova Sonic documentation.





---

# Azure Voice Live API (Beta)

The Azure Voice Live API provider enables your agent to use Microsoft's comprehensive speech-to-speech solution for low-latency, high-quality voice interactions. This unified API eliminates the need to manually orchestrate multiple components by integrating speech recognition, generative AI, and text-to-speech into a single interface.

:::note Preview Feature
This feature is currently in public preview. This preview is provided without a service-level agreement, and is not recommended for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/voice-live).
:::

## Installation

Install the Azure-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-azure"
```

## Authentication

The Azure Voice Live plugin requires an Azure AI Services resource with Cognitive Services endpoint.

**Setup Steps:**
1. Create an AI Services resource for Speech in the [Azure portal](https://portal.azure.com) or from [Azure AI Foundry](https://ai.azure.com/foundryProject/overview)
2. Get the AI Services resource endpoint and primary key. After your resource is deployed, select "Go to resource" to view and manage keys

Set `AZURE_VOICE_LIVE_ENDPOINT` and `AZURE_VOICE_LIVE_API_KEY` in your `.env` file:

```bash
AZURE_VOICE_LIVE_ENDPOINT=your-azure-ai-service-endpoint
AZURE_VOICE_LIVE_API_KEY=your-azure-ai-service-primary-key
```

## Importing

```python
from videosdk.plugins.azure import AzureVoiceLive, AzureVoiceLiveConfig
from videosdk.agents import RealTimePipeline
```

## Example Usage

```python
from videosdk.plugins.azure import AzureVoiceLive, AzureVoiceLiveConfig
from videosdk.agents import RealTimePipeline

# Configure the Voice Live API settings
config = AzureVoiceLiveConfig(
    voice="en-US-EmmaNeural",  # Azure neural voice
    temperature=0.7,
    turn_detection_timeout=1000,
    enable_interruption=True
)

# Initialize the Azure Voice Live model
model = AzureVoiceLive(
    # When environment variables are set in .env - DON'T pass credentials
    # api_key="your-azure-speech-key",
    model="gpt-4o-realtime-preview",
    config=config
)

# Create the pipeline with the model
pipeline = RealTimePipeline(model=model)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit `api_key`, `speech_region`, and other credential parameters from your code.
:::

:::note
To initiate a conversation with Azure Voice Live, the user must speak first. The model listens for user input to begin the interaction.
:::

## Configuration Options

- `model`: The Voice Live model to use (e.g., `"gpt-4o-realtime-preview"`, `"gpt-4o-mini-realtime-preview"`)
- `api_key`: Your Azure Speech API key (can also be set via environment variable)
- `speech_region`: Your Azure Speech region (can also be set via environment variable)
- `credential`: Azure DefaultAzureCredential for authentication (alternative to API key)
- `config`: An `AzureVoiceLiveConfig` object for advanced options:
  - `voice`: (str) The Azure neural voice to use (e.g., `"en-US-EmmaNeural"`, `"hi-IN-AnanyaNeural"`)
  - `temperature`: (float) Sampling temperature for response randomness (default: 0.7)
  - `turn_detection_timeout`: (int) Timeout for turn detection in milliseconds
  - `enable_interruption`: (bool) Allow users to interrupt the agent during speech
  - `noise_suppression`: (bool) Enable noise suppression for clearer audio
  - `echo_cancellation`: (bool) Enable echo cancellation
  - `phrase_list`: (List[str]) Custom phrases for improved recognition accuracy

## See it in Action

Explore a complete, end-to-end implementation of an agent using this provider in our [AI Agent Quickstart Guide](https://docs.videosdk.live/ai_agents/voice-agent-quick-start).

## Additional Resources

The following resources provide more information about using Azure Voice Live with VideoSDK Agents SDK.

- **[Azure Voice Live API Documentation](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/voice-live)**: Complete Azure Voice Live API documentation.
- **[Azure Speech Service Overview](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/overview)**: Overview of Azure Speech services.





---

# Google Gemini (LiveAPI)

The Google Gemini (Live API) provider allows your agent to leverage Google's Gemini models for real-time, multimodal AI interactions.

## Installation

Install the Gemini-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-google"
```

## Authentication

The Google plugin requires an [Gemini API key](https://aistudio.google.com/apikey).

Set `GOOGLE_API_KEY` in your `.env` file.

## Importing

```python
from videosdk.plugins.google import GeminiRealtime, GeminiLiveConfig
```

## Example Usage

```python
from videosdk.plugins.google import GeminiRealtime, GeminiLiveConfig
from videosdk.agents import RealTimePipeline

# Initialize the Gemini real-time model
model = GeminiRealtime(
    model="gemini-2.5-flash-native-audio-preview-12-2025",
    # When GOOGLE_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-google-api-key",
    config=GeminiLiveConfig(
        voice="Leda", # Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus, and Zephyr.
        response_modalities=["AUDIO"]
    )
)

# Create the pipeline with the model
pipeline = RealTimePipeline(model=model)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit api_key, videosdk_auth, and other credential parameters from your code.
:::

## Vertex AI Integration

You can also use Google's Gemini models through Vertex AI. This requires a different authentication and configuration setup.

### Authentication for Vertex AI

For Vertex AI, you need to set up Google Cloud credentials. Create a service account, download the JSON key file, and set the path to this file in your environment.

```bash
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"
```

You should also configure your project ID and location. These can be set as environment variables or directly in the code. If not set, the `project_id` is inferred from the credentials file and the `location` defaults to `us-central1`.

```bash
export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"
export GOOGLE_CLOUD_LOCATION="your-gcp-location"
```

### Example Usage with Vertex AI

To use Vertex AI, set `vertexai=True` when initializing `GeminiRealtime`. You can configure the project and location using `VertexAIConfig`, which will take precedence over environment variables.

```python
from videosdk.plugins.google import GeminiRealtime, VertexAIConfig
from videosdk.agents import RealTimePipeline

# Initialize the Gemini real-time model with Vertex AI configuration
model = GeminiRealtime(
    model="gemini-live-2.5-flash-native-audio",
    vertexai=True,
    vertexai_config=VertexAIConfig(
        project_id="videosdk",
        location="us-central1"
    )
)

# Create the pipeline with the model
pipeline = RealTimePipeline(model=model)
```


## Vision Support

Google Gemini Live can also accept `video stream` directly from the VideoSDK room. To enable this, simply turn on your camera and set the vision flag to true in the session context. Once that's done, start your agent as usual—no additional changes are required in the pipeline.

```python
pipeline = RealTimePipeline(model=model)

session = AgentSession(
    agent=my_agent,
    pipeline=pipeline,
)

job_context = JobContext(
  room_options = RoomOptions(
    room_id = "YOUR_ROOM_ID",
    name = "Agent",
    vision = True
  )
)
```

- `vision` (bool, room options) – when `True`, forwards Video Stream from VideoSDK's room to Gemini’s LiveAPI (defaults to `False`).

## See it in Action

Explore a complete, end-to-end implementation of an agent using this provider in our [AI Agent Quickstart Guide](https://docs.videosdk.live/ai_agents/voice-agent-quick-start).

## Configuration Options

- `model`: The Gemini model to use (e.g., `"gemini-2.5-flash-native-audio-preview-12-2025"`). Other supported models include: `"gemini-2.5-flash-preview-native-audio-dialog"` and `"gemini-2.5-flash-exp-native-audio-thinking-dialog"`.
- `api_key`: Your Google API key (can also be set via environment variable)
- `config`: A `GeminiLiveConfig` object for advanced options:
  - `voice`: (str or None) The voice to use for audio output (e.g., `"Puck"`).
  - `language_code`: (str or None) The language code for the conversation (e.g., `"en-US"`).
  - `temperature`: (float or None) Sampling temperature for response randomness.
  - `top_p`: (float or None) Nucleus sampling probability.
  - `top_k`: (float or None) Top-k sampling for response diversity.
  - `candidate_count`: (int or None) Number of candidate responses to generate.
  - `max_output_tokens`: (int or None) Maximum number of tokens in the output.
  - `presence_penalty`: (float or None) Penalty for introducing new topics.
  - `frequency_penalty`: (float or None) Penalty for repeating tokens.
  - `response_modalities`: (List[str] or None) List of enabled output modalities (e.g., `["TEXT"]`or `["AUDIO"]`(one at a time)).
  - `output_audio_transcription`: (`AudioTranscriptionConfig` or None) Configuration for audio output transcription.

## Additional Resources

The following resources provide more information about using Google with VideoSDK Agents SDK.

- **[Plugin quickstart](<https://github.com/videosdk-live/agents-quickstart/tree/main/Realtime%20Pipeline/Google%20Gemini%20(LiveAPI)>)**: Quickstart for the Gemini Realtime API plugin.

- **[Gemini docs](https://ai.google.dev/gemini-api/docs/live)**: Gemini Live API documentation.





---

# OpenAI

The OpenAI provider enables your agent to use OpenAI's real-time models (like GPT-4o) for text and audio interactions.

## Installation

Install the OpenAI-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-openai"
```

## Authentication

The OpenAI plugin requires an [OpenAI API key](https://platform.openai.com/api-keys).

Set `OPENAI_API_KEY` in your `.env` file.

## Importing

```python
from videosdk.plugins.openai import OpenAIRealtime, OpenAIRealtimeConfig
```

## Example Usage

```python
from videosdk.plugins.openai import OpenAIRealtime, OpenAIRealtimeConfig
from videosdk.agents import RealTimePipeline
from openai.types.beta.realtime.session import  TurnDetection

# Initialize the OpenAI real-time model
model = OpenAIRealtime(
    model="gpt-realtime-2025-08-28",
    # When OPENAI_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-openai-api-key",
    config=OpenAIRealtimeConfig(
        voice="alloy", # alloy, ash, ballad, coral, echo, fable, onyx, nova, sage, shimmer, and verse
        modalities=["text", "audio"],
        turn_detection=TurnDetection(
            type="server_vad",
            threshold=0.5,
            prefix_padding_ms=300,
            silence_duration_ms=200,
        ),
        tool_choice="auto"
    )
)

# Create the pipeline with the model
pipeline = RealTimePipeline(model=model)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit api_key, videosdk_auth, and other credential parameters from your code.
:::

## See it in Action

Explore a complete, end-to-end implementation of an agent using this provider in our [AI Agent Quickstart Guide](https://docs.videosdk.live/ai_agents/voice-agent-quick-start).

## Configuration Options

- `model`: The OpenAI model to use (e.g., `"gpt-realtime-2025-08-28"`)
- `api_key`: Your OpenAI API key (can also be set via environment variable)
- `config`: An `OpenAIRealtimeConfig` object for advanced options:
  - `voice`: (str) The voice to use for audio output (e.g., `"alloy"`).
  - `temperature`: (float) Sampling temperature for response randomness.
  - `turn_detection`: (`TurnDetection` or None) Configure how the agent detects when a user has finished speaking.
  - `input_audio_transcription`: (`InputAudioTranscription` or None) Configure audio-to-text (e.g., Whisper).
  - `tool_choice`: (str or None) Tool selection mode (e.g., `"auto"`).
  - `modalities`: (list[str]) List of enabled modalities (e.g., `["text", "audio"]`).

## Additional Resources

The following resources provide more information about using OpenAI with VideoSDK Agents SDK.

- **[Plugin quickstart](https://github.com/videosdk-live/agents-quickstart/tree/main/Realtime%20Pipeline/OpenAI)**: Quickstart for the OpenAI Realtime API plugin.

- **[OpenAI docs](https://platform.openai.com/docs/guides/realtime)**: OpenAI Realtime API documentation.





---

# Ultravox

The Ultravox provider enables your agent to use Ultravox's models for real-time, conversational AI interactions.

## Installation

Install the Ultravox-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-ultravox"
```

## Authentication

The Ultravox plugin requires an [Ultravox API key](https://app.ultravox.ai/).

Set the `ULTRAVOX_API_KEY` in your `.env` file.

## Importing

```python
from videosdk.plugins.ultravox import UltravoxRealtime, UltravoxLiveConfig
```

## Example Usage

```python
from videosdk.plugins.ultravox import UltravoxRealtime, UltravoxLiveConfig
from videosdk.agents import RealTimePipeline

# Initialize the Ultravox real-time model
model = UltravoxRealtime(
    model="fixie-ai/ultravox",
    # When ULTRAVOX_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-ultravox-api-key",
    config=UltravoxLiveConfig(
        voice="54ebeae1-88df-4d66-af13-6c41283b4332"
    )
)

# Create the pipeline with the model
pipeline = RealTimePipeline(model=model)
```

:::note
When using a `.env` file for credentials, you do not need to pass the `api_key` as an argument to the model instance; the SDK reads it automatically.
:::

## Key Features

- **Real-time Interactions**: Utilize Ultravox's powerful models for low-latency voice conversations.
- **Function Calling**: Empower your agent to perform actions like retrieving weather data or calling external APIs.
- **Custom Agent Behaviors**: Define a unique personality and interaction style for your agent through system prompts.
- **Call Control**: Agents can manage the conversation flow and gracefully terminate calls.
- **MCP Integration**: Connect to external tools and data sources using the Model Context Protocol (MCP) via `MCPServerStdio` for local processes or `MCPServerHTTP` for remote services.

## Configuration Options

- `model`: The Ultravox model to use (e.g., `"fixie-ai/ultravox"`).
- `api_key`: Your Ultravox API key (can also be set via the `ULTRAVOX_API_KEY` environment variable).
- `config`: An `UltravoxLiveConfig` object for advanced options:
  - `voice`: (str) The Voice ID for the synthesized speech.
  - `language_hint`: (str) A hint for the conversation's language (e.g., `"en"`).
  - `temperature`: (float) Controls the randomness of responses (0.0 to 1.0).
  - `vad_turn_endpoint_delay`: (int) Delay in milliseconds for voice activity detection to determine the end of a turn.
  - `vad_minimum_turn_duration`: (int) The minimum duration in milliseconds for a valid speech turn.

## Additional Resources

The following resources provide more information about using Ultravox with the VideoSDK Agents SDK.





---

# xAI (Grok)

The xAI (Grok) provider enables your agent to use xAI's powerful Grok models for real-time, multimodal AI interactions.

## Installation

Install the xAI-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-xai"
```

## Authentication

The xAI plugin requires an [xAI API key](https://console.x.ai).

Set `XAI_API_KEY` in your `.env` file.

## Importing

```python
from videosdk.plugins.xai import XAIRealtime, XAIRealtimeConfig
```

## Example Usage

```python
from videosdk.plugins.xai import XAIRealtime, XAIRealtimeConfig
from videosdk.agents import RealTimePipeline

# Initialize the xAI Grok real-time model
model = XAIRealtime(
    model="grok-4-1-fast-non-reasoning",
    # When XAI_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-xai-api-key",
    config=XAIRealtimeConfig(
        voice="Eve",
        # collection_id="your-collection-id" # Optional
    )
)

# Create the pipeline with the model
pipeline = RealTimePipeline(model=model)
```

:::note
When using a `.env` file for credentials, don't pass them as arguments to model instances. The SDK automatically reads environment variables, so omit the `api_key` parameter from your code.
:::

## Key Features

- **Multi-modal Interactions**: Utilize xAI's powerful Grok models for voice and text.
- **Function Calling**: Define custom tools to retrieve weather data, interact with external APIs, or perform other actions.
- **Web Search**: Enable real-time web search capabilities by setting `enable_web_search=True`.
- **X Search**: Access X (formerly Twitter) content by setting `enable_x_search=True` and providing `allowed_x_handles`.

## Configuration Options

- `model`: The Grok model to use (e.g., `"grok-4-1-fast-non-reasoning"`).
- `api_key`: Your xAI API key (can also be set via the `XAI_API_KEY` environment variable).
- `config`: An `XAIRealtimeConfig` object for advanced options:
    - `voice`: (str) The voice to use for audio output (e.g., `"Eve"`, `"Ara"`, `"Rex"`, `"Sal"`, `"Leo"`).
    - `enable_web_search`: (bool) Enable or disable web search capabilities.
    - `enable_x_search`: (bool) Enable or disable search on X (Twitter).
    - `allowed_x_handles`: (List[str]) A list of allowed X handles to search within.
    - `collection_id`: (str, optional) The ID of a custom collection from your xAI Console storage to provide additional context.
    - `turn_detection`: Configuration for detecting when a user has finished speaking.

## Collection Storage

xAI Grok supports using "collections" to provide additional context to your agent, grounding its responses in your own documents or data.

To use a collection:

1.  **Navigate to xAI Console**: Go to your [console.x.ai](https://console.x.ai) dashboard.
2.  **Access Storage**: Click on the **Storage** section in the sidebar.
3.  **Create New Collection**: Click the "Create New Collection" button.
4.  **Upload Files**: Upload your relevant documents or data files to the new collection.
5.  **Get Collection ID**: Once the collection is created, copy its **Collection ID**.
6.  **Use in Config**: Pass the copied ID to your agent's configuration:

```python
config=XAIRealtimeConfig(
    voice="Eve",
    collection_id="your-collection-id-from-console",
    # ... other config options
)
```

The agent will now use the content of this collection to inform its responses.

## Additional Resources

The following resources provide more information about using xAI (Grok) with the VideoSDK Agents SDK.





---

# Silero VAD

The Silero VAD (Voice Activity Detection) provider enables your agent to detect when users start and stop speaking. When added to a cascading pipeline, it automatically enables interrupt functionality - allowing users to interrupt the agent mid-response.

## Installation

Install the Silero VAD-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-silero"
```

## Importing

```python
from videosdk.plugins.silero import SileroVAD
```

## Example Usage

```python
from videosdk.plugins.silero import SileroVAD
from videosdk.agents import CascadingPipeline

# Initialize the Silero VAD
vad = SileroVAD(
    input_sample_rate=48000,
    model_sample_rate=16000,
    threshold=0.3,
    min_speech_duration=0.1,
    min_silence_duration=0.75,
    prefix_padding_duration=0.3
)

# Add VAD to cascading pipeline - automatically enables interrupts
pipeline = CascadingPipeline(vad=vad)
```

## Configuration Options

- `input_sample_rate`: (int) Sample rate of input audio in Hz (default: `48000`)
- `model_sample_rate`: (Literal[8000, 16000]) Model's expected sample rate (default: `16000`)
- `threshold`: (float) Voice activity detection sensitivity (0.0 to 1.0, default: `0.3`)
- `min_speech_duration`: (float) Minimum speech duration to trigger detection in seconds (default: `0.1`)
- `min_silence_duration`: (float) Minimum silence duration to end speech detection in seconds (default: `0.75`)
- `max_buffered_speech`: (float) Maximum speech buffer duration in seconds (default: `60.0`)
- `force_cpu`: (bool) Force CPU usage instead of GPU acceleration (default: `True`)
- `prefix_padding_duration`: (float) Audio padding before speech detection in seconds (default: `0.3`)

## Additional Resources

The following resources provide more information about using Silero VAD with VideoSDK Agents SDK.

- **[Silero VAD project](https://github.com/snakers4/silero-vad)**: The open source VAD model that powers the VideoSDK Silero VAD plugin.





---

# AssemblyAI STT

The AssemblyAI STT provider enables your agent to use AssemblyAI's real-time WebSocket API for fast and accurate speech-to-text conversion.

## Installation

Install the AssemblyAI-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-assemblyai"
```

## Authentication

The AssemblyAI plugin requires an [AssemblyAI API key](https://www.assemblyai.com/dashboard/docs/your-api-key).

Set `ASSEMBLYAI_API_KEY` in your `.env` file.

## Importing

```python
from videosdk.plugins.assemblyai import AssemblyAISTT
```

## Example Usage

```python
from videosdk.plugins.assemblyai import AssemblyAISTT
from videosdk.agents import CascadingPipeline

# Initialize the AssemblyAI STT model
stt = AssemblyAISTT(
    api_key="your-assemblyai-api-key",
    language_code="en_us"
)

#  Add stt to cascading pipeline
pipeline = CascadingPipeline(stt=stt)
```

:::note
When using a `.env` file for credentials, don't pass them as arguments to model instances. The SDK automatically reads environment variables, so omit `api_key` and other credential parameters from your code.
:::

## Configuration Options

- `api_key`: Your AssemblyAI API key (required, can also be set via `ASSEMBLYAI_API_KEY` environment variable).
- `language_code`: The language code for transcription (e.g., `"en_us"`, `"es"`).

## Additional Resources

The following resources provide more information about using AssemblyAI with the VideoSDK Agents SDK.

- **[AssemblyAI Docs](https://www.assemblyai.com/docs/guides/speech-to-text/real-time-streaming-transcription)**: AssemblyAI's official real-time streaming transcription documentation.

```



```


---

# Azure STT

The Azure STT provider enables your agent to use Microsoft Azure's advanced speech-to-text models for high-accuracy, real-time audio transcription with support for multiple languages and custom phrase lists.

## Installation

Install the Azure-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-azure"
```

## Importing

```python
from videosdk.plugins.azure import AzureSTT
```

## Authentication

The Azure STT plugin requires an Azure AI Speech Service resource.

**Setup Steps:**
1. Create an AI Services resource for Speech in the [Azure portal](https://portal.azure.com) or from [Azure AI Foundry](https://ai.azure.com/foundryProject/overview)
2. Get the Speech resource key and region. After your Speech resource is deployed, select "Go to resource" to view and manage keys

Set `AZURE_SPEECH_KEY` and `AZURE_SPEECH_REGION` in your `.env` file:

```bash
AZURE_SPEECH_KEY=your-azure-speech-key
AZURE_SPEECH_REGION=your-azure-region
```

## Example Usage

```python
from videosdk.plugins.azure import AzureSTT
from videosdk.agents import CascadingPipeline

# Initialize the Azure STT model
stt = AzureSTT(
    language="en-US",
    sample_rate=16000,
    enable_phrase_list=True,
    phrase_list=["VideoSDK", "artificial intelligence", "machine learning"]
)

# Add stt to cascading pipeline
pipeline = CascadingPipeline(stt=stt)
```

:::note
When using environment variables for credentials, don't pass the `speech_key` and `speech_region` as arguments to the model instance. The SDK automatically reads the environment variables.
:::

## Configuration Options

- `speech_key`: (Optional[str]) Azure Speech API key. Uses `AZURE_SPEECH_KEY` environment variable if not provided.
- `speech_region`: (Optional[str]) Azure Speech region (e.g., `"eastus"`, `"westus2"`). Uses `AZURE_SPEECH_REGION` environment variable if not provided.
- `language`: (str) The language code for transcription (default: `"en-US"`). See [supported languages](https://learn.microsoft.com/en-us/globalization/locale/standard-locale-names).
- `sample_rate`: (int) The target audio sample rate in Hz for transcription (default: `16000`). The input audio at 48000Hz will be resampled to this rate.
- `enable_phrase_list`: (bool) Whether to enable phrase list for better recognition accuracy (default: `False`).
- `phrase_list`: (Optional[List[str]]) List of phrases to boost recognition for domain-specific terms (default: `None`).

## Additional Resources

The following resources provide more information about using Azure with VideoSDK Agents SDK.

- **[Azure Speech Service Overview](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/overview)**: Complete overview of Azure Speech services.
- **[Azure STT docs](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/index-speech-to-text)**: Azure Speech-to-Text documentation.
- **[Getting Started Guide](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/get-started-speech-to-text?tabs=macos&pivots=programming-language-python#prerequisites)**: Azure STT setup and prerequisites.





---

# Azure OpenAI STT

The Azure OpenAI STT provider enables your agent to use Azure OpenAI's speech-to-text models (like Whisper) for converting audio input to text.

## Installation

Install the Azure OpenAI-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-openai"
```

## Authentication

The Azure OpenAI plugin requires either an [Azure OpenAI API key](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/create-resource?pivots=web-portal).

Set `AZURE_OPENAI_API_KEY` , `AZURE_OPENAI_ENDPOINT` and `OPENAI_API_VERSION` in your `.env` file.

## Importing

```python
from videosdk.plugins.openai import OpenAISTT
```

## Example Usage

```python
from videosdk.plugins.openai import OpenAISTT
from videosdk.agents import CascadingPipeline

# Initialize the Azure OpenAI STT model
stt = OpenAISTT.azure(
    azure_deployment="gpt-4o-transcribe",
    language="en",
)

#  Add stt to cascading pipeline
pipeline = CascadingPipeline(stt=stt)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit api_key, videosdk_auth, and other credential parameters from your code.
:::

## Configuration Options

- `azure_deployment`: The OpenAI deployment ID to use (by default it is model name: e.g., `"gpt-4o-mini-transcribe"`, `"gpt-4o-transcribe"`)
- `api_key`: Your Azure OpenAI API key (can also be set via environment variable)
- `azure_endpoint`: Your Azure OpenAI Deployment Endpoint URL (can also be set via environment variable)
- `api_version`: Your Azure OpenAI API version (can also be set via environment variable)
- `language`: (str) Language code for transcription (default: `"en"`)

## Additional Resources

The following resources provide more information about using OpenAI with VideoSDK Agents SDK.





---

# Cartesia STT

The Cartesia STT provider enables your agent to use Cartesia's advanced speech-to-text models for high-accuracy, real-time audio transcription.

## Installation

Install the Cartesia-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-cartesia"
```

## Importing

```python
from videosdk.plugins.cartesia import CartesiaSTT
```

## Authentication

The Cartesia plugin requires a [Cartesia API key](https://play.cartesia.ai/keys).

Set `CARTESIA_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.cartesia import CartesiaSTT
from videosdk.agents import CascadingPipeline

# Initialize the Cartesia STT model
stt = CartesiaSTT(
    # When CARTESIA_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-cartesia-api-key",
    language="en-US",
    model="ink-whisper",
)

#  Add stt to cascading pipeline
pipeline = CascadingPipeline(stt=stt)
```

:::note
When using an environment variable for credentials, don't pass the `api_key` as an argument to the model instance. The SDK automatically reads the environment variable.
:::

## Configuration Options

- `api_key`: (str) Your Cartesia API key. Can also be set via the `CARTESIA_API_KEY` environment variable.
- `model`: (str) The Cartesia STT model to use (e.g., `"ink-whisper"`). Defaults to `"ink-whisper"`.
- `language`: (str) Language code for transcription (default: `"en"`).

## Additional resources

The following resources provide more information about using Cartesia with VideoSDK Agents.

- **[Cartesia docs](https://docs.cartesia.ai/build-with-cartesia/models/stt)**: Cartesia STT docs.





---

# Deepgram STT

The Deepgram STT provider enables your agent to use Deepgram's advanced speech-to-text models for high-accuracy, real-time audio transcription.

## Installation

Install the Deepgram-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-deepgram"
```

## Authentication

The Deepgram plugin requires a [Deepgram API key](https://console.deepgram.com/).

Set `DEEPGRAM_API_KEY` in your `.env` file.

## Importing

**DeepgramSTT:**

```python
from videosdk.plugins.deepgram import DeepgramSTT
```

---

**DeepgramSTTV2:**

```python
from videosdk.plugins.deepgram import DeepgramSTTV2
```


## Example Usage

**DeepgramSTT:**

```python
from videosdk.plugins.deepgram import DeepgramSTT
from videosdk.agents import CascadingPipeline

# Initialize the Deepgram STT model
stt = DeepgramSTT(
# When DEEPGRAM_API_KEY is set in .env - DON'T pass api_key parameter
api_key="your-deepgram-api-key",
model="nova-2",
language="en-US",
interim_results=True,
punctuate=True,
smart_format=True
)

#  Add stt to cascading pipeline
pipeline = CascadingPipeline(stt=stt)
```

---

**DeepgramSTTV2:**

```python
from videosdk.plugins.deepgram import DeepgramSTTV2  
from videosdk.agents import CascadingPipeline  
  
# Initialize the Deepgram STT V2 model with Flux  
stt = DeepgramSTTV2(  
# When DEEPGRAM_API_KEY is set in .env - DON'T pass api_key parameter  
api_key="your-deepgram-api-key",  
model="flux-general-en",  
eager_eot_threshold=0.6,  
eot_threshold=0.8,  
eot_timeout_ms=7000  
)  
  
# Add stt to cascading pipeline  
pipeline = CascadingPipeline(stt=stt)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit api_key, videosdk_auth, and other credential parameters from your code.
:::

## Configuration Options

**DeepgramSTT:**

- `api_key`: Your Deepgram API key (can also be set via DEEPGRAM_API_KEY environment variable)
- `model`: The Deepgram model to use (e.g., "`nova-2`", "`nova-3`", "`whisper-large`") (default: "`nova-2`")
- `language`: (str) Language code for transcription (e.g., "`en-US`", "`es`", "`fr`") (default: "`en-US`")
- `interim_results`: (bool) Enable real-time partial transcription results (default: `True`)
- `punctuate`: (bool) Add punctuation to transcription (default: `True`)
- `smart_format`: (bool) Apply intelligent formatting to output (default: `True`)
- `filler_words`: (bool) Include filler words like "uh", "um" in transcription (default: `True`)
- `sample_rate`: (int) Audio sample rate in Hz (default: `48000`)
- `endpointing`: (int) Silence detection threshold in milliseconds (default: `50`)
- `base_url`: (str) WebSocket endpoint URL (default: `"wss://api.deepgram.com/v1/listen"`)

---

**DeepgramSTTV2:**

### Required Parameters

- `api_key`: Your Deepgram API key (can also be set via DEEPGRAM_API_KEY environment variable)
- `model`: The Flux model to use - language is embedded in model name (default: "`flux-general-en`")(currently only english is available)
- `input_sample_rate`: (int) Input audio sample rate in Hz (default: `48000`)
- `target_sample_rate`: (int) Target sample rate for Deepgram processing (default: `16000`)
- `eager_eot_threshold`: Confidence threshold for early end-of-turn detection, range 0.0-1.0 (default: `0.6`)
  - Lower values = more aggressive early detection
  - Higher values = wait for higher confidence before early turn end
- `eot_threshold`: Standard end-of-turn confidence threshold, range 0.0-1.0 (default: `0.8`)
  - Controls when a turn is definitively ended
- `eot_timeout_ms`: Timeout in milliseconds before forcing end-of-turn (default: `7000`)
  - Maximum silence duration before automatically ending turn
- `base_url`: (str) WebSocket endpoint URL (default: `"wss://api.deepgram.com/v2/listen"`)


## Additional Resources

The following resources provide more information about using Deepgram with VideoSDK Agents SDK.

- **[Deepgram docs V1](https://developers.deepgram.com/docs/live-streaming-audio)**: Deepgram's STT V1 docs
- **[Deepgram docs V2](https://developers.deepgram.com/docs/flux/quickstart)**: Deepgram's STT V2 docs
- **[Github URL V1](https://github.com/videosdk-live/agents/blob/main/videosdk-plugins/videosdk-plugins-deepgram/videosdk/plugins/deepgram/stt.py)** : Deepgram STT Plugin Source Code   
- **[Github URL V2](https://github.com/videosdk-live/agents/blob/main/videosdk-plugins/videosdk-plugins-deepgram/videosdk/plugins/deepgram/stt_v2.py)** : Deepgram STT V2 Plugin Source Code 




---

# ElevenLabs STT

The ElevenLabs STT provider enables your agent to use `ElevenLabs` advanced speech-to-text models for high-accuracy, real-time audio transcription with advanced voice activity detection.

## Installation

Install the ElevenLabs-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-elevenlabs"
```

## Importing

```python
from videosdk.plugins.elevenlabs import ElevenLabsSTT
```

## Authentication

The ElevenLabs plugin requires an [ElevenLabs API key](https://elevenlabs.io/app/settings/api-keys).

Set `ELEVENLABS_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.elevenlabs import ElevenLabsSTT
from videosdk.agents import CascadingPipeline

# Initialize the ElevenLabs STT model
stt = ElevenLabsSTT(
    # When ELEVENLABS_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-elevenlabs-api-key",
    model_id="scribe_v2_realtime",
    language_code="en",
    commit_strategy="vad",
    vad_silence_threshold_secs=0.8,
    vad_threshold=0.4,
    min_speech_duration_ms=50,
    min_silence_duration_ms=50
)

# Add stt to cascading pipeline
pipeline = CascadingPipeline(stt=stt)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit api_key, videosdk_auth, and other credential parameters from your code.
:::

## Configuration Options

- `api_key`: Your ElevenLabs API key (can also be set via ELEVENLABS_API_KEY environment variable)
- `model_id`: (str) STT model identifier (default: `"scribe_v2_realtime"`)
- `language_code`: (str) Language code for transcription (default: `"en"`)
- `sample_rate`: (int) Sample rate of input audio in Hz (default: `48000`)
- `commit_strategy`: (str) Strategy for committing transcripts (default: `"vad"`)
  - `"vad"` - Voice Activity Detection based commit strategy
- `vad_silence_threshold_secs`: (float) Duration of silence in seconds to detect end-of-speech (default: `0.8`)
- `vad_threshold`: (float) Threshold for detecting voice activity (default: `0.4`)
- `min_speech_duration_ms`: (int) Minimum duration in milliseconds for a speech segment (default: `50`)
- `min_silence_duration_ms`: (int) Minimum duration in milliseconds of silence to consider end-of-speech (default: `50`)

## Additional Resources

The following resources provide more information about using ElevenLabs with VideoSDK Agents SDK.

- **[ElevenLabs docs](https://elevenlabs.io/docs)**: ElevenLabs STT docs.





---

# Gladia STT

The Gladia STT provider enables your agent to use Gladia's fast and accurate speech-to-text models for real-time audio transcription with support for multiple languages and code-switching.

## Installation

Install the Gladia-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-gladia"
```

## Authentication

The Gladia plugin requires a [Gladia API key](https://app.gladia.io/signup).

Set `GLADIA_API_KEY` in your `.env` file.

## Importing

```python
from videosdk.plugins.gladia import GladiaSTT
```

## Example Usage

```python
from videosdk.plugins.gladia import GladiaSTT
from videosdk.agents import CascadingPipeline

# Initialize the Gladia STT model
stt = GladiaSTT(
    # When GLADIA_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-gladia-api-key",
    languages=["en"],
    code_switching=True,
    receive_partial_transcripts=True
)

#  Add stt to a cascading pipeline
pipeline = CascadingPipeline(stt=stt)
```

:::note
When using a `.env` file for credentials, you do not need to pass the `api_key` as an argument to the model instance; the SDK reads it automatically.
:::

## Configuration Options

- `api_key`: (str, optional) Your Gladia API key. Can also be set via the `GLADIA_API_KEY` environment variable.
- `model`: (str, optional) The model to use. Defaults to `"solaria-1"`.
- `languages`: (List[str], optional) A list of language codes to detect (e.g., `["en", "fr"]`). Defaults to `["en"]`.
- `code_switching`: (bool, optional) Enables automatic language switching between the provided languages. Defaults to `True`.
- `input_sample_rate`: (int, optional) The sample rate of the incoming audio. Defaults to `48000`.
- `output_sample_rate`: (int, optional) The sample rate Gladia should process. Defaults to `16000`.
- `encoding`: (str, optional) The audio encoding format. Defaults to `"wav/pcm"`.
- `bit_depth`: (int, optional) The bit depth of the audio. Defaults to `16`.
- `channels`: (int, optional) The number of audio channels. Defaults to `1` (mono).
- `receive_partial_transcripts`: (bool, optional) Set to `True` to receive interim transcription results for lower latency. Defaults to `False`.

---

# Google STT

The Google STT provider enables your agent to use Google's advanced speech-to-text models for high-accuracy, real-time audio transcription.

## Installation

Install the Google-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-google"
```

## Importing

```python
from videosdk.plugins.google import GoogleSTT
```

## Setup Credentials/Authentication

To use Google STT, you need to set up your Google Cloud credentials. You can do this by setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account key file.

```bash
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"
```

Alternatively, you can pass the path to the key file directly to the `GoogleSTT` constructor via the `api_key` parameter.
**or** Set `GOOGLE_APPLICATION_CREDENTIALS` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.google import GoogleSTT
from videosdk.agents import CascadingPipeline

# Initialize the Google STT model
stt = GoogleSTT(
    # If GOOGLE_APPLICATION_CREDENTIALS is set, you can omit api_key
    api_key="/path/to/your/keyfile.json",
    languages="en-US",
    model="latest_long",
    interim_results=True,
    punctuate=True
)

#  Add stt to cascading pipeline
pipeline = CascadingPipeline(stt=stt)
```

:::note
When using an environment variable for credentials, don't pass the `api_key` as an argument to the model instance. The SDK automatically reads the environment variable.
:::

## Configuration Options

- `api_key`: (str) Path to your Google Cloud service account JSON file. This can also be set via the `GOOGLE_APPLICATION_CREDENTIALS` environment variable.
- `languages`: (Union[str, list[str]]) Language code or a list of language codes for transcription (default: `"en-US"`).
- `model`: (str) The Google STT model to use (e.g., `"latest_long"`, `"telephony"`) (default: `"latest_long"`).
- `sample_rate`: (int) The target audio sample rate in Hz for transcription (default: `16000`). The input audio at 48000Hz will be resampled to this rate.
- `interim_results`: (bool) Enable real-time partial transcription results (default: `True`).
- `punctuate`: (bool) Add punctuation to transcription (default: `True`).
- `min_confidence_threshold`: (float) The minimum confidence level for a transcription result to be considered valid (default: `0.1`).
- `location`: (str) The Google Cloud location to use for the STT service (default: `"global"`).

## Additional Resources

The following resources provide more information about using Google with VideoSDK Agents SDK.

- **[Google STT docs](https://cloud.google.com/speech-to-text/docs)**: Google Cloud STT documentation.





---

# Navana STT

The Navana STT provider enables your agent to use Navana's Bodhi speech-to-text models, which are highly optimized for a variety of Indian languages and accents.

## Installation

Install the Navana-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-navana"
```

## Authentication

The Navana plugin requires a **Customer ID** and an **API Key** from your [Navana Bodhi account](https://bodhi.navana.ai/).

Set both `NAVANA_API_KEY` and `NAVANA_CUSTOMER_ID` in your `.env` file.

## Importing

```python
from videosdk.plugins.navana import NavanaSTT
```

## Example Usage

```python
from videosdk.plugins.navana import NavanaSTT
from videosdk.agents import CascadingPipeline

# Initialize the Navana STT model
stt = NavanaSTT(
    api_key="your-navana-api-key",
    customer_id="your-navana-customer-id",
    model="en-in-general-v2-8khz",
    language="en-IN"
)

#  Add stt to cascading pipeline
pipeline = CascadingPipeline(stt=stt)
```

:::note
When using a `.env` file for credentials, don't pass them as arguments to model instances. The SDK automatically reads environment variables, so omit `api_key`, `customer_id`, and other credential parameters from your code.
:::

## Configuration Options

- `api_key`: Your Navana API key (required, can also be set via `NAVANA_API_KEY` environment variable).
- `customer_id`: Your Navana Customer ID (required, can also be set via `NAVANA_CUSTOMER_ID` environment variable).
- `model`: The Navana STT model to use (e.g., `"en-in-general-v2-8khz"`, `"hi-general-v2-8khz"`).
- `language`: The language code for transcription (e.g., `"en-IN"`, `"hi-IN"`).

## Additional Resources

The following resources provide more information about using Navana with the VideoSDK Agents SDK.

- **[Navana Docs](https://navana.gitbook.io/bodhi/streaming-asr/streaming-websocket)**: Navana's official streaming API documentation.





---

# Nvidia STT

The Nvidia STT provider enables your agent to use Nvidia's Riva speech-to-text models for high-performance, low-latency speech recognition.

## Installation

Install the Nvidia-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-nvidia"
```

## Authentication

The Nvidia plugin requires an Nvidia API key.

Set `NVIDIA_API_KEY` in your `.env` file.

## Importing

```python
from videosdk.plugins.nvidia import NvidiaSTT
```

## Example Usage

```python
from videosdk.plugins.nvidia import NvidiaSTT
from videosdk.agents import CascadingPipeline

# Initialize the Nvidia STT model
stt = NvidiaSTT(
    # When NVIDIA_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-nvidia-api-key",
    model="parakeet-1.1b-en-US-asr-streaming-silero-vad-sortformer",
    language_code="en-US",
    profanity_filter=False,
    automatic_punctuation=True
)

#  Add stt to cascading pipeline
pipeline = CascadingPipeline(stt=stt)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit api_key and other credential parameters from your code.
:::

## Configuration Options

- `api_key`: Your Nvidia API key (required, can also be set via environment variable)
- `model`: The Nvidia Riva model to use (default: `"parakeet-1.1b-en-US-asr-streaming-silero-vad-sortformer"`)
- `server`: The Nvidia Riva server address (default: `"grpc.nvcf.nvidia.com:443"`)
- `function_id`: The specific function ID for the service (default: `"1598d209-5e27-4d3c-8079-4751568b1081"`)
- `language_code`: Language code for transcription (default: `"en-US"`)
- `sample_rate`: Audio sample rate in Hz (default: `16000`)
- `profanity_filter`: (bool) Enable or disable profanity filtering (default: `False`)
- `automatic_punctuation`: (bool) Enable or disable automatic punctuation (default: `True`)
- `use_ssl`: (bool) Enable SSL connection (default: `True`)

## Additional Resources

The following resources provide more information about using Nvidia Riva with VideoSDK Agents SDK.

- **[Nvidia Riva docs](https://docs.nvidia.com/deeplearning/riva/user-guide/docs/index.html)**: Nvidia Riva documentation.





---

# OpenAI STT

The OpenAI STT provider enables your agent to use OpenAI's speech-to-text models (like Whisper) for converting audio input to text.

## Installation

Install the OpenAI-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-openai"
```

## Authentication

The OpenAI plugin requires an [OpenAI API key](https://platform.openai.com/api-keys).

Set `OPENAI_API_KEY` in your `.env` file.

## Importing

```python
from videosdk.plugins.openai import OpenAISTT
```

## Example Usage

```python
from videosdk.plugins.openai import OpenAISTT
from videosdk.agents import CascadingPipeline

# Initialize the OpenAI STT model
stt = OpenAISTT(
    # When OPENAI_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-openai-api-key",
    model="whisper-1",
    language="en",
    prompt="Transcribe this audio with proper punctuation and formatting."
)

#  Add stt to cascading pipeline
pipeline = CascadingPipeline(stt=stt)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit api_key, videosdk_auth, and other credential parameters from your code.
:::

## Configuration Options

- `api_key`: Your OpenAI API key (required, can also be set via environment variable)
- `model`: The OpenAI STT model to use (e.g., `"whisper-1"`, `"gpt-4o-mini-transcribe"`)
- `base_url`: Custom base URL for OpenAI API (optional)
- `prompt`: (str) Custom prompt to guide transcription style and format
- `language`: (str) Language code for transcription (default: `"en"`)
- `turn_detection`: (dict) Configuration for detecting conversation turns

## Additional Resources

The following resources provide more information about using OpenAI with VideoSDK Agents SDK.

- **[OpenAI docs](https://platform.openai.com/docs/guides/speech-to-text)**: OpenAI STT API documentation.





---

# Sarvam AI STT

The Sarvam AI STT provider enables your agent to use Sarvam AI's speech-to-text models for transcription. This provider uses Voice Activity Detection (VAD) to send audio chunks for transcription after a period of silence.

## Installation

Install the Sarvam AI-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-sarvamai"
```

## Importing

```python
from videosdk.plugins.sarvamai import SarvamAISTT
```

## Authentication

The Sarvam plugin requires a [Sarvam API key](https://dashboard.sarvam.ai/key-management).

Set `SARVAM_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.sarvamai import SarvamAISTT
from videosdk.agents import CascadingPipeline

# Initialize the Sarvam AI STT model
stt = SarvamAISTT(
    # When SARVAMAI_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-sarvam-ai-api-key",
    model="saarika:v2",
    language="en-IN"
)

#  Add stt to cascading pipeline
pipeline = CascadingPipeline(stt=stt)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit `api_key` and other credential parameters from your code.
:::

## Configuration Options

- `api_key`: (str) Your Sarvam AI API key. Can also be set via the `SARVAMAI_API_KEY` environment variable.
- `model`: (str) The Sarvam AI model to use (default: `"saarika:v2"`).
- `language`: (str) Language code for transcription (default: `"en-IN"`).
- `input_sample_rate`: (int) The sample rate of the audio from the source in Hz (default: `48000`).
- `output_sample_rate`: (int) The sample rate to which the audio is resampled before sending for transcription (default: `16000`).
- `silence_threshold`: (float) The normalized amplitude threshold for silence detection (default: `0.01`).
- `silence_duration`: (float) The duration of silence in seconds that triggers the end of a speech segment for transcription (default: `0.8`).

## Additional Resources

The following resources provide more information about using Sarvam AI with VideoSDK Agents SDK.

- **[Sarvam docs](https://docs.sarvam.ai/)**: Sarvam's full docs site.





---

# AWS Polly TTS

The AWS Polly TTS provider enables your agent to use AWS Polly's high-quality text-to-speech models for generating natural-sounding voice output.

## Installation

Install the AWS Poly-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-aws"
```

## Importing

```python
from videosdk.plugins.aws import AWSPollyTTS
```

## Authentication

- `AWS Account`: You have an active AWS account with permissions to access Amazon Polly.
- `Region Selection`: You're operating in the US East (N. Virginia) (us-east-1) region, as model access is region-specific.
- `AWS Credentials`: Your AWS credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION) are configured, either through environment variables or your preferred credential management method.

## Example Usage

```python
from videosdk.plugins.aws import AWSPollyTTS
from videosdk.agents import CascadingPipeline

# Initialize the AWS Polly TTS model
tts = AWSPollyTTS(
    voice="Joanna",
    engine="neural",
    speed=1.2,
    pitch=0.1,
)

# Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit `api_key` and other credential parameters from your code.
:::

## Configuration Options

- `voice`: (str) Voice ID for the TTS output (default: `"Joanna"`).
- `engine`: (str) Polly engine type: `"standard"` or `"neural"` (default: `"neural"`).
- `region`: (str) AWS region for Polly service (default: `"us-east-1"` or from `AWS_DEFAULT_REGION`).
- `aws_access_key_id`: (str) AWS access key ID (optional; can be set via environment variable).
- `aws_secret_access_key`: (str) AWS secret access key (optional; can be set via environment variable).
- `aws_session_token`: (str) Optional AWS session token for temporary credentials.
- `speed`: (float) Speech rate multiplier (e.g., `1.0` is normal speed, `1.5` is 50% faster).
- `pitch`: (float) Pitch adjustment multiplier (e.g., `0.0` is normal, `0.2` raises pitch).

## Additional Resources

The following resources provide more information about using AWS Polly with VideoSDK Agents SDK.

- **[AWS Polly docs](https://docs.aws.amazon.com/polly/latest/dg/what-is.html)**: AWS Polly documentation.





---

# Azure TTS

The Azure TTS provider enables your agent to use Microsoft Azure's high-quality text-to-speech models for generating natural-sounding voice output with advanced voice tuning and expressive speaking styles.

## Installation

Install the Azure-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-azure"
```

## Importing

```python
from videosdk.plugins.azure import AzureTTS, VoiceTuning, SpeakingStyle
```

## Authentication

The Azure TTS plugin requires an Azure AI Speech Service resource.

**Setup Steps:**
1. Create an AI Services resource for Speech in the [Azure portal](https://portal.azure.com) or from [Azure AI Foundry](https://ai.azure.com/foundryProject/overview)
2. Get the Speech resource key and region. After your Speech resource is deployed, select "Go to resource" to view and manage keys

Set `AZURE_SPEECH_KEY` and `AZURE_SPEECH_REGION` in your `.env` file:

```bash
AZURE_SPEECH_KEY=your-azure-speech-key
AZURE_SPEECH_REGION=your-azure-region
```

## Example Usage

```python
from videosdk.plugins.azure import AzureTTS, VoiceTuning, SpeakingStyle
from videosdk.agents import CascadingPipeline

# Configure voice tuning for prosody control
voice_tuning = VoiceTuning(
    rate="fast",
    volume="loud", 
    pitch="high"
)

# Configure speaking style for expressive speech
speaking_style = SpeakingStyle(
    style="cheerful",
    degree=1.5
)

# Initialize the Azure TTS model
tts = AzureTTS(
    voice="en-US-EmmaNeural",
    language="en-US",
    tuning=voice_tuning,
    style=speaking_style
)

# Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit `speech_key`, `speech_region`, and other credential parameters from your code.
:::

## Configuration Options

- `speech_key`: (Optional[str]) Azure Speech API key. Uses `AZURE_SPEECH_KEY` environment variable if not provided.
- `speech_region`: (Optional[str]) Azure Speech region (e.g., `"eastus"`, `"westus2"`). Uses `AZURE_SPEECH_REGION` environment variable if not provided.
- `speech_endpoint`: (Optional[str]) Custom endpoint URL. Uses `AZURE_SPEECH_ENDPOINT` environment variable if not provided.
- `voice`: (str) Voice name to use for audio output (default: `"en-US-EmmaNeural"`). Get available voices using the [Azure voices API](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/how-to-speech-synthesis?tabs=browserjs%2Cterminal&pivots=programming-language-python#select-synthesis-language-and-voice).
- `language`: (str) Language code (optional, inferred from voice if not specified).
- `tuning`: (`VoiceTuning`) Voice tuning object for rate, volume, and pitch control:
  - `rate`: (str) Speaking rate (`"x-slow"`, `"slow"`, `"medium"`, `"fast"`, `"x-fast"` or percentage like `"50%"`)
  - `volume`: (str) Speaking volume (`"silent"`, `"x-soft"`, `"soft"`, `"medium"`, `"loud"`, `"x-loud"` or percentage)
  - `pitch`: (str) Voice pitch (`"x-low"`, `"low"`, `"medium"`, `"high"`, `"x-high"` or frequency like `"+50Hz"`)
- `style`: (`SpeakingStyle`) Speaking style object for expressive speech:
  - `style`: (str) Speaking style (e.g., `"cheerful"`, `"sad"`, `"angry"`, `"excited"`, `"friendly"`)
  - `degree`: (float) Style intensity from 0.01 to 2.0 (default: 1.0)
- `deployment_id`: (str) Custom deployment ID for custom models.
- `speech_auth_token`: (str) Authorization token for authentication.

## Voice Selection

You can find available voices using the Azure Voices List API:

```bash
curl --location --request GET 'https://eastus2.tts.speech.microsoft.com/cognitiveservices/voices/list' \
--header 'Ocp-Apim-Subscription-Key: YOUR_SPEECH_KEY'
```

Popular voice options include:
- `en-US-EmmaNeural` (Female, neutral)
- `en-US-BrianNeural` (Male, neutral)  
- `en-US-AriaNeural` (Female, cheerful)
- `en-GB-SoniaNeural` (Female, British)

## Additional Resources

The following resources provide more information about using Azure with VideoSDK Agents SDK.

- **[Azure Speech Service Overview](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/overview)**: Complete overview of Azure Speech services.
- **[Azure TTS docs](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/index-text-to-speech)**: Azure Text-to-Speech documentation.
- **[Voice Selection Guide](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/how-to-speech-synthesis?tabs=browserjs%2Cterminal&pivots=programming-language-python#select-synthesis-language-and-voice)**: Guide for selecting synthesis language and voice.
- **[Speech Synthesis Markup](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/speech-synthesis-markup-voice#adjust-prosody)**: Learn about prosody adjustments and voice tuning.





---

# Azure OpenAI TTS

The Azure OpenAI TTS provider enables your agent to use Azure OpenAI's text-to-speech models for converting text responses to natural-sounding audio output.

## Installation

Install the Azure OpenAI-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-openai"
```

## Importing

```python
from videosdk.plugins.openai import OpenAITTS
```

## Authentication

The Azure OpenAI plugin requires either an [Azure OpenAI API key](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/create-resource?pivots=web-portal).

Set `AZURE_OPENAI_API_KEY` , `AZURE_OPENAI_ENDPOINT` and `OPENAI_API_VERSION` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.openai import OpenAITTS
from videosdk.agents import CascadingPipeline

# Initialize the Azure OpenAI TTS model
tts = OpenAITTS.azure(
    azure_deployment="gpt-4o-mini-tts",
    speed=1.0,
    response_format="pcm"
)

#  Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit api_key, videosdk_auth, and other credential parameters from your code.
:::

## Configuration Options

- `azure_deployment`: The OpenAI deployment ID to use (by default it is model name: e.g., `"gpt-4o-mini-tts"`)
- `api_key`: Your Azure OpenAI API key (can also be set via environment variable)
- `azure_endpoint`: Your Azure OpenAI Deployment Endpoint URL (can also be set via environment variable)
- `api_version`: Your Azure OpenAI API version (can also be set via environment variable)
- `voice`: (str) Voice to use for audio output (e.g., `"alloy"`, `"echo"`, `"fable"`, `"onyx"`, `"nova"`, `"shimmer"`)
- `speed`: (float) Speed of the generated audio (0.25 to 4.0, default: 1.0)

## Additional Resources

The following resources provide more information about using OpenAI with VideoSDK Agents SDK.





---

# Cartesia TTS

The Cartesia TTS provider enables your agent to use Cartesia's high-quality, low-latency text-to-speech models for generating natural-sounding voice output.

## Installation

Install the Cartesia-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-cartesia"
```

## Importing

```python
from videosdk.plugins.cartesia import CartesiaTTS
```

## Authentication

The Cartesia plugin requires a [Cartesia API key](https://play.cartesia.ai/keys).

Set `CARTESIA_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.cartesia import CartesiaTTS
from videosdk.agents import CascadingPipeline

# Initialize the Cartesia TTS model
tts = CartesiaTTS(
    # When CARTESIA_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-cartesia-api-key",
    model="sonic-2",
    voice_id="794f9389-aac1-45b6-b726-9d9369183238",
    language="en"
)

# Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances. The SDK automatically reads environment variables, so omit `api_key` and other credential parameters from your code.
:::

## Configuration Options

- `api_key`: (str) Your Cartesia API key. Can also be set via the `CARTESIA_API_KEY` environment variable.
- `model`: (str) The Cartesia TTS model to use (e.g., `"sonic-2"`, `"sonic-turbo"`). Defaults to `"sonic-2"`.
- `voice_id`: (str) The ID of the voice to use for generating speech.
- `language`: (str) The language of the voice (e.g., `"en"`, `"fr"`). Defaults to `"en"`.

## Additional resources

The following resources provide more information about using Cartesia with VideoSDK Agents.

- **[Cartesia docs](https://docs.cartesia.ai/build-with-cartesia/models/tts)**: Cartesia TTS docs.





---

# Deepgram TTS 

The Deepgram TTS provider enables your agent to use Deepgram's high-quality text-to-speech models for generating natural, expressive voice output with advanced voice capabilities.

## Installation

Install the Deepgram-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-deepgram"
```

## Importing

```python
from videosdk.plugins.deepgram import DeepgramTTS
```

## Authentication

The Deepgram plugin requires an [Deepgram API key](https://developers.deepgram.com/docs/create-additional-api-keys).

Set `DEEPGRAM_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.deepgram import DeepgramTTS
from videosdk.agents import CascadingPipeline

# Initialize the Deepgram TTS model
tts = Deepgram(
    # When DEEPGRAM_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-deepgram-api-key",
    model="aura-asteria-en",
    encoding="linear16", # linear16, mulaw, alaw, opus, mp3, flac, aac
    sample_rate=24000
)

# Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit api_key, videosdk_auth, and other credential parameters from your code.
:::

## Configuration Options

- `model` : The Deepgram model to use (e.g., `"aura-asteria-en"`, `"aura-luna-en"`)
- `api_key`: Your Deepgram API key (can also be set via environment variable)
- `encoding` : (str) Encoding allows you to specify the expected encoding of your audio output (default : `"linear16"`)
- `sample_rate`: (int) Sample rate for output (default: `24000`)

## Additional Resources

The following resources provide more information about using Deepgram with VideoSDK Agents SDK.

- **[Deepgram docs](https://developers.deepgram.com/reference/text-to-speech-api/speak-streaming)**: Deepgram TTS docs.





---

# ElevenLabs TTS

The ElevenLabs TTS provider enables your agent to use ElevenLabs' high-quality text-to-speech models for generating natural, expressive voice output with advanced voice cloning capabilities.

## Installation

Install the ElevenLabs-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-elevenlabs"
```

## Importing

```python
from videosdk.plugins.elevenlabs import ElevenLabsTTS, VoiceSettings
```

## Authentication

The ElevenLabs plugin requires an [ElevenLabs API key](https://elevenlabs.io/app/settings/api-keys).

Set `ELEVENLABS_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.elevenlabs import ElevenLabsTTS, VoiceSettings
from videosdk.agents import CascadingPipeline

# Configure voice settings
voice_settings = VoiceSettings(
    stability=0.71,
    similarity_boost=0.5,
    style=0.0,
    use_speaker_boost=True
)

# Initialize the ElevenLabs TTS model
tts = ElevenLabsTTS(
    # When ELEVENLABS_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-elevenlabs-api-key",
    model="eleven_flash_v2_5",
    voice="your-voice-id",
    speed=1.0,
    response_format="pcm_24000",
    voice_settings=voice_settings,
    enable_streaming=True
)

# Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit api_key, videosdk_auth, and other credential parameters from your code.
:::

## Configuration Options

- `model`: The ElevenLabs model to use (e.g., `"eleven_flash_v2_5"`, `"eleven_multilingual_v2"`)
- `voice`: (str) Voice ID to use for audio output (get from ElevenLabs dashboard)
- `speed`: (float) Speed of the generated audio (default: 1.0)
- `api_key`: Your ElevenLabs API key (can also be set via environment variable)
- `response_format`: (str) Audio format for output (default: `"pcm_24000"`)
- `voice_settings`: (`VoiceSettings`) Advanced voice configuration options:
  - `stability`: (float) Voice stability (0.0 to 1.0, default: 0.71)
  - `similarity_boost`: (float) Voice similarity enhancement (0.0 to 1.0, default: 0.5)
  - `style`: (float) Voice style exaggeration (0.0 to 1.0, default: 0.0)
  - `use_speaker_boost`: (bool) Enable speaker boost for clarity (default: `True`)
- `base_url`: (str) Custom base URL for ElevenLabs API (optional)
- `enable_streaming`: (bool) Enable real-time audio streaming (default: `False`)

## Additional Resources

The following resources provide more information about using ElevenLabs with VideoSDK Agents SDK.

- **[ElevenLabs docs](https://elevenlabs.io/docs)**: ElevenLabs TTS docs.





---

# Google TTS

The Google TTS provider enables your agent to use Google's high-quality text-to-speech models for generating natural-sounding voice output.

## Installation

Install the Google-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-google"
```

## Importing

```python
from videosdk.plugins.google import GoogleTTS, GoogleVoiceConfig
```

## Authentication

The Google plugin requires an [Gemini API key](https://aistudio.google.com/apikey).

Set `GOOGLE_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.google import GoogleTTS, GoogleVoiceConfig
from videosdk.agents import CascadingPipeline

# Configure voice settings
voice_config = GoogleVoiceConfig(
    languageCode="en-US",
    name="en-US-Chirp3-HD-Aoede",
    ssmlGender="FEMALE"
)

# Initialize the Google TTS model
tts = GoogleTTS(
    # When GOOGLE_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-google-api-key",
    speed=1.0,
    pitch=0.0,
    voice_config=voice_config
)

# Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit `api_key` and other credential parameters from your code.
:::

## Configuration Options

- `api_key`: (str) Your Google Cloud TTS API key. Can also be set via the `GOOGLE_API_KEY` environment variable.
- `speed`: (float) The speaking rate of the generated audio (default: `1.0`).
- `pitch`: (float) The pitch of the generated audio. Can be between -20.0 and 20.0 (default: `0.0`).
- `response_format`: (str) The format of the audio response. Currently only supports `"pcm"` (default: `"pcm"`).
- `voice_config`: (`GoogleVoiceConfig`) Configuration for the voice to be used.
  - `languageCode`: (str) The language code of the voice (e.g., `"en-US"`, `"en-GB"`) (default: `"en-US"`).
  - `name`: (str) The name of the voice to use (e.g., `"en-US-Chirp3-HD-Aoede"`, `"en-US-News-N"`) (default: `"en-US-Chirp3-HD-Aoede"`).
  - `ssmlGender`: (str) The gender of the voice (`"MALE"`, `"FEMALE"`, `"NEUTRAL"`) (default: `"FEMALE"`).

## Additional Resources

The following resources provide more information about using Google with VideoSDK Agents SDK.

- **[Google TTS docs](https://cloud.google.com/text-to-speech/docs)**: Google Cloud TTS documentation.





---

# Groq TTS

The Groq TTS provider enables your agent to use Groq's high-quality text-to-speech models for generating natural-sounding voice output.

## Installation

Install the Groq-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-groq"
```

## Importing

```python
from videosdk.plugins.groq import GroqTTS
```

## Authentication

The Groq plugin requires an [Groq API key](https://console.groq.com/keys).

Set `GROQ_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.groq import GroqTTS
from videosdk.agents import CascadingPipeline

# Initialize the Groq AI TTS model
tts = GroqTTS(
    model="playai-tts",
    voice="Fritz-PlayAI",
)

# Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit `api_key` and other credential parameters from your code.
:::

## Configuration Options

- `model` (str): The TTS model to use. Default: "playai-tts"
- `voice` (str): The voice to use. Default: "Fritz-PlayAI"
- `speed` (float): Speed of speech (0.5 to 5.0). Default: 1.0
- `api_key` (str, optional): Groq API key. If not provided, uses GROQ_API_KEY environment variable

## Additional Resources

The following resources provide more information about using Groq with VideoSDK Agents SDK.

- **[Groq docs](https://console.groq.com/docs/text-to-speech)**: Groq TTS docs.





---

# Hume AI TTS

The Hume AI TTS provider enables your agent to use Hume AI's high-quality text-to-speech models for generating natural-sounding voice output.

## Installation

Install the Hume AI-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-humeai"
```

## Importing

```python
from videosdk.plugins.humeai import HumeAITTS
```

## Authentication

The Hume plugin requires an [Hume API key](https://platform.hume.ai/settings/keys).

Set `HUMEAI_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.hume import HumeAITTS
from videosdk.agents import CascadingPipeline

# Initialize the Hume AI TTS model
tts = HumeAITTS(
    voice="Serene Assistant",
    instant_mode=True,
)

# Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit `api_key` and other credential parameters from your code.
:::

## Configuration Options

- `instant_mode`: (bool) Whether to use instant mode synthesis (default: `True`). Instant mode requires specifying a voice.
- `voice`: (str) Voice name to use (default: `"Serene Assistant"`). Required when `instant_mode` is `True`.
- `speed`: (float) Speaking rate multiplier (default: `1.0`). Values >1.0 increase speed.
- `api_key`: (str) Hume AI API key. Can also be set via the `HUMEAI_API_KEY` environment variable.

## Additional Resources

The following resources provide more information about using Hume with VideoSDK Agents SDK.

- **[Hume AI docs](https://dev.hume.ai/docs/text-to-speech-tts)**: Hume AI docs.





---

# Inworld AI TTS

The Inworld AI TTS provider enables your agent to use Inworld AI's high-quality text-to-speech models for generating natural-sounding voice output.

## Installation

Install the Inworld AI-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-inworldai"
```

## Importing

```python
from videosdk.plugins.inworld import InworldAITTS
```

## Authentication

The Inworld plugin requires an [Inworld API key](https://studio.inworld.ai/login).

Set `INWORLD_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.inworldai import InworldAITTS
from videosdk.agents import CascadingPipeline

# Initialize the Inworld AI TTS model
tts = InworldAITTS(
    api_key="your-api-key",
    voice_id="Hades",
    model_id="inworld-tts-1"
)

# Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit `api_key` and other credential parameters from your code.
:::

## Configuration Options

- `model_id`: (str) Inworld TTS model identifier (default: `"inworld-tts-1"`).
- `voice_id`: (str) Voice identifier to use (default: `"Hades"`).
- `temperature`: (float) Sampling temperature for variation in prosody (default: `0.8`).
- `api_key`: (str) Inworld API key. Can also be set via the `INWORLD_API_KEY` environment variable.

## Additional Resources

The following resources provide more information about using Inworld with VideoSDK Agents SDK.

- **[Inworld AI docs](https://docs.inworld.ai/docs/introduction)**: Inworld AI docs.





---

# LMNT AI TTS

The LMNT AI TTS provider enables your agent to use LMNT AI's high-quality text-to-speech models for generating natural-sounding voice output.

## Installation

Install the LMNT AI-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-lmnt"
```

## Importing

```python
from videosdk.plugins.lmnt import LMNTTTS
```

## Authentication

The LMNT plugin requires an [LMNT API key](https://app.lmnt.com/account).

Set `LMNT_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.lmnt import LMNTTTS
from videosdk.agents import CascadingPipeline

# Initialize the LMNT TTS model
tts = LMNTTTS(
    voice="ava",
    model="blizzard",
    language="auto",
)

# Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit `api_key` and other credential parameters from your code.
:::

## Configuration Options

- `api_key`: Your LMNT API key (can also be set via `LMNT_API_KEY` environment variable)
- `voice`: Voice ID to use for synthesis (required)
- `model`: Model to use for synthesis (default: "blizzard")
- `language`: Language code for synthesis (default: "auto")

## Additional Resources

The following resources provide more information about using LMNT with VideoSDK Agents SDK.

- **[LMNT docs](https://docs.lmnt.com/)**: LMNT API docs.





---

# Murf AI TTS

The Murf AI TTS provider enables your agent to use Murf AI's high-quality text-to-speech models for generating natural, expressive voice output with advanced voice customization.

## Installation

Install the Murf AI-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-murfai"
```

## Importing

```python
from videosdk.plugins.murfai import MurfAITTS, MurfAIVoiceSettings
```

## Authentication

The Murf AI plugin requires a [Murf AI API key](https://murf.ai/).

Set `MURFAI_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.murfai import MurfAITTS, MurfAIVoiceSettings
from videosdk.agents import CascadingPipeline

# Configure voice settings
voice_settings = MurfAIVoiceSettings(
    pitch=0,
    rate=0,
    style="Conversational",
    variation=1,
    multi_native_locale=None
)

# Initialize the Murf AI TTS model
tts = MurfAITTS(
    # When MURFAI_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-murfai-api-key",
    region="US_EAST",
    model="Falcon",
    voice="en-US-natalie",
    voice_settings=voice_settings,
    enable_streaming=True
)

# Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit api_key, videosdk_auth, and other credential parameters from your code.
:::

## Configuration Options

- `api_key`: Your Murf AI API key (can also be set via MURFAI_API_KEY environment variable)
- `region`: (str) The region code for API deployment (default: `"US_EAST"`)
  - Available regions: `"GLOBAL"`, `"US_EAST"`, `"US_WEST"`, `"INDIA"`, `"CANADA"`, `"SOUTH_KOREA"`, `"UAE"`, `"JAPAN"`, `"AUSTRALIA"`, `"EU_CENTRAL"`, `"UK"`, `"SOUTH_AFRICA"`
- `model`: (str) The Murf AI model to use (default: `"Falcon"`)
  - Available models: `"Gen2"`, `"Falcon"`
- `voice`: (str) Voice ID to use for audio output (default: `"en-US-natalie"`)
- `voice_settings`: (`MurfAIVoiceSettings`) Advanced voice configuration options:
  - `pitch`: (int) Voice pitch adjustment, range varies by voice (default: `0`)
  - `rate`: (int) Speech rate adjustment, range varies by voice (default: `0`)
  - `style`: (str) Voice style/emotion (default: `"Conversational"`)
  - `variation`: (int) Voice variation for diversity (default: `1`)
  - `multi_native_locale`: (str) Optional locale for multi-native voices (default: `None`)
- `enable_streaming`: (bool) Enable WebSocket streaming for low latency. When `False`, uses HTTP chunked transfer (default: `True`)

## Additional Resources

The following resources provide more information about using Murf AI with VideoSDK Agents SDK.

- **[Murf AI docs](https://murf.ai/api/docs/introduction/overview)**: Murf AI TTS docs.





---

# Neuphonic TTS

The Neuphonic TTS provider enables your agent to use Neuphonic's high-quality text-to-speech models for generating natural-sounding voice output.

## Installation

Install the Neuphonic-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-neuphonic"
```

## Importing

```python
from videosdk.plugins.neuphonic import NeuphonicTTS
```

## Authentication

The Neuphonic plugin requires an [Neuphonic API key](https://app.neuphonic.com/apikey).

Set `NEUPHONIC_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.neuphonic import NeuphonicTTS
from videosdk.agents import CascadingPipeline

# Initialize the Neuphonic AI TTS model
tts = NeuphonicTTS(
    lang_code="en",
    voice_id="8e9c4bc8-3979-48ab-8626-df53befc2090",
    speed=1.0,
)

# Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit `api_key` and other credential parameters from your code.
:::

## Configuration Options

- `api_key`: Your Neuphonic API key (can also be set via `NEUPHONIC_API_KEY` environment variable)
- `lang_code`: Language code for the desired language (e.g., 'en', 'es', 'de', 'nl', 'hi')
- `voice_id`: The voice ID for the desired voice
- `speed`: Playback speed of the audio (range: 0.7-2.0, default: 1.0)

## Additional Resources

The following resources provide more information about using Neuphonic with VideoSDK Agents SDK.

- **[Neuphonic AI docs](https://docs.neuphonic.com/)**: Neuphonic docs.





---

# Nvidia TTS

The Nvidia TTS provider enables your agent to use Nvidia's Riva text-to-speech models for converting text responses to natural-sounding audio output with low latency.

## Installation

Install the Nvidia-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-nvidia"
```

## Authentication

The Nvidia plugin requires an Nvidia API key.

Set `NVIDIA_API_KEY` in your `.env` file.

## Importing

```python
from videosdk.plugins.nvidia import NvidiaTTS
```

## Example Usage

```python
from videosdk.plugins.nvidia import NvidiaTTS
from videosdk.agents import CascadingPipeline

# Initialize the Nvidia TTS model
tts = NvidiaTTS(
    # When NVIDIA_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-nvidia-api-key",
    voice_name="Magpie-Multilingual.EN-US.Aria",
    language_code="en-US",
    sample_rate=24000
)

#  Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit api_key and other credential parameters from your code.
:::

## Configuration Options

- `api_key`: Your Nvidia API key (required, can also be set via environment variable)
- `server`: The Nvidia Riva server address (default: `"grpc.nvcf.nvidia.com:443"`)
- `function_id`: The specific function ID for the service (default: `"877104f7-e885-42b9-8de8-f6e4c6303969"`)
- `voice_name`: (str) The voice to use (default: `"Magpie-Multilingual.EN-US.Aria"`)
- `language_code`: (str) Language code for synthesis (default: `"en-US"`)
- `sample_rate`: (int) Audio sample rate in Hz (default: `24000`)
- `use_ssl`: (bool) Enable SSL connection (default: `True`)

## Additional Resources

The following resources provide more information about using Nvidia Riva with VideoSDK Agents SDK.

- **[Nvidia Riva docs](https://docs.nvidia.com/deeplearning/riva/user-guide/docs/index.html)**: Nvidia Riva documentation.





---

# OpenAI TTS

The OpenAI TTS provider enables your agent to use OpenAI's text-to-speech models for converting text responses to natural-sounding audio output.

## Installation

Install the OpenAI-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-openai"
```

## Importing

```python
from videosdk.plugins.openai import OpenAITTS
```

## Authentication

The OpenAI plugin requires an [OpenAI API key](https://platform.openai.com/api-keys).

Set `OPENAI_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.openai import OpenAITTS
from videosdk.agents import CascadingPipeline

# Initialize the OpenAI TTS model
tts = OpenAITTS(
    # When OPENAI_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-openai-api-key",
    model="tts-1",
    voice="alloy",
    speed=1.0,
    response_format="pcm"
)

#  Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit api_key, videosdk_auth, and other credential parameters from your code.
:::

## Configuration Options

- `model`: The OpenAI TTS model to use (e.g., `"tts-1"`, `"tts-1-hd"`)
- `voice`: (str) Voice to use for audio output (e.g., `"alloy"`, `"echo"`, `"fable"`, `"onyx"`, `"nova"`, `"shimmer"`)
- `speed`: (float) Speed of the generated audio (0.25 to 4.0, default: 1.0)
- `instructions`: (str) Custom instructions to guide speech synthesis style
- `api_key`: Your OpenAI API key (can also be set via environment variable)
- `base_url`: Custom base URL for OpenAI API (optional)
- `response_format`: (str) Audio format for output (default: `"pcm"`)

## Additional Resources

The following resources provide more information about using OpenAI with VideoSDK Agents SDK.

- **[OpenAI docs](https://platform.openai.com/docs/guides/text-to-speech)**: OpenAI TTS API documentation.





---

# Papla Media TTS

The Papla Media TTS provider enables your agent to use Papla Media's text-to-speech service for converting text responses into spoken audio.

## Installation

Install the Papla Media-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-papla"
```

## Importing

```python
from videosdk.plugins.papla import PaplaTTS
```

## Authentication

The Papla Media plugin requires an API key, which you can generate from your app dashboard.

Set `PAPLA_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.papla import PaplaTTS
from videosdk.agents import CascadingPipeline

# Initialize the Papla Media TTS service
tts = PaplaMediaTTS(
    # When PAPLA_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-papla-media-api-key",
)

#  Add tts to a cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using a `.env` file for credentials, don't pass them as arguments to model instances. The SDK automatically reads environment variables, so you should omit the `api_key` parameter from your code.
:::

## Configuration Options

### Initialization Parameters

These are the options you can set when creating an instance of `PaplaMediaTTS`.

- `model_id` (str): The TTS model to use. Defaults to `"papla_p1"`.
- `api_key` (str, optional): Your Papla Media API key. It's recommended to set this via the `PAPLA_API_KEY` environment variable instead.
- `base_url` (str, optional): Custom base URL for the Papla Media API. Defaults to `"https://api.papla.media/v1"`.

## Additional Resources

The following resources provide more information about using Papla Media with the VideoSDK Agent Framework.

- **[Papla Media API Docs](https://api.papla.media/docs)**: Papla Media's official API documentation.





---

# Resemble AI TTS

The Resemble AI TTS provider enables your agent to use Resemble AI's high-quality text-to-speech models for generating natural-sounding voice output.

## Installation

Install the Resemble AI-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-resemble"
```

## Importing

```python
from videosdk.plugins.resemble import ResembleTTS
```

## Authentication

The Resemble plugin requires an [Resemble API key](https://app.resemble.ai/account/api).

Set `RESEMBLE_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.resemble import ResembleTTS
from videosdk.agents import CascadingPipeline

# Initialize the Resemble AI TTS model
tts = ResembleTTS(
    # When RESEMBLE_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-resemble-api-key",
    voice_uuid="55592656"
)

# Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit `api_key` and other credential parameters from your code.
:::

## Configuration Options

- `api_key`: (str) Your Resemble AI API key. Can also be set via the `RESEMBLE_API_KEY` environment variable.
- `voice_uuid`: (str) The UUID of the voice to use for synthesis (default: `"55592656"`).

## Additional Resources

The following resources provide more information about using Resemble with VideoSDK Agents SDK.

- **[Resemble AI docs](https://docs.app.resemble.ai)**: Resemble AI docs.





---

# Rime AI TTS

The Rime AI TTS provider enables your agent to use Rime AI's high-quality text-to-speech models for generating natural-sounding voice output.

## Installation

Install the Rime AI-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-rime"
```

## Importing

```python
from videosdk.plugins.rime import RimeTTS
```

## Authentication

The Rime plugin requires an [Rime API key](https://rime.ai/).

Set `RIME_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.Rime import RimeTTS
from videosdk.agents import CascadingPipeline

# Initialize the Rime AI TTS model
tts = RimeTTS(
    speaker="river",
    model_id="mist",
    lang="eng",
    speed_alpha=1.0
)

# Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit `api_key` and other credential parameters from your code.
:::

## Configuration Options

- `speaker`: (str) Voice ID to use (default: `"river"`). Must match the model's available speakers.
- `model_id`: (str) Rime model identifier (default: `"mist"`). Supported: `"mist"`, `"mistv2"`.
- `lang`: (str) Language code for the voice (default: `"eng"`).
- `speed_alpha`: (float) Controls speaking rate (`1.0` is normal speed).
- `reduce_latency`: (bool) Whether to minimize streaming delay (default: `False`).
- `pause_between_brackets`: (bool) Insert pauses around bracketed text (default: `False`).
- `phonemize_between_brackets`: (bool) Use phonemes for bracketed text (default: `False`).
- `inline_speed_alpha`: (str) Optional per-word speed override (e.g., `"1.2,1.0,0.8"`).
- `api_key`: (str) Rime API key. Can also be set via the `RIME_API_KEY` environment variable.

## Additional Resources

The following resources provide more information about using Rime with VideoSDK Agents SDK.

- **[Rime AI docs](https://docs.rime.ai/)**: Rime AI docs.





---

# Sarvam AI TTS

The Sarvam AI TTS provider enables your agent to use Sarvam AI's text-to-speech models for generating voice output.

## Installation

Install the Sarvam AI-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-sarvamai"
```

## Importing

```python
from videosdk.plugins.sarvamai import SarvamAITTS
```

## Authentication

The Sarvam plugin requires a [Sarvam API key](https://dashboard.sarvam.ai/key-management).

Set `SARVAM_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.sarvamai import SarvamAITTS
from videosdk.agents import CascadingPipeline

# Initialize the Sarvam AI TTS model
tts = SarvamAITTS(
    # When SARVAMAI_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-sarvam-ai-api-key",
    model="bulbul:v2",
    speaker="anushka",
    target_language_code="en-IN",
    pitch=0.0,
    pace=1.0,
    loudness=1.2
)

# Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit `api_key` and other credential parameters from your code.
:::

## Configuration Options

- `api_key`: (str) Your Sarvam AI API key. Can also be set via the `SARVAMAI_API_KEY` environment variable.
- `model`: (str) The Sarvam AI model to use (default: `"bulbul:v2"`).
- `speaker`: (str) The speaker voice to use (default: `"anushka"`).
- `target_language_code`: (str) The language code for the generated audio (default: `"en-IN"`).
- `pitch`: (float) The pitch of the generated audio (default: `0.0`).
- `pace`: (float) The pace or speed of the generated audio (default: `1.0`).
- `loudness`: (float) The loudness of the generated audio (default: `1.2`).
- `enable_preprocessing`: (bool) Whether to enable text preprocessing on the server (default: `True`).

## Additional Resources

The following resources provide more information about using Sarvam AI with VideoSDK Agents SDK.

- **[Sarvam docs](https://docs.sarvam.ai/)**: Sarvam's full docs site.





---

# SmallestAI TTS

The SmallestAI TTS provider enables your agent to use SmallestAI's high-quality text-to-speech models for generating voice output.

## Installation

Install the SmallestAI-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-smallestai"
```

## Importing

```python
from videosdk.plugins.smallestai import SmallestAITTS
```

## Authentication

The Smallest AI plugin requires a [Smallest AI API key](https://console.smallest.ai/apikeys).

Set `SMALLEST_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.smallestai import SmallestAITTS
from videosdk.agents import CascadingPipeline

# Initialize the SmallestAI TTS model
tts = SmallestAITTS(
    # When SMALLEST_API_KEY is set in .env - DON'T pass api_key parameter
    api_key="your-smallestai-api-key",
    model="lightning",
    voice_id="emily"
)

# Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances. The SDK automatically reads environment variables, so omit `api_key` from your code.
:::

## Configuration Options

- `api_key`: (str) Your SmallestAI API key. Can also be set via the `SMALLEST_API_KEY` environment variable.
- `model`: (str) The TTS model to use (e.g., `"lightning"`, `"lightning-large"`). Defaults to `"lightning"`.
- `voice_id`: (str) The ID of the voice to use. Defaults to `"emily"`.
- `speed`: (float) Speech speed multiplier. Defaults to `1.0`.
- `consistency`: (float) Controls word repetition and skipping. Only supported in `lightning-large` model. Defaults to `0.5`.
- `similarity`: (float) Controls similarity to the reference audio. Only supported in `lightning-large` model. Defaults to `0.0`.
- `enhancement`: (bool) Enhances speech quality at the cost of increased latency. Only supported in `lightning-large` model. Defaults to `False`.

## Additional Resources

The following resources provide more information about using Smallest AI with VideoSDK Agents SDK.

- **[Smallest AI docs](https://waves-docs.smallest.ai/v3.0.1/content/introduction/introduction)**: Smallest AI docs.





---

# Speechify TTS

The Speechify TTS provider enables your agent to use Speechify's high-quality text-to-speech models for generating natural-sounding voice output.

## Installation

Install the Speechify-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-speechify"
```

## Importing

```python
from videosdk.plugins.speechify import SpeechifyTTS
```

## Authentication

The Speechify plugin requires an [Speechify API key](https://console.sws.speechify.com/).

Set `SPEECHIFY_API_KEY` in your `.env` file.

## Example Usage

```python
from videosdk.plugins.speechify import SpeechifyTTS
from videosdk.agents import CascadingPipeline

# Initialize the Speechify TTS model
tts = SpeechifyTTS(
    voice_id="kristy",
    model="simba-english"
)

# Add tts to cascading pipeline
pipeline = CascadingPipeline(tts=tts)
```

:::note
When using .env file for credentials, don't pass them as arguments to model instances or context objects. The SDK automatically reads environment variables, so omit `api_key` and other credential parameters from your code.
:::

## Configuration Options

- `voice_id`: (str) The Speechify voice to use (default: `"kristy"`).
- `api_key`: (str) Speechify API key. Can also be set via the `SPEECHIFY_API_KEY` environment variable.
- `model`: (str) The model variant to use (`"simba-base"`, `"simba-english"`, `"simba-multilingual"`, `"simba-turbo"`). Default: `"simba-english"`.
- `language`: (str) Optional ISO language code for multilingual models (e.g., `"en"`, `"es"`).

## Additional Resources

The following resources provide more information about using Speechify with VideoSDK Agents SDK.

- **[Speechify AI docs](https://docs.sws.speechify.com/v1/docs)**: Speechify AI docs.





---

# Turn Detector

The Turn Detector uses a Hugging Face model to determine whether a user's turn is completed or not, enabling precise conversation flow management in cascading pipelines.

## Installation

Install the Turn Detector-enabled VideoSDK Agents package:

```bash
pip install "videosdk-plugins-turn-detector"
```

## Importing

```python
from videosdk.plugins.turn_detector import TurnDetector
```

## Example Usage

```python
from videosdk.plugins.turn_detector import TurnDetector, pre_download_model
from videosdk.agents import CascadingPipeline

# Pre-download the model (optional but recommended)
pre_download_model()

# Initialize the Turn Detector
turn_detector = TurnDetector(
    threshold=0.7
)

# Add Turn Detector to cascading pipeline
pipeline = CascadingPipeline(turn_detector=turn_detector)
```

## Configuration Options

- `threshold`: (float) Confidence threshold for turn completion detection (0.0 to 1.0, default: `0.7`)

## Pre-downloading Model

To avoid delays during agent initialization, you can pre-download the Hugging Face model:

```python
from videosdk.plugins.turn_detector import pre_download_model

# Download model before running the agent
pre_download_model()
```

## Additional Resources

The following resources provide more information about VideoSDK Turn Detector plugin for AI Agents SDK.





---

The AI Agent SDK now supports session recordings, which can be enabled with a simple configuration. When enabled, all interactions between the user and the agent are recorded.

These recordings can be played back directly from the dashboard with autoscrolling transcripts and precise timestamps, and you can also download them for offline review and analysis.


## Enabling Recording

To enable recording for an AI agent session, you need to set the `recording` flag to `true` in the session context. Once that's done, start your agent as usual—no additional changes are required in the pipeline.

By default, the recording flag is set to `false`.

```python
job_context = JobContext(
  room_options = RoomOptions(
    room_id = "YOUR_ROOM_ID",
    name = "Agent",
    recording = True
  )
)
```


---

The worker system provides a robust way to run AI agent instances using Python's multiprocessing. It offers process isolation, proper lifecycle management, and a clean separation between agent logic and infrastructure concerns.

## Key Components

### 1. WorkerJob

`WorkerJob` is the main class that defines an agent task to be executed in a separate process. It takes two parameters:

- `entrypoint`: An async function that accepts a JobContext parameter
- `jobctx`: A JobContext object or a callable that returns a JobContext

```python
job = WorkerJob(entrypoint=my_function, jobctx=my_context)
```

### 2. JobContext

`JobContext` provides the runtime environment for your agent, including:

- **Room Management**: Handles VideoSDK room connections
- **Shutdown Callbacks**: Allows cleanup operations
- **Process Isolation**: Each job runs in its own process

### 3. Worker

`Worker` manages the execution of jobs in separate processes, providing:

- Process isolation for each agent instance
- Automatic cleanup on shutdown
- Error handling and logging

## Usage Example

Here's a complete example of how to use the worker system with a voice agent:

```python
import asyncio
import aiohttp
from videosdk.plugins.google import GeminiRealtime, GeminiLiveConfig
from videosdk.agents import Agent, AgentSession, RealTimePipeline, WorkerJob, JobContext, RoomOptions
class MyVoiceAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are a helpful voice assistant that can answer questions and help with tasks.",
        )

    async def on_enter(self) -> None:
        await self.session.say("Hello, how can I help you today?")

    async def on_exit(self) -> None:
        await self.session.say("Goodbye!")

async def entrypoint(ctx: JobContext):
    model = GeminiRealtime(
        model="gemini-2.5-flash-native-audio-preview-12-2025",
        config=GeminiLiveConfig(
            voice="Leda",
            response_modalities=["AUDIO"]
        )
    )

    pipeline = RealTimePipeline(model=model)
    agent = MyVoiceAgent(ctx)

    session = AgentSession(
        agent=agent,
        pipeline=pipeline,
    )
    
    async def cleanup_session():
        print("Cleaning up session...")
    
    ctx.add_shutdown_callback(cleanup_session)

    try:
        # connect to the room
        await ctx.connect()
        await ctx.room.wait_for_participant()
        await session.start()
        await asyncio.Event().wait()
    except KeyboardInterrupt:
        print("Shutting down...")
    finally:
        await session.close()
        await ctx.shutdown()

def make_context() -> JobContext:
    room_options = RoomOptions(
        room_id="<meeting_id>", 
        name="Sandbox Agent", 
        playground=True
    )
    
    return JobContext(room_options=room_options)

if __name__ == "__main__":
    job = WorkerJob(entrypoint=entrypoint, jobctx=make_context)
    job.start()
```

## Configuration Options

### RoomOptions
- `room_id`: The VideoSDK meeting ID
- `auth_token`: Authentication token (or use VIDEOSDK_AUTH_TOKEN env var)
- `name`: Agent name displayed in the meeting
- `playground`: Enable playground mode for testing
- `vision`: Enable vision capabilities
- `avatar`: Use virtual avatars from available providers

## Best Practices

1. **Always use cleanup callbacks**: Register shutdown callbacks to ensure proper resource cleanup
2. **Handle exceptions gracefully**: Use try-finally blocks to ensure cleanup happens
3. **Use playground mode for testing**: Set `playground=True` for easy testing and debugging
4. **Set environment variables**: Use `VIDEOSDK_AUTH_TOKEN` for authentication
5. **Wait for participants**: Use `wait_for_participant()` to ensure agent waits for a participant

The worker system provides a production-ready way to deploy AI agents with proper isolation, lifecycle management, and error handling.


---

# VideoSDK AI SIP Framework

A production-ready framework for creating AI-powered voice agents using VideoSDK and various SIP providers (e.g., Twilio). This framework enables you to build and deploy sophisticated conversational AI agents that can handle both inbound and outbound phone calls with natural language processing.

## How It Works

The framework simplifies a complex process into a manageable workflow. Here’s a high-level overview of the architecture:

1.  **Phone Call**: A user calls a phone number you have acquired from a SIP provider (like Twilio, Plivo, etc.).
2.  **SIP Provider**: The provider receives the call and sends a webhook notification to your application server.
3.  **Your Application Server**: This is the application you build using this framework.
    *   It receives the webhook.
    *   It uses the `SIPManager` to create a secure VideoSDK room for the call.
    *   It launches your custom AI Agent.
    *   It responds to the SIP provider with instructions (e.g., TwiML) to forward the call's audio into the VideoSDK room.
4.  **VideoSDK & AI Agent**: Your AI Agent joins the room, receives the live audio from the phone call, processes it using your chosen AI models (for speech-to-text, language understanding, and text-to-speech), and responds in real-time to create a seamless, interactive conversation.

--- 

## Prerequisites

Before you get started, ensure you have the following:

### System Requirements
- **Python**: 3.11 or higher
- **Network**: Public internet access for webhook delivery

### Required Credentials
- **VideoSDK Credentials**: Sign up at [app.videosdk.live](https://app.videosdk.live/) to get your token and SIP credentials.

![VideoSDK SIP Credentials](https://strapi.videosdk.live/uploads/sip_dashboard_screenshot_8025aba2ec.png)
- **SIP Provider Account**: Obtain provider-specific credentials.
- **AI Model Provider**: An account with Google, OpenAI, or another supported provider.

---

## Get Started

### 1. Installation

Create and activate a virtual environment
**macOS/Linux:**

```js
python3 -m venv venv
source venv/bin/activate
```

---

**Windows:**

```js
python3 -m venv venv
venv\Scripts\activate
```

Install the core framework
```bash
pip install videosdk-plugins-sip
```
Install plugins for your chosen AI services (e.g., Google)
```bash
pip install videosdk-plugins-google
```

### 2. Environment Configuration

Your agent requires credentials for both VideoSDK and your chosen SIP provider. You can provide these through environment variables (recommended) or directly in your code.

Create a `.env` file in your project's root directory, edit the file with your credentials.

#### **VideoSDK Credentials (Required)**
These are essential for the framework to function.

```ini
VIDEOSDK_AUTH_TOKEN=your_videosdk_jwt_token
VIDEOSDK_SIP_USERNAME=your_videosdk_sip_username
VIDEOSDK_SIP_PASSWORD=your_videosdk_sip_password
```

#### **AI Model Credentials (Required)**
Add the API key for your chosen AI provider.

```ini
GOOGLE_API_KEY=your_google_api_key_here
```

#### **SIP Provider Credentials**
Fill in the details for the provider you will be using. The framework will automatically use the correct variables based on the `SIP_PROVIDER` you set.

**Twilio:**

Get your credentials from the [Twilio console](https://console.twilio.com/dashboard).
```ini
SIP_PROVIDER=twilio
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_PHONE_NUMBER=+1234567890
```

Copy the example environment file and populate it with your credentials.

```bash
cp env.example .env
```

Now, edit the `.env` file:
```ini
# VideoSDK Configuration
VIDEOSDK_AUTH_TOKEN=your_videosdk_jwt_token
VIDEOSDK_SIP_USERNAME=your_videosdk_sip_username
VIDEOSDK_SIP_PASSWORD=your_videosdk_sip_password

# AI Model Configuration (Example for Google Gemini)
GOOGLE_API_KEY=your_google_api_key

# Provider Selection (currently, 'twilio' is supported)
SIP_PROVIDER=twilio

# Twilio Configuration
TWILIO_ACCOUNT_SID=your_twilio_account_sid
TWILIO_AUTH_TOKEN=your_twilio_auth_token
TWILIO_PHONE_NUMBER=+1234567890
```

## AI Agent and SIP Setup
Here’s how to structure your application.

### Step 1: Initialize the SIP Manager


The `create_sip_manager` function is the main entry point. It establishes the connection to your SIP provider by reading the environment variables you configured.

```python
import os
from dotenv import load_dotenv
from videosdk.plugins.sip import create_sip_manager

# Load variables from the .env file
load_dotenv()

# This function reads your .env variables and configures the correct provider
sip_manager = create_sip_manager(
    provider=os.getenv("SIP_PROVIDER"),
    videosdk_token=os.getenv("VIDEOSDK_AUTH_TOKEN"),
    # The provider_config dictionary passes provider-specific environment variables.
    provider_config={
        # Twilio
        "account_sid": os.getenv("TWILIO_ACCOUNT_SID"),
        "auth_token": os.getenv("TWILIO_AUTH_TOKEN"),
        "phone_number": os.getenv("TWILIO_PHONE_NUMBER"),
    }
)
```

### Step 2: Define Your Agent's Pipeline


The pipeline defines which AI models your agent uses. Here, we are using Google's Gemini for a [Real-time Pipeline](https://docs.videosdk.live/ai_agents/core-components/realtime-pipeline). You could also use a [Cascading Pipeline](https://docs.videosdk.live/ai_agents/core-components/cascading-pipeline).

```python
from videosdk.agents import RealTimePipeline
from videosdk.plugins.google import GeminiRealtime, GeminiLiveConfig

def create_agent_pipeline():
    """This creates the AI model pipeline for our agent."""
    model = GeminiRealtime(
        api_key=os.getenv("GOOGLE_API_KEY"),
        model="gemini-2.5-flash-native-audio-preview-12-2025",
        config=GeminiLiveConfig(
            voice="Leda", # Choose your desired voice
            response_modalities=["AUDIO"], # We want the agent to speak back
        ),
    )
    return RealTimePipeline(model=model)
```


### Step 3: Define Your Agent's Personality and Tools


The `Agent` class defines the system prompt (instructions), personality, and custom [function tools](https://docs.videosdk.live/ai_agents/core-components/agent) and [MCP Servers](https://docs.videosdk.live/ai_agents/mcp-integration) that your agent can use.

```python
import asyncio
from videosdk.agents import Agent, function_tool, JobContext
from typing import Optional

class SIPAIAgent(Agent):
    """An AI agent for handling voice calls."""

    def __init__(self, ctx: Optional[JobContext] = None):
        super().__init__(
            instructions="You are a friendly and helpful voice assistant. Keep your responses concise.",
            tools=[self.end_call],
            # You can also integrate other function tools and MCP Servers here.
        )
        self.ctx = ctx
        self.greeting_message = "Hello! Thank you for calling. How can I assist you today?"

    async def on_enter(self) -> None:
        pass

    async def greet_user(self) -> None:
        """Greets the user with the message defined above."""
        await self.session.say(self.greeting_message)

    async def on_exit(self) -> None:
        pass
```


## Server Setup and Deployment

Your application must be accessible from the public internet so that your SIP provider can send it webhooks. You have two main options for this.

**Local:**

For testing on your local machine, `ngrok` is the perfect tool. It creates a secure, public URL that tunnels directly to your local server.

The `lifespan` manager in our example code handles this for you automatically. When you start the server, it will generate a unique URL and automatically configure the `SIPManager` with it.

**Code Snippet (FastAPI Lifespan Manager):**
```python
import os
import logging
from contextlib import asynccontextmanager
from fastapi import FastAPI
from pyngrok import ngrok

logger = logging.getLogger(__name__)

@asynccontextmanager
async def lifespan(app: FastAPI):
"""Lifespan manager for FastAPI app startup and shutdown."""
port = int(os.getenv("PORT", 8000))
try:
    ngrok.kill()
    ngrok_auth_token = os.getenv("NGROK_AUTHTOKEN")
    if ngrok_auth_token:
        ngrok.set_auth_token(ngrok_auth_token)
    tunnel = ngrok.connect(port, "http")

    # The Base URL is generated here
    sip_manager.set_base_url(tunnel.public_url)

    logger.info(f"NGROK TUNNEL CREATED: {tunnel.public_url}")
except Exception as e:
    logger.error(f"Failed to start ngrok tunnel: {e}")

yield

try:
    ngrok.kill()
    logger.info("Ngrok tunnel closed")
except Exception as e:
    logger.error(f"Error closing ngrok tunnel: {e}")

app = FastAPI(title="SIP AI Agent", lifespan=lifespan)
```

---

**Cloud/Server:**

For a live application, you will deploy your code to a cloud server (e.g., AWS EC2, Google Cloud Run, Heroku) that has a permanent public IP address or domain name.

In this case, you should **not** use the `ngrok` `lifespan` manager. Instead, set the base URL directly in your code.

**Code Snippet (Cloud Server Setup):**
```python
from fastapi import FastAPI

# Your FastAPI app for production
app = FastAPI(title="SIP AI Agent")

# IMPORTANT: Set your server's public URL before starting the app.
# This should be the actual domain where your service is hosted.
PUBLIC_URL = "https://api.your-public-url.com"
sip_manager.set_base_url(PUBLIC_URL)
```

:::note
You must configure your SIP provider's webhook to point to `https://your-public-or-ngrok-url.com/webhook/incoming`.
:::

## API Endpoint Guide

Your application server, powered by the `sip` framework, exposes a set of endpoints for controlling and monitoring calls.

---

### `POST /webhook/incoming`

This is the **most important endpoint for handling inbound calls**. When a user calls your SIP provider's phone number, the provider sends an HTTP request (a webhook) to this URL.

*   **Purpose**: To serve as the primary entry point for all incoming phone calls.
*   **Provider Configuration**: You **must** configure this full URL in your SIP provider's dashboard for your phone number.
*   **Core Process**:
    1.  Receives the webhook from the SIP provider.
    2.  Creates a new VideoSDK room for the call.
    3.  Launches your `SIPAIAgent` in a separate process, which then waits in the room.
    4.  Responds to the provider with instructions (XML-based TwiML/ExoML) detailing how to forward the call's audio stream to the newly created room's SIP address.

---

### `POST /call/make`

This endpoint allows you to **programmatically initiate an outbound call** from your agent to a user's phone number.

```bash
# Replace with the destination phone number
curl -X POST "http://localhost:8000/call/make?to_number=+1234567890"
```

*   **Purpose**: To start new conversations with users. Ideal for automated reminders, lead qualification, or proactive support.
*   **Query Parameters**:

| Parameter | Type | Description | Required |
| :--- | :--- | :--- | :--- |
| `to_number` | `string` | The full phone number to call, in E.164 format (e.g., `+15551234567`). | Yes |

*   **Core Process (Outbound Call Flow)**:
    1.  Your request hits the endpoint.
    2.  The `SIPManager` creates a VideoSDK room and immediately launches your `SIPAIAgent`. The agent then waits in the room.
    3.  The manager sends an API request to your SIP provider (e.g., Twilio), instructing it to call the `to_number`.
    4.  Crucially, it provides the SIP provider with a unique webhook URL for this specific call: `https://<your-url>/sip/answer/{room_id}`.
    5.  When the user answers their phone, the SIP provider sends a webhook to that unique answer URL to connect the user to the waiting agent.

---

### `POST /sip/answer/{room_id}`

This is an **internal-facing endpoint** designed to complete the outbound call loop. You will not call this endpoint directly.
*   **Purpose**: To serve as the dynamic "answer URL" for outbound calls.
*   **Path Parameters**:

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `room_id` | `string` | The unique ID of the VideoSDK room where the agent is waiting. |

*   **Core Process**:
    1.  This endpoint is called by the SIP provider *only after* the user answers an outbound call initiated by `/call/make`.
    2.  It uses the `room_id` to find the correct SIP address for the room where the agent is waiting.
    3.  It returns a simple TwiML/XML response that tells the provider how to bridge the just-answered call with the agent.
    
---

### `GET /sessions`

A simple utility endpoint for **monitoring the health and status** of your service.

*   **Purpose**: To see how many calls are currently active.
*   **Core Process**:
    1.  Receives a simple `GET` request.
    2.  Checks the `SIPManager`'s internal state.
    3.  Returns a count of active sessions and a list of their corresponding room IDs.

---
:::tip
If you experience high latency when connecting a call, it may be due to a mismatch between the geographical region of your VideoSDK meeting server (which defaults to the nearest server region to you) and your SIP provider's region. To reduce latency, upgrade to an enterprise plan and set `VIDEOSDK_REGION=sip_provider_region` in your `.env` file for a low-latency experience.
:::

---

VideoSDK's AI Agent framework offers powerful **Tracing and Observability** tools, providing deep insights into your AI agent's performance and behavior. These tools, accessible from the VideoSDK dashboard, allow you to monitor sessions, analyze interactions, and debug issues with precision.

## Prerequisites

To View Tracing and Observability At VideoSDK Dashboard, make sure to install the VideoSDK AI Agent package using pip:

```bash
pip install videosdk-agents==0.0.23
```

:::note
Tracing and Observability support was added starting from version 0.0.23, which is why this version is required.
:::

## Sessions

The Sessions dashboard provides a comprehensive list of all interactions with your AI agents. Each session is a unique conversation between a user and an agent, identified by a `Session ID` and associated with a `Room ID`.

<center>

<img style={{height: '450px'}} src="https://cdn.videosdk.live/website-resources/docs-resources/agent_sessions-list.png" />

</center>

### Key Metrics

For each session, you can monitor the following key metrics at a glance:

- **Session ID**: A unique identifier for the session.
- **Room ID**: The identifier of the room where the session took place.
- **TTFW (Time to First Word)**: The time it takes for the agent to utter its first word after the user has finished speaking. This metric is crucial for measuring the responsiveness of your agent.
- **P50, P90, P95**: These are percentile metrics for latency, providing a statistical distribution of response times. For example, P90 indicates that 90% of the responses were faster than the specified value.
- **Interruption**: The number of times the agent was interrupted by the user.
- **Duration**: The total duration of the session.
- **Recording**: Indicates whether the session was recorded. You can play back the recording directly from the dashboard.
- **Created At**: The timestamp of when the session was created.
- **Actions**: From here, you can navigate to the detailed analytics view for the session.

## Session View

By clicking on "View Analytics" for a specific session, you are taken to the Session View. This view provides a complete transcript of the conversation, along with timestamps and speaker identification (Caller or Agent).

<center>

<img style={{height: '450px'}} src="https://cdn.videosdk.live/website-resources/docs-resources/agent_session_recording_transcription.png" />

</center>

If the session was recorded, you can play back the audio and follow along with the transcript, which automatically scrolls as the conversation progresses. This is an invaluable tool for understanding the user experience and identifying areas for improvement.

By analyzing these metrics, you can quickly identify underperforming agents, diagnose latency issues, and gain a holistic view of the user experience. The next section will delve into the detailed session and trace views, where you can explore individual conversations and their underlying processes.


---

The real power of VideoSDK's Tracing and Observability tools lies in the detailed session and trace views. These views provide a granular breakdown of each conversation, allowing you to analyze every turn, inspect component latencies, and understand the agent's decision-making process.

## Trace View

The Trace View offers an even deeper level of insight, breaking down the entire session into a hierarchical structure of traces and spans.

<center>

<img style={{height: '450px'}} src="https://cdn.videosdk.live/website-resources/docs-resources/agent_session_trace_overview.png" />

</center>

### Session Configuration

At the top level, you'll find the **Session Configuration**, which details all the parameters the agent was initialized with. This includes the models used for STT, LLM, and TTS, as well as any function tools or MCP tools that were configured. This information is crucial for reproducing and debugging specific agent behaviors.

### User & Agent Turns

The core of the Trace View is the breakdown of the conversation into **User & Agent Turns**. Each turn represents a single exchange between the user and the agent.

<center>

<img style={{height: '450px'}} src="https://cdn.videosdk.live/website-resources/docs-resources/agent_session_trace_turn.png" />

</center>

Within each turn, you can see a detailed timeline of the underlying processes, including:

- **STT (Speech-to-Text) Processing**: The time it took to transcribe the user's speech.
- **EOU (End-of-Utterance) Detection**: The time taken to detect that the user has finished speaking.
- **LLM Processing**: The time the Large Language Model took to process the input and generate a response.
- **TTS (Text-to-Speech) Processing**: The time it took to convert the LLM's text response into speech.
- **Time to First Byte**: The initial delay before the agent starts speaking.
- **User Input Speech**: The duration of the user's speech.
- **Agent Output Speech**: The duration of the agent's spoken response.

### Turn Properties

For each turn, you can inspect the properties of the components involved. This includes the transcript of the user's input, the response from the LLM, and any errors that may have occurred.

<center>

<img  src="https://cdn.videosdk.live/website-resources/docs-resources/agent_session_trace_turns.png" />

</center>

By leveraging the detailed information in the Trace View, you can pinpoint performance bottlenecks, debug errors, and gain a comprehensive understanding of your AI agent's inner workings.

### Tool Calls

When an LLM invokes a tool, the Trace View provides specific details about the tool call, including the tool's name and the parameters it was called with. This is essential for debugging integrations and ensuring that your agent's tools are functioning as expected.

<center>

<img style={{height: '450px'}} src="https://cdn.videosdk.live/website-resources/docs-resources/agent_session_trace_tool_call.png" />

</center>


---

# Vision

For supported LLM providers ([OpenAI](/ai_agents/plugins/llm/openai.md), [Anthropic](/ai_agents/plugins/llm/anthropic.md), [Google](/ai_agents/plugins/llm/google.md)), you can add images to their chat context to leverage their full capabilities. You can add images as URLs or base64-encoded data from your frontend or directly. Additionally, you can use live video with a realtime model such as [Gemini Live](/ai_agents/plugins/realtime/google.md).

## Image Input (Cascading Pipeline)

The agent's chat context supports both image and text input. You can add multiple images in a given session, although larger chat contexts may lead to slower response times.

To add an image, you can simply pass an image URL or base64-encoded image data to the `ImageContent` class. Below is an example of image addition:

```python
self.agent.chat_context.add_message(
    role=ChatRole.USER, content=[ImageContent(image="YOUR_IMAGE_URL")]
)
```

Sample code for adding image context from conversation flow:

```python
class MyConversationFlow(ConversationFlow):
    def __init__(self, agent, stt=None, llm=None, tts=None):
        super().__init__(agent, stt, llm, tts)

    async def run(self, transcript: str) -> AsyncIterator[str]:
        await self.on_turn_start(transcript)
        # Add image context
        self.agent.chat_context.add_message(
            role=ChatRole.USER, content=[ImageContent(image="YOUR_IMAGE_URL")]
        )
        async for response_chunk in self.process_with_llm():
            yield response_chunk
        await self.on_turn_end()

    async def on_turn_start(self, transcript: str) -> None:
        self.is_turn_active = True

    async def on_turn_end(self) -> None:
        self.is_turn_active = False
```

### Inference Detail

If your LLM provider supports it, you can set the `inference_detail` parameter to "high" or "low" to control token usage and inference quality. The default is "auto", which uses the provider's default setting.

:::info
Inference detail is only available by OpenAI.
:::

## Live Video Input (Realtime Pipeline)

Set the `vision` parameter to `True` in `RoomOptions` to enable live video input. This feature is only supported with the [Gemini Live](/ai_agents/plugins/realtime/google.md) model.

```python
job_context = JobContext(
  room_options = RoomOptions(
    room_id = "YOUR_ROOM_ID",
    name = "Agent",
    vision = True
  )
)
```

---

# AI Voice Agent Quick Start

Get started with VideoSDK Agents in minutes. This guide covers both Realtime (speech-to-speech) and Cascaded (STT-LLM-TTS) pipeline implementations.

## Prerequisites

Before you begin, ensure you have:

- A VideoSDK authentication token (generate from [app.videosdk.live](https://app.videosdk.live)), follow to guide to [generate videosdk token](/ai_agents/authentication-and-token)
- A VideoSDK meeting ID (you can generate one using the [Create Room API](https://docs.videosdk.live/api-reference/realtime-communication/create-room) or through the VideoSDK dashboard)
- Python 3.12 or higher

## Understanding the Architecture

Before diving into implementation, let's understand the two main pipeline architectures available:

**real-time-pipeline:**

**Realtime Pipeline** provides direct speech-to-speech processing with minimal latency:

![Realtime Pipeline Architecture](https://cdn.videosdk.live/website-resources/docs-resources/videosdk_realtime_pipeline.png)

The realtime pipeline processes audio directly through a unified model that handles:

- **User Voice Input** → **Speech to Speech model** → **Agent Voice Output**

This approach offers the fastest response times and is ideal for real-time conversations.

---

**cascading-pipeline:**

**Cascading Pipeline** processes audio through distinct stages for maximum control:

![Cascading Pipeline Architecture](https://cdn.videosdk.live/website-resources/docs-resources/videosdk_casading_pipeline.png)

The cascading pipeline processes audio through three sequential stages:

- **User Voice Input** → **STT (Speech-to-Text)** → **LLM (Large Language Model)** → **TTS (Text-to-Speech)** → **Agent Voice Output**

This approach provides better control over each processing stage and supports more complex AI reasoning.

## Installation

Create and activate a virtual environment with Python 3.12 or higher:

**macOS/Linux:**

```js
python3.12 -m venv venv
source venv/bin/activate
```

---

**Windows:**

```js
python -m venv venv
venv\Scripts\activate
```

**cascading-pipeline:**

```bash
pip install "videosdk-agents[deepgram,openai,elevenlabs,silero,turn_detector]"
```

> Want to use a different provider? Check out our plugins for [STT](https://docs.videosdk.live/ai_agents/plugins/stt/openai), [LLM](https://docs.videosdk.live/ai_agents/plugins/llm/openai), and [TTS](https://docs.videosdk.live/ai_agents/plugins/tts/eleven-labs).

---

**real-time-pipeline:**

```bash
pip install videosdk-agents

# Choose your real-time provider:
# For OpenAI
pip install "videosdk-plugins-openai"

# For Gemini (LiveAPI)
pip install "videosdk-plugins-google"

# For AWS Nova
pip install "videosdk-plugins-aws"
```

## Environment Setup

It's recommended to use environment variables for secure storage of API keys, secret tokens, and authentication tokens. Create a `.env` file in your project root:

**cascading-pipeline:**

```shell title=".env"
DEEPGRAM_API_KEY = "Your Deepgram API Key"
OPENAI_API_KEY = "Your OpenAI API Key"
ELEVENLABS_API_KEY = "Your ElevenLabs API Key"
VIDEOSDK_AUTH_TOKEN = "VideoSDK Auth token"
```

> **API Keys** - Get API keys [Deepgram ↗](https://console.deepgram.com/), [OpenAI ↗](https://platform.openai.com/api-keys), [ElevenLabs ↗](https://elevenlabs.io/app/settings/api-keys) & [VideoSDK Dashboard ↗](https://app.videosdk.live/api-keys) follow to guide to [generate videosdk token ](/ai_agents/authentication-and-token)

---

**real-time-pipeline:**

```bash title=".env"
VIDEOSDK_AUTH_TOKEN="VideoSDK Auth token"
OPENAI_API_KEY="Your OpenAI API Key"

// For Google Live API
// GOOGLE_API_KEY="Google Live API Key"

// For AWS Nova API
// AWS_ACCESS_KEY_ID="AWS Key Id"
// AWS_SECRET_ACCESS_KEY="AWS Secret Key"
// AWS_DEFAULT_REGION="AWS Region"
```

> **API Keys** - Get API keys [OpenAI ↗](https://platform.openai.com/api-keys) or [Gemini ↗](https://aistudio.google.com/app/apikey) or [AWS Nova Sonic ↗](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html) & [VideoSDK Dashboard ↗](https://app.videosdk.live/api-keys)> follow to guide to [generate videosdk token ](/ai_agents/authentication-and-token)

### Step 1: Creating a Custom Agent


First, let's create a custom voice agent by inheriting from the base `Agent` class:

**cascading-pipeline:**

```python title="main.py"
import asyncio, os
from videosdk.agents import Agent, AgentSession, CascadingPipeline, JobContext, RoomOptions, WorkerJob,ConversationFlow
from videosdk.plugins.silero import SileroVAD
from videosdk.plugins.turn_detector import TurnDetector, pre_download_model
from videosdk.plugins.deepgram import DeepgramSTT
from videosdk.plugins.openai import OpenAILLM
from videosdk.plugins.elevenlabs import ElevenLabsTTS
from typing import AsyncIterator

# Pre-downloading the Turn Detector model
pre_download_model()

class MyVoiceAgent(Agent):
def __init__(self):
    super().__init__(instructions="You are a helpful voice assistant that can answer questions and help with tasks.")
async def on_enter(self): await self.session.say("Hello! How can I help?")
async def on_exit(self): await self.session.say("Goodbye!")

```

---

**real-time-pipeline:**

```python title="main.py"
import asyncio, os
from videosdk.agents import Agent, AgentSession, RealTimePipeline, JobContext, RoomOptions, WorkerJob
from videosdk.plugins.openai import OpenAIRealtime, OpenAIRealtimeConfig
from openai.types.beta.realtime.session import  TurnDetection

class MyVoiceAgent(Agent):
def __init__(self):
    super().__init__(instructions="You are a helpful voice assistant that can answer questions and help with tasks.")
async def on_enter(self): await self.session.say("Hello! How can I help?")
async def on_exit(self): await self.session.say("Goodbye!")
```

This code defines a basic voice agent with:

- Custom instructions that define the agent's personality and capabilities
- An entry message when joining a meeting
- State change handling to track the agent's current activity



### Step 2: Assembling and Starting the Agent Session


The pipeline connects your agent to an AI model.

**cascading-pipeline:**

```python title="main.py"
async def start_session(context: JobContext):
# Create agent and conversation flow
agent = MyVoiceAgent()
conversation_flow = ConversationFlow(agent)

# Create pipeline
pipeline = CascadingPipeline(
    stt=DeepgramSTT(model="nova-2", language="en"),
    llm=OpenAILLM(model="gpt-4o"),
    tts=ElevenLabsTTS(model="eleven_flash_v2_5"),
    vad=SileroVAD(threshold=0.35),
    turn_detector=TurnDetector(threshold=0.8)
)

session = AgentSession(
    agent=agent,
    pipeline=pipeline,
    conversation_flow=conversation_flow
)

try:
    await context.connect()
    await session.start()
    # Keep the session running until manually terminated
    await asyncio.Event().wait()
finally:
    # Clean up resources when done
    await session.close()
    await context.shutdown()

def make_context() -> JobContext:
room_options = RoomOptions(
 #  room_id="YOUR_MEETING_ID",  # Set to join a pre-created room; omit to auto-create
    name="VideoSDK Cascaded Agent",
    playground=True
)

return JobContext(room_options=room_options)

if __name__ == "__main__":
job = WorkerJob(entrypoint=start_session, jobctx=make_context)
job.start()
```

---

**real-time-pipeline:**

```python title="main.py"
async def start_session(context: JobContext):
# Initialize Model
model = OpenAIRealtime(
    model="gpt-realtime-2025-08-28",
    config=OpenAIRealtimeConfig(
        voice="alloy",  # Available voices:alloy, ash, ballad, coral, echo, fable, onyx, nova, sage, shimmer, and verse
        modalities=["text", "audio"],
        turn_detection=TurnDetection(
            type="server_vad",
            threshold=0.5,
            prefix_padding_ms=300,
            silence_duration_ms=200,
        )
    )
)

# Create pipeline
pipeline = RealTimePipeline(
    model=model
)

session = AgentSession(
    agent=MyVoiceAgent(),
    pipeline=pipeline
)

try:
    await context.connect()
    await session.start()
    # Keep the session running until manually terminated
    await asyncio.Event().wait()
finally:
    # Clean up resources when done
    await session.close()
    await context.shutdown()

def make_context() -> JobContext:
room_options = RoomOptions(
#   room_id="YOUR_MEETING_ID",  # Set to join a pre-created room; omit to auto-create
    name="VideoSDK Realtime Agent",
    playground=True
)

return JobContext(room_options=room_options)

if __name__ == "__main__":
job = WorkerJob(entrypoint=start_session, jobctx=make_context)
job.start()
```



### Step 3: Running the Project


Once you have completed the setup, you can run your AI Voice Agent project using Python. Make sure your `.env` file is properly configured and all dependencies are installed.

**console-mode:**

```bash
python main.py console
```

Want to see the magic instantly? Try console mode to interact with your agent directly through the terminal! No need to join a meeting room - just speak and listen through your local system. Perfect for quick testing and development.

![Console Mode](https://cdn.videosdk.live/website-resources/docs-resources/ai_agents_console_mode_image.png)

Learn more about [Console Mode](/ai_agents/console_mode).

---

**room:**

```bash
python main.py
```

Once you run this command, a playground URL will appear in your terminal. You can use this URL to interact with your AI agent.



### Step 4: Connecting with VideoSDK Client Applications


When working with a Client SDK, make sure to create the room first using the [Create Room API](https://docs.videosdk.live/api-reference/realtime-communication/create-room)
. Then, simply pass the generated `room id` in both your client SDK and the `RoomOptions` for your AI Agent so they connect to the same session.




:::tip

Get started quickly with the [Quick Start Example](https://github.com/videosdk-live/agents-quickstart/) for the VideoSDK AI Agent SDK — everything you need to build your first AI agent fast.

:::


---

# Wake Up Call

Wake Up Call enables AI agents to automatically trigger actions when users remain inactive for a specified duration. This feature helps maintain user engagement and provides proactive assistance during conversation sessions.

## Overview

The Wake Up Call system allows AI agents to:
- Monitor user inactivity periods during conversations
- Automatically trigger custom callback functions after specified timeouts
- Re-engage users with proactive messages or actions

## Key Components

### 1. Wake Up Configuration

Set the inactivity timeout duration in the `AgentSession` constructor using the `wake_up` parameter:

```python
session = AgentSession(
    agent=agent, 
    pipeline=pipeline,
    conversation_flow=conversation_flow,
    wake_up=10  # seconds
)
```

**Important**: If a `wake_up` time is provided, you must set a callback function before starting the session. If no `wake_up` time is specified, no timer or callback will be activated.

### 2. Callback Function

Define a custom async function that will be executed when the inactivity threshold is reached:

```python
async def on_wake_up():
    print("Wake up triggered - user inactive for 10 seconds")
    session.say("Hello, how can I help you today?")

# Assign the callback function to the session
session.on_wake_up = on_wake_up
```

:::tip

Get started quickly with the [Wake Up Call Example](https://github.com/videosdk-live/agents/tree/main/examples/wakeup_call.py) — everything you need to implement inactivity detection in your AI agents.

:::


---

This quickstart guide will walk you through creating a powerful AI voice agent that can answer calls made to your WhatsApp Business number. We will achieve this using a direct SIP integration between the Meta Business Platform and VideoSDK, which simplifies the architecture and removes the need for a third-party telephony provider.

### **Architecture Overview - Call Flow**

The diagram below illustrates the end-to-end call flow we are building. A call initiated by a **WhatsApp User** is received by the **Meta Business Platform**, which then forwards it directly via SIP to the **VideoSDK SIP Gateway**. From there, **Routing Rules** direct the call to our **AI Agent**.

![Whats Voice Agent Call Flow](https://assets.videosdk.live/images/whatsapp-ai-voice-agent-call-flow.png)

### **Prerequisites for Meta Configuration**

This guide assumes you have already completed the initial setup of your business presence on the Meta platform.

- A **[Meta (Facebook) Business Manager Account](https://business.facebook.com/)** that is verified.
- A **Phone number** that has been added and verified in your WhatsApp Business Account (WABA).
- A **[Meta Developer App](https://developers.facebook.com/)** with the `whatsapp_business_management` permission enabled.
- A **[Permanent User Access Token](https://developers.facebook.com/docs/graph-api/get-started#step-2--generate-an-access-token)** for meta graph api endpoint.

:::tip **Essential: Meta Graph API Setup**

Integrating inbound/outbound WhatsApp calls requires updating your number's settings via the Meta Graph API. This guide covers the process in [Part 3: Enable WhatsApp SIP Forwarding](#part-3-enable-whatsapp-sip-forwarding). For a deeper understanding of the API, refer to the [official Meta Graph API overview](https://developers.facebook.com/docs/graph-api/overview).

:::

## Part 1: Build and Run Your Custom Voice Agent

First, we'll create the AI agent that will handle the conversation logic. This agent will run on your local machine for testing.

### Step 1: Project Setup


Create a directory for your project and add the following files:

- `.env`: To store your secret credentials.
- `requirements.txt`: To list the Python dependencies.
- `main.py`: The main script for your AI agent.



### Step 2: Add Credentials and Dependencies


In your `.env` file, add the necessary API keys.

**realtime-pipeline:**

```bash title=".env"
VIDEOSDK_AUTH_TOKEN="your_videosdk_token_here"
GOOGLE_API_KEY="your_google_api_key_here"
```

> **API Keys**: Get your [Google API Key](https://aistudio.google.com/app/apikey) and create a [VideoSDK Account](https://app.videosdk.live/api-keys) to [generate your token ](/ai_agents/authentication-and-token).

---

**cascading-pipeline:**

```bash title=".env"
VIDEOSDK_AUTH_TOKEN="your_videosdk_token_here"
DEEPGRAM_API_KEY="your_deepgram_api_key_here"
OPENAI_API_KEY="your_openai_api_key_here"
ELEVENLABS_API_KEY="your_elevenlabs_api_key_here"
```

> **API Keys**: Get keys from [Deepgram](https://console.deepgram.com/), [OpenAI](https://platform.openai.com/api-keys), [ElevenLabs](https://elevenlabs.io/app/settings/api-keys), and [VideoSDK Account](https://app.videosdk.live/api-keys) to [generate videosdk token ](/ai_agents/authentication-and-token).

In `requirements.txt`, add the dependencies.

**realtime-pipeline:**

```text title="requirements.txt"
videosdk-agents==0.0.45
videosdk-plugins-google==0.0.45
python-dotenv==1.1.1
```

---

**cascading-pipeline:**

```text title="requirements.txt"
videosdk-agents[deepgram,openai,elevenlabs,silero,turn_detector]==0.0.45
python-dotenv==1.1.1
```

> **Latest Version**: Check the latest [videosdk-agents version on PyPI](https://pypi.org/project/videosdk-agents/) for the most recent release.



### Step 3: Create the Agent Logic


Paste the following code into `main.py`. This defines the agent's personality and sets it up to be discoverable by VideoSDK's telephony service.

**realtime-pipeline:**

```python title="main.py"
import asyncio, os, traceback, logging
from videosdk.agents import Agent, AgentSession, RealTimePipeline, JobContext, WorkerJob, Options
from videosdk.plugins.google import GeminiRealtime, GeminiLiveConfig
from dotenv import load_dotenv

logging.basicConfig(level=logging.INFO)
load_dotenv()

# Define the agent's behavior and personality
class MyWhatsappAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are a friendly and helpful assistant answering WhatsApp calls. Keep your responses concise and clear.",
        )
    async def on_enter(self) -> None:
        await self.session.say("Hello! You've reached the VideoSDK assistant. How can I help you today?")
    async def on_exit(self) -> None:
        await self.session.say("Thank you for calling. Goodbye!")

async def start_session(context: JobContext):

    model = GeminiRealtime(
        model="gemini-2.5-flash-native-audio-preview-12-2025",
        api_key=os.getenv("GOOGLE_API_KEY"),
        config=GeminiLiveConfig(voice="Leda", response_modalities=["AUDIO"])
    )

    pipeline = RealTimePipeline(model=model)
    session = AgentSession(agent=MyWhatsappAgent(), pipeline=pipeline)

    try:
        await context.connect()
        await session.start()
        await asyncio.Event().wait()
    finally:
        await session.close()
        await context.shutdown()

if __name__ == "__main__":
    try:
        options = Options(
            agent_id="agent1",  # CRITICAL: Unique ID for routing
            register=True,      # REQUIRED: Register with VideoSDK for telephony
            max_processes=10,
        )
        job = WorkerJob(entrypoint=start_session, options=options)
        job.start()
    except Exception as e:
        traceback.print_exc()
```

---

**cascading-pipeline:**

```python title="main.py"
import asyncio, os, traceback, logging
from videosdk.agents import Agent, AgentSession, CascadingPipeline, JobContext, WorkerJob, Options, ConversationFlow
from videosdk.plugins.silero import SileroVAD
from videosdk.plugins.turn_detector import TurnDetector, pre_download_model
from videosdk.plugins.deepgram import DeepgramSTT
from videosdk.plugins.openai import OpenAILLM
from videosdk.plugins.elevenlabs import ElevenLabsTTS
from dotenv import load_dotenv

logging.basicConfig(level=logging.INFO)
load_dotenv()
pre_download_model()

# Define the agent's behavior and personality
class MyWhatsappAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are a friendly and helpful assistant answering WhatsApp calls. Keep your responses concise and clear.",
        )
    async def on_enter(self) -> None:
        await self.session.say("Hello! You've reached the VideoSDK assistant. How can I help you today?")
    async def on_exit(self) -> None:
        await self.session.say("Thank you for calling. Goodbye!")

async def start_session(context: JobContext):

    pipeline = CascadingPipeline(
        stt=DeepgramSTT(model="nova-2", language="en"),
        llm=OpenAILLM(model="gpt-4o"),
        tts=ElevenLabsTTS(model="eleven_flash_v2_5"),
        vad=SileroVAD(threshold=0.35),
        turn_detector=TurnDetector(threshold=0.8)
    )
    session = AgentSession(
        agent=MyWhatsappAgent(),
        pipeline=pipeline,
        conversation_flow=ConversationFlow(MyWhatsappAgent())
    )
    try:
        await context.connect()
        await session.start()
        await asyncio.Event().wait()
    finally:
        await session.close()
        await context.shutdown()

if __name__ == "__main__":
    try:
        options = Options(
            agent_id="agent1",  # CRITICAL: Unique ID for routing
            register=True,               # REQUIRED: Register with VideoSDK for telephony
            max_processes=10,
        )
        job = WorkerJob(entrypoint=start_session, options=options)
        job.start()
    except Exception as e:
        traceback.print_exc()
```



### Step 4: Install Dependencies and Run the Agent


```bash title="CLI Commands"
# Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install packages
pip install -r requirements.txt

# Run the agent
python main.py
```

Your agent is now running and waiting for connections. Keep the terminal open.



## Part 2: Configure VideoSDK Gateways and Routing

Next, we need to tell VideoSDK how to handle incoming calls and where to send them.

### Step 1: Configure an Inbound Gateway


This is the entry point for calls coming from WhatsApp into VideoSDK.

**dashboard:**

Go to **Telephony > Inbound Gateways** in the [VideoSDK Dashboard](https://app.videosdk.live/telephony/inbound-gateways) and click **Add**.

Give your gateway a name (e.g., "WhatsApp Gateway") and enter your WhatsApp Business phone number.

<div style={{ textAlign: "center" }}>
  
</div>

---

**api:**

```bash title="cURL"
curl --request POST \
  --url https://api.videosdk.live/v2/sip/inbound-gateways \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "WhatsApp Gateway", "numbers": ["+1234567890"] }'
```

> **API Reference**: [Create Inbound Gateway](/api-reference/realtime-communication/sip/inbound-gateway/create-inbound-gateway)



### Step 2: Configure an Outbound Gateway


This is the exit point for calls your agent makes to the phone network.

**dashboard:**

Go to **Telephony > Outbound Gateways** and click **Add**.

Give it a name and provide the SIP details from your provider. For WhatsApp, this step is for enabling agent-initiated outbound calls.

To get `username` and `password` make use of meta graph API, switch in **Via API** tab.

{" "}

{" "}

<div style={{ textAlign: "center" }}>
  
</div>

---

**api:**

**Get SIP Credentials from Meta**

First, you need to get the SIP credentials from the Meta Graph API.

```bash title="cURL"
curl --location --globoff 'https://graph.facebook.com/v17.0/{{phone_id}}/settings?include_sip_credentials=true' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json'
```

The API response will look something like this:

```json title="Response"
{
  "calling": {
"status": "ENABLED",
"call_icon_visibility": "DEFAULT",
"callback_permission_status": "DISABLED",
"srtp_key_exchange_protocol": "DTLS",
"sip": {
  "status": "ENABLED",
  "servers": [
    {
      "app_id": 1300814931425659,
      "hostname": "9WXXXXXXXX.sip.videosdk.live",
      "sip_user_password": "v18yo4xxxxxxxxxxxx"
    }
  ]
}
  },
  "storage_configuration": {
"status": "DEFAULT"
  }
}
```

**Create VideoSDK Outbound Gateway**

Now, use the `sip_user_password` from the previous step to create an outbound gateway in VideoSDK.

```bash title="cURL"
curl --request POST \
  --url https://api.videosdk.live/v2/sip/outbound-gateways \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "My Outbound Gateway", "numbers": ["+1234567890"], "address": "9WXXXXXXXX.sip.videosdk.live", "auth": { "username": "your_whatsapp_number", "password": "v18yo40Lhxxxxxx" } }'
```

> **API Reference**: [Create Outbound Gateway](/api-reference/realtime-communication/sip/outbound-gateway/create-outbound-gateway)



### Step 3: Create a Routing Rule


This rule connects the Inbound Gateway to your specific AI agent.

**dashboard:**

Go to **Telephony > Routing Rules** and click **Add**.

Configure the rule:

- **Gateway**: Select the "WhatsApp Gateway" you just created.
- **Numbers**: Add your WhatsApp Business phone number.
- **Dispatch**: Choose **Agent**.
- **Agent Type**: Set to `Self Hosted`.
- **Agent ID**: Enter `agent1`. This **must exactly match** the `agent_id` in your `main.py` script.

Click **Create**.

<div style={{ textAlign: "center" }}>
  
</div>

---

**api:**

```bash title="cURL"
curl --request POST \
  --url https://api.videosdk.live/v2/sip/routing-rules \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "gatewayId": "your_inbound_gateway_id", "name": "WhatsApp Call Routing", "numbers": ["+1234567890"], "dispatch": "agent", "agentType": "self_hosted", "agentId": "agent1" }'
```

> **API Reference**: [Create Routing Rule](/api-reference/realtime-communication/sip/routing-rules/create-routing-rule)



---

## Part 3: Enable WhatsApp SIP Forwarding

Now, we'll instruct Meta to forward incoming WhatsApp calls to your VideoSDK Inbound Gateway. This is done via the **Meta Graph API**.

### Step 1: API Request


Use the following `curl` command to update your WhatsApp phone number's settings.

```bash title="cURL"
curl --location 'https://graph.facebook.com/v19.0/{{phone_number_id}}/settings' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{ "calling": { "status": "ENABLED", "sip": { "status": "ENABLED", "servers": [ { "hostname": "9WXXXXXXX.sip.videosdk.live" } ] }, "srtp_key_exchange_protocol": "DTLS" } }'
```

**Replace the placeholders:**

- `{{phone_number_id}}`: Your WhatsApp Business Phone Number ID from the Meta dashboard.
- `{{access_token}}`: A valid User or System User access token with `whatsapp_business_management` permission.



### Step 2: API Response


A successful request will return:

```json title="Response"
{
  "success": true
}
```

Your integration is now complete! Meta will forward all incoming voice calls to your WhatsApp number to VideoSDK, which will then route them to your running agent.



---

## Time to Talk! Test Your Agent

:::tip **Keep Your Agent Running**

Make sure your `main.py` script is still running locally before making or receiving calls. The agent must be active to handle any communication.

:::

### Receive an Inbound Call

1.  Ensure your `main.py` script is still running locally.
2.  Using a different WhatsApp account, place a voice call to your WhatsApp Business number.
3.  Your local agent will answer, and you'll hear its greeting. Start a conversation!

### Make an Outbound Call

To have your agent initiate a call to a WhatsApp number, use the VideoSDK SIP Call API.

```bash title="cURL"
curl --request POST \
  --url https://api.videosdk.live/v2/sip/call \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "gatewayId": "your_outbound_gateway_id", "sipCallTo": "whatsapp_number_to_call" }'
```

This commands your agent to dial out through your configured outbound gateway.

:::tip **Geographic Optimization**

For optimal performance, run your agent in the same geographic region as your SIP provider. This reduces latency and improves call quality.

:::

## Next Steps

Congratulations! You've built and deployed a sophisticated AI telephony agent. You've seen how to run it locally and connect it to the global phone network for both inbound and outbound communication.

- [Deploy Your Agent](/ai_agents/deployments/introduction): Learn how to deploy your AI agent to production
- [Explore Telephony Docs](/telephony/introduction): Comprehensive telephony documentation and guides
- [Provider Integrations](/telephony/integrations/twilio-sip-integration): SIP provider setup guides (Twilio, Vonage, etc.)




---

## Custom Video Track - Android

- You can create a Video Track using `createCameraVideoTrack()` method of `VideoSDK`.
- This method can be used to create video track using different encoding parameters, camera facing mode, bitrateMode, maxLayer and optimization mode.

### Parameters

- **encoderConfig**:

  - type: `String`
  - required: `true`
  - default: `h480p_w720p`
  - You can choose from the below mentioned list of values for the encoder config.

| Config            | Resolution | Frame Rate | Optimized (kbps) | Balanced (kbps) | High Quality (kbps) |
| :---------------- | :--------: | :--------: | :--------------: | :-------------: | :-----------------: |
| h144p_w176p |  176x144   |   15 fps   |        60        |       100       |         150         |
| h240p_w320p |  320x240   |   15 fps   |        80        |       150       |         300         |
| h360p_w640p |  360x640   |  25 fps   |       200        |       400       |         800         |
| h480p_w640p |  640x480   |   25 fps   |       300        |       600       |        1000         |
| h480p_w720p |  720x480   |   30 fps   |       400        |       700       |        1100         |
| h720p_w960p |  960x720   |   30 fps   |       800        |      1300       |        1800         |
| h720p_w1280p |  1280x720  |   30 fps   |       1000       |      1600       |        2400         |
| h1080p_w1440p | 1440x1080  |   30 fps   |       2000       |      2500       |        3500         |

:::note

Above mentioned encoder configurations are valid for both, landscape as well as portrait mode.

:::

- **facingMode**:

  - type: `String`
  - required: `true`
  - Allowed values : `front` | `back`
  - It will specify wheater to use front or back camera for the video track.

- **optimizationMode**

  - type: `CustomStreamTrack.VideoMode`
  - required: `true`
  - Allowed values: `motion` | `text` | `detail`
  - It will specify the optimization mode for the video track being generated.

- **multiStream**:

  - type: `boolean`
  - required: `true`
  - It will specify if the stream should send multiple resolution layers or single resolution layer.

- **context**:

  - type: `Context`
  - required: `true`
  - Pass the Android Context for this parameter.

- **observer**:

  - type: `CapturerObserver`
  - required: `false`
  - If you want to use video filter from external SDK(e.g., [Banuba](https://www.banuba.com/)) then pass instance of `CapturerObserver` in this parameter.

- **videoDeviceInfo**:

  - type: `VideoDeviceInfo`
  - required: `false`
  - If you want to specify a camera device to be used in the meeting.


- **bitrateMode**:

  - type: `BitrateMode`
  - required: `false`
  - Allowed values : `BitrateMode.BANDWIDTH_OPTIMIZED` | `BitrateMode.BALANCED` | `BitrateMode.HIGH_QUALITY`
  - Controls the video quality and bandwidth consumption. You can choose between `BitrateMode.HIGH_QUALITY` for the best picture, `BitrateMode.BANDWIDTH_OPTIMIZED` to save data, or `BitrateMode.BALANCED` for a mix of both. Defaults to `BitrateMode.BALANCED`.


- **maxLayer**:

  - type: `Integer`
  - required: `false`
  - Allowed values : `2` | `3`
  - Specifies the maximum number of simulcast layers to publish. This parameter only has an effect if `multiStream` is set to true.

:::note

For Banuba integraion with VideoSDK, please visit [Banuba Intergation with VideoSDK](/android/guide/video-and-audio-calling-api-sdk/video-processor/banuba-integration)

:::

:::info

- To learn more about optimizations and best practices for using custom video tracks, [follow this guide](/android/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track).

:::

#### Returns

- `CustomStreamTrack`

### Example



**Kotlin:**

```javascript
val videoCustomTrack: CustomStreamTrack = VideoSDK.createCameraVideoTrack("h720p_w960p", "front", CustomStreamTrack.VideoMode.MOTION, true, this, 2, BitrateMode.HIGH_QUALITY)
```

---

**Java:**

```javascript
CustomStreamTrack customStreamTrack = VideoSDK.createCameraVideoTrack("h720p_w960p", "front", CustomStreamTrack.VideoMode.MOTION, true, this, 2, BitrateMode.HIGH_QUALITY);
```

## Custom Audio Track - Android

- You can create a Audio Track using `createAudioTrack()` method of `VideoSDK`.
- This method can be used to create audio track using different encoding parameters.

### Parameters

- **encoderConfig**:

  - type: `String`
  - required: `true`
  - default: `speech_standard`
  - You can choose from the below mentioned list of values for the encoder config.

| Encoder Config      | Bitrate  | Auto Gain | Echo Cancellation | Noise Suppression |
| ------------------- | :------: | :-------: | :---------------: | :---------------: |
| speech_low_quality  | 16 kbps  |   TRUE    |       TRUE        |       TRUE        |
| speech_standard     | 24 kbps  |   TRUE    |       TRUE        |       TRUE        |
| music_standard      | 32 kbps  |   FALSE   |       FALSE       |       FALSE       |
| standard_stereo     | 64 kbps  |   FALSE   |       FALSE       |       FALSE       |
| high_quality        | 128 kbps |   FALSE   |       FALSE       |       FALSE       |
| high_quality_stereo | 192 kbps |   FALSE   |       FALSE       |       FALSE       |

- **context**

  - type: `Context`
  - required: `true`
  - Pass the Android Context for this parameter.

#### Returns

- `CustomStreamTrack`

### Example

**Kotlin:**

```js
val audioCustomTrack: CustomStreamTrack = VideoSDK.createAudioTrack("speech_standard",this)
```

---

**Java:**

```js
CustomStreamTrack audioCustomTrack=VideoSDK.createAudioTrack("speech_standard", this);
```

## Custom Screen Share Track - Android

- You can create a Screen Share track using `createScreenShareVideoTrack()` method of `VideoSDK`.
- This method can be used to create screen share track using different encoding parameters.

### Parameters

- **encoderConfig**:

  - type: `String`
  - required: `true`
  - default: `h720p_15fps`
  - You can choose from the below mentioned list of values for the encoder config.

| Encoder Config | Resolution | Frame Rate |   Bitrate    |
| -------------- | :--------: | :--------: | :----------: |
| h360p_30fps    |  640x360   |   3 fps    | 200000 kbps  |
| h720p_5fps     |  1280x720  |   5 fps    | 400000 kbps  |
| h720p_15fps    |  1280x720  |   15 fps   | 1000000 kbps |
| h1080p_15fps   | 1920x1080  |   15 fps   | 1500000 kbps |
| h1080p_30fps   | 1920x1080  |   15 fps   | 1000000 kbps |

:::note

Above mentioned encoder configurations are valid for both, landscape as well as portrait mode.

:::

- **data**

  - type: `Intent`
  - required: `true`
  - It is Intent received from onActivityResult when user provide permission for ScreenShare.

- **context**

  - type: `Context`
  - required: `true`
  - Pass the Android Context for this parameter.

- **listener**
  - type: `CustomTrackListener`
  - required: `true`
  - Callback to this listener will be made when track is ready with CustomTrack as parameter.

### Example

**Kotlin:**

```javascript
// data is received from onActivityResult method.
VideoSDK.createScreenShareVideoTrack("h720p_15fps", data, this) { track ->
meeting!!.enableScreenShare(track)
}
```

---

**Java:**

```javascript
// data is received from onActivityResult method.
VideoSDK.createScreenShareVideoTrack("h720p_15fps", data, this, (track)->{
meeting.enableScreenShare(track);
});
```


---

# Meeting Error Codes - Android

If you encounter any of the errors listed below, refer to the [Developer Experience Guide](../../guide/best-practices/developer-experience.md#listen-for-error-events), which offers recommended solutions based on common error categories.



### 1. Errors associated with Organization 

This table lists errors that occur due to the configuration and limitations within your organization’s account. These include account status, participant limits, and add-on service availability.

| Type                                   | Code  | Message                                             |
|----------------------------------------|-------|-----------------------------------------------------|
| ACCOUNT_DEACTIVATED                   | 4006  | Your account has been deactivated. Please contact VideoSDK support. |
| ACCOUNT_DISCONTINUED                  | 4007  | Your account has been discontinued. Please reach out to support for more details. |
| MAX_PARTICIPANT_REACHED               | 4009  | You have reached the maximum participant limit for this meeting. |
| MAX_SPEAKER_REACHED                   | 4010  | The maximum number of speakers for this meeting has been reached. |
| MAX_SPEAKER_LIMIT_REACHED_ON_ORGANIZATION | 4026  | Your organization has reached the maximum number of speakers allowed. |
| MAX_VIEWER_LIMIT_REACHED_ON_ORGANIZATION | 4027  | Your organization has reached the maximum number of viewers allowed. |
| ADD_ON_SERVICES_DISABLED              | 4021  | Add-On services have been disabled. Please contact support to enable them. |
| MAX_RECORDING_LIMIT_REACHED_ON_ORGANIZATION              | 4028  | You have reached max limit of recording on organization. To increase contact at support@videosdk.live |
| MAX_HLS_LIMIT_REACHED_ON_ORGANIZATION  | 4029  | You have reached max limit of hls on organization. To increase contact at support@videosdk.live |
| MAX_LIVESTREAM_LIMIT_REACHED_ON_ORGANIZATION  | 4030  | You have reached max limit of livestream on organization. To increase contact at support@videosdk.live |

### 2. Errors associated with Token

Errors listed here are related to issues with the API key, authentication tokens, or permissions assigned to users. These errors can occur when tokens are missing, expired, or improperly configured.

| Type                                    | Code  | Message                                                |
|-----------------------------------------|-------|--------------------------------------------------------|
| INVALID_API_KEY                        | 4001  | The provided API key is either missing or invalid. |
| INVALID_TOKEN                          | 4002  | The provided token is empty, invalid, or has expired. |
| INVALID_PERMISSIONS                    | 4008  | The permissions in the token are incorrect. Please verify them. |
| UNAUTHORIZED_MEETING_ID                | 4022  | The provided token is not authorized for this meeting ID. |
| UNAUTHORIZED_PARTICIPANT_ID            | 4023  | The provided token is not authorized for this participant ID. |
| UNAUTHORIZED_ROLE                      | 4024  | The role specified in the token is not valid for joining this meeting. |
| UNAUTHORIZED_REQUEST                      | 4025 | Your request does not match the security configuration. |

### 3. Errors associated with Meeting and Participant

This table lists errors resulting from invalid or missing meeting or participant details, including cases where a participant attempts to join with a duplicate ID.

| Type                    | Code  | Message                                         |
|-------------------------|-------|-------------------------------------------------|
| INVALID_MEETING_ID      | 4003  | The meeting ID provided is either invalid or missing. |
| INVALID_PARTICIPANT_ID  | 4004  | The participant ID is either invalid or missing. |
| DUPLICATE_PARTICIPANT   | 4005  | This participant has joined from another device. |

### 4. Errors associated with Add-on Service

This section addresses errors that occur while using VideoSDK's add-on services such as recording, livestreaming, HLS streaming, and transcription.

### Recording-related errors

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_RECORDING_FAILED      | 4011  | Failed to start recording. Please try again.   |
| STOP_RECORDING_FAILED       | 4012  | Failed to stop recording. Please try again.    |
| RECORDING_FAILED            | 5001  | Recording was stopped due to an error.         |
| START_PARTICIPANT_RECORDING_FAILED | 4035 | Failed to start participant recording. Please check the request. |
| STOP_PARTICIPANT_RECORDING_FAILED  | 4036 | Failed to stop participant recording. |
| PARTICIPANT_RECORDING_FAILED       | 5012 | Participant recording has stopped due to an error. |
| START_TRACK_RECORDING_FAILED | 4037 | Failed to start track recording.                |
| STOP_TRACK_RECORDING_FAILED  | 4038 | Failed to stop track recording.                 |
| TRACK_RECORDING_FAILED  | 5013 | Track recording stopped due to an unknown error.                 |
| PREV_RECORDING_PROCESSING  | 4018 | Previous recording session is being processed, please try again after few seconds.                 |
| RECORDING_DURATION_LIMIT_REACHED | 5004 | Recording stopped due to maximum duration being reached. |

### Livestream-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| INVALID_LIVESTREAM_CONFIG           | 4015  | Livestream 'outputs' configuration provided was invalid            |
| START_LIVESTREAM_FAILED     | 4013  | Failed to start livestream. Please try again.  |
| STOP_LIVESTREAM_FAILED      | 4014  | Failed to stop livestream. Please try again.   |
| LIVESTREAM_FAILED           | 5002  | Livestream stopped due to an error.            |
| PREV_RTMP_RECORDING_PROCESSING | 4019 | Previous RTMP recording session is being processed, please try again after few seconds! |
| LIVESTREAM_DURATION_LIMIT_REACHED | 5005 | Livestream stopped due to maximum duration being reached. |

### HLS-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_HLS_FAILED            | 4016  | Failed to start HLS stream.                    |
| STOP_HLS_FAILED             | 4017  | Failed to stop HLS stream.                     |
| HLS_FAILED                  | 5003  | HLS streaming stopped due to an error.         |
| PREV_HLS_STREAMING_PROCESSING | 4020 | Previous HLS streaming session is still being processed. |
| HLS_DURATION_LIMIT_REACHED  | 5006  | HLS stream stopped due to maximum duration being reached. |

### Transcription-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_TRANSCRIPTION_FAILED  | 4031  | Failed to start transcription. Please try again. |
| STOP_TRANSCRIPTION_FAILED   | 4032  | Failed to stop transcription.                  |
| TRANSCRIPTION_FAILED        | 5007  | Transcription stopped due to an error.         |

### 5.Errors associated with Media

These errors involve media access, device availability, or permission-related issues affecting camera, microphone, and screen sharing.

### Device access-related errors

| Type                                      | Code  | Message                                          |
|-------------------------------------------|-------|--------------------------------------------------|
| ERROR_CAMERA_ACCESS  | 3002  | Something went wrong. Unable to access camera. |
| ERROR_MIC_ACCESS_DENIED  | 3003  | It seems like microphone access was denied or dismissed. To proceed, kindly grant access through your device's settings. |
| ERROR_CAMERA_ACCESS_DENIED | 3004 | It seems like camera access was denied or dismissed. To proceed, kindly grant access through your device's settings. |

### 6.Errors associated with Track

These errors occur when there are issues with video or audio tracks, such as disconnections or invalid custom tracks.

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| ERROR_CUSTOM_SCREEN_SHARE_TRACK_ENDED      | 3005  | The provided custom track is in an ended state. Please try again with new custom track. |
| ERROR_CUSTOM_SCREEN_SHARE_TRACK_DISPOSED      | 3006  | The provided custom track was disposed. Please try again with new custom track. |
| ERROR_CHANGE_WEBCAM      | 3007  | Something went wrong, and the camera could not be changed. Please try again. |

### 7.Errors associated with Actions

Below error is triggered when an action is attempted before joining a meeting.

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| ERROR_ACTION_PERFORMED_BEFORE_MEETING_JOINED     | 3001  | Oops! Something went wrong. The room was in a connecting state, and during that time, an action encountered an issue. Please try again after joining a meeting. |





---

# Initializing a Meeting - Android

<div class="sdk-api-ref">

## initialize()

To initialize the meeting, first you have to initialize the `VideoSDK`.
You can initialize the `VideoSDK` using `initialize()` method provided by the SDK.

#### Parameters

- **context**: Context

#### Returns

- _`void`_

```js title="initialize"
  VideoSDK.initialize(Context context)
```

---

## config()

Now, you have to set `token` property of `VideoSDK` class.
By using `config()` method, you can set the `token` property of `VideoSDK` class.

Please refer this [documentation](/api-reference/realtime-communication/intro/) to generate a token.

#### Parameters

- **token**: String

#### Returns

- _`void`_

```js title="config"
 VideoSDK.config(String token)
```

---

## initMeeting()

- Now, you can initialize the meeting using a factory method provided by the SDK called `initMeeting()`.
- `initMeeting()` will generate a new [`Meeting`](./meeting-class/introduction.md) class and the initiated meeting will be returned.

```js title="initMeeting"
   VideoSDK.initMeeting(
        Context context,
        String meetingId,
        String name,
        boolean micEnabled,
        boolean webcamEnabled,
        String participantId,
        String mode,
        boolean multiStream,
        Map

### multiStream

- It will specify if the stream should send multiple resolution layers or single resolution layer.

  - type: `boolean`
  - `REQUIRED`

### customTracks

- If you want to use custom tracks from start of the meeting, you can pass map of custom tracks in this paramater.

  - type : `Map<String, CustomStreamTrack>` or `null`
  - `REQUIRED`

Please refer this [documentation](../../guide/video-and-audio-calling-api-sdk/features/custom-track/custom-video-track) to know more about CustomTrack.

### metaData

- If you want to provide additional details about a user joining a meeting, such as their profile image, you can pass that information in this parameter.

  - type: `JSONObject`
  - `REQUIRED`

### signalingBaseUrl

- If you want to use a proxy server with the VideoSDK, you can specify your baseURL here.

  - type: `String`
  - `OPTIONAL`

:::note

If you intend to use a proxy server with the VideoSDK, priorly inform us at support@videosdk.live

:::

### preferredProtocol

- If you want to provide a preferred network protocol for communication, you can specify that in `PreferredProtocol`, with options including `UDP_ONLY`, `UDP_OVER_TCP`, and `TCP_ONLY`.

  - type: `PreferredProtocol`
  - `OPTIONAL`

## Returns

### meeting

- After initializing the meeting, `initMeeting()` will return a new [`Meeting`](./meeting-class/introduction.md) instance.

---

## Example



**Kotlin:**

```js title="initMeeting"

VideoSDK.initialize(applicationContext)

// Configure the token
VideoSDK.config(token) // pass the token generated from VideoSDK Dashboard

// Initialize the meeting
var meeting = VideoSDK.initMeeting(
  arrayOf(
this@MainActivity,
"abc-1234-xyz",
"John Doe",
true,
true,
null,
null,
false,
null,
null
  )
)
```

---

**Java:**

```js title="initMeeting"

VideoSDK.initialize(getApplicationContext());

// Configure the token
VideoSDK.config(token);  // pass the token generated from VideoSDK Dashboard

// Initialize the meeting
Meeting meeting = VideoSDK.initMeeting({
  MainActivity.this,
  "abc-1234-xyz",
  "John Doe",
  true,
  true,
  null,
  null,
  false,
  null,
  null,
  null
});
```

</div>


---

# MediaEffects library - Android

<div id="tailwind" class="sdk-api-ref">

## Introduction

- The `MediaEffects` library enhances video applications with advanced media effects, including virtual backgrounds. It supports real-time processing and is optimized for Android devices.

- The `MediaEffects` library offers three classes to customize your video background: using a custom image, applying a blur effect, or choosing a solid color.

:::info

The Virtual Background feature in VideoSDK can be utilized regardless of the meeting environment, including the pre-call screen.

:::

## 1. BackgroundImageProcessor

- `BackgroundImageProcessor` sets a specified image as the background in a video stream, allowing you to customize the visual appearance of the video.
- `BackgroundImageProcessor` class provides following method.

  - `setBackgroundSource()` method updates the virtual background by setting a new image as the background that the user wants to switch to.
  
     - **Parameters**: `Uri`: An image URI for the background image.

     - **Return Type**: `void`
  


**Kotlin:**

```js
val uri = Uri.parse("https://st.depositphotos.com/2605379/52364/i/450/depositphotos_523648932-stock-photo-concrete-rooftop-night-city-view.jpg")
val backgroundImageProcessor = BackgroundImageProcessor(uri) // Sets the background image

val newUri = Uri.parse("https://img.freepik.com/free-photo/plant-against-blue-wall-mockup_53876-96052.jpg?size=626&ext=jpg&ga=GA1.1.2008272138.1723420800&semt=ais_hybrid")
backgroundImageProcessor.setBackgroundSource(newUri) // Changed background image
```

---

**Java:**

```java
Uri uri = Uri.parse("https://st.depositphotos.com/2605379/52364/i/450/depositphotos_523648932-stock-photo-concrete-rooftop-night-city-view.jpg");
BackgroundImageProcessor backgroundImageProcessor= new BackgroundImageProcessor(uri); // Sets the background image

Uri uri = Uri.parse("https://img.freepik.com/free-photo/plant-against-blue-wall-mockup_53876-96052.jpg?size=626&ext=jpg&ga=GA1.1.2008272138.1723420800&semt=ais_hybrid");
backgroundImageProcessor.setBackgroundSource(uri); //Changed background image
```


## 2. BackgroundBlurProcessor
- `BackgroundBlurProcessor` applies a blur effect to the video background, with the intensity controlled by a float value, creating a softened visual effect.
- `BackgroundBlurProcessor` class provides following method.

  - `setBlurRadius()` method adjusts the blur effect on the video background, with the blur strength controlled by the specified float value.
  

     - **Parameters**: `Float`: representing the blur strength; higher values mean stronger blur. The supported range is 0 to 25.

     - **Return Type**: `void`


**Kotlin:**

```js
val backgroundBlurProcessor = BackgroundBlurProcessor(25, this) // Applies a blur with intensity 25
backgroundBlurProcessor.setBlurRadius(17) // Changes the blur intensity to 17
```

---

**Java:**

```java
BackgroundBlurProcessor backgroundBlurProcessor = new BackgroundBlurProcessor(25, this);// Applies a blur with intensity 25
backgroundBlurProcessor.setBlurRadius(17); // changes the blur intensity to 17
```

## 3. BackgroundColorProcessor
- `BackgroundColorProcessor` sets a solid color as the video background using a `Color` object, enabling you to create a uniform color backdrop for your video.
- `BackgroundColorProcessor` class provides following method.

  - `setBackgroundColor()` method sets the color that user wants to switch to, for virtual background effect.

     - **Parameters**: `Integer`: Specifies the color for the virtual background.
     - **Return Type**: `void`

**Kotlin:**

```js
val backgroundColorProcessor = BackgroundColorProcessor(Color.BLUE) // Sets the background color to blue
backgroundColorProcessor.setBackgroundColor(Color.CYAN) // Changes the background color to CYAN
```

---

**Java:**

```java
BackgroundColorProcessor backgroundColorProcessor = new BackgroundColorProcessor(Color.BLUE);// Sets the background color to blue
backgroundColorProcessor.setBackgroundColor(Color.CYAN); // changed the background color to CYAN
```

</div>

---

# Video SDK Meeting Class - Android

<div class="sdk-api-ref">

## Introduction

The `Meeting` class includes properties, methods and meeting-event-listener-class for managing a meeting, participants, video, audio and share streams, messaging and UI customization.





## Meeting Properties

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [getmeetingId()](/android/api/sdk-reference/meeting-class/properties#getmeetingid)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getLocalParticipant()](./properties#getlocalparticipant)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getConnectionState()](./properties#getconnectionstate)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getParticipants()](./properties#getparticipants)

</div>
<div class="col col--4 margin-bottom--sm" >

- [pubSub](./properties#pubsub)

</div>
<div class="col col--4 margin-bottom--sm" >

- [LeaveReason Enum](./properties#leavereason-enum)

</div>

</div>

## Meeting Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [join()](./methods#join)

</div>
<div class="col col--4 margin-bottom--sm" >

- [leave()](./methods#leave)

</div>
<div class="col col--4 margin-bottom--sm" >

- [end()](./methods#end)

</div>
<div class="col col--4 margin-bottom--sm" >

- [enableWebcam()](./methods#enablewebcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disableWebcam()](./methods#disablewebcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [unmuteMic()](./methods#unmutemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [muteMic()](./methods#mutemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [enableScreenShare()](./methods#enablescreenshare)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disableScreenShare()](./methods#disablescreenshare)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startRecording()](./methods#startrecording)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopRecording()](./methods#stoprecording)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startLiveStream()](./methods#startlivestream)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopLiveStream()](./methods#stoplivestream)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startHls()](./methods#starthls)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopHls()](./methods#stophls)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startTranscription()](./methods#starttranscription)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopTranscription()](./methods#stoptranscription)

</div>
<div class="col col--4 margin-bottom--sm" >

- [changeMode()](./methods#changemode)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getMics()](./methods#getmics)

</div>
<div class="col col--4 margin-bottom--sm" >

- [changeMic()](./methods#changemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [setAudioDeviceChangeListener()](./methods#setaudiodevicechangelistener)

</div>
<div class="col col--4 margin-bottom--sm" >

- [changeWebcam()](./methods#changewebcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [uploadBase64File()](./methods#uploadbase64file)

</div>
<div class="col col--4 margin-bottom--sm" >

- [fetchBase64File()](./methods#fetchbase64file)

</div>
<div class="col col--4 margin-bottom--sm" >

- [addEventListener()](./methods#addeventlistener)

</div>
<div class="col col--4 margin-bottom--sm" >

- [removeEventListener()](./methods#removeeventlistener)

</div>
<div class="col col--4 margin-bottom--sm" >

- [removeAllListeners()](./methods#removealllisteners)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startWhiteboard()](./methods#startwhiteboard)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopWhiteboard()](./methods#stopwhiteboard)

</div>
<div class="col col--4 margin-bottom--sm" >

- [pauseAllStreams()](./methods#pauseallstreams)

</div>
<div class="col col--4 margin-bottom--sm" >

- [resumeAllStreams()](./methods#resumeallstreams)

</div>

<div class="col col--4 margin-bottom--sm" >

- [requestMediaRelay()](./methods#requestmediarelay)

</div>

<div class="col col--4 margin-bottom--sm" >

- [stopMediaRelay()](./methods#stopmediarelay)

</div>

<div class="col col--4 margin-bottom--sm" >

- [switchTo()](./methods#switchto)

</div>

</div>

## Meeting Events

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [onMeetingJoined](./meeting-event-listener-class#onmeetingjoined)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onMeetingLeft](./meeting-event-listener-class#onmeetingleft)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onParticipantJoined](./meeting-event-listener-class#onparticipantjoined)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onParticipantLeft](./meeting-event-listener-class#onparticipantleft)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onSpeakerChanged](./meeting-event-listener-class#onspeakerchanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onPresenterChanged](./meeting-event-listener-class#onpresenterchanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onEntryRequested](./meeting-event-listener-class#onentryrequested)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onEntryResponded](./meeting-event-listener-class#onentryresponded)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onWebcamRequested](./meeting-event-listener-class#onwebcamrequested)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onMicRequested](./meeting-event-listener-class#onmicrequested)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onRecordingStateChanged](./meeting-event-listener-class#onrecordingstatechanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onRecordingStarted](./meeting-event-listener-class#onrecordingstarted)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onRecordingStopped](./meeting-event-listener-class#onrecordingstopped)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onLivestreamStateChanged](./meeting-event-listener-class#onlivestreamstatechanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onLivestreamStarted](./meeting-event-listener-class#onlivestreamstarted)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onLivestreamStopped](./meeting-event-listener-class#onlivestreamstopped)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onHlsStateChanged](./meeting-event-listener-class#onhlsstatechanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onTranscriptionStateChanged](./meeting-event-listener-class#ontranscriptionstatechanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onTranscriptionText](./meeting-event-listener-class#ontranscriptiontext)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onExternalCallStarted](./meeting-event-listener-class#onexternalcallstarted)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onMeetingStateChanged](./meeting-event-listener-class#onmeetingstatechanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onParticipantModeChanged](./meeting-event-listener-class#onparticipantmodechanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onPinStateChanged()](./meeting-event-listener-class#onpinstatechanged)

</div>

<div class="col col--4 margin-bottom--sm" >

- [onWhiteboardStarted()](./meeting-event-listener-class#onwhiteboardstarted)

</div>

<div class="col col--4 margin-bottom--sm" >

- [onWhiteboardStopped()](./meeting-event-listener-class#onwhiteboardstopped)

</div>

<div class="col col--4 margin-bottom--sm" >

- [onExternalCallRinging()](./meeting-event-listener-class#onexternalcallringing)

</div>

<div class="col col--4 margin-bottom--sm" >

- [onExternalCallStarted()](./meeting-event-listener-class#onexternalcallstarted-1)

</div>

<div class="col col--4 margin-bottom--sm" >

- [onExternalCallHangup()](./meeting-event-listener-class#onexternalcallhangup)

</div>

<div class="col col--4 margin-bottom--sm" >

- [onPausedAllStreams()](./meeting-event-listener-class#onpausedallstreams)

</div>

<div class="col col--4 margin-bottom--sm" >

- [onResumedAllStreams()](./meeting-event-listener-class#onresumedallstreams)

</div>

<div class="col col--4 margin-bottom--sm" >

- [onMediaRelayRequestReceived()](./meeting-event-listener-class#onmediarelayrequestreceived)

</div>

<div class="col col--4 margin-bottom--sm" >

- [onMediaRelayRequestResponse()](./meeting-event-listener-class#onmediarelayrequestreceived)

</div>

<div class="col col--4 margin-bottom--sm" >

- [onMediaRelayStarted()](./meeting-event-listener-class#onmediarelaystarted)

</div>

<div class="col col--4 margin-bottom--sm" >

- [onMediaRelayStopped()](./meeting-event-listener-class#onmediarelaystopped)

</div>

<div class="col col--4 margin-bottom--sm" >

- [onMediaRelayError()](./meeting-event-listener-class#onmediarelayerror)

</div>




</div>

</div>


---

# MeetingEventListener Class - Android

<div class="sdk-api-ref-only-h4">

---

### implementation

- You can implement all the methods of `MeetingEventListener` abstract Class and add the listener to `Meeting` class using the `addEventListener()` method of `Meeting` Class.

#### Example



**Kotlin:**

```javascript
private val meetingEventListener = object : MeetingEventListener() {
  override fun onMeetingJoined() {
Log.d("#meeting", "onMeetingJoined()")
  }
}
```

---

**Java:**

```javascript
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onMeetingJoined() {
Log.d("#meeting", "onMeetingJoined()");
  }
}
```

---

### onMeetingJoined()

- This event will be emitted when a [localParticipant](./properties#getlocalparticipant) successfully joined the meeting.

#### Example

**Kotlin:**

```javascript
 override fun onMeetingJoined() {
Log.d("#meeting", "onMeetingJoined()")
 }
```

---

**Java:**

```javascript
 @Override
 public void onMeetingJoined() {
 Log.d("#meeting", "onMeetingJoined()");
 }
```

---

### onMeetingLeft()

- This event will be emitted when a [localParticipant](./properties#getlocalparticipant) left the meeting.
- For more context on why the participant left, use the overloaded `onMeetingLeft(LeaveReason reason)` method.

#### Example

**Kotlin:**

```javascript
 override fun onMeetingLeft() {
Log.d("#meeting", "onMeetingLeft()")
 }
```

---

**Java:**

```javascript
 @Override
 public void onMeetingLeft() {
Log.d("#meeting", "onMeetingLeft()");
 }
```

---

### onMeetingLeft(LeaveReason reason)

- This event is an overload for `onMeetingLeft()` and provides the specific reason why the local participant left the meeting.

#### Event callback parameters

- **reason**: `LeaveReason` - The reason why the participant left. See [LeaveReasons Enum](./properties#leavereason-enum) for all possible values.

#### Example

**Kotlin:**

```javascript
 override fun onMeetingLeft(reason: LeaveReason) {
Log.d("#meeting", "onMeetingLeft() :: reason: ${reason.message}")
 }
```

---

**Java:**

```javascript
 @Override
 public void onMeetingLeft(LeaveReason reason) {
Log.d("#meeting", "onMeetingLeft() :: reason: " + reason.getMessage());
 }
```

---

### onParticipantJoined()

- This event will be emitted when a new [participant](../participant-class/introduction) joined the meeting.

#### Event callback parameters

- **participant**: [Participant](../participant-class/introduction)

#### Example

**Kotlin:**

```javascript
 override fun onParticipantJoined(participant: Participant) {
Log.d("#meeting", participant.displayName + " joined");
 }
```

---

**Java:**

```javascript
 @Override
 public void onParticipantJoined(Participant participant) {
Log.d("#meeting", participant.getDisplayName() + " joined");
 }
```

---

### onParticipantLeft(Participant participant)

- This event will be emitted when a joined [participant](../participant-class/introduction) left the meeting.
- For more context on why the participant left, use the overloaded `onParticipantLeft(Participant participant, LeaveReason reason)` method.

#### Event callback parameters

- **participant**: [Participant](../participant-class/introduction)

#### Example

**Kotlin:**

```javascript
 override fun onParticipantLeft(participant: Participant) {
Log.d("#meeting", participant.displayName + " left");
 }
```

---

**Java:**

```javascript
 @Override
 public void onParticipantLeft(Participant participant) {
Log.d("#meeting", participant.getDisplayName() + " left");
 }
```

---

### onParticipantLeft(Participant participant, LeaveReason reason)

- This event is an overload for `onParticipantLeft()` and provides the specific reason why a remote participant left the meeting.

#### Event callback parameters

- **participant**: [Participant](../participant-class/introduction)
- **reason**: `LeaveReason` - The reason why the participant left. See [LeaveReasons Enum](./properties#leavereason-enum) for all possible values.

#### Example

**Kotlin:**

```javascript
 override fun onParticipantLeft(participant: Participant, reason: LeaveReason) {
Log.d("#meeting", "${participant.displayName} left :: reason: ${reason.message}")
 }
```

---

**Java:**

```javascript
 @Override
 public void onParticipantLeft(Participant participant, LeaveReason reason) {
Log.d("#meeting", participant.getDisplayName() + " left :: reason: " + reason.getMessage());
 }
```

---

### onSpeakerChanged()

- This event will be emitted when a active speaker changed.
- If you want to know which participant is actively speaking, then this event will be used.
- If no participant is actively speaking, then this event will pass `null` as en event callback parameter.

#### Event callback parameters

- **participantId**: String

#### Example

**Kotlin:**

```javascript
 override fun onSpeakerChanged(participantId: String?) {
  //
 }
```

---

**Java:**

```javascript
 @Override
 public void onSpeakerChanged(String participantId) {
  //
 }
```

---

### onPresenterChanged()

- This event will be emitted when any [participant](../participant-class/introduction) starts or stops screen sharing.
- It will pass `participantId` as an event callback parameter.
- If a participant stops screensharing, then this event will pass `null` as en event callback parameter.

#### Event callback parameters

- **participantId**: String

#### Example

**Kotlin:**

```javascript
 override fun onPresenterChanged(participantId: String) {
  //
 }
```

---

**Java:**

```javascript
 @Override
 public void onPresenterChanged(String participantId) {
  //
 }
```

---

### onEntryRequested()

- This event will be emitted when a new [participant](../participant-class/introduction) who is trying to join the meeting, is having permission **`ask_join`** in token.
- This event will only be emitted to the [participants](./properties#getparticipants) in the meeting, who is having the permission **`allow_join`** in token.
- This event will pass following parameters as an event parameters, `participantId` and `name` of the new participant who is trying to join the meeting, `allow()` and `deny()` to take required actions.

#### Event callback parameters

- **peerId**: String
- **name**: String

#### Example

**Kotlin:**

```javascript
 override fun onEntryRequested(id: String?, name: String?) {
//
}
```

---

**Java:**

```javascript
 @Override
 public void onEntryRequested(String id, String name) {
//
}
```

---

### onEntryResponded()

- This event will be emitted when the `join()` request is responded.
- This event will be emitted to the [participants](./properties#getparticipants) in the meeting, who is having the permission **`allow_join`** in token.
- This event will be also emitted to the [participant](../participant-class/introduction) who requested to join the meeting.

#### Event callback parameters

- **participantId**: _String_
- **decision**: _"allowed"_ | _"denied"_

#### Example

**Kotlin:**

```javascript
 override fun onEntryResponded(id: String?, decision: String?) {
//
  }
```

---

**Java:**

```javascript
 @Override
 public void onEntryResponded(String id, String decision) {
//
  }
```

---

### onWebcamRequested()

- This event will be emitted to the participant `B` when any other participant `A` requests to enable webcam of participant `B`.
- On accepting the request, webcam of participant `B` will be enabled.

#### Event callback parameters

- **participantId**: String
- **listener**: WebcamRequestListener \{ **accept**: Method; **reject**: Method }

#### Example

**Kotlin:**

```javascript
  override fun onWebcamRequested(participantId: String, listener: WebcamRequestListener) {
 // if accept request
 listener.accept()

 // if reject request
 listener.reject()
 }
```

---

**Java:**

```javascript
  @Override
 public void onWebcamRequested(String participantId, WebcamRequestListener listener) {
 // if accept request
 listener.accept();

 // if reject request
 listener.reject();
 }
```

### onMicRequested()

- This event will be emitted to the participant `B` when any other participant `A` requests to enable mic of participant `B`.
- On accepting the request, mic of participant `B` will be enabled.

#### Event callback parameters

- **participantId**: String
- **listener**: MicRequestListener \{ **accept**: Method; **reject**: Method }

#### Example

**Kotlin:**

```javascript
 override fun onMicRequested(participantId: String, listener: MicRequestListener) {
 // if accept request
 listener.accept()

 // if reject request
 listener.reject()
 }
```

---

**Java:**

```javascript
 @Override
 public void onMicRequested(String participantId, MicRequestListener listener) {
 // if accept request
 listener.accept();

 // if reject request
 listener.reject();
 }
```

---

### onRecordingStateChanged()

- This event will be emitted when the meeting's recording status changed.

#### Event callback parameters

- **recordingState**: String

`recordingState` has following values

- `RECORDING_STARTING` - Recording is in starting phase and hasn't started yet.
- `RECORDING_STARTED` - Recording has started successfully.
- `RECORDING_STOPPING` - Recording is in stopping phase and hasn't stopped yet.
- `RECORDING_STOPPED` - Recording has stopped successfully.

#### Example

**Kotlin:**

```javascript
  override fun onRecordingStateChanged(recordingState: String) {
when (recordingState) {
    "RECORDING_STARTING" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is starting")
    }
    "RECORDING_STARTED" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is started")
    }
    "RECORDING_STOPPING" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is stopping")
    }
    "RECORDING_STOPPED" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is stopped")
    }
}
  }
```

---

**Java:**

```javascript
  @Override
  public void onRecordingStateChanged(String recordingState) {
  switch (recordingState) {
      case "RECORDING_STARTING":
          Log.d("onRecordingStateChanged", "Meeting recording is starting");
          break;
      case "RECORDING_STARTED":
          Log.d("onRecordingStateChanged", "Meeting recording is started");
          break;
      case "RECORDING_STOPPING":
          Log.d("onRecordingStateChanged", "Meeting recording is stopping");
          break;
      case "RECORDING_STOPPED":
          Log.d("onRecordingStateChanged", "Meeting recording is stopped");
          break;
  }
  }
```

---

### onRecordingStarted()

_`This event will be deprecated soon`_

- This event will be emitted when recording of the meeting is started.

#### Example

**Kotlin:**

```javascript
 override fun onRecordingStarted() {
   //
 }
```

---

**Java:**

```javascript
 @Override
 public void onRecordingStarted() {
   //
 }
```

---

### onRecordingStopped()

_`This event will be deprecated soon`_

- This event will be emitted when recording of the meeting is stopped.

#### Example

**Kotlin:**

```javascript
 override fun onRecordingStopped() {
   //
 }
```

---

**Java:**

```javascript
 @Override
 public void onRecordingStopped() {
   //
 }
```

---

### onLivestreamStateChanged()

- This event will be emitted when the meeting's livestream status changed.

#### Event callback parameters

- **livestreamState**: String

`livestreamState` has following values

- `LIVESTREAM_STARTING` - Livestream is in starting phase and hasn't started yet.
- `LIVESTREAM_STARTED` - Livestream has started successfully.
- `LIVESTREAM_STOPPING` - Livestream is in stopping phase and hasn't stopped yet.
- `LIVESTREAM_STOPPED` - Livestream has stopped successfully.

#### Example

**Kotlin:**

```javascript
  override fun onLivestreamStateChanged(livestreamState: String?) {
when (livestreamState) {
    "LIVESTREAM_STARTING" -> Log.d( "LivestreamStateChanged",
        "Meeting livestream is starting"
    )
    "LIVESTREAM_STARTED" -> Log.d( "LivestreamStateChanged",
        "Meeting livestream is started"
    )
    "LIVESTREAM_STOPPING" -> Log.d("LivestreamStateChanged",
        "Meeting livestream is stopping"
    )
    "LIVESTREAM_STOPPED" -> Log.d("LivestreamStateChanged",
        "Meeting livestream is stopped"
    )
}
  }
```

---

**Java:**

```javascript
  @Override
  public void onLivestreamStateChanged(String livestreamState) {
  switch (livestreamState) {
      case "LIVESTREAM_STARTING":
          Log.d("LivestreamStateChanged", "Meeting livestream is starting");
          break;
      case "LIVESTREAM_STARTED":
          Log.d("LivestreamStateChanged", "Meeting livestream is started");
          break;
      case "LIVESTREAM_STOPPING":
          Log.d("LivestreamStateChanged", "Meeting livestream is stopping");
          break;
      case "LIVESTREAM_STOPPED":
          Log.d("LivestreamStateChanged", "Meeting livestream is stopped");
          break;
  }
  }
```

---

### onLivestreamStarted()

_`This event will be deprecated soon`_

- This event will be emitted when `RTMP` live stream of the meeting is started.

#### Example

**Kotlin:**

```javascript
 override fun onLivestreamStarted() {
   //
 }
```

---

**Java:**

```javascript
 @Override
 public void onLivestreamStarted() {
   //
 }
```

---

### onLivestreamStopped()

_`This event will be deprecated soon`_

- This event will be emitted when `RTMP` live stream of the meeting is stopped.

#### Example

**Kotlin:**

```javascript
 override fun onLivestreamStopped() {
   //
 }
```

---

**Java:**

```javascript
 @Override
 public void onLivestreamStopped() {
   //
 }
```

---

### onHlsStateChanged()

- This event will be emitted when the meeting's HLS(Http Livestreaming) status changed.

#### Event callback parameters

- **HlsState**: \{ **status**: String}

  - `status` has following values :
    - `HLS_STARTING` - HLS is in starting phase and hasn't started yet.
    - `HLS_STARTED` - HLS has started successfully.
    - `HLS_PLAYABLE` - HLS can be playable now.
    - `HLS_STOPPING` - HLS is in stopping phase and hasn't stopped yet.
    - `HLS_STOPPED` - HLS has stopped successfully.

- when you receive `HLS_PLAYABLE` status you will receive 2 urls in response
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

#### Example

**Kotlin:**

```javascript
  override fun onHlsStateChanged(HlsState: JSONObject) {
when (HlsState.getString("status")) {
    "HLS_STARTING" -> Log.d("onHlsStateChanged", "Meeting hls is starting")
    "HLS_STARTED" -> Log.d("onHlsStateChanged", "Meeting hls is started")
    "HLS_PLAYABLE" -> {
        Log.d("onHlsStateChanged", "Meeting hls is playable now")
        // on hls playable you will receive playbackHlsUrl and livestreamUrl
        val playbackHlsUrl = HlsState.getString("playbackHlsUrl")
        val livestreamUrl = HlsState.getString("livestreamUrl")

    }
    "HLS_STOPPING" -> Log.d("onHlsStateChanged", "Meeting hls is stopping")
    "HLS_STOPPED" -> Log.d("onHlsStateChanged", "Meeting hls is stopped")
}
  }
```

---

**Java:**

```javascript
  @Override
  public void onHlsStateChanged(JSONObject HlsState) {
  switch (HlsState.getString("status")) {
      case "HLS_STARTING":
          Log.d("onHlsStateChanged", "Meeting hls is starting");
          break;
      case "HLS_STARTED":
          Log.d("onHlsStateChanged", "Meeting hls is started");
          break;
      case "HLS_PLAYABLE":
          Log.d("onHlsStateChanged", "Meeting hls is playable now");
          // on hls started you will receive playbackHlsUrl and livestreamUrl
          String playbackHlsUrl = HlsState.getString("playbackHlsUrl");
          String livestreamUrl = HlsState.getString("livestreamUrl");
          break;
      case "HLS_STOPPING":
          Log.d("onHlsStateChanged", "Meeting hls is stopping");
          break;
      case "HLS_STOPPED":
          Log.d("onHlsStateChanged", "Meeting hls is stopped");
          break;
  }
  }
```

---

### onTranscriptionStateChanged()

- This event will be triggered whenever state of realtime transcription is changed.

#### Event callback parameters

- **data**: \{ **status**: String, **id**: String }
  - **status**: String
  - **id**: String

`status` has following values

- `TRANSCRIPTION_STARTING` - Realtime Transcription is in starting phase and hasn't started yet.
- `TRANSCRIPTION_STARTED` - Realtime Transcription has started successfully.
- `TRANSCRIPTION_STOPPING` - Realtime Transcription is in stopping phase and hasn't stopped yet.
- `TRANSCRIPTION_STOPPED` - Realtime Transcription has stopped successfully.

#### Example

**Kotlin:**

```javascript
override fun onTranscriptionStateChanged(data: JSONObject) {
  //Status can be :: TRANSCRIPTION_STARTING
  //Status can be :: TRANSCRIPTION_STARTED
  //Status can be :: TRANSCRIPTION_STOPPING
  //Status can be :: TRANSCRIPTION_STOPPED
  val status = data.getString("status")
  Log.d("MeetingActivity", "Transcription status: $status")
}
```

---

**Java:**

```javascript
@Override
public void onTranscriptionStateChanged(JSONObject data) {
  //Status can be :: TRANSCRIPTION_STARTING
  //Status can be :: TRANSCRIPTION_STARTED
  //Status can be :: TRANSCRIPTION_STOPPING
  //Status can be :: TRANSCRIPTION_STOPPED
  String status = data.getString("status");
  Log.d("MeetingActivity", "Transcription status: " + status);
}
```

---

### onTranscriptionText()

- This event will be emitted when text for running realtime transcription received.

#### Event callback parameters

- **data**: TranscriptionText
  - **TranscriptionText.participantId**: String
  - **TranscriptionText.participantName**: String
  - **TranscriptionText.text**: String
  - **TranscriptionText.timestamp**: int
  - **TranscriptionText.type**: String

#### Example

**Kotlin:**

```javascript
override fun onTranscriptionText(data: TranscriptionText) {
  val participantId = data.participantId
  val participantName = data.participantName
  val text = data.text
  val timestamp = data.timestamp
  val type = data.type

  Log.d("MeetingActivity", "$participantName: $text $timestamp")
}
```

---

**Java:**

```javascript
@Override
public void onTranscriptionText(TranscriptionText data) {
  String participantId = data.getParticipantId();
  String participantName = data.getParticipantName();
  String text = data.getText();
  int timestamp = data.getTimestamp();
  String type = data.getType();

  Log.d("MeetingActivity", participantName + ": " + text + " " + timestamp);
}
```

---

### onWhiteboardStarted()

- This event will be triggered when the whiteboard is successfully started.

#### Event callback parameters

**url**: String

#### Example

**Kotlin:**

```javascript
override fun onWhiteboardStarted(url: String) {
super.onWhiteboardStarted(url)
//...
}
```

---

**Java:**

```java
@Override
public void onWhiteboardStarted(String url) {
  super.onWhiteboardStarted(url);
  //...
}
```

---

### onWhiteboardStopped()

- This event will be triggered when the whiteboard session is successfully terminated.

#### Example

**Kotlin:**

```javascript
override fun onWhiteboardStopped() {
super.onWhiteboardStopped()
//...
}
```

---

**Java:**

```java
@Override
public void onWhiteboardStopped() {
  super.onWhiteboardStopped();
  //...
}
```

---

### onExternalCallStarted()

- This event will be emitted when local particpant receive incoming call.

#### Example

**Kotlin:**

```javascript
 override fun onExternalCallStarted() {
   //
 }
```

---

**Java:**

```javascript
 @Override
 public void onExternalCallStarted() {
   //
 }
```

---

### onMeetingStateChanged()

- This event will be emitted when state of meeting changes.
- It will pass **`state`** as an event callback parameter which will indicate current state of the meeting.
- All available states are `CONNECTING`, `CONNECTED`, `RECONNECTING`, `DISCONNECTED`.

#### Event callback parameters

- **state**: MeetingState

#### Example

**Kotlin:**

```javascript
override fun onMeetingStateChanged(state: ConnectionState) {
super.onMeetingStateChanged(state)
Log.d("TAG", "onMeetingStateChanged: $state")
}
```

---

**Java:**

```javascript
@Override
public void onMeetingStateChanged(ConnectionState state) {
super.onMeetingStateChanged(state);
Log.d("TAG", "onMeetingStateChanged: "+ state);
}
```

---


### onExternalCallRinging()

This callback is triggered when the user's phone starts ringing. whether it’s a traditional phone call or a VoIP call (e.g., WhatsApp).

This event allows us to detect when the user is receiving an external call.
#### Example

**Kotlin:**

```javascript
override fun onExternalCallRinging() {
Log.d("#meeting", "onExternalCallAnswered: User phone is ringing")
}

```

---

**Java:**

```javascript
@Override
public void onExternalCallRinging() {
Log.d("#meeting", "onExternalCallAnswered: User phone is ringing");
}
```

---

### onExternalCallStarted()

This callback is triggered when the user answers an external phone call. whether it’s a traditional phone call or a VoIP call (e.g., WhatsApp).


This event allows us to detect when the user has started a call.

#### Example

**Kotlin:**

```javascript
override fun onExternalCallStarted() {
Log.d("#meeting", "onExternalCallAnswered: User call is answered")
}
```

---

**Java:**

```javascript
@Override
public void onExternalCallStarted() {
Log.d("#meeting", "onExternalCallAnswered: User call is answered");
}
```

---

### onExternalCallHangup()

This callback is triggered when an external call ends, whether it’s a traditional phone call or a VoIP call (e.g., WhatsApp).

This event detects when a call has ended

#### Example

**Kotlin:**

```javascript
override fun onExternalCallHangup() {
Log.d("#meeting", "onExternalCallAnswered: User call ends")
}
```

---

**Java:**

```javascript
@Override
public void onExternalCallHangup() {
Log.d("#meeting", "onExternalCallAnswered: User call ends");
}
```

---

### onPausedAllStreams()

- This callback is triggered when all or specified media streams within the meeting are successfully paused


#### Parameters

- **`kind`**: Specifies the type of media stream that was paused.
  - **Type**: `String`
  - **Possible values**:
    - `"audio"`: Indicates that audio streams have been paused.
    - `"video"`: Indicates that video streams have been paused.
    - `"share"`: Indicates that screen-sharing video streams have been paused

#### Example

**Kotlin:**

```javascript
override fun onPausedAllStreams(kind: String) {
Log.d("TAG", "onPausedAllStreams: $kind")
super.onPausedAllStreams(kind)
}
```

---

**Java:**

```javascript
@Override
public void onPausedAllStreams(String kind) {
Log.d("TAG", "onPausedAllStreams: " + kind);
super.onPausedAllStreams(kind);
}
```

---

### onResumedAllStreams()

- This callback is triggered when all or specified media streams within the meeting are successfully resumed


#### Parameters

- **`kind`**: Specifies the type of media stream that was resumed.
  - **Type**: `String`
  - **Possible values**:
    - `"audio"`: Indicates that audio streams have been resumed.
    - `"video"`: Indicates that video streams have been resumed.
    - `"share"`: Indicates that screen-sharing video streams have been resumed


#### Example

**Kotlin:**

```javascript
override fun onResumedAllStreams(kind: String) {
Log.d("TAG", "onResumedAllStreams: $kind")
super.onResumedAllStreams(kind)
}
```

---

**Java:**

```javascript
@Override
public void onResumedAllStreams(String kind) {
Log.d("TAG", "onResumedAllStreams: " + kind);
super.onResumedAllStreams(kind);
}
```

---


### onParticipantModeChanged()

This event is triggered when a participant's mode is updated.

It passes `data` as an event callback parameter, which includes the following:

- **`SEND_AND_RECV`**: Both audio and video streams will be produced and consumed.

- **`SIGNALLING_ONLY`**: Audio and video streams will not be produced or consumed. It is used solely for signaling.

- **`RECV_ONLY`**: Only audio and video streams will be consumed without producing any.
  This event is triggered when a participant's mode is updated.

#### Event Callback Parameters

- **data**: `{ mode: String, participantId: String }`
  - **mode**: `String`
  - **participantId**: `String`





#### Example

**Kotlin:**

```javascript
 override fun onParticipantModeChanged(data: JSONObject?) {
   //...
  }
```

---

**Java:**

```javascript
@Override
  public void onParticipantModeChanged(JSONObject data) {
//...
  }

```

---

### onPinStateChanged()

- This event will be triggered when any participant got pinned or unpinned by any participant got pinned or unpinned by any participant.

#### Event callback parameters

- **pinStateData**: \{ **peerId**: String, **state**: JSONObject, **pinnedBy**: String }
  - **peerId**: String
  - **state**: JSONObject
  - **pinnedBy**: String

#### Example

**Kotlin:**

```javascript
 override fun onPinStateChanged(pinStateData: JSONObject?) {
   Log.d("onPinStateChanged: ", pinStateData.getString("peerId")) // id of participant who were pinned
   Log.d("onPinStateChanged: ", pinStateData.getJSONObject("state")) // { cam: true, share: true }
   Log.d("onPinStateChanged: ", pinStateData.getString("pinnedBy")) // id of participant who pinned that participant
  }
```

---

**Java:**

```javascript
@Override
  public void onPinStateChanged(JSONObject pinStateData) {
Log.d("onPinStateChanged: ", pinStateData.getString("peerId")); // id of participant who were pinned
Log.d("onPinStateChanged: ", pinStateData.getJSONObject("state")); // { cam: true, share: true }
Log.d("onPinStateChanged: ", pinStateData.getString("pinnedBy")); // id of participant who pinned that participant
  }

```

---

### onMediaRelayRequestReceived()

- This callback is triggered when a request is recieved for media relay in the destination meeting.


#### Event callback parameters

- **`participantId - (String)`**: Specifies the participantId who requested the media relay.

- **`meetingId - (String)`**: Specifies the meeting from where the media relay request was made.

- **`listener - (RelayRequestListener)`**: A callback interface with the following methods:
  - **accept()**: Call this to approve the media relay request.
  - **reject()**:  Call this to deny the media relay request.



#### Example

**Kotlin:**

```javascript
override fun onMediaRelayRequestReceived(participantId: String,liveStreamId: String,listener: RelayRequestListener) {
// If accepting the request
listener.accept()

// If rejecting the request
listener.reject()
}
```

---

**Java:**

```javascript
@Override
public void onMediaRelayRequestReceived(String participantId, String liveStreamId, RelayRequestListener listener) {
 // if accept request
 listener.accept();

 // if reject request
 listener.reject();
}
```

---

### onMediaRelayRequestResponse()

- This callback is triggered when a response is recieved for media relay request in the source meeting.


#### Event callback parameters

- **`participantId - (String)`**: Specifies the participantId who responded the request for the media relay.

- **`decision - (String)`**: Specifies the decision whether the request for media relay was accepted or not.


#### Example

**Kotlin:**

```javascript
override fun onMediaRelayRequestResponse(participantId: String, decision: String) {
super.onMediaRelayRequestResponse(participantId, decision)

Log.d("MediaRelay", "Participant ID: $participantId, Decision: $decision")
}
```

---

**Java:**

```javascript
@Override
public void onMediaRelayRequestResponse(String participantId, String decision) {
super.onMediaRelayRequestResponse(participantId, decision);

Log.d("MediaRelay", "Participant ID: " + participantId + ", Decision: " + decision);
}
```

---

### onMediaRelayStarted()

- This callback is triggered when the media relay to the destination meeting succesfully starts.


#### Parameters

- **`meetingId - (String)`**: Specifies the meeting where the media relay started.

#### Example

**Kotlin:**

```javascript
override fun onMediaRelayStarted(relayMeetingId: String) {
super.onMediaRelayStarted(relayMeetingId)
Log.d("MediaRelay", "Media relay started to meeting ID: $relayMeetingId")
}
```

---

**Java:**

```javascript
override fun onMediaRelayStarted(relayMeetingId: String) {
super.onMediaRelayStarted(relayMeetingId)

Log.d("MediaRelay", "Media relay started to meeting ID: $relayMeetingId")
}
```

---

### onMediaRelayStopped()

- This callback is triggered when the media relay to the destination meeting stops for any reason.


#### Parameters

- **`meetingId - (String)`**: Specifies the meeting where the media relay stopped.

- **`reason - (String)`**: Specifies the reason why the media relay stopped

#### Example

**Kotlin:**

```javascript
override fun onMediaRelayStopped(meetingId: String, reason: String) {
super.onMediaRelayStopped(meetingId, reason)
Log.d("MediaRelay", "Media relay stopped for meeting ID: $meetingId, Reason: $reason")
}
```

---

**Java:**

```javascript
@Override
public void onMediaRelayStopped(String meetingId, String reason) {
super.onMediaRelayStopped(meetingId, reason);
Log.d("MediaRelay", "Media relay stopped for meeting ID: " + meetingId + ", Reason: " + reason);
}
```

---

### onMediaRelayError()

- This callback is triggered when an error occurs during media relay to the destination meeting.


#### Parameters

- **`meetingId - (String)`**: Specifies the meeting where the media relay stopped.

- **`error - (String)`**: Specifies the error that occured.

#### Example

**Kotlin:**

```javascript
override fun onMediaRelayError(meetingId: String, error: String) {
super.onMediaRelayError(meetingId, error)
Log.e("MediaRelay", "Media relay error for meeting ID: $meetingId, Error: $error")
}
```

---

**Java:**

```javascript
@Override
public void onMediaRelayError(String meetingId, String error) {
super.onMediaRelayError(meetingId, error);
Log.e("MediaRelay", "Media relay error for meeting ID: " + meetingId + ", Error: " + error);
}
```

---




</div>


---

# Meeting Class Methods - Android

<div class="sdk-api-ref-only-h4">

### join()

- It is used to join a meeting.
- After meeting initialization by [`initMeeting()`](../initMeeting) it returns a new instance of [Meeting](./introduction). However by default, it will not automatically join the meeting. Hence, to join the meeting you should call `join()`.

#### Events associated with `join()`:

- Local Participant will receive a [`onMeetingJoined`](./meeting-event-listener-class#onmeetingjoined) event, when successfully joined.
- Remote Participant will receive a [`onParticipantJoined`](./meeting-event-listener-class#onparticipantjoined) event with the newly joined [`Participant`](../participant-class/introduction) object from the event callback.

#### Participant having `ask_join` permission inside token

- If a token contains the permission `ask_join`, then the participant will not join the meeting directly after calling `join()`, but an event will be emitted to the participant having the permission `allow_join` called [`onEntryRequested`](./meeting-event-listener-class#onentryrequested).

- After the decision from the remote participant, an event will be emitted to participant called [`onEntryResponded`](./meeting-event-listener-class#onentryresponded). This event will contain the decision made by the remote participant.

#### Participant having `allow_join` permission inside token

- If a token containing the permission `allow_join`, then the participant will join the meeting directly after calling `join()`.

#### Returns

- _`void`_

---

### leave()

- It is used to leave the current meeting.

#### Events associated with `leave()`:

- Local participant will receive a [`onMeetingLeft`](./meeting-event-listener-class#onmeetingleft) event.
- All remote participants will receive a [`onParticipantLeft`](./meeting-event-listener-class#onparticipantleft) event with `participantId`.

#### Returns

- _`void`_

---

### end()

- It is used to end the current running session.
- By calling `end()`, all joined [participants](properties#getparticipants) including [localParticipant](./properties.md#getlocalparticipant) of that session will leave the meeting.

#### Events associated with `end()`:

- All [participants](./properties.md#getparticipants) and [localParticipant](./properties.md#getlocalparticipant), will be emitted [`onMeetingLeft`](./meeting-event-listener-class#onmeetingleft) event.

#### Returns

- _`void`_

---

### enableWebcam()

- It is used to enable self camera.
- [`onStreamEnabled`](../participant-class/participant-event-listener-class#onstreamenabled) event of `ParticipantEventListener` will be emitted with [`stream`](../stream-class/introduction) object from the event callback.

#### Returns

- _`void`_

---

### disableWebcam()

- It is used to disable self camera.
- [`onStreamDisabled`](../participant-class/participant-event-listener-class#onstreamdisabled) event of `ParticipantEventListener` will be emitted with [`stream`](../stream-class/introduction) object from the event callback.

#### Returns

- _`void`_

---

### unmuteMic()

- It is used to enable self microphone.
- [`onStreamEnabled`](../participant-class/participant-event-listener-class#onstreamenabled) event of `ParticipantEventListener` will be emitted with [`stream`](../stream-class/introduction) object from the event callback.

#### Returns

- _`void`_

---

### muteMic()

- It is used to disable self microphone.
- [`onStreamDisabled`](../participant-class/participant-event-listener-class#onstreamdisabled) event of `ParticipantEventListener` will be emitted with [`stream`](../stream-class/introduction) object from the event callback.

#### Returns

- _`void`_

---

### enableScreenShare()

- it is used to enable screen-sharing.

- [`onStreamEnabled`](../participant-class/participant-event-listener-class#onstreamenabled) event of `ParticipantEventListener` will be emitted with [`stream`](../stream-class/introduction) object from the event callback.

- [`onPresenterChanged()`](./meeting-event-listener-class#onpresenterchanged) event will be trigget to all participant with `participantId`.

#### Parameters

- **data**: Intent

#### Returns

- _`void`_

---

### disableScreenShare()

- It is used to disable screen-sharing.

- [`onStreamDisabled`](../participant-class/participant-event-listener-class#onstreamdisabled) event of `ParticipantEventListener` will be emitted with [`stream`](../stream-class/introduction) object from the event callback.

- [`onPresenterChanged()`](./meeting-event-listener-class#onpresenterchanged) event will be trigget to all participant with `null`.

#### Returns

- _`void`_

---

### uploadBase64File()

- It is used to upload your file to Videosdk's Temporary storage.

- `base64Data` convert your file to base64 and pass here.
- `token` pass your videosdk token. Read more about token [here](/android/guide/video-and-audio-calling-api-sdk/authentication-and-token)
- `fileName` provide your fileName with extension.
- `TaskCompletionListener` will handle the result of the upload operation.

  - When the upload is complete, the `onComplete()` method of `TaskCompletionListener` will provide the corresponding `fileUrl`, which can be used to retrieve the uploaded file.

  - If an error occurs during the upload process, the `onError()` method of `TaskCompletionListener` will provide the error details.

#### Parameters

- **base64Data**: String
- **token**: String
- **fileName**: String
- **listener**: TaskCompletionListener

#### Returns

- _`void`_

#### Example



**Kotlin:**

```js
private fun uploadFile() {
  val base64Data = "

#### Parameters

- **mode**: `String`
- **mode**: `String`

#### Returns

- _`void`_

#### Events associated with `changeMode()`:

- Every participant will receive a callback on [`onParticipantModeChanged()`](./meeting-event-listener-class#onparticipantmodechanged)

**Kotlin:**

```javascript
meeting!!.changeMode("SIGNALLING_ONLY")
meeting!!.changeMode("SIGNALLING_ONLY")
```

---

**Java:**

```javascript
meeting!!.changeMode("SIGNALLING_ONLY")
meeting!!.changeMode("SIGNALLING_ONLY")
```

---

### getMics()

- It will return all connected mic devices.

#### Returns

- `Set<AppRTCAudioManager.AudioDevice>`

#### Example

**Kotlin:**

```javascript
val mics = meeting!!.mics
var mic: String
for (i in mics.indices) {
  mic = mics.toTypedArray()[i].toString()
  Toast.makeText(this, "Mic : $mic", Toast.LENGTH_SHORT).show()
}
```

---

**Java:**

```javascript
Set<AppRTCAudioManager.AudioDevice> mics = meeting.getMics();
String mic;
for (int i = 0; i < mics.size(); i++) {
mic=mics.toArray()[i].toString();
Toast.makeText(this, "Mic : " + mic, Toast.LENGTH_SHORT).show();
}
```

---

### changeMic()

- It is used to change the mic device.
- If multiple mic devices are connected, by using `changeMic()` one can change the mic device.

#### Parameters

- **device**: AppRTCAudioManager.AudioDevice

#### Returns

- _`void`_

#### Example

**Kotlin:**

```javascript
meeting!!.changeMic(AppRTCAudioManager.AudioDevice.BLUETOOTH)
```

---

**Java:**

```javascript
meeting.changeMic(AppRTCAudioManager.AudioDevice.BLUETOOTH);
```

---

### changeWebcam()

- It is used to change the camera device.
- If multiple camera devices are connected, by using `changeWebcam()`, one can change the camera device with its respective device id.
- You can get a list of connected video devices using [`VideoSDK.getVideoDevices()`](../videosdk-class/methods#getvideodevices)

#### Parameters

- **deviceId**:

  - The `deviceId` represents the unique identifier of the camera device you wish to switch to. If no deviceId is provided, the facing mode will toggle, from the back camera to the front camera if the back camera is currently in use, or from the front camera to the back camera if the front camera is currently in use.

    - type : String
    - `OPTIONAL`

#### Returns

- _`void`_

#### Example

**Kotlin:**

```javascript
meeting!!.changeWebcam()
```

---

**Java:**

```javascript
meeting.changeWebcam();
```

---

### pauseAllStreams()

This method pauses active media streams within the meeting.

#### Parameters

- **kind**:  Specifies the type of media stream to be paused. If this parameter is omitted, all media streams (audio, video, and screen share) will be paused.

  - **Type**: `String`  
  - **Optional**: Yes

    - Possible values:
    - `"audio"`: Pauses audio streams.
    - `"video"`: Pauses video streams.
    - `"share"`: Pauses screen-sharing video streams.
  
#### Returns

- _`void`_

#### Example

**Kotlin:**

```javascript
meeting!!.pauseAllStreams()
```

---

**Java:**

```javascript
meeting.pauseAllStreams();
```
---


### resumeAllStreams()

This method resumes media streams that have been paused

#### Parameters

- **kind**:  Specifies the type of media stream to be resumed. If this parameter is omitted, all media streams (audio, video, and screen share) will be resumed.
  
  - **Type**: `String`  
  - **Optional**: Yes

    - Possible values:
    - `"audio"`: Resumes audio streams.
    - `"video"`: Resumes video streams.
    - `"share"`:Resumes screen-sharing video streams.
  
#### Returns

- _`void`_

#### Example

**Kotlin:**

```javascript
meeting!!.resumeAllStreams()
```

---

**Java:**

```javascript
meeting.resumeAllStreams();
```
---

### requestMediaRelay()

This method starts relaying selected media streams (like camera video, microphone audio, screen share) from the current meeting to a specified destination meeting.

#### Parameters

- **destinationMeetingId (String) – Required**: ID of the target meeting where media should be relayed.

- **token (String) – : Authentication token for the destination meeting.
  - If you pass `null`, the SDK will use the existing authentication token.

- **kinds (Array of Strings) – : Array of media types to relay. 
  - Possible values:
    - `"audio"`: Resumes audio streams.
    - `"video"`: Resumes video streams.
    - `"share"`:Resumes screen-sharing video streams.

  - If you pass `null`, all media types (audio, video, share) will be relayed by default.

#### Returns

- _`void`_

#### Example

**Kotlin:**

```javascript
meeting.requestMediaRelay("<meeting-id>", null, null)

```

---

**Java:**

```javascript
meeting.requestMediaRelay("<meeting-id>",null,null);
```
---

### stopMediaRelay()

This method stops the ongoing media relay to a specific destination meeting.

#### Parameters

- **destinationMeetingId (String) – Required**: ID of the destination meeting where the media relay should be stopped.

#### Returns

- _`void`_

#### Example

**Kotlin:**

```javascript
 meeting.stopMediaRelay("<meeting-id>")
```

---

**Java:**

```javascript
 meeting.stopMediaRelay("<meeting-id>");
```
---

### switchTo()

This method enables a seamless transition from the current meeting to another, without needing to disconnect and reconnect manually.

#### Parameters

- **meetingId (String) – Required**: ID of the new meeting to switch to.

- **token (String) – Optional**: Authentication token for the new meeting.

#### Returns

- _`void`_

#### Example

**Kotlin:**

```javascript
meeting.switchTo("<meeting-id>")
//or
meeting.switchTo("<meeting-id>",token)
```

---

**Java:**

```javascript
meeting.switchTo("<meeting-id>");
//or
meeting.switchTo("<meeting-id>",token);
```
---

### setAudioDeviceChangeListener()

- When a Local participant changes the Mic, `AppRTCAudioManager.AudioManagerEvents()` is triggered which can be set by using `setAudioDeviceChangeListener()` method.

#### Parameters

- **audioManagerEvents**: AppRTCAudioManager.AudioManagerEvents

#### Returns

- _`void`_

#### Example

**Kotlin:**

```javascript
meeting!!.setAudioDeviceChangeListener(object : AudioManagerEvents {
  override fun onAudioDeviceChanged(
    selectedAudioDevice: AppRTCAudioManager.AudioDevice,
    availableAudioDevices: Set<AppRTCAudioManager.AudioDevice>
  ) {
      when (selectedAudioDevice) {
        AppRTCAudioManager.AudioDevice.BLUETOOTH ->
          Toast.makeText(this@MainActivity, "Selected AudioDevice: BLUETOOTH", Toast.LENGTH_SHORT).show()

        AppRTCAudioManager.AudioDevice.WIRED_HEADSET ->
          Toast.makeText(this@MainActivity, "Selected AudioDevice: WIRED_HEADSET", Toast.LENGTH_SHORT).show()

        AppRTCAudioManager.AudioDevice.SPEAKER_PHONE ->
          Toast.makeText(this@MainActivity, "Selected AudioDevice: SPEAKER_PHONE", Toast.LENGTH_SHORT).show()

        AppRTCAudioManager.AudioDevice.EARPIECE ->
          Toast.makeText(this@MainActivity, "Selected AudioDevice: EARPIECE", Toast.LENGTH_SHORT).show()
      }
    }
})
```

---

**Java:**

```javascript
meeting.setAudioDeviceChangeListener(new AppRTCAudioManager.AudioManagerEvents() {
     @Override
    public void onAudioDeviceChanged(AppRTCAudioManager.AudioDevice selectedAudioDevice, Set<AppRTCAudioManager.AudioDevice> availableAudioDevices) {
        switch (selectedAudioDevice) {
            case BLUETOOTH:
              Toast.makeText(MainActivity.this, "Selected AudioDevice: BLUETOOTH", Toast.LENGTH_SHORT).show();
              break;
            case WIRED_HEADSET:
              Toast.makeText(MainActivity.this, "Selected AudioDevice: WIRED_HEADSET", Toast.LENGTH_SHORT).show();
              break;
            case SPEAKER_PHONE:
              Toast.makeText(MainActivity.this, "Selected AudioDevice: SPEAKER_PHONE", Toast.LENGTH_SHORT).show();
              break;
            case EARPIECE:
              Toast.makeText(MainActivity.this, "Selected AudioDevice: EARPIECE", Toast.LENGTH_SHORT).show();
              break;
           }
    }
});
```

---

### addEventListener()

#### Parameters

- **listener**: MeetingEventListener

#### Returns

- _`void`_

---

### removeEventListener()

#### Parameters

- **listener**: MeetingEventListener

#### Returns

- _`void`_

---

### removeAllListeners()

#### Returns

- _`void`_
</div>


---

# Meeting Class Properties - Android

<div class="sdk-api-ref-only-h4">

## getmeetingId()

- type: `String`

- `getmeetingId()` will return `meetingId`, which is unique id of the meeting where the participant has joined.

---

## getLocalParticipant()

- type: [Participant](../participant-class/introduction)

- It will be the instance of [Participant](../participant-class/introduction) class for the local participant(You) who joined the meeting.

---

## getMeetingState()

- type: `MeetingState`

- `getMeetingState()` will return `MeetingState`, which is current connection state of the meeting.

#### Example

**Kotlin:**

```javascript
meeting!!.getMeetingState()
```

---

**Java:**

```javascript
meeting.getMeetingState();
```
---

## getParticipants()

- type: [`Map`](https://developer.android.com/reference/java/util/Map) of [Participant](../participant-class/introduction)

- `Map<String, Participant>`

  - Map{'<'}`participantId`, [Participant](../participant-class/introduction)>

- It will contain all joined participants in the meeting except the `localParticipant`.

- This will be the [`Map`](https://developer.android.com/reference/java/util/Map) what will container all participants attached with the key as id of that participant.



**Kotlin:**

```javascript
val remoteParticipantId = "ajf897"

val participant = meeting!!.participants[remoteParticipantId]
```

---

**Java:**

```javascript
String remoteParticipantId = "ajf897";

Participant participant = meeting.getParticipants().get(remoteParticipantId);
```

---

## pubSub

- type: [`PubSub`](../pubsub-class/introduction)
- It is used to enable Publisher-Subscriber feature in [`meeting`](introduction) class.

Learn more about `PubSub`, [here](../pubsub-class/introduction)

---

## `LeaveReason` Enum

The `LeaveReason` enum provides detailed context for why a meeting or participant departure event was triggered. The following table lists all possible values:

| Code | Reason Constant | Description |
| :--- | :--- | :--- |
| 1001 | `WEBSOCKET_DISCONNECTED` | Socket disconnected. |
| 1002 | `REMOVE_PEER` | Participant was removed from the meeting. |
| 1003 | `REMOVE_PEER_VIEWER_MODE_CHANGED` | Participant Removed because viewer mode was changed. |
| 1004 | `REMOVE_PEER_MEDIA_RELAY_STOP` | Participant Removed because media relay was stopped. |
| 1005 | `SWITCH_ROOM` | Participant switched to a different room. |
| 1006 | `ROOM_CLOSE` | The meeting has been closed. |
| 1007 | `UNKNOWN` | Participant disconnected due to an unknown reason. |
| 1008 | `REMOVE_ALL` | Remove All from the meeting. |
| 1009 | `MEETING_END_API` | Meeting Ended. |
| 1010 | `REMOVE_PEER_API` | Participant removed from the meeting. |
| 1011 | `DUPLICATE_PARTICIPANT` | Leaving meeting, since this participantId joined from another device. |
| 1101 | `MANUAL_LEAVE_CALLED` | Participant manually called the leave() method to exit the meeting. |
| 1102 | `WEBSOCKET_CONNECTION_ATTEMPTS_EXHAUSTED` | Meeting left after multiple failed websocket connection attempts. |
| 1103 | `JOIN_ROOM_FAILED` | Meeting left due to an error while joining the room. |
| 1104 | `SWITCH_ROOM_FAILED` | Meeting left due to an error while switching rooms. |

</div>


---

# Meeting Class

## using Meeting Class

The `Meeting Class` includes methods and events for managing meetings, participants, video & audio streams, data channels and UI customization.




## Constructor

### Meeting(String meetingId, Participant localParticipant)

- return type : `void`

## Properties

### getmeetingId()

- `getmeetingId()` will return `meetingId`, which represents the meetingId for the current meeting
- return type : `void`

### getLocalParticipant()

- `getLocalParticipant()` will return Local participant
- return type :`Participant`

### getParticipants()

- `getParticipants()` will return all Remote participant
- return type : `void`

### pubSub()

- `pubSub()` will return object of `PubSub` class
- return type : `PubSub`

### Events


      
      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>

### Methods


      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>


---

# MeetingEventListener Class

## using MeetingEventListener Class

The `MeetingEventListener Class` is responsible for listening to all the events that are related to `Meeting Class`.




### Listeners


      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>


---

# Video SDK Participant Class - Android

<div class="sdk-api-ref">





Participant class includes all the properties, methods and events related to all the participants joined in a particular meeting.

## Get local and remote participants

You can get the local streams and participant meta from `meeting.getLocalParticipant()`. And a Map of joined participants is always available via `meeting.getParticipants()`



**Kotlin:**

```js title="Javascript"
val localParticipant = meeting!!.getLocalParticipant()
val participants = meeting!!.getParticipants()
```

---

**Java:**

```js title="Javascript"
Participant localParticipant = meeting.getLocalParticipant();
Map<String, Participant> participants = meeting.getParticipants();
```

## Participant Properties

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [getId()](./properties#getid)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getDisplayName()](./properties#getdisplayname)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getQuality()](./properties#getquality)

</div>

<div class="col col--4 margin-bottom--sm" >

- [isLocal()](./properties#islocal)

</div>

<div class="col col--4 margin-bottom--sm" >

- [getStreams()](./properties#getstreams)

</div>

<div class="col col--4 margin-bottom--sm" >

- [getMode()](./properties#getmode)

</div>

<div class="col col--4 margin-bottom--sm" >

- [getMetaData()](./properties#getmetadata)

</div>

</div>

## Participant Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [enableWebcam()](./methods#enablewebcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disableWebcam()](./methods#disablewebcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [enableMic()](./methods#enablemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disableMic()](./methods#disablemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [remove()](./methods#remove)

</div>
<div class="col col--4 margin-bottom--sm" >

- [setQuality()](./methods#setquality)

</div>
<div class="col col--4 margin-bottom--sm" >

- [setViewPort()](./methods#setviewport)

</div>
<div class="col col--4 margin-bottom--sm" >

- [captureImage()](./methods#captureimage)

</div>

</div>

## Participant Events

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [onStreamEnabled](./participant-event-listener-class#onstreamenabled)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onStreamDisabled](./participant-event-listener-class#onstreamdisabled)

</div>

</div>

</div>


---

# Participant Class Methods - Android

<div class="sdk-api-ref-only-h4">

### enableWebcam()

- `enableWebcam()` is used to enable participant's camera.

#### Events associated with `enableWebcam()` :

- First the participant will get a callback on [onWebcamRequested()](../meeting-class/meeting-event-listener-class#onwebcamrequested) and once the participant accepts the request, webcam will be enabled.

- Every Participant will receive a `streamEnabled` event of `ParticipantEventListener` Class with `stream` object.

#### Returns

- `void`

---

### disableWebcam()

- `disableWebcam()` is used to disable participant camera.

#### Events associated with `disableWebcam()` :

- Every Participant will receive a `streamDisabled` event of `ParticipantEventListener` Class with `stream` object.

#### Returns

- `void`

---

### enableMic()

- `enableMic()` is used to enable participant microphone.

#### Events associated with `enableMic()` :

- First the participant will get a callback on [onMicRequested()](../meeting-class/meeting-event-listener-class#onmicrequested) and once the participant accepts the request, mic will be enabled.

- Every Participant will receive a `streamEnabled` event of `ParticipantEventListener` Class with `stream` object.

#### Returns

- `void`

---

### disableMic()

- `disableMic()` is used to disable participant microphone.

#### Events associated with `disableMic()`:

- Every Participant will receive a `streamDisabled` event of `ParticipantEventListener` Class with `stream` object.

#### Returns

- `void`

---

### pin()

- It is used to set pin state of the participant. You can use it to pin the screen share, camera or both of the participant. It accepts a paramter of type `String`. Default `SHARE_AND_CAM`

#### Parameters

- **pinType**: `SHARE_AND_CAM` | `CAM` | `SHARE`

---

### unpin()

- It is used to unpin participant. You can use it to unpin the screen share, camera or both of the participant. It accepts a paramter of type `String`. Default is `SHARE_AND_CAM`

#### Parameters

- **pinType**: `SHARE_AND_CAM` | `CAM` | `SHARE`

---

### setQuality()

- `setQuality()` is used to set the quality of the participant's video stream.

#### Parameters

- `quality`: low | med | high

#### Returns

- `void`

---

### setViewPort()

- `setViewPort()` is used to set the quality of the participant's video stream based on the viewport height and width.

#### Parameters

- **width**: int
- **height**: int

#### Returns

- `void`

:::info

MultiStream is not supported by the Android SDK. Use `customTrack` rather than `setQuality()` and `setViewPort()` if you want to change participant's quality who joined using our Android SDK.

To know more about customTrack visit [here](/android/guide/video-and-audio-calling-api-sdk/features/custom-track/custom-video-track)

:::

---

### remove()

- `remove()` is used to remove the participant from the meeting.

#### Events associated with `remove()` :

- Local participant will receive a [`onMeetingLeft`](../meeting-class/meeting-event-listener-class.md#onmeetingleft) event.
- All remote participants will receive a [`onParticipantLeft`](../meeting-class/meeting-event-listener-class.md#onparticipantleft) event with `participantId`.

#### Returns

- `void`

---

### captureImage()

- It is used to capture image of local participant's current videoStream.

- You need to pass an implementation of `TaskCompletionListener` as a parameter. This listener will handle the result of the image capture task.

- When the image capture task is complete, the `onComplete()` method will provide the image in the form of a `base64` string. If an error occurs, the `onError()` method will provide the error details.

#### Parameters

- **height**: int
- **width**: int
- **listener**: TaskCompletionListener

#### Returns

- _`void`_

---

### getVideoStats()

- `getVideoStats()` will return an JSONArray which will contain details regarding the participant's critical video metrics such as **Jitter**, **Packet Loss**, **Quality Score** etc.

#### Returns

- `JSONArray`
  - `jitter` : It represents the distortion in the stream.
  - `bitrate` : It represents the bitrate of the stream which is being transmitted.
  - `totalPackets` : It represents the total packet count which were transmitted for that particiular stream.
  - `packetsLost` : It represents the total packets lost during the transimission of the stream.
  - `rtt` : It represents the time between the stream being reached to client from the server in milliseconds(ms).
  - `codec`: It represents the codec used for the stream.
  - `network`: It represents the network used to transmit the stream
  - `size`: It is object containing the height, width and frame rate of the stream.

  **Kotlin:**

```javascript
  val videoStats = participant.getVideoStats() // will return all possible stream layers in JSONArray
  val videoStat = videoStats.getJSONObject(0) // will return the first stream layer in JSONObject
  ```

---

**Java:**

```javascript
  JSONArray videoStats = participant.getVideoStats(); // will return all possible stream layers in JSONArray
  JSONObject videoStat = videoStats.getJSONObject(0); // will return the first stream layer in JSONObject
  ```

:::note

getVideoStats() will return the metrics for the participant at that given point of time and not average data of the complete meeting.

To view the metrics for the complete meeting using the stats API documented [here](/api-reference/realtime-communication/fetch-session-quality-stats).

:::

:::info

If you are getting `rtt` greater than 300ms, try using a different region which is nearest to your user. To know more about changing region [visit here](/api-reference/realtime-communication/create-room).

If you are getting high packet loss, try using the `customTrack` for better experience. To know more about customTrack [visit here](/android/guide/video-and-audio-calling-api-sdk/features/custom-track/custom-video-track)

:::

---

### getAudioStats()

- `getAudioStats()` will return an JSONObject which will contain details regarding the participant's critical audio metrics such as **Jitter**, **Packet Loss**, **Quality Score** etc.

#### Returns

- `JSONObject`
  - `jitter` : It represents the distortion in the stream.
  - `bitrate` : It represents the bitrate of the stream which is being transmitted.
  - `totalPackets` : It represents the total packet count which were transmitted for that particiular stream.
  - `packetsLost` : It represents the total packets lost during the transimission of the stream.
  - `rtt` : It represents the time between the stream being reached to client from the server in milliseconds(ms).
  - `codec`: It represents the codec used for the stream.
  - `network`: It represents the network used to transmit the stream

  **Kotlin:**

```javascript
  val audioStat = videoStats.getAudioStats() 
  ```

---

**Java:**

```javascript
  JSONObject audioStat = videoStats.getAudioStats();
  ```

:::note

getAudioStats() will return the metrics for the participant at that given point of time and not average data of the complete meeting.

To view the metrics for the complete meeting using the stats API documented [here](/api-reference/realtime-communication/fetch-session-quality-stats).

:::

:::info

If you are getting `rtt` greater than 300ms, try using a different region which is nearest to your user. To know more about changing region [visit here](/api-reference/realtime-communication/create-room).

:::

### getShareStats()

- `getShareStats()` will return an JSONObject which will contain details regarding the participant's critical video metrics such as **Jitter**, **Packet Loss**, **Quality Score** etc.

#### Returns

- `JSONObject`
  - `jitter` : It represents the distortion in the stream.
  - `bitrate` : It represents the bitrate of the stream which is being transmitted.
  - `totalPackets` : It represents the total packet count which were transmitted for that particiular stream.
  - `packetsLost` : It represents the total packets lost during the transimission of the stream.
  - `rtt` : It represents the time between the stream being reached to client from the server in milliseconds(ms).
  - `codec`: It represents the codec used for the stream.
  - `network`: It represents the network used to transmit the stream
  - `size`: It is object containing the height, width and frame rate of the stream.


**Kotlin:**

```javascript
  val shareStat = videoStats.getShareStats()
  ```

---

**Java:**

```javascript
  JSONObject shareStat = videoStats.getShareStats();
  ```


:::note

getShareStats() will return the metrics for the participant at that given point of time and not average data of the complete meeting.

To view the metrics for the complete meeting using the stats API documented [here](/api-reference/realtime-communication/fetch-session-quality-stats).

:::

:::info

If you are getting `rtt` greater than 300ms, try using a different region which is nearest to your user. To know more about changing region [visit here](/api-reference/realtime-communication/create-room).

:::

### addEventListener()

#### Parameters

- **listener**: ParticipantEventListener

#### Returns

- _`void`_

---

### removeEventListener()

#### Parameters

- **listener**: ParticipantEventListener

#### Returns

- _`void`_

---

### removeAllListeners()

#### Returns

- _`void`_

</div>


---

# ParticipantEventListener Class - Android

<div class="sdk-api-ref-only-h4">

### Implementation

- You can implement all the methods of `ParticipantEventListener` abstract Class and add the listener to `Participant` class using the `addEventListener()` method of `Participant` Class.

---

### onStreamEnabled()

- `onStreamEnabled()` is a callback which gets triggered whenever a participant's video, audio or screen share stream is enabled.

#### Event callback parameters

- **stream**: [Stream](../stream-class/introduction.md)

---

### onStreamDisabled()

- `onStreamDisabled()` is a callback which gets triggered whenever a participant's video, audio or screen share stream is disabled.

#### Event callback parameters

- **stream**: [Stream](../stream-class/introduction.md)

---

### onStreamPaused()

- This event will be emitted when any participant pauses consuming or producing stream of any type.

--- 

### onStreamResumed()

- This event will be emitted when any participant resumes consuming or producing stream of any type.

---

### onE2eeStateChanged()

- This event will be emitted when participant's E2EE State changes. 

---

### Example



**Kotlin:**

```js
  meeting!!.localParticipant.addEventListener(object : ParticipantEventListener() {
override fun onStreamEnabled(stream: Stream) {
    //
}

override fun onStreamDisabled(stream: Stream) {
    //
}

override fun onStreamPaused(kind: String, reason: String) {
    // 
}

override fun onStreamResumed(kind: String, reason: String) {
    // 
}

override fun onE2eeStateChanged(state: E2EEState, stream: Stream) {
    // 
}
  });
```

---

**Java:**

```js
  participant.addEventListener(new ParticipantEventListener() {
@Override
public void onStreamEnabled(Stream stream) {
    //
}

@Override
public void onStreamDisabled(Stream stream) {
    //
}

@Override
public void onStreamPaused(String kind, String reason) {
    //
}

@Override
public void onStreamResumed(String kind, String reason) {
    //
}

@Override
public void onE2eeStateChanged(E2EEState state, Stream stream) {
    //
}
  });
```

</div>


---

# Participant Class Properties - Android

<div class="sdk-api-ref-only-h4">

### getId()

- type: `String`

- `getId` will return unique id of the participant who has joined the meeting.

---

### getDisplayName()

- type: `String`

- It will return the `displayName` of the participant who has joined the meeting.

---

### getQuality()

- type: `String`

- `getQuality()` will return quality of participant's stream. Stream could be `audio` , `video` or `share`.

---

### isLocal()

- type: `boolean`

- `isLocal()` will return `true` if participant is Local,`false` otherwise.

---

### getStreams()

- type: `Map<String,name>`

- It will represents the stream for that particular participant who has joined the meeting. Streams could be `audio` , `video` or `share`.

---

### getMode()

- type : `string`

- ` getMode()` will return mode of the Participant.

---

### getMetaData()

- type : `JSONObject`

- `getMetaData()` will return additional information, that you have passed in `initMeeting()`.

</div>


---

# Participant Class

## Introduction

The `Participant Class` includes methods and events for participants and their associated video & audio streams, data channels and UI customization.




## Properties

### getId()

- `getId()` will return participant's Id
- return type : `String`

### getDisplayName()

- `getDisplayName()` will return name of participant
- return type : `String`

### getQuality()

- `getQuality()` will return quality of participant's video stream
- return type : `String`

### isLocal()

- `isLocal()` will return `true` if participant is Local,`false` otherwise
- return type : `boolean`

### getStreams()

- `getStreams()` will return streams of participant
- return type : `Map<String, Stream>`
- Map contains `streamId` as key and `stream` as value

## Events

### addEventListener(ParticipantEventListener listener)

- By using `addEventListener(ParticipantEventListener listener)`, we can add listener to the List of `ParticipantEventListener`
- return type : `void`

### removeEventListener(ParticipantEventListener listener)

- By using `removeEventListener(ParticipantEventListener listener)`, we can remove listener from List of `ParticipantEventListener`
- return type : `void`

### removeAllListeners()

- By using `removeAllListeners()`, we can remove all listener from List
- return type : `void`

## Methods

### enableMic()

- By using `enableMic()` function, a participant can enable the Mic of any particular Remote Participant
- When `enableMic()` is called,
  - Local Participant will receive a callback on `streamEnabled()` of `ParticipantEventListener` class
  - Remote Participant will receive a callback for `onMicRequested()` and once the remote participant accepts the request, mic will be enabled for that participant
- return type : `void`

### disableMic()

- By using `disableMic()` function, a participant can disable the Mic of any particular Remote Participant
- When `enableMic()` is called,
  - Local Participant will receive a callback on `streamDisabled()` of `ParticipantEventListener` class
  - Remote Participant will receive a callback on `streamDisabled()` of `ParticipantEventListener` class
- return type : `void`

### enableWebcam()

- By using `enableWebcam()` function, a participant can enable the Webcam of any particular Remote Participant
- When `enableWebcam()` is called,
  - Local Participant will receive a callback on `streamEnabled()` of `ParticipantEventListener` class
  - Remote Participant will receive a callback for `webcamRequested()` and once the remote participant accepts the request, webcam will be enabled for that participant
- return type : `void`

### disableWebcam()

- By using `disableWebcam()` function, a participant can disable the Webcam of any particular Remote Participant
- When `disableWebcam()` is called,
  - Local Participant will receive a callback on `streamDisabled()` of `ParticipantEventListener` class
  - Remote Participant will receive a callback on `streamDisabled()` of `ParticipantEventListener` class
- return type : `void`

### remove()

- By using `remove()` function, a participant can remove any particular Remote Participant
- When `remove()` is called,
  - Local Participant will receive a callback on `meetingLeft()`
  - Remote Participant will receive a callback on `participantLeft()`
- return type : `void`

### setQuality()

- By using `setQuality()`,you can set quality of participant's video stream
- return type : `void`


---

# ParticipantEventListener Class

## using ParticipantEventListener Class

The `ParticipantEventListener Class` is responsible for listening to all the events that are related to `Participant Class`.




### Listeners


      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>


---

# Video SDK PubSub Class - Android

<div class="sdk-api-ref">

## Introduction

PubSub class provides the methods to implement Publisher-Subscriber feature in your Application.

## PubSub Methods

<div class="row">

<div  class="col col--4 margin-bottom--sm" >

- [publish()](methods#publish)

</div>

<div  class="col col--4 margin-bottom--sm" >

- [subscribe()](methods#subscribe)

</div>

<div  class="col col--4 margin-bottom--sm" >

- [unsubscribe()](methods#unsubscribe)

</div>
</div>
</div>


---

# PubSub Class Methods - Android

<div class="sdk-api-ref-only-h4">

### publish()

- `publish()` is used to publish messages on a specified topic in the meeting.

#### Parameters

- topic

  - type: `String`
  - This is the name of the topic, for which message will be published.

- message

  - type: `String`
  - This is the actual message.

- options
  - type: [`PubSubPublishOptions`](pubsub-publish-options-class)
  - This specifies the options for publish.

- payload

  - type: `JSONObject`
  - `OPTIONAL`
  - If you need to include additional information along with a message, you can pass here as `JSONObject`.

#### Returns

- _`void`_

#### Example



**Kotlin:**

```js
// Publish message for 'CHAT' topic
val publishOptions = PubSubPublishOptions()
publishOptions.isPersist = true

meeting!!.pubSub.publish("CHAT", "Hello from Android", publishOptions)
```

---

**Java:**

```js
// Publish message for 'CHAT' topic
PubSubPublishOptions publishOptions = new PubSubPublishOptions();
publishOptions.setPersist(true);

meeting.pubSub.publish("CHAT", "Hello from Android", publishOptions);
```

---

### subscribe()

- `subscribe()` is used to subscribe a particular topic to get all the messages of that particular topic in the meeting.

#### Parameters

- topic:

  - type: `String`
  - Participants can listen to messages on that particular topic.

- listener:

  - type: [`PubSubMessageListener`](pubsub-message-listener-class)

#### Returns

- _`void`_

#### Example

**Kotlin:**

```js
val pubSubMessageListener = object : PubSubMessageListener {
override fun onMessageReceived(message: PubSubMessage) {
    Log.d("#message", "onMessageReceived: ${message.message}")
}

override fun onOldMessagesReceived(messages: List<PubSubMessage>) {
    Log.d("#message", "onOldMessagesReceived: $messages")
}
}

  // Subscribe for 'CHAT' topic
  meeting!!.pubSub.subscribe("CHAT", pubSubMessageListener)
```

---

**Java:**

```js
PubSubMessageListener pubSubMessageListener = new PubSubMessageListener() {
@Override
public void onMessageReceived(PubSubMessage message) {
    Log.d("#message", "onMessageReceived: " + message.getMessage());
}

@Override
  public void onOldMessagesReceived(List<PubSubMessage> messages) {
  Log.d("#message", "onOldMessagesReceived: " + messages);
}
};

 // Subscribe for 'CHAT' topic
 meeting.pubSub.subscribe("CHAT", pubSubMessageListener);
```

---

### unsubscribe()

- `unsubscribe()` is used to unsubscribe a particular topic on which you have subscribed priviously.

#### Parameters

- topic:

  - type: `String`
  - This is the name of the topic to be unsubscribed.

- listener:

  - type: [`PubSubMessageListener`](pubsub-message-listener-class)

#### Returns

- _`void`_

#### Example

**Kotlin:**

```js
// Unsubscribe for 'CHAT' topic
meeting!!.pubSub.unsubscribe("CHAT", pubSubMessageListener)
```

---

**Java:**

```js
// Unsubscribe for 'CHAT' topic
meeting.pubSub.unsubscribe("CHAT", pubSubMessageListener);
```

</div>


---

# Properties - Android

<div class="sdk-api-ref-only-h4">

### getId()

- type: `String`

- `getId()` will return unique id of the pubsub message.

---

### getMessage()

- type: `String`

- `getMessage()` will return message that has been published on the specific topic.

---

### getTopic()

- type: `String`

- `getTopic()` will return name of the message topic.

---

### getSenderId()

- type: `String`

- `getSenderId()` will return id of the participant, who has sent the message.

---

### getSenderName()

- type: `String`

- `getSenderName()` will return name of the participant, who has sent the pubsub message.

---

### getTimestamp()

- type: `long`

- `getTimestamp()` will return timestamp at which, the pubsub message was sent.

---

### getPayload()

- type: `JSONObject`

- `getPayload()` will return data that you have send with message.

</div>


---

# PubSubMessageListener Class - Android

<div class="sdk-api-ref-only-h4">

---

#### onMessageReceived()

- This event will be emitted whenever any pubsub message received.


#### onOldMessagesReceived()

- This event will be emitted history of all old messages

#### Example



**Kotlin:**

```javascript
val pubSubMessageListener = object : PubSubMessageListener {
override fun onMessageReceived(message: PubSubMessage) {
    Log.d("#message", "onMessageReceived: ${message.message}")
}

override fun onOldMessagesReceived(messages: List<PubSubMessage>) {
    Log.d("#message", "onOldMessagesReceived: $messages")
}
}
```

---

**Java:**

```javascript
PubSubMessageListener pubSubMessageListener = new PubSubMessageListener() {
@Override
public void onMessageReceived(PubSubMessage message) {
    Log.d("#message", "onMessageReceived: " + message.getMessage());
}

@Override
  public void onOldMessagesReceived(List<PubSubMessage> messages) {
  Log.d("#message", "onOldMessagesReceived: " + messages);
}
};
```

</div>


---

# PubSubPublishOptions Class - Android

<div class="sdk-api-ref-only-h4">


## Properties

### persist

- type: `boolean`

- defaultValue: `false`

- This property specifies whether to store messages on server for upcoming participants.

- If the value of this property is true, then server will store pubsub messages for the upcoming participants.

---

### sendOnly

- type: `String[]`

- defaultValue: `null`

- If you want to send a message to specific participants, you can pass their respective `participantId` here. If you don't provide any IDs or pass a `null` value, the message will be sent to all participants by default.

:::note
Make sure that participantId present in the array must be subscribe to that specific topic.
:::

</div>


---

# PubSub Class

## using PubSub Class

The `PubSub` includes methods for pubsub.




### Methods


      
      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>


---

# PubSubMessage Class

## using PubSubMessage Class

The `PubSubMessage` includes properties of PubSub message.




### Properties


      
      
      
      
      
      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>


---

# PubSubPublishOptions Class

## using PubSubPublishOptions Class

The `PubSubPublishOptions` includes properties of PubSub options.




### Properties


      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>

### Methods


      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>


---

# RealtimeStore Methods - Android

<div class="sdk-api-ref-only-h4">

### `set()`

- `set()` is used to store or update data in the RealtimeStore. If a key already exists, it will be overwritten with the new value. Passing `null` as the value deletes the key.

#### Parameters

- key
  - type: `String`
  - The unique key to store the data under.

- value
  - type: `String?`
  - The string value to be stored. Pass `null` to delete the key.

- callback
  - type: `RealtimeStoreCallback<String>`
  - A callback that reports the success or failure of the operation.

#### Returns

- _`void`_

#### Example



**Kotlin:**

```kotlin
  meeting.realtimeStore.set("YOUR_KEY", message, object : RealtimeStoreCallback<String> {
  override fun onSuccess(value: String) {
      Log.d("VideoSDK", "Value: $value")
  }
  
  override fun onError(error: String) {
      Log.e("VideoSDK", "Error: $error")
  }
  })
```

---

**Java:**

```java
meeting.realtimeStore.set("YOUR_KEY", message, new RealtimeStoreCallback<String>() {
    @Override
    public void onSuccess(String value) {
        Log.d("VideoSDK", "Value: " + value);
    }

    @Override
    public void onError(String error) {
        Log.e("VideoSDK", "Error: " + error);
    }
});
```

---

### `get()`

- `get()` retrieves the current value associated with a given key.

#### Parameters

- key:
  - type: `String`
  - The key whose value you want to retrieve.

- callback:
  - type: `RealtimeStoreCallback<String>`
  - A callback that provides the value on success or an error on failure.

#### Returns

- _`void`_

#### Example

**Kotlin:**

```kotlin
meeting.realtimeStore.get("YOUR_KEY", object : RealtimeStoreCallback<String> {
  override fun onSuccess(value: String) {
Log.d("VideoSDK", "Value: $value")
  }

  override fun onError(error: String) {
Log.e("VideoSDK", "Error: $error")
  }
})
```

---

**Java:**

```java
meeting.realtimeStore.get("YOUR_KEY", new RealtimeStoreCallback<String>() {
@Override
public void onSuccess(String value) {
    Log.d("VideoSDK", "value: " + value);
}

@Override
public void onError(String error) {
    Log.e("VideoSDK", "Error: " + error);
}
});
```

---

### `observe()`

- `observe()` subscribes to real-time updates for a given key. When the key’s value changes, the `onValueChanged` method on your `RealtimeStoreListener` is triggered.

#### Parameters

- key:
  - type: `String`
  - The key to observe.

- listener:
  - type: `RealtimeStoreListener`
  - An object that will receive notifications about value changes.

#### Returns

- _`void`_

#### Example

**Kotlin:**

```kotlin
val realtimeStoreListener = object : RealtimeStoreListener {
  override fun onValueChanged(newValue: String, updatedBy: Participant?) {
  Log.d("VideoSDK", "onValueChange: Received update from: ${updatedBy.displayName}")
  Log.d("VideoSDK", "onValueChange: New Value -> $newValue")
  }
}

meeting.realtimeStore.observe(KEY_CHAT_HISTORY, realtimeStoreListener!!)
```

---

**Java:**

```java
private RealtimeStoreListener realtimeStoreListener;

realtimeStoreListener = new RealtimeStoreListener() {

@Override
public void onValueChanged(String newValue, Participant updatedBy) {
    Log.d("VideoSDK", "onValueChange: Received update from: " + updatedBy.getDisplayName());
    Log.d("VideoSDK", "onValueChange: New Value -> " + newValue);
}
  };

meeting.realtimeStore.observe(KEY_CHAT_HISTORY, realtimeStoreListener);
```

---

### `stopObserving()`

- `stopObserving()` stops receiving updates for a specific key and listener combination.

#### Parameters

- key:
  - type: `String`
  - The key you want to stop observing.

- listener:
  - type: `RealtimeStoreListener`
  - The listener that should be removed.

#### Returns

- _`void`_

#### Example

**Kotlin:**

```kotlin
meeting.realtimeStore.stopObserving("YOUR_KEY", realtimeStoreListener)
```

---

**Java:**

```java
meeting.realtimeStore.stopObserving("YOUR_KEY", realtimeStoreListener);
```

</div>


---

# RealtimeStore

The `RealtimeStore` class allows you to store, update, retrieve, and observe custom key-value data within a meeting — in real time. It acts as a shared data layer across all connected participants, ensuring asynchronized states throughout the session.

## RealtimeStore Methods

<div class="row">

<div  class="col col--4 margin-bottom--sm" >

- [set()](methods#set)

</div>
<div  class="col col--4 margin-bottom--sm" >

- [delete()](methods#set)

</div>

<div  class="col col--4 margin-bottom--sm" >

- [get()](methods#get)

</div>

<div  class="col col--4 margin-bottom--sm" >

- [observe()](methods#observe)

</div>

<div  class="col col--4 margin-bottom--sm" >

- [stopObserving()](methods#stopobserving)

</div>
</div>


---

# `RealtimeStoreCallback<String>` Class - Android

A callback interface used for asynchronous operations in `RealtimeStore`.

<div class="sdk-api-ref-only-h4">

---

### `onSuccess()`

- This event will be emitted when the operation completes successfully.

#### Parameters

- result
  - type: `String`
  - The result of the operation.

---

### `onError()`

- This event will be emitted when the operation fails.

#### Parameters

- error
  - type: `String`
  - A string message detailing what went wrong.

</div>


---

# RealtimeStoreListener Class - Android

<div class="sdk-api-ref-only-h4">

---

#### onValueChanged()

- This event will be emitted whenever the observed key's value changes.

#### Example



**Kotlin:**

```kotlin
val realtimeStoreListener = object : RealtimeStoreListener {
  override fun onValueChanged(newValue: String, updatedBy: Participant?) {
  Log.d("VideoSDK", "onValueChange: Received update from: ${updatedBy.displayName}")
  Log.d("VideoSDK", "onValueChange: New Value -> $newValue")
  }
}
```

---

**Java:**

```java
private RealtimeStoreListener realtimeStoreListener;

realtimeStoreListener = new RealtimeStoreListener() {

@Override
public void onValueChanged(String newValue, Participant updatedBy) {
    Log.d("VideoSDK", "onValueChange: Received update from: " + updatedBy.getDisplayName());
    Log.d("VideoSDK", "onValueChange: New Value -> " + newValue);
}
  };
```

</div>


---

# Setup - Android

## Setting up android sdk

Android SDK is client for real-time communication for android devices. It inherits the same terminology as all other SDKs does.

## Minimum OS/SDK versions

It supports the following OS/SDK versions.

### Android: minSdkVersion >= 21

## Installation

1. If your Android Studio Version is older than Android Studio Bumblebees, add the repository to project's `build.gradle` file. <br/>
   If your are using Android Studio Bumblebees or newer Version, add the repository to `settings.gradle` file.

:::note

You can use imports with Maven Central after rtc-android-sdk version `0.1.12`.

Whether on Maven or Jitpack, the same version numbers always refer to the same SDK.

:::



**Maven Central:**

```js title="build.gradle"
allprojects {
  repositories {
// ...
google()
mavenCentral()
maven { url "https://maven.aliyun.com/repository/jcenter" }
  }
}
```

```js title="settings.gradle"
dependencyResolutionManagement{
  repositories {
// ...
google()
mavenCentral()
maven { url "https://maven.aliyun.com/repository/jcenter" }
  }
}

```

---

**Jitpack:**

```js title="build.gradle"
allprojects {
  repositories {
// ...
google()
maven { url 'https://jitpack.io' }
mavenCentral()
maven { url "https://maven.aliyun.com/repository/jcenter" }
  }
}
```

```js title="settings.gradle"
dependencyResolutionManagement{
  repositories {
// ...
google()
maven { url 'https://jitpack.io' }
mavenCentral()
maven { url "https://maven.aliyun.com/repository/jcenter" }
  }
}

```

### Step 2: Add the following dependency in your app's `app/build.gradle`.

```js title="app/build.gradle"
dependencies {
  implementation 'live.videosdk:rtc-android-sdk:0.3.0'

  // library to perform Network call to generate a meeting id
  implementation 'com.amitshekhar.android:android-networking:1.0.2'

  // other app dependencies
  }
```

:::important

Android SDK compatible with armeabi-v7a, arm64-v8a, x86_64 architectures. If you want to run the application in an emulator, choose ABI x86_64 when creating a device.

:::

## Integration

### Step 1: Add the following permissions in `AndroidManifest.xml`.

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

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

```

### Step 2: Create `MainApplication` class which will extend the `android.app.Application`.

**Kotlin:**

```js title="MainApplication.kt"
package live.videosdk.demo;

import live.videosdk.android.VideoSDK

class MainApplication : Application() {
override fun onCreate() {
    super.onCreate()
    VideoSDK.initialize(applicationContext)
}
}
```

---

**Java:**

```js title="MainApplication.java"
package live.videosdk.demo;

import android.app.Application;

import live.videosdk.android.VideoSDK;

public class MainApplication extends Application {
@Override
public void onCreate() {
    super.onCreate();
    VideoSDK.initialize(getApplicationContext());
}
}
```

### Step 3: Add `MainApplication` to `AndroidManifest.xml`.

```js title="AndroidManifest.xml"
<application
        android:name=".MainApplication"
				...
>
  
</application>
```

### Step 4: In your `JoinActivity` add the following code in `onCreate()` method.

**Kotlin:**

```js title="JoinActivity.kt"
override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  setContentView(R.layout.activity_join)

  val meetingId = "<meeting-id>"
  val participantName = "John Doe"

  var micEnabled = true
  var webcamEnabled = true

  // generate the jwt token from your api server and add it here
  VideoSDK.config("JWT TOKEN GENERATED FROM SERVER")

  // create a new meeting instance
  meeting = VideoSDK.initMeeting(
  this@MeetingActivity, meetingId, participantName,
  micEnabled, webcamEnabled, null, null, false, null, null)

  // get permissions and join the meeting with meeting.join();
  // checkPermissionAndJoinMeeting();
}
```

---

**Java:**

```js title="JoinActivity.java"
@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_join);

  final String meetingId = "<meeting-id>";
  final String participantName = "John Doe";

  final boolean micEnabled = true;
  final boolean webcamEnabled = true;

  // generate the jwt token from your api server and add it here
  VideoSDK.config("JWT TOKEN GENERATED FROM SERVER");

  // create a new meeting instance
  Meeting meeting = VideoSDK.initMeeting(
      MainActivity.this, meetingId, participantName,
      micEnabled, webcamEnabled, null, null, false, null, null
  );

  // get permissions and join the meeting with meeting.join();
  // checkPermissionAndJoinMeeting();
}
```

All set! Here is the link to the complete sample code on [Github](https://github.com/videosdk-live/videosdk-rtc-android-java-sdk-example). Please refer to the [documentation](initMeeting) for a full list of available methods, events and features of the SDK.


---

# Video SDK Stream Class - Android

<div id="tailwind" class="sdk-api-ref">




Stream class is responsible for handling audio, video and screen sharing streams.

Stream class defines instance of audio, video and shared screen stream of participants.

## Stream Properties

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [getId()](./properties#getid)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getKind()](./properties#getkind)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getTrack()](./properties#gettrack)

</div>

</div>

## Stream Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [resume()](methods#resume)

</div>
<div class="col col--4 margin-bottom--sm" >

- [pause()](./methods#pause)

</div>

</div>

</div>


---

# Stream Class Methods - Android

<div class="sdk-api-ref-only-h4">

### resume()

- By using `resume()`, a participant can resume the stream of Remote Participant.

#### Returns

- `void`

---

### pause()

- By using `pause()`, a participant can pause the stream of Remote Participant.

#### Returns

- `void`

</div>


---

# Stream Class Properties - Android

<div class="sdk-api-ref-only-h4">

### getId()

- type: `String`

- `getId()` will return id for that stream .

---

### getKind()

- type: `String`

- `getKind()` will return `kind`, which represents the type of stream which could be `audio` | `video` or `share` .

---

### getTrack()

- type: `MediaStreamTrack`

- `getTrack()` will return a MediaStreamTrack object stored in the MediaStream object.

</div>


---

# Stream Class

## Introduction

The `Stream Class` includes methods and events of video & audio streams.




## Properties

### getId()

- `getId()` will return Id of stream
- return type : `String`

### getKind()

- `getKind()` will return kind of stream, which can `audio`,`video` or `share`
- return type : `String`

### getTrack()

- `getTrack()` will return a MediaStreamTrack object stored in the MediaStream object
- return type : `MediaStreamTrack`

## Methods

### pause()

- By using `pause()` function, a participant can pause the stream of Remote Participant
- return type : `void`

### resume()

- By using `resume()` function, a participant can resume the stream of Remote Participant
- return type : `void`


---

<h1> {props.title} </h1>{" "}

When integrating VideoSDK, you will come across with multiple terms like meeting, room, session and many more.

Let's discuss each term in detail so while integrating VideoSDK you don't get confused.

### Meeting / Room

- A Meeting or Room is a VideoSDK object which represents a real-time audio, video, and/or screen-share session, and is the basic building block for media sharing among participants which is returned by the VideoSDK once a successful connection is established.
- Meeting or Room can be uniquely identified by `meetingId` or `roomId`.

:::note
Meeting and Room are both the same. Similarly `meetingId` and `roomId` are same.
:::

### Session

- A Session is the instance of an ongoing meeting/room which has one or more participants in it. A single room or meeting can have multiple sessions.
- Each session can be uniquely identified by `sessionId`.
- All the sessions are associated with `meetingId`/`roomId` and can be listed using it.

### Participant

- Participant is a VideoSDK object which represents each user/client in the meeting or room and can share audio/video media with other.
- There can be multiple participants in a meeting/room and each participant can be uniquely identified by `participantId`.

### MediaStream

- MediaStream is the collection of audio and video tracks which holds the segments of audio/video media that are send and received by all the participants in the meeting.

### RTMP Live Stream

- RTMP live streaming is used to live stream your video conferencing apps to platforms like YouTube, Twitch, Facebook, etc. by providing the platform specific `streamKey` and `streamUrl`.

### Interactive Live streaming (HLS)

- Interactive live streaming is used to live stream your video conferencing apps within your own platform to allow a larger number of viewers who can not be accomodated in a real-time conference.



---

# VideoSDK Class Events - Android

<div class="sdk-api-ref-only-h4">


### onAudioDeviceChanged()

- This event will be emitted when an audio device, is connected to or removed from the device.

#### Example



**Kotlin:**

```javascript
VideoSDK.setAudioDeviceChangeListener(object : VideoSDK.AudioDeviceChangeEvent {
override fun onAudioDeviceChanged(
    selectedAudioDevice: AudioDeviceInfo?,
    audioDevices: MutableSet<AudioDeviceInfo>?
) {
    Log.d(
        "VideoSDK",
        "Selected Audio Device: " + selectedAudioDevice.label
    )
    for (audioDevice in audioDevices) {
        Log.d("VideoSDK", "Audio Devices" + audioDevice.label)
    }
}
})
```

---

**Java:**

```javascript
VideoSDK.setAudioDeviceChangeListener(new VideoSDK.AudioDeviceChangeEvent() {
@Override
public void onAudioDeviceChanged(AudioDeviceInfo selectedAudioDevice, Set<AudioDeviceInfo> audioDevices) {
    Log.d("VideoSDK", "Selected Audio Device: " + selectedAudioDevice.getLabel());
    for (AudioDeviceInfo audioDevice :
            audioDevices) {
        Log.d("VideoSDK", "Audio Devices" + audioDevice.getLabel());
    }
}
});
```

---

</div>


---

# VideoSDK Class - Android 

<div class="sdk-api-ref">

## Introduction

The `VideoSDK` class includes properties, methods and events for creating and configuring a meeting, and managing media devices.


//import properties from "./../data/meeting-class/properties.json";


## VideoSDK Properties

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [getSelectedAudioDevice()](./properties.md#getselectedaudiodevice)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getSelectedVideoDevice()](./properties#getselectedvideodevice)

</div>

</div>

## VideoSDK Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [initialize()](./methods#initialize)

</div>

<div class="col col--4 margin-bottom--sm" >

- [config()](./methods#config)

</div>
<div class="col col--4 margin-bottom--sm" >

- [initMeeting()](./methods#initmeeting)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getDevices()](./methods#getdevices)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getVideoDevices()](./methods#getvideodevices)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getAudioDevices()](./methods#getaudiodevices)

</div>
<div class="col col--4 margin-bottom--sm" >

- [checkPermissions()](./methods#checkpermissions)

</div>

<div class="col col--4 margin-bottom--sm" >

- [setAudioDeviceChangeListener()](./methods#setaudiodevicechangelistener)

</div>
<div class="col col--4 margin-bottom--sm" >

- [setSelectedAudioDevice()](./methods#setselectedaudiodevice)

</div>
<div class="col col--4 margin-bottom--sm" >

- [setSelectedVideoDevice()](./methods#setselectedvideodevice)

</div>

</div>

## VideoSDK Events

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [onAudioDeviceChanged](./events.md#onaudiodevicechanged)

</div>

</div>

</div>


---

# VideoSDK Class Methods - Android

<div class="sdk-api-ref-only-h4">

### initialize()

To initialize the meeting, first you have to initialize the `VideoSDK`.
You can initialize the `VideoSDK` using `initialize()` method provided by the SDK.

#### Parameters

- **context**: Context

#### Returns

- _`void`_

```js title="initialize"
  VideoSDK.initialize(Context context)
```

---

### config()

By using `config()` method, you can set the `token` property of `VideoSDK` class.

Please refer this [documentation](/api-reference/realtime-communication/intro/) to generate a token.

#### Parameters

- **token**: String

#### Returns

- _`void`_

```js title="config"
 VideoSDK.config(String token)
```

---

### initMeeting()

- Initialize the meeting using a factory method provided by the SDK called `initMeeting()`.
- `initMeeting()` will generate a new [`Meeting`](../meeting-class/introduction.md) class and the initiated meeting will be returned.

```js title="initMeeting"
   VideoSDK.initMeeting(
        Context context,
        String meetingId,
        String name,
        boolean micEnabled,
        boolean webcamEnabled,
        String participantId,
        String mode,
        boolean multiStream,
        Map<String, CustomStreamTrack> customTracks
        JSONObject metaData,
        String signalingBaseUrl
        PreferredProtocol preferredProtocol
      )
```
- Please refer this [documentation](../initMeeting.md#initmeeting) to know more about `initMeeting()`.

---

### getDevices()

- The `getDevices()` method returns a list of the currently available media devices, such as microphones, cameras, headsets, and so forth. The method returns a list of `DeviceInfo` objects describing the devices.

- `DeviceInfo` class has four properties :

  1. `DeviceInfo.deviceId`

     - Returns a string that is an identifier for the represented device, persisted across sessions.

  2. `DeviceInfo.label`

     - Returns a string describing this device (for example `BLUETOOTH`).

  3. `DeviceInfo.kind`

     - Returns an enumerated value that is either `video` or `audio`.

  4. `DeviceInfo.FacingMode`

     - Returns a value of type `FacingMode` indicating which camera device is in use (front or back).

#### Returns

- `Set<DeviceInfo>`

#### Example



**Kotlin:**

```javascript
val devices: Set<DeviceInfo> = VideoSDK.getDevices()
for (deviceInfo in devices) {
Log.d("VideoSDK", "Device's DeviceId " + deviceInfo.deviceId)
Log.d("VideoSDK", "Device's Label " + deviceInfo.label)
Log.d("VideoSDK", "Device's Kind " + deviceInfo.kind)
Log.d("VideoSDK", "Device's Facing Mode " + deviceInfo.facingMode) //Value will be null for Audio Devices
}
```

---

**Java:**

```javascript
Set<DeviceInfo> devices = VideoSDK.getDevices();
for (DeviceInfo deviceInfo :
    devices) {
Log.d("VideoSDK", "Device's DeviceId " + deviceInfo.getDeviceId());
Log.d("VideoSDK", "Device's Label " + deviceInfo.getLabel());
Log.d("VideoSDK", "Device's Kind " + deviceInfo.getKind());
Log.d("VideoSDK", "Device's Facing Mode " + deviceInfo.getFacingMode()) //Value will be null for Audio Devices
}
```

---

### getVideoDevices()

- The `getVideoDevices` method returns a list of currently available video devices. The method returns a list of `VideoDeviceInfo` objects describing the video devices.

- `VideoDeviceInfo` class has four properties :

  1. `VideoDeviceInfo.deviceId`

     - Returns a string that is an identifier for the represented device, persisted across sessions.

  2. `VideoDeviceInfo.label`

     - Returns a string describing this device (for example `BLUETOOTH`).

  2. `VideoDeviceInfo.kind`

     - Returns an enumerated value that is `video` .

  4. `VideoDeviceInfo.FacingMode`

     - Returns a value of type `FacingMode` indicating which camera device is in use (front or back).


#### Returns

- `Set<VideoDeviceInfo>`

#### Example

**Kotlin:**

```js
val videoDevices: Set<VideoDeviceInfo> = VideoSDK.getVideoDevices()
for (videoDevice in videoDevices) {
Log.d("VideoSDK", "Video Device's DeviceId " + videoDevice.deviceId)
Log.d("VideoSDK", "Video Device's Label " + videoDevice.label)
Log.d("VideoSDK", "Video Device's Kind " + videoDevice.kind)
}
```

---

**Java:**

```js
Set<VideoDeviceInfo> videoDevices = VideoSDK.getVideoDevices();
for (VideoDeviceInfo videoDevice:
    videoDevices) {
Log.d("VideoSDK", "Video Device's DeviceId " + videoDevice.getDeviceId());
Log.d("VideoSDK", "Video Device's Label " + videoDevice.getLabel());
Log.d("VideoSDK", "Video Device's Kind " + videoDevice.getKind());
}
```

---

### getAudioDevices()

- The `getAudioDevices` method returns a list of currently available audio devices. The method returns a list of `AudioDeviceInfo` objects describing the audio devices.

- `AudioDeviceInfo` class has three properties :

  1. `AudioDeviceInfo.deviceId`

     - Returns a string that is an identifier for the represented device, persisted across sessions.

  2. `AudioDeviceInfo.label`

     - Returns a string describing this device (for example `BLUETOOTH`).

  3. `AudioDeviceInfo.kind`

     - Returns an enumerated value that is `audio`.

#### Returns

- `Set<AudioDeviceInfo>`

#### Example

**Kotlin:**

```js
val audioDevices: Set<AudioDeviceInfo> = VideoSDK.getAudioDevices()
for (audioDevice in audioDevices) {
Log.d("VideoSDK", "Audio Device's DeviceId " + audioDevice.deviceId)
Log.d("VideoSDK", "Audio Device's Label " + audioDevice.label)
Log.d("VideoSDK", "Audio Device's Kind " + audioDevice.kind)
}
```

---

**Java:**

```js
Set<AudioDeviceInfo> audioDevices = VideoSDK.getAudioDevices();
for (AudioDeviceInfo audioDevice:
 audioDevices) {
Log.d("VideoSDK", "Audio Device's DeviceId " + audioDevice.getDeviceId());
Log.d("VideoSDK", "Audio Device's Label " + audioDevice.getLabel());
Log.d("VideoSDK", "Audio Device's Kind " + audioDevice.getKind());
}
```

---

### setAudioDeviceChangeListener()

- The `AudioDeviceChangeEvent` is emitted when an audio device, is connected to or removed from the device. This event can be set by using `setAudioDeviceChangeListener()` method.

#### Parameters

- **audioDeviceChangeEvent**: AudioDeviceChangeEvent

#### Returns

- _`void`_

#### Example

**Kotlin:**

```javascript
VideoSDK.setAudioDeviceChangeListener { selectedAudioDevice: AudioDeviceInfo, audioDevices: Set<AudioDeviceInfo> ->
Log.d(
    "VideoSDK",
    "Selected Audio Device: " + selectedAudioDevice.label
)
for (audioDevice in audioDevices) {
    Log.d("VideoSDK", "Audio Devices" + audioDevice.label)
}
}
```

---

**Java:**

```javascript
VideoSDK.setAudioDeviceChangeListener((selectedAudioDevice, audioDevices) -> {
Log.d("VideoSDK", "Selected Audio Device: " + selectedAudioDevice.getLabel());
for (AudioDeviceInfo audioDevice :
        audioDevices) {
    Log.d("VideoSDK", "Audio Devices" + audioDevice.getLabel());
}
});
```

---

### checkPermissions()

- The `checkPermissions()` method verifies whether permissions to access camera and microphone devices have been granted. If the required permissions are not granted, the method will proceed to request these permissions from the user.

#### Parameters

- context

  - type: `Context`
  - `REQUIRED`
  - The android context.

- permission

  - type: `List<Permission>`
  - `REQUIRED`
  - The permission to be requested.

- permissionHandler

  - type: `PermissionHandler`
  - `REQUIRED`
  - The permission handler object for handling callbacks of various user actions such as permission granted, permission denied, etc.

- rationale

  - type: `String`
  - `OPTIONAL`
  - Explanation to be shown to user if they have denied permission earlier. If this parameter is not provided, permissions will be requested without showing the rationale dialog.

- options

  - type: `Permissions.Options`
  - `OPTIONAL`
  - The options object for setting title and description of dialog box that prompts users to manually grant permissions by navigating to device settings. If this parameter is not provided,the default title and decription will be used for the dialog box.

#### Returns

- _`void`_

#### Example

**Kotlin:**

```js
private val permissionHandler: PermissionHandler = object : PermissionHandler() {
override fun onGranted() {}
override fun onBlocked(
    context: Context,
    blockedList: java.util.ArrayList<Permission>
): Boolean {
    for (blockedPermission in blockedList) {
        Log.d("VideoSDK Permission", "onBlocked: $blockedPermission")
    }
    return super.onBlocked(context, blockedList)
}

override fun onDenied(
    context: Context,
    deniedPermissions: java.util.ArrayList<Permission>
) {
    for (deniedPermission in deniedPermissions) {
        Log.d("VideoSDK Permission", "onDenied: $deniedPermission")
    }
    super.onDenied(context, deniedPermissions)
}

override fun onJustBlocked(
    context: Context,
    justBlockedList: java.util.ArrayList<Permission>,
    deniedPermissions: java.util.ArrayList<Permission>
) {
    for (justBlockedPermission in justBlockedList) {
        Log.d("VideoSDK Permission", "onJustBlocked: $justBlockedPermission")
    }
    super.onJustBlocked(context, justBlockedList, deniedPermissions)
}
}
val permissionList: MutableList<Permission> = ArrayList()
permissionList.add(Permission.audio)
permissionList.add(Permission.video)
permissionList.add(Permission.bluetooth)
val rationale = "Please provide permissions"
val options =
Permissions.Options().setRationaleDialogTitle("Info").setSettingsDialogTitle("Warning")
//If you wish to disable the dialog box that prompts 
//users to manually grant permissions by navigating to device settings, 
//you can set options.sendDontAskAgainToSettings(false)
VideoSDK.checkPermissions(this, permissionList, rationale, options, permissionHandler)
```

---

**Java:**

```js
private final PermissionHandler permissionHandler = new PermissionHandler() {
@Override
public void onGranted() {
}

@Override
public boolean onBlocked(Context context, ArrayList<Permission> blockedList) {
    for (Permission blockedPermission :
            blockedList) {
        Log.d("VideoSDK Permission", "onBlocked: " + blockedPermission);
    }
    return super.onBlocked(context, blockedList);
}

@Override
public void onDenied(Context context, ArrayList<Permission> deniedPermissions) {
    for (Permission deniedPermission :
            deniedPermissions) {
        Log.d("VideoSDK Permission", "onDenied: " + deniedPermission);
    }
    super.onDenied(context, deniedPermissions);
}

@Override
public void onJustBlocked(Context context, ArrayList<Permission> justBlockedList, ArrayList<Permission> deniedPermissions) {
    for (Permission justBlockedPermission :
            justBlockedList) {
        Log.d("VideoSDK Permission", "onJustBlocked: " + justBlockedPermission);
    }
    super.onJustBlocked(context, justBlockedList, deniedPermissions);
}
};
List<Permission> permissionList = new ArrayList<>();
permissionList.add(Permission.audio);
permissionList.add(Permission.video);
permissionList.add(Permission.bluetooth);
String rationale = "Please provide permissions";
Permissions.Options options =
    new Permissions.Options().setRationaleDialogTitle("Info").setSettingsDialogTitle("Warning");
//If you wish to disable the dialog box that prompts 
//users to manually grant permissions by navigating to device settings, 
//you can set options.sendDontAskAgainToSettings(false)
VideoSDK.checkPermissions(this, permissionList, rationale, options, permissionHandler);
```

---

### setSelectedAudioDevice()

- It sets the selected audio device, allowing the user to specify which audio device to use in the meeting.

#### Parameters

- **selectedAudioDevice**: AudioDeviceInfo

#### Returns

- _`void`_

#### Example

**Kotlin:**

```js
val audioDevices: Set<AudioDeviceInfo> = VideoSDK.getAudioDevices()
val audioDeviceInfo: AudioDeviceInfo = audioDevices.toTypedArray().get(0) as AudioDeviceInfo
VideoSDK.setSelectedAudioDevice(audioDeviceInfo)
```

---

**Java:**

```js
Set<AudioDeviceInfo> audioDevices = VideoSDK.getAudioDevices();
AudioDeviceInfo audioDeviceInfo = (AudioDeviceInfo) audioDevices.toArray()[0];
VideoSDK.setSelectedAudioDevice(audioDeviceInfo);
```

---

### setSelectedVideoDevice()

- It sets the selected video device, allowing the user to specify which video device to use in the meeting.

#### Parameters

- **selectedVideoDevice**: VideoDeviceInfo

#### Returns

- _`void`_

#### Example

**Kotlin:**

```js
val videoDevices: Set<VideoDeviceInfo> = VideoSDK.getVideoDevices()
val videoDeviceInfo: VideoDeviceInfo = videoDevices.toTypedArray().get(1) as VideoDeviceInfo
VideoSDK.setSelectedVideoDevice(videoDeviceInfo)
```

---

**Java:**

```js
Set<VideoDeviceInfo> videoDevices = VideoSDK.getVideoDevices();
VideoDeviceInfo videoDeviceInfo = (VideoDeviceInfo) videoDevices.toArray()[1];
VideoSDK.setSelectedVideoDevice(videoDeviceInfo);
```

---

### applyVideoProcessor()

- This method allows users to dynamically apply virtual background to their video stream during a live session.

#### Parameters

- videoFrameProcessor

  - type: `VideoFrameProcessor`
  - This is an object of the `VideoFrameProcessor` class, which overrides the `onFrameCaptured(VideoFrame videoFrame)` method.

#### Returns

- _`void`_

#### Example

**Kotlin:**

```js
val uri = Uri.parse("https://st.depositphotos.com/2605379/52364/i/450/depositphotos_523648932-stock-photo-concrete-rooftop-night-city-view.jpg")
val backgroundImageProcessor = BackgroundImageProcessor(uri)
VideoSDK.applyVideoProcessor(backgroundImageProcessor)
```

---

**Java:**

```java
Uri uri = Uri.parse("https://st.depositphotos.com/2605379/52364/i/450/depositphotos_523648932-stock-photo-concrete-rooftop-night-city-view.jpg");
BackgroundImageProcessor backgroundImageProcessor = new BackgroundImageProcessor(uri)
VideoSDK.applyVideoProcessor(backgroundColorProcessor);
```

---

### removeVideoProcessor()

- This method provides users with a convenient way to revert their video background to its original state, removing any previously applied virtual background.

   - **Returns:**
      - _`void`_

#### Example

```js
VideoSDK.removeVideoProcessor();
```


</div>


---

# VideoSDK Class Properties - Android

<div class="sdk-api-ref-only-h4">

### getSelectedAudioDevice()

- type: `AudioDeviceInfo`

- The `getSelectedAudioDevice()` method will return the object of the audio device, which is currently in use.

---

### getSelectedVideoDevice()

- type: `VideoDeviceInfo`

- The `getSelectedVideoDevice()` method will return the object of the video device, which is currently in use.



</div>


---

# VideoSDK Class

The entry point into real-time communication SDK.

## using VideoSDK Class

The `VideoSDK Class` includes methods and events to initialize and configure the SDK. It is a factory class.




### Parameters


      
      
      
      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>

### Methods


      
      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>

## Example



**Kotlin:**

```js title="initMeeting"
// Configure the token
VideoSDK.config(token)

// Initialize the meeting
Meeting meeting = VideoSDK.initMeeting(
  context,
  meetingId, // required
  name, // required
  micEnabled, // required
  webcamEnabled, // required
  null, // required
  null, // required
  null // required
  )
});
```

---

**Java:**

```js title="initMeeting"
// Configure the token
VideoSDK.config(token)

// Initialize the meeting
Meeting meeting = VideoSDK.initMeeting({
  context,
  meetingId, // required
  name, // required
  micEnabled, // required
  webcamEnabled, // required
  null, // required
  null // required
  null // required
});
```


---

# App Size Optimization - Android

This guide is designed to help developers optimize app size, enhancing performance and efficiency across different devices. By following these best practices, you can reduce load times, minimize storage requirements, and deliver a more seamless experience to users, all while preserving essential functionality.

## Deliver Leaner Apps with App Bundles

Using Android App Bundles (AAB) is an effective way to optimize the size of your application, making it lighter and more efficient for users to download and install. App Bundles allow Google Play to dynamically generate APKs tailored to each device, so users only download the resources and code relevant to their specific configuration. This approach reduces app size significantly, leading to faster installs and conserving storage space on users’ devices.

Recommended Practices:

- `Enable App Bundles`: Configure your build to use the App Bundle format instead of APKs. This will allow Google Play to optimize your app for each device type automatically.

- `Organize Resources by Device Type`: Ensure that resources (like images and layouts) are organized by device type (such as screen density or language) to maximize the benefits of App Bundles.

- `Test Modularization`: If your app contains large, optional features, use dynamic feature modules to let users download them on demand. This reduces the initial download size and provides features only as needed.

- `Monitor Size Reductions`: Regularly analyze your app size to see where the most savings occur, and make sure that App Bundle optimizations are effectively reducing your app size across different device configurations.

### Optimize Libraries for a Leaner App Experience

Managing dependencies carefully is essential for minimizing app size and improving performance. Every library or dependency included in your app adds to its overall size, so it’s crucial to only incorporate what’s necessary. Optimizing dependencies helps streamline your app, reduce load times, and enhance maintainability.

Recommended Practices:

- `Use Only Essential Libraries`: Review all libraries and dependencies, removing any that are not critical to your app’s functionality. This helps avoid unnecessary bloat.

- `Leverage Lightweight Alternatives`: Whenever possible, choose lightweight libraries or modularized versions of larger ones. For example, opt for a specific feature module rather than including an entire library.

- `Monitor Library Updates`: Regularly update your dependencies to take advantage of any optimizations or size reductions made by the library maintainers. Newer versions are often more efficient.

- `Minimize Native Libraries`: If your app uses native libraries, ensure they’re essential and compatible across platforms, as they can significantly increase app size.

- `Analyze Dependency Tree`: Use tools like Gradle’s dependency analyzer to identify unnecessary or redundant dependencies, ensuring your app’s dependency tree is as lean as possible.


### Optimize with ProGuard

ProGuard is a powerful tool for shrinking, optimizing, and obfuscating your code, which can significantly reduce your app's size and improve performance. By removing unused code and reducing the size of classes, fields, and methods, ProGuard helps to minimize the footprint of your app without sacrificing functionality. Additionally, ProGuard’s obfuscation feature enhances security by making reverse engineering more difficult. You can refer to the official [documentation](https://developer.android.com/build/shrink-code) for more information.

Recommended Practices:

- `Enable ProGuard`: To enable ProGuard in your project, ensure that your `proguard-rules.pro` file is properly configured, and add the following lines to your `build.gradle` file:

```js title="build.gradle"
buildTypes {
    release {
        minifyEnabled true
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    }
}
```

- `Customize ProGuard Rules`: Carefully review and customize ProGuard rules in the proguard-rules.pro file to avoid stripping essential code. For example, to keep a specific class, add:

```js
-keep class com.example.myapp.MyClass { *; }
```

If you encounter an issue after enabling ProGuard rules, refer to our [known issues section](https://docs.videosdk.live/android/guide/video-and-audio-calling-api-sdk/known-issues).

---

# Developer Experience Guidelines - Android

This section provides best practices for creating a smooth and efficient development process when working with VideoSDK. From handling errors gracefully to managing resources and event subscriptions, these guidelines help developers build more reliable and maintainable applications. Following these practices can simplify troubleshooting, prevent common pitfalls, and improve overall application performance.

### Initiate Key Features After Meeting Join Event

To provide a seamless and reliable meeting experience, initiate specific features **only** after the [onMeetingJoined()](https://docs.videosdk.live/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmeetingjoined) event has been triggered.

- **Trigger Key Actions After Joining the Meeting** : Initiating crucial actions after the `onMeetingJoined()` event helps avoid errors and optimizes the meeting setup, ensuring a smoother experience for participants. If your application utilizes any of the following features or you want to perform any action as soon as meeting joins, it's recommended to call them only after the meeting has successfully started:

    - `Chat Subscription`: To enable in-meeting chat functionality, subscribe to the chat topic after the `onMeetingJoined()` event is triggered. This ensures that messages are reliably received by participants.

    <br/>
    <div style={{textAlign: 'center'}}>

    <img src="https://cdn.videosdk.live/docs/best-practices/mobile/android_chat_correct_incorrect_code.png" />

    </div>

    - `Device Management`: If you need users to use specific audio or video devices when the meeting is first joined, you can utilize the [`setSelectedAudioDevice()`](https://docs.videosdk.live/android/api/sdk-reference/videosdk-class/methods#setselectedaudiodevice) and [`setSelectedVideoDevice()`](https://docs.videosdk.live/android/api/sdk-reference/videosdk-class/methods#setselectedvideodevice) methods of `VideoSDK` class.

    - `Recording and Transcription`: To automatically start recording or transcription as soon as the meeting begins, configure the `autoStartConfig` in the `createMeeting` API. For detailed information, refer to the documentation [here](https://docs.videosdk.live/api-reference/realtime-communication/create-room#autoCloseConfig).

### Dispose Custom Tracks When Necessary

Proper disposal of custom tracks is essential for managing system resources and ensuring a smooth experience. In most scenarios, tracks are automatically disposed of by the SDK, ensuring efficient resource management. However, in specific cases outlined below, you will need to dispose of custom tracks explicitly:

1. **When Enabling/Disabling the Camera on a Precall Screen**:
    - If your application includes a precall screen and you want to ensure that the device's camera is not used when the camera is disabled, you must dispose of the custom video track. Otherwise, the device’s camera will continue to be used even when the camera is off.
    - Additionally, remember to create a new track when the user enables the camera again.
    - If you don’t need to manage the camera's usage on the device level (i.e., you’re okay with the camera being used whether it’s enabled or disabled), you can skip this step.
    - Here's how you can manage customTrack on a precall screen :



**Kotlin:**

```js
import live.videosdk.rtc.android.CustomStreamTrack
import live.videosdk.rtc.android.VideoSDK
import live.videosdk.rtc.android.VideoView

class JoinActivity : AppCompatActivity() {
private var videoTrack: CustomStreamTrack? = null
private var joinView: VideoView? = null

private fun toggleWebcam(videoDevice: VideoDeviceInfo?) {
    if (isWebcamEnabled) {
        // check the track state is LIVE
        if(videoTrack?.track?.state()?.equals("LIVE") == true){
            videoTrack?.track?.dispose()  // Dispose the current video track
            videoTrack?.track?.setEnabled(false) // Disable the track
        }
        videoTrack = null
        joinView!!.removeTrack() // Remove the video track from the view
        joinView!!.releaseSurfaceViewRenderer()
        joinView!!.visibility = View.INVISIBLE;
    } else {
        // Re-enabling the webcam by creating a new track
        videoTrack = VideoSDK.createCameraVideoTrack(
            "h720p_w960p",
            "front",
            CustomStreamTrack.VideoMode.TEXT,
            true,
            this,
            videoDevice  // Passes the VideoDeviceInfo object of the user's selected device
        )
        // display in localView
        joinView!!.addTrack(videoTrack!!.track as VideoTrack?)
        joinView!!.visibility = View.VISIBLE
    }
    isWebcamEnabled = !isWebcamEnabled // Toggle webcam state
}
}
```

---

**Java:**

```js
import live.videosdk.rtc.android.CustomStreamTrack
import live.videosdk.rtc.android.VideoSDK
import live.videosdk.rtc.android.VideoView

public class JoinActivity extends AppCompatActivity {
private CustomStreamTrack videoTrack = null;
private VideoView joinView = null;
private boolean isWebcamEnabled = false;

private void toggleWebcam(VideoDeviceInfo videoDevice) {
    if (isWebcamEnabled) {
        // Check if the track state is LIVE
        if (videoTrack != null && "LIVE".equals(videoTrack.getTrack().state())) {
            videoTrack.getTrack().dispose(); // Dispose the current video track
            videoTrack.getTrack().setEnabled(false); // Disable the track
        }
        videoTrack = null;
        joinView.removeTrack(); // Remove the video track from the view
        joinView.releaseSurfaceViewRenderer();
        joinView.setVisibility(View.INVISIBLE);
    } else {
        // Re-enabling the webcam by creating a new track
        videoTrack = VideoSDK.createCameraVideoTrack(
            "h720p_w960p",
            "front",
            CustomStreamTrack.VideoMode.TEXT,
            true,
            this,
            videoDevice // Passes the VideoDeviceInfo object of the user's selected device
        );
        // Display in the local view
        joinView.addTrack((VideoTrack) videoTrack.getTrack());
        joinView.setVisibility(View.VISIBLE);
    }
    isWebcamEnabled = !isWebcamEnabled; // Toggle webcam state
}
}
```


## Listen for Error Events

Listening to error events enables your application to handle unexpected issues efficiently, providing users with clear feedback and potential solutions. Error codes pinpoint specific problems, whether from configuration settings, account restrictions, permission limitations, or device constraints. Here are recommended solutions based on common error categories:

1. [Errors associated with Organization](../../api/sdk-reference/error-codes.md#1-errors-associated-with-organization): If you encounter errors related to your organization (e.g., account status or participant limits), reach out to support at support@videosdk.live or reach out to us on [Discord](https://discord.com/invite/Qfm8j4YAUJ) for assistance.

2. [Errors associated with Token](../../api/sdk-reference/error-codes#2-errors-associated-with-token): For errors related to authentication tokens, ensure the token is valid and hasn’t expired, then try the request again.

3. [Errors associated with Meeting and Participant](../../api/sdk-reference/error-codes#3-errors-associated-with-meeting-and-participant): Check that meetingId and participantId are correctly passed and valid. Also, ensure each participant has a unique participantId to avoid duplicate entries.

4. [Errors associated with Add-on Service](../../api/sdk-reference/error-codes#4-errors-associated-with-add-on-service): If you encounter errors with add-on services (such as recording or streaming), try restarting the service after receiving a failure event. For example, if a `START_RECORDING_FAILED` error event occurs, attempt to call the `startRecording()` method again. If you're using webhooks, you can also retry on [recording-failed](https://docs.videosdk.live/api-reference/realtime-communication/user-webhooks#recording-failed) hook.

5. [Errors associated with Media](../../api/sdk-reference/error-codes#5errors-associated-with-media): Inform the user about media access issues, such as microphone or camera permissions. Design the UI to clearly indicate what is preventing the mic or camera from enabling, helping the user understand the problem.

6. [Errors associated with Track](../../api/sdk-reference/error-codes#6errors-associated-with-track): Ensure that the track you’ve created and passed to enable the mic or camera methods meets the required specifications.

7. [Errors associated with Actions](../../api/sdk-reference/error-codes#7errors-associated-with-actions): If you need to perform actions as soon as a meeting joins, only initiate them after receiving the [onMeetingJoined()](https://docs.videosdk.live/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmeetingjoined) event, otherwise it will not work well.

- Here's how to listen for the error event:

**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  //..
  override fun onError(error: JSONObject) {
  try {
  val errorCodes: JSONObject = VideoSDK.getErrorCodes()
  val code = error.getInt("code")
  Log.d("#error", "Error is: " + error["message"])
  } catch (e: Exception) {
      e.printStackTrace()
  }
  }
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  //..
  @Override
  public void onError(JSONObject error) {
  try {
      JSONObject errorCodes = VideoSDK.getErrorCodes();
      int code = error.getInt("code");
      Log.d("#error", "Error is: " + error.get("message"));
  } catch (Exception e) {
      e.printStackTrace();
  }
  }
};
```


---

# Handle Large Rooms - Android

Managing large meetings requires specific strategies to ensure performance, stability, and a seamless user experience. This section provides best practices for optimizing VideoSDK applications to handle high participant volumes effectively. By implementing these recommendations, you can reduce lag, maintain video and audio quality, and provide a smooth experience even in large rooms.

##  User Interface Optimization

When hosting large meetings, an optimized UI helps manage participant visibility and ensures smooth performance.

Recommended Practices:

- `Limit Visible Participants`: Display only a limited number of participants on screen at any given time, adapting the view based on screen size. Use pagination to allow users to browse or switch between additional participants seamlessly. For example, you could display only users whose video stream is enabled, or you could choose to display all active speakers. This approach helps manage screen space efficiently, ensuring that the most relevant participants are visible without overwhelming the interface.
- `Prioritize Active Speakers`: Ensure all active speakers are displayed on the screen to highlight who is currently talking, helping participants stay engaged and aware of ongoing discussions. To identify which participant is speaking, you can use the [onSpeakerChanged()](https://docs.videosdk.live/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onspeakerchanged) event.

##  Optimizing Media Streams 

In large video calls, it’s important to manage media streams effectively to optimize system resources while maintaining a smooth user experience. 

Recommended Practices:

- `Pause Streams for Non-Visible Participants`: To optimize performance, pause the video and/or audio streams of participants who are not currently visible on the screen. This reduces unnecessary resource consumption.
- `Resume Streams When Visible`: Once a participant comes into view, resume their stream to provide an uninterrupted experience as they appear on the screen.

For detailed setup instructions on how to achieve this, check out our in-depth documentation [here](https://docs.videosdk.live/android/guide/video-and-audio-calling-api-sdk/render-media/layout-and-grid-management#pauseresume-stream).

##  Media Stream Quality Adjustment

In large meetings, managing media stream quality is essential to balance performance and user experience. 

Recommended Practices:

- `High Quality for Active Speakers`: For all active speakers, set the video stream quality to a higher level using the setQuality method (e.g., `setQuality("high")`). This ensures that participants will receive higher-quality video for active speakers, providing a clearer and more engaging experience.
- `Lower Quality for Non-Speaking Participants`: For other participants who are not actively speaking, set their video stream quality to a lower level (e.g., `setQuality("low")`). This helps conserve bandwidth and system resources while maintaining overall meeting performance.

Checkout the documentation for `setQuality()` method [here](https://docs.videosdk.live/android/api/sdk-reference/participant-class/methods#setquality) 


---

# User Experience Guidelines - Android

This guide aims to help developers optimize the user experience and functionality of video conferencing applications with VideoSDK. By following these best practices, you can create smoother interactions, minimize common issues, and deliver a more reliable experience for users.

Here are our recommended best practices to enhance the user experience in your application:

| **Section**                          | **Description**                                                                                                                                                      |
|--------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Configure Precall for Effortless Meeting Join](#configure-precall-for-effortless-meeting-join) | Users may enter meetings unprepared due to device or connection issues. A Precall setup can help them configure devices and settings beforehand for a smooth start. |
| [Listen Key Events for Optimal User Experience](#listen-key-events-for-optimal-user-experience) | Users can feel lost without real-time updates on meeting status, events, and errors. Event monitoring and notifications keep them informed and engaged.              |
| [Handling Media Devices](#handling-media-devices)                                             | Users may want to change their audio or video setup mid-meeting but struggle to manage device controls. Providing easy device switching enhances control and flexibility. |
| [Monitoring Real-Time Participant Statistics](#monitoring-real-time-participant-statistics)   | Poor video or audio quality without real-time feedback leaves users frustrated. Real-time stats let them assess connection quality and troubleshoot issues actively.    |

## Configure Precall for Effortless Meeting Join

A Precall step is crucial for ensuring users are set up correctly and have no device before joining a meeting. This step allows users to configure their devices and settings before entering a meeting, leading to a smoother experience and minimizing technical issues once the call begins.

Recommended Practices:

- `Request Permissions`: Prompt users to grant microphone, and camera permissions before entering the meeting, ensuring seamless access to their devices.
- `Device Selection`: Allow users to select their preferred camera, and microphone giving them control over their setup from the start.
- `Entry Preferences`: Provide options to join with the microphone and camera either on or off, letting users choose their level of engagement upon entry.
- `Camera Preview`: Show a live camera preview, allowing users to adjust angles and lighting to ensure they appear clearly and professionally.
- `Virtual Backgrounds`: Allow users to choose from different virtual backgrounds or enter with a virtual background enabled, enhancing privacy and creating a more polished appearance.

For detailed setup instructions on each of these features, check out our in-depth documentation [here](https://docs.videosdk.live/android/guide/video-and-audio-calling-api-sdk/setup-call/precall).

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_precall.gif" />

</div>

## Monitor Key Events for Optimal User Experience

Listening for crucial events is vital for providing users with a responsive and engaging experience in your application. By effectively managing state changes and user notifications, you can keep participants informed and enhance their overall experience during meetings.

Recommended Practices:

- `Monitor State Change Events`: Listen for state change events, such as `onMeetingStateChanged` and `onRecordingStateChanged`, and notify users promptly about these transitions. Keeping users informed helps them understand the current state of the meeting.

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_meeting_state.jpg" />

</div>

- `UI Handling on Event Trigger`: Update the user interface only in response to specific events. For instance, display that the meeting is recording only when the `onRecordingStateChanged` event with the status `RECORDING_STARTED` is received, rather than when the record button is clicked. This ensures users receive accurate and timely updates.

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_recording.gif" />

</div>

- `Notify Participants of Join/Leave Events`: Keep users informed about participant activity by notifying them when someone joins or leaves the meeting. This fosters a sense of presence and awareness of who is currently available to engage.
- `Listen for Error Events`: It is crucial to monitor error events and notify users promptly when issues arise. Clear communication about errors can help users troubleshoot and address problems quickly, minimizing disruptions to the meeting.


## Handling Media Devices

Providing seamless control over devices enhances user convenience and allows participants to adjust their setup for the best meeting experience. Proper device management within the UI also helps users stay informed about their current settings and troubleshoot issues effectively.

Recommended Practices:

- `Allow Device Switching`: Provide users with the option to switch between available microphone, and camera devices during the meeting. This flexibility is essential, especially if users want to adjust their setup mid-call.
- `Display Selected Devices`: Ensure the UI shows users which microphone, and camera devices are currently selected. Clear device labeling in the interface can reduce confusion and help users verify their setup at a glance.

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_audio_selected_device.jpg" />

</div>

## Monitoring Real-Time Participant Statistics

Providing real-time insights into stream quality allows participants to monitor and optimize their connection for the best experience. With detailed metrics on video, audio, and screen sharing, users can assess and troubleshoot quality issues, ensuring smooth and uninterrupted meetings. To display these statistics, you can use the [getVideoStats()](https://docs.videosdk.live/android/api/sdk-reference/participant-class/methods#getvideostats), [getAudioStats()](https://docs.videosdk.live/android/api/sdk-reference/participant-class/methods#getaudiostats), and [getShareStats()](https://docs.videosdk.live/android/api/sdk-reference/participant-class/methods#getsharestats) methods.


<div style={{textAlign: 'center'}}>



</div>

<br/>

:::note
To show the popup dialog for the participant's realtime stats, you can [refer to this function](https://github.com/videosdk-live/videosdk-rtc-android-kotlin-sdk-example/blob/main/app/src/main/java/live/videosdk/rtc/android/kotlin/Common/Utils/HelperClass.kt#L91).
:::


---

# Face Match API


This API verifies whether two provided images are same or not. It returns a boolean value indicating whether the faces match.

:::important

This API is available in Enterprise plan only.

:::

## HTTP Method and Endpoint

**<span style={{ color: "#86EFAC", fontWeight: "bold" }}>POST</span>** | `https://api.videosdk.live/ai/v1/face-verification/verify`

## Headers Parameter

### Authorization

**values** : YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

_Note_ : the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by referring to this Guide: [Generate Auth token](https://docs.videosdk.live/api-reference/realtime-communication/intro)

### Content-Type

**values** : `application/json`

This is useful for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.

## Data Parameter

#### Base64 Encoding Format

The images should be converted from binary format to a Base64 string




Images must be Base64 encoded in the following format:

```
data:image/jpeg;base64,${Base64data}
```

#### Request Format

The request body should contain two Base64-encoded images in the following format:

```js
const data = {
  img1: "data:image/jpeg;base64,${Base64data}", // Base64-encoded image 1
  img2: "data:image/jpeg;base64,${Base64data}", // Base64-encoded image 2
};
```

## Sending Image Comparison Request

The request is made using the following code:




This sends the encoded images to the specified URL for comparison.

## Code Snippet for API Integration

Below is a code snippet demonstrating how to use the Face Match API (BETA) with Node.js:

```js




// Load environment variables from .env file
dotenv.config();

// Get the directory of the current file
const __dirname = path.resolve();

// Function to read image files and convert them to base64
function getBase64Image(imageName) {
  const filePath = path.join(__dirname, "image", imageName);
  console.log(`Resolved file path: ${filePath}`);
  try {
    const image = readFileSync(filePath);
    const base64Data = Buffer.from(image).toString("base64");
    return `data:image/jpeg;base64,${base64Data}`;
  } catch (error) {
    console.error(`Error reading image file: ${filePath}`, error.message);
    throw error;
  }
}

// Function to perform Face Match
async function faceMatch(ovdImageName, selfieImageName) {
  const url = "https://api.videosdk.live/ai/v1/face-verification/verify";
  const headers = {
    Authorization: `${process.env.API_KEY}`,
    "Content-Type": "application/json",
  };

  const data = {
    img1: getBase64Image(ovdImageName),
    img2: getBase64Image(selfieImageName),
  };

  try {
    const response = await axios.post(url, data, { headers });
    console.log("Face Match Result:", response.data);
  } catch (error) {
    console.error(
      "Error during face match:",
      error.response ? error.response.data : error.message
    );
  }
}

// Main function to run the API calls
async function main() {
  const ovdImageName = "img1.jpg";
  const selfieImageName = "img2.jpg";

  await faceMatch(ovdImageName, selfieImageName);
}

// Run the main function
main().catch((error) =>
  console.error("Error in main function:", error.message)
);
```

## Examples of Face Match API (BETA) Usage

### Example 1 : Matching Images of the Same Person

In this scenario, we take two different pictures of the same individual. For instance:

<div
  style={{ display: "flex", justifyContent: "center", alignItems: "center" }}
>
  <div style={{ textAlign: "center", marginRight: "-15px" }}>
    <img
      src="https://cdn.videosdk.live/website-resources/docs-resources/face_match_girl_1.png"
      alt="Image 1"
      width="90%"
    />
    <p>Image 1</p>
  </div>
  <div style={{ textAlign: "center", marginLeft: "-15px" }}>
    <img
      src="https://cdn.videosdk.live/website-resources/docs-resources/face_match_girl_2.png"
      alt="Image 2"
      width="90%"
    />
    <p>Image 2</p>
  </div>
</div>

When these images are sent to the Face Match API (BETA), the expected output would be:

```
Face Match Result: { "verified": true }
```

This result indicates that despite differences in lighting, angle, or expression, the API successfully recognizes that both images depict the same individual.

### Example 2 : Matching Images of Different Persons

In this case, we compare two photos of different individuals. For example:

<div
  style={{ display: "flex", justifyContent: "center", alignItems: "center" }}
>
  <div style={{ textAlign: "center", marginRight: "-15px" }}>
    <img
      src="https://cdn.videosdk.live/website-resources/docs-resources/face_match_male_1.png"
      alt="Image 1"
      width="90%"
    />
    <p>Image 1</p>
  </div>
  <div style={{ textAlign: "center", marginLeft: "-15px" }}>
    <img
      src="https://cdn.videosdk.live/website-resources/docs-resources/face_match_male_2.png"
      alt="Image 2"
      width="90%"
    />
    <p>Image 2</p>
  </div>
</div>

When these images are processed through the Face Match API (BETA), the expected output would be:

```
Face Match Result: { "verified": false }
```

This result demonstrates the API's ability to differentiate between distinct individuals accurately.







---

# Face Spoof Detection


This API verifies if the image is original or spoofed. It returns a boolean value spoof_detected in output.

:::important

This API is available in Enterprise plan only.

:::

## HTTP Method and Endpoint

**<span style={{ color: "#86EFAC", fontWeight: "bold" }}>POST</span>** | `POST https://api.videosdk.live/ai/v1/face-verification/detect-spoof`

## Headers Parameter

### Authorization

**values** : YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

_Note_ : the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by refering this Guide: [Generate Auth token](https://docs.videosdk.live/api-reference/realtime-communication/intro)

### Content-Type

**values** : `application/json`

This is usefull for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.




## Data Parameter

#### Base64 Encoding Format

The images should be converted from binary format to a Base64 string




Images must be Base64 encoded in the following format:

```
data:image/jpeg;base64,${Base64data}
```

#### Request Format

The request body should contain two Base64-encoded images in the following format:

```js
const data = {
  img: "data:image/jpeg;base64,${Base64data}", // Base64-encoded image
};
```

## Sending Image Comparison Request

The request is made using the following code:




This sends the encoded images to the specified URL for comparison.

## Code Snippet for API Integration

Below is a code snippet demonstrating how to use the Face Spoof Detection API (BETA) with Node.js:

```js




// Load environment variables from .env file
dotenv.config();

// Get the directory of the current file
const __dirname = path.resolve();

// Function to read image files and convert them to base64
function getBase64Image(imageName) {
  const filePath = path.join(__dirname, "image", imageName);
  console.log(`Resolved file path: ${filePath}`);
  try {
    const image = readFileSync(filePath);
    const base64Data = Buffer.from(image).toString("base64");
    return `data:image/jpeg;base64,${base64Data}`;
  } catch (error) {
    console.error(`Error reading image file: ${filePath}`, error.message);
    throw error;
  }
}

async function spoofDetection(spoofimg) {
  const url = "https://api.videosdk.live/ai/v1/face-verification/detect-spoof";
  const headers = {
    Authorization: `${process.env.API_KEY}`,
    "Content-Type": "application/json",
  };
  const data = {
    img: getBase64Image(spoofimg),
  };

  try {
    const response = await axios.post(url, data, { headers });
    console.log(response.data);
  } catch (error) {
    console.error(
      "Error during spoof detection:",
      error.response ? error.response.data : error.message
    );
  }
}

// Main function to run the API calls
async function main() {
  const spoofimg = "img.jpg";
  await spoofDetection(spoofimg);
}

// Run the main function
main().catch((error) =>
  console.error("Error in main function:", error.message)
);
```

##### Given below is a test run of the example.

**Input Image** :

<div
  style={{
    display: "flex",
    justifyContent: "left",
    alignItems: "left",
    gap: "10px",
  }}
>
  <img
    src="https://cdn.videosdk.live/website-resources/docs-resources/input_spoof.jpg"
    alt="Image 1"
    width="45%"
  />
</div>

When this image is sent to the Face Spoof Detection API (BETA), the response will return a boolean value spoof_detected in output :

```js
{
  spoof_detected: true; // true if spoof detected in image else false
  accuracy: 0.9899068176746368; // accuracy of spoof detection
}
```


---

# Number of Face Detection


This API checks how many faces are there in the image and returns an int value number_of_faces in output.

:::important

This API is available in Enterprise plan only.

:::

## HTTP Method and Endpoint

**<span style={{ color: "#86EFAC", fontWeight: "bold" }}>POST</span>** | `https://api.videosdk.live/ai/v1/face-verification/detect-faces`

## Headers Parameter

### Authorization

**values** : YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

_Note_ : the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by refering this Guide: [Generate Auth token](https://docs.videosdk.live/api-reference/realtime-communication/intro)

### Content-Type

**values** : `application/json`

This is usefull for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.




## Data Parameter

#### Base64 Encoding Format

The images should be converted from binary format to a Base64 string




Images must be Base64 encoded in the following format:

```
data:image/jpeg;base64,${Base64data}
```

#### Request Format

The request body should contain two Base64-encoded images in the following format:

```js
const data = {
  img: "data:image/jpeg;base64,${Base64data}", // Base64-encoded image
};
```

## Sending Image Comparison Request

The request is made using the following code:




This sends the encoded images to the specified URL for comparison.

## Code Snippet for API Integration

Below is a code snippet demonstrating how to use the number of faces detection API with Node.js:

```js




// Load environment variables from .env file
dotenv.config();

// Get the directory of the current file
const __dirname = path.resolve();

// Function to read image files and convert them to base64
function getBase64Image(imageName) {
  const filePath = path.join(__dirname, "image", imageName);
  console.log(`Resolved file path: ${filePath}`);
  try {
    const image = readFileSync(filePath);
    const base64Data = Buffer.from(image).toString("base64");
    return `data:image/jpeg;base64,${base64Data}`;
  } catch (error) {
    console.error(`Error reading image file: ${filePath}`, error.message);
    throw error;
  }
}

async function noOfFaces(getImg) {
  const url = "https://api.videosdk.live/ai/v1/face-verification/detect-faces";
  const headers = {
    Authorization: `${process.env.API_KEY}`,
    "Content-Type": "application/json",
  };
  const data = {
    img: getBase64Image(getImg),
  };

  try {
    const response = await axios.post(url, data, { headers });
    console.log(response.data);
  } catch (error) {
    console.error(
      "Error during Number of face detection :",
      error.response ? error.response.data : error.message
    );
  }
}

// Main function to run the API calls
async function main() {
  const getImg = "img1.jpg";
  await spoofDetection(getImg);
}

// Run the main function
main().catch((error) =>
  console.error("Error in main function:", error.message)
);
```

##### Given below is a test run of the example.

**Input Image** : group_photo.jpg - A photo showing a group of five people.

<div style={{ display: "flex", alignItems: "center", gap: "10px" }}>
  <img
    src="https://cdn.videosdk.live/website-resources/docs-resources/group_of_people.jpg"
    alt="Image 1"
    width="45%"
  />
</div>

When this image is sent to the Face Detection API, The response will return an int value number_of_faces in output :

```js
{
  number_of_faces: 5; // number of faces detected
}
```







---

# OCR API


---
title: Ocr | Android SDK Documentation | VideoSDK
description: Learn how to implement ocr using VideoSDK's Android SDK. Step-by-step integration guide for seamless identity verification or SIP connectivity.
---

This API will take front and back part of the document in input, scan through the document and return all the available fields of the document in JSON formatted response. Fields can vary as per type of document in response..

:::important

This API is available in Enterprise plan only.

:::

## HTTP Method and Endpoint

**<span style={{ color: "#86EFAC", fontWeight: "bold" }}>POST</span>** | `https://api.videosdk.live/ai/v1/ocr`

## Headers Parameter

### Authorization

**values** : YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

_Note_ : the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by referring this Guide: [Generate Auth token](https://docs.videosdk.live/api-reference/realtime-communication/intro)

### Content-Type

**values** : `application/json`

This is useful for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.




## Data Parameter

#### Base64 Encoding Format

The images should be converted from binary format to a Base64 string




Images must be Base64 encoded in the following format:

```
data:image/jpeg;base64,${Base64data}
```

#### Request Format

The request body should contain two Base64-encoded images in the following format:

```
const data = {
   "frontpart": "data:image/jpeg;base64,${Base64data}", // Base64-encoded image
   "backpart": "data:image/jpeg;base64,${Base64data}", // Base64-encoded image
}
```

## Sending Image Comparison Request

The request is made using the following code:




This sends the encoded images to the specified URL for comparison.

## Response

The response will return all the available fields of document in JSON formated response :

```javascript
{
   idType: "", // document Type
   idNumber: "", // document Number
   name: "", // name
   dateOfBirth: "",
   address: "",
   gender: "",
   mobileNumber: ""
};
```

## Code Snippet for API Integration

Below is a code snippet demonstrating how to use OCR API (BETA) with Node.js:

```javascript




// Load environment variables from .env file
dotenv.config();

// Get the directory of the current file
const __dirname = path.resolve();

// Function to read image files and convert them to base64
function getBase64Image(imageName) {
  const filePath = path.join(__dirname, "image", imageName);
  console.log(`Resolved file path: ${filePath}`);
  try {
    const image = readFileSync(filePath);
    const base64Data = Buffer.from(image).toString("base64");
    return `data:image/jpeg;base64,${base64Data}`;
  } catch (error) {
    console.error(`Error reading image file: ${filePath}`, error.message);
    throw error;
  }
}

async function ocr(frontImg, backImg) {
  const url = "https://api.videosdk.live/ai/v1/ocr";
  const headers = {
    Authorization: `${process.env.API_KEY}`,
    "Content-Type": "application/json",
  };
  const data = {
    frontPart: getBase64Image(frontImg),
    backPart: getBase64Image(backImg),
  };

  try {
    const response = await axios.post(url, data, { headers });
    console.log(response.data);
  } catch (error) {
    console.error(
      "Error during OCR :",
      error.response ? error.response.data : error.message
    );
  }
}

// Main function to run the API calls
async function main() {
  const frontImg = "img4.jpg";
  const backImg = "img5.jpg";
  await ocr(frontImg, backImg);
}

// Run the main function
main().catch((error) =>
  console.error("Error in main function:", error.message)
);
```







---

# Understanding Analytics Dashboard - Android

Welcome to the world of actionable insights and empowered decision-making. VideoSDK's session analytics dashboard is your gateway to understanding, optimizing, and elevating every aspect of your sessions.

## Accessing Analytics Made Easy

Navigating through session data is a breeze with VideoSDK. Simply head to your session page at https://app.videosdk.live/meetings/sessions, where a treasure trove of session information awaits.

### How to Access Analytics?

Open Session Analytics effortlessly by following these steps:

1. **Click on Meeting-ID:**
    - Directly access analytics by clicking on the meeting-ID within the session table.
2. **Hover and Click View Analytics:**
    - Hover over a specific meeting row to reveal the **View Analytics** button in the Actions Column.
    - Click on **View Analytics** to open the Session Overview sidebar, unlocking a wealth of insights.

![Access Analytics](https://cdn.videosdk.live/website-resources/docs-resources/access_analytics.png)

---

There are three tabs available within the session analytics view:

## **1. Session Overview**

This tab provides an overview of the session, including its duration and participant details. You can explore individual participant statistics to understand their session performance better.

## **2. Errors**

In this tab, you can find information about any errors encountered during the session. It helps you identify and address issues like network problems or technical glitches promptly.

## **3. Session Stats**

Explore data and metrics sent and received by participants to measure performance of the session in this tab. It offers insights into data exchange among participants, including metrics on jitter, RTT, and packet loss, resolutions, and fps aiding in assessing communication efficiency.

Let's dive deeper into each of these tabs to gain a better understanding of session analytics.

# Session Overview

The session overview page is your compass in the sea of data. Here's what you'll uncover:

- **Meeting ID:** Unique identifier for the meeting in the format of `abcd-efgh-ijkl`.
- **Session ID:** Unique identifier for each session, uniquely identified by its `sessionId`.
- **Session Status:** Indicates if the session is ongoing or ended.
- **Session Initiating Time:** Time taken by the first participant to establish the connection.
- **Start and End Time:** Marks the start and end of the session.
- **Total Unique Participants Joined:** Total number of unique participants in the session.
- **Total Session Duration:** Overall duration of the session from start to end.
- **Total Participant Minutes:** A sum of all participant duration.
- **Recording, HLS, RTMP:** Additional services used in the session.

### Participant Table List

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for each participant.
- **Join Time:** Time taken by the participant to establish connection.
- **Duration:** Total time spent by this participant in the session.

### Efficient Session Management with Actions

Enhance your session management with streamlined actions:

- **Kick Out Participants:** Effortlessly remove/kickout participants from ongoing sessions.
- **Detailed Participant Analytics:**
- Hover over a specific participant row to reveal the `View Stats` button at the end of the row.
- Click on `View Stats` to open the Participant Overview sidebar.
    
![View Stats](https://cdn.videosdk.live/website-resources/docs-resources/view_stats.png)

## Explore Participant Insights

Discover valuable participant data that provides a clear view of engagement and experience:

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for better interaction.
- **Joined At:** Indicates the precise moment when participant connects to the session.
- **Left At:** Indicates the precise moment when participant left the session.
- **Total Duration:** Total duration of participant within that session.
- **Joining Time:** Time taken by the this participant to establish the connection.
- **Location:** Approx. geographic location from where the participant joined.
- **Platform:** Specifies whether participants are using a desktop or mobile device.
- **Device Info:** Offers details regarding the participant's device.
- **OS:** Provides information about the participant's OS.
- **Browser:** Provides specifics about the participant's browser
- **SDK Version:** Indicates the version of the SDK used by participants.

### Understanding Participant Call Health

We've developed call health to offer a rapid assessment of participant performance during calls. This feature highlights the performance of audio, video, and screen sharing audio-video separately. We've utilized color theory, with green indicating good performance, orange for moderate, and red for poor performance, to enhance clarity. For detailed insights, simply hover over the bars

![Participant Call Health](https://cdn.videosdk.live/website-resources/docs-resources/participant_call_health.png)

## Participant Session Stats

Dive into Participant Session Stats for valuable insights into your session experience! With just a click on `View Session Stats` at the bottom of the page, unlock a treasure trove of data crucial for understanding audio and video experiences.

Within this section, you can observe quality metrics for the selected participant, comparing them to others. Additionally, the `Sessions Stats` covers quality stats comparison for every participant. Keep reading to explore more about Session Stats.

**Visualizing Session Performance from Both Sides**

This section provides a two-sided view of your session's metrics.

- **Left Side: Sender Participant Graph** This section displays graphs representing the metrics sent by the sender participant.. Here, you can see how the various factors impacted the data you transmitted.
- **Right Side: Receiver Participant Graph** On the right side, you'll find a dropdown menu where you can select a specific participant. Choosing a receiver will display graphs showcasing the metrics **received by that participant**. This allows you to compare the sending experience (left side) with the receiving experience (right side) for different participants.

![VideoSDK Jitter Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_jitter_graph.png)

**See How Your Session Performed**

These metrics give you a clear picture of your session's quality. Understanding them helps you spot any issues and keep things running smoothly. Let's dive into what each metric means!

**Jitter:** Imagine your internet connection like a bumpy road. Jitter is how much those bumps cause your signal to bounce around. Less jitter means a smoother ride for your data (audio and video, threshold ≤ 30ms).

**RTT (Latency):** This is how long it takes for data to travel between you and the server you're connected to. Think of it like the time it takes for a message to get delivered – a lower RTT means a faster delivery (affects both audio and video, threshold ≤ 300ms).

**Bitrate:** This measures the amount of data flowing through your connection per second. Imagine it like the width of a water pipe – a higher bitrate allows for more data to flow, which can be good for high-quality audio/video or fast downloads.

**Packet Loss:** Think of data traveling in tiny packets. Packet loss is when some of those packets get dropped along the way. More packet loss means information might be missing, affecting things like audio/video quality or lag in games (threshold ≤ 5%).

**Resolution:** This refers to the sharpness and detail of an image or video. Think of it like the number of pixels on your screen – a higher resolution means a crisper picture (**Video Only**).

**FPS (Frames Per Second):** This measures how many images (frames) are displayed on your screen every second. Imagine it like a flipbook – a higher FPS creates a smoother and more fluid animation or video experience (**Video Only**).

![VideoSDK FPS Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_fps_graph.png)

![VideoSDK Resolution Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_resolution_graph.png)

---

# **Investigate Session Errors**

Get to the root of smoother sessions by addressing errors directly. Use the Errors tab to explore details of errors encountered during your session. Note: Session errors are visible with JS SDK v0.0.82 or higher, React SDK v0.1.85 or higher, and React Native v0.1.6 or newer versions.

- **Participant Name & ID:** Quickly identify the participant associated with each error for swift resolution.
- **Error Types:** Understand the different types of errors encountered, such as network issues or connection disruptions.
- **Detailed Descriptions:** Access clear explanations of errors to take actionable steps towards solution.

![VideoSDK Error Details](https://cdn.videosdk.live/website-resources/docs-resources/error_new.png)

# **Analyse Session Stats**

Similar to `Participant Session Stats`, this tab covers quality statistics sent by individual participants. You can select any participant to compare effectively with others.

Choose a sender participant from the dropdown menu on the left and select a recipient on the right to compare data over different time frames. This allows you to identify and explore issues within specific durations.

This tab covers the same metrics as covered in the `participant session stats`: Jitter, RTT (Latency), Bitrate, Packet-loss, Resolution (Video only), and FPS (Video only).

![VideoSDK Session Stats](https://cdn.videosdk.live/website-resources/docs-resources/session_stats.png)


---

# Understanding Call Quality - Android

When developing a video call app, customer satisfaction heavily depends on the app's video and audio quality and its fluctuation.

## Call Quality

From the user's perspective, good video quality is defined as smooth and clear video, along with crystal clear audio. Developers consider good video quality as high-resolution, high-frame-rate video with minimal latency and high-bitrate audio with minimal audio loss.

## Factors affecting Quality

When measuring video and audio quality, several variables come into play. The common factors affecting quality are as follows:

### `1. Network Bandwidth`

- Network bandwidth is the measure of a user's network capacity, indicating how much data can be received and sent.
- If the participant's bandwidth is low, they are likely to experience pixelated or frozen video, along with robotic voice or minor audio interruptions.
- Frequent changes in network providers can also lead to significant fluctuations in internet bandwidth, resulting in poor video quality.

### `2. Latency`

- Latency refers to the time it takes for data to transfer from one machine to another.
- If the meeting is hosted in `Ohio` region, and users are joining from `Singapore` region, this can result in a long delay for data to transfer between mackines. Therefore, it is advisable to choose a server based on your user base.
- With VideoSDK, you can specify the server during the creation of a Meeting/Room.

### `3. CPU Usage`

- CPU Usage is also a determining factor, as all the audio and video streams going out and coming in need to be encoded or decoded, requiring a significant amount of computation.
- The higher the resolution and frame rate of the videos, the greater the computation required, which can lead to a bottleneck in delivering good-quality video.
- If the CPU is heavily consumed, it can also result in choppy or robotic audio.

### `4. Camera and Mic Quality`

- The camera and microphone should capture high-quality streams to ensure that remote users don't receive a low-quality stream even if they have bad network bandwidth.

## Identifying various issues related to Quality.

In order to identify potential issues, VideoSDK collects various audio and video-related metrics that can help pinpoint quality concerns. Take a look at these metrics and understand what they indicate.

### `1. Resolution and Framerate`

- Resolution and frame rate serve as crucial metrics for video quality in a video call app. Resolution indicates the number of pixels in a video image, while frame rate denotes the number of frames displayed per second.

- While higher resolutions and frame rates can enhance video quality, they also demand more bandwidth and processing power. It's essential to optimize these metrics based on the devices and network conditions of your users.

- For instance, if the majority of your users are on mobile devices, opting for a lower resolution and frame rate may be more suitable to ensure smooth playback and minimize bandwidth usage.

- If your user base comprises both mobile and desktop devices, adopting higher resolution for desktops and mid-resolutions for mobile devices can contribute to improved performance and quality while conserving bandwidth on mobile devices.

### `2. Bitrate`

- Bitrate represents the number of bits per second transmitted or received during the transmission of audio or video streams. It is a crucial parameter for assessing the quality of audio or video streams and should be adjusted for each resolution to strike a balance between performance and bandwidth utilization.

- In scenarios with excellent network conditions, a higher bitrate can lead to significantly improved video quality. However, it's essential to be cautious when dealing with very high bitrates on mobile devices, as it may result in heating issues due to the substantial computational requirements for encoding and decoding videos.

##### Example

We used the same phone **(iPhone 14)**, for both participants, but there were differences in resolution and bitrate. The first participant had a resolution of **`1280x720`** with a bitrate of **`1442 kbps`**, while the second participant had a resolution of **`960x540`** with a bitrate of **`642 kbps`**. Surprisingly, both participants' videos appeared to be of equal quality despite variations in resolution and bitrate.

![resolution-and-bitrate](/img/resolution-and-bitrate.png)

### `3. Packet Loss`

- Packet loss is a metric that reveals the number of lost data packets during transmission from the sender to the receiver. It can happen due to network congestion, hardware or software issues, or network latency. Increased packet loss can lead to degraded video and audio quality, as the absence of packets may cause gaps or distortions in the media stream.


<div style={{textAlign: 'center'}}>



</div>

### `4. Jitter`

- The audio and video packets are sent out at random intervals over a specified time frame as they travel between the server and client. Jitter occurs when there is a variation in transmitting or receiving these data packets due to a faulty network connection.

- When data packets experience delays during transmission to the participant, usually because the network is busy, they may result in pixelated video during a video call or sound choppy, distorted, or robotic in a voice call upon arrival. This creates jitter, with packets arriving at random intervals.

### `5. Round Trip Time (Latency)`

- Round trip time refers to the duration it takes for data packets to be transmitted from the user's device to the server and back. If the servers are located far from the user's location, they may experience high latency (delay).

- With VideoSDK, this factor is addressed as we automatically choose the nearest available server for participants. However, if you are geofencing to a specific region, ensure that you choose the server nearest to your users.

<center>

![resolution-and-bitrate](/img/rtt.png)

</center>

## Checking Realtime Statistics

VideoSDK provides methods to check the realtime statistics of audio and video of all the participants.

### `getVideoStats()`

- The `getVideoStats()` method returns an object containing the different quality parameters for video stream, which can be accessed through the `useParticipant` hook.

- This object will contain values for the specific participant's video stream, including resolution, frame rate, bitrate, jitter, round trip time, and packet loss.

<div style={{textAlign: 'center'}}>



</div>

### `getAudioStats()`

- The `getAudioStats()` method returns an object containing the different quality parameters for audio stream, which can be accessed through the `useParticipant` hook.

- This object will contain values for the specific participant's audio stream, including bitrate, jitter, round trip time and packet loss.

### `getShareStats()`

- The `getShareStats()` method returns an object containing the different quality parameters for screen share stream, which can be accessed through the `useParticipant` hook.

- This objects will contain values for the specific participant's screen share stream, including resolution, frame rate, bitrate, jitter, round trip time, and packet loss.

### `getShareAudioStats()`

- The `getShareAudioStats()` method returns an object containing the different quality parameters for screen share audio stream, which can be accessed through the `useParticipant` hook.

- This object will contain values for the specific participant's screen share audio stream, including bitrate, jitter, round trip time and packet loss.

:::note
To show the popup dialog for the participant's realtime stats, you can [refer to this component](https://github.com/videosdk-live/videosdk-rtc-react-sdk-example/blob/main/src/utils/common.js#L142).
:::

## Quality analysis Graphs

For all sessions conducted using VideoSDK, you can access quality analysis graphs from the [VideoSDK Dashboard](https://app.videosdk.live/meetings/sessions). These graphs help you visualize real-time data and identify spikes in certain parameters during calls, aiding in understanding the reasons for quality issues.

![quality analysis](/img/quality-analysis.png)

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [getVideoStats()](/android/api/sdk-reference/participant-class/methods#getvideostats)
- [getAudioStats()](/android/api/sdk-reference/participant-class/methods#getaudiostats)
- [getShareStats()](/android/api/sdk-reference/participant-class/methods#getsharestats)


---

# Change Mode - Android

In a live stream, audience members usually join in `RECV_ONLY` mode, meaning they can only view and listen to the hosts. However, if a host invites an audience member to actively participate (e.g., to speak or present), the audience member can switch their mode to `SEND_AND_RECV` using the changeMode() method.

This guide explains how to use the changeMode() method and walks through a sample implementation where a host invites an audience member to become a host using PubSub.

### `changeMode()`

- The `changeMode()` method from the `Meeting` class allows a participant to switch between modes during a live stream—for example, from audience to host.

#### Example



**Kotlin:**

```js
class LiveStreamActivity : AppCompatActivity() {
 override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_live_stream);
// initialize the meeting
liveStream = VideoSDK.initMeeting(... )
...

// join meeting
liveStream!!.join()

// Button to change mode
val changeModeBtn: Button = findViewById(R.id.btnChangeMode)
changeModeBtn.setOnClickListener {
    liveStream.changeMode(MeetingMode.SEND_AND_RECV)
}
  }
}
```

---

**Java:**

```java
public class LiveStreamActivity extends AppCompatActivity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_live_stream);
// initialize the meeting
Meeting liveStream = VideoSDK.initMeeting( ...);
...

// join meeting
liveStream.join()  

// Button to change mode
Button changeModeBtn = findViewById(R.id.btnChangeMode);
changeModeBtn.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View v) {
        liveStream.changeMode(MeetingMode.SEND_AND_RECV);
    }
});
  
  }
}
```

#### Implementation Guide

#### Step 1 : Create a Pubsub Topic

- Set up a PubSub topic to send a mode change request from the host to a specific audience member.

**Kotlin:**

```js
fun sendInvite(livestream: Meeting, participantId: String) {
val pubSubPublishOptions = PubSubPublishOptions().apply {
    isPersist = false
}

livestream.pubSub.publish(
    "REQUEST_TO_JOIN_AS_HOST_$participantId", // PubSub topic specific to participant
    "SEND_AND_RECV", // message
    pubSubPublishOptions
)
}
```

---

**Java:**

```java
void sendInvite(Meeting livestream, String participantId) {
   PubSubPublishOptions pubSubPublishOptions = new PubSubPublishOptions(); 
   pubSubPublishOptions.setPersist(false);
   livestream.pubSub.publish(
    "REQUEST_TO_JOIN_AS_HOST_"+ participantId, // PubSub topic specific to participant
    "SEND_AND_RECV", // message
    pubSubPublishOptions
);
}
```

#### Step 2 : Create an Invite Button

- Add an "Invite on Stage" button for each audience member. When clicked, it publishes a PubSub message with the mode "SEND_AND_RECV" to that participant.

**Kotlin:**

```js
// In ParticipantListAdapter.kt, inside showPopup method
if (participant!!.mode == "RECV_ONLY") {
popup.menu.add("Add as a co-host")

popup.setOnMenuItemClickListener { item: MenuItem ->
    if (item.toString() == "Add as a co-host") {
        sendInvite(liveStream,participantId);
        holder.requestedIndicator.visibility = View.VISIBLE
        holder.btnParticipantMoreOptions.isEnabled = false
        return@setOnMenuItemClickListener true
    }
    false
}
}
```

---

**Java:**

```java
// In ParticipantListAdapter.java, inside showPopup method
if ("RECV_ONLY".equals(participant.getMode())) {
popup.getMenu().add("Add as a co-host");

popup.setOnMenuItemClickListener(new PopupMenu.OnMenuItemClickListener() {
    @Override
    public boolean onMenuItemClick(MenuItem item) {
        if ("Add as a co-host".equals(item.toString())) {
            sendInvite(liveStream,participantId);
            holder.requestedIndicator.setVisibility(View.VISIBLE);
            holder.btnParticipantMoreOptions.setEnabled(false);
            return true;
        }
        return false;
    }
});
}

```

#### Step 3 : Create a Listener to Change the Mode

- On the audience side, subscribe to the specific PubSub topic. When a mode request is received, update the participant’s mode using changeMode().

**Kotlin:**

```js
// In your class where you define coHostListener
val coHostListener = object : PubSubMessageListener {
override fun onMessage(pubSubMessage: PubSubMessage) {
    showCoHostRequestDialog()
}
}

liveStream.pubSub.subscribe(
"REQUEST_TO_JOIN_AS_HOST_${liveStream.localParticipant.id}", 
coHostListener
)

// In the showCoHostRequestDialog method
private fun showCoHostRequestDialog() {
// Dialog setup code...

acceptBtn.setOnClickListener {
    liveStream.changeMode("SEND_AND_RECV")
}
// Rest of the dialog code...
}
```

---

**Java:**

```java
// In your class where you define coHostListener
PubSubMessageListener coHostListener = new PubSubMessageListener () {
@Override
public void onMessage(PubSubMessage pubSubMessage) {
    showCoHostRequestDialog();
}
};

liveStream.pubSub.subscribe("REQUEST_TO_JOIN_AS_HOST_" + liveStream.getLocalParticipant().getId(), coHostListener);

// In the showCoHostRequestDialog method
private void showCoHostRequestDialog() {
// Dialog setup code...

acceptBtn.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View v) {
        liveStream.changeMode("SEND_AND_RECV");
    }
});

// Rest of the dialog code...
}
```




## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [changeMode()](/android/api/sdk-reference/meeting-class/methods#changemode)
- [Participant](/android/api/sdk-reference/participant-class/properties)
- [Meeting](/android/api/sdk-reference/meeting-class/properties)
- [pubSub()](/android/api/sdk-reference/pubsub-class/introduction)


---

# Remove Participant - Android

When hosting a live stream, it's essential for the host to have the capability to to remove a participant from the live stream. This can be useful in various scenarios where a participant is causing disturbance, behaving inappropriately, or is not following the guidelines. This guide focuses on this very aspect of removing a particpant from the live stream.

VideoSDK provides three ways to do so:

1. [Using SDK](#1-using-sdk)
2. [Using VideoSDK Dashboard](#2-using-videosdk-dashboard)
3. [Using Rest API](#3-using-rest-api)

## 1. Using SDK

### `remove()`

The `remove()` method allows for the removal of a participant during an on-going session. This can be helpful when moderation is required in a particular live stream.



**Kotlin:**

```js
btnRemoveParticipant!!.setOnClickListener { _: View? ->
  val remoteParticipantId = "<participant-id>"
  // Get specific participant instance
  val participant = meeting!!.participants[remoteParticipantId]
  // Remove participant from active session
  // This will emit an event called "onParticipantLeft" for that particular participant
  participant!!.remove()
}
```

---

**Java:**

```js
btnRemoveParticipant.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
String remoteParticipantId = "<participant-id>";
// Get specific participant instance
Participant participant = meeting.getParticipants().get(remoteParticipantId);
// Remove participant from active session
// This will emit an event called "onParticipantLeft" for that particular participant
participant.remove();
  }
});
```

### Events associated with remove()

Following callbacks are received when a participant is removed from the meeting.

- The participant who was removed from the meeting will receive a callback on the [`onMeetingLeft`](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmeetingleft) event of the `Meeting` class.

- All other [remote participants](/android/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a callback [`onParticipantLeft`](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onparticipantleft) with Participant object.

## 2. Using VideoSDK Dashboard

- For removing a participant using the VideoSDK Dashboard, navigate to the session page on [VideoSDK Dashboard](https://app.videosdk.live/meetings/sessions). Select the specific session, and from the list of participants, choose the participant you wish to remove. Utilize the provided options to remove the selected participant from the session.


<div style={{textAlign: 'center'}}>



</div>

## 3. Using Rest API

- You can also remove a particular participant from the live stream [using the REST API](/api-reference/realtime-communication/remove-participant).
- To employ this method, you need the `sessionId` of the live stream and the `participantId` of the individual you intend to remove.

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [remove()](/android/api/sdk-reference/participant-class/methods#remove)
- [onMeetingLeft()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmeetingleft)
- [onParticipantLeft()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onparticipantleft)


---

# Audience Polls during Live Stream - Android

Interactive polls are a great way to increase engagement during livestreams. Using VideoSDK’s PubSub mechanism, you can easily implement real-time audience polling, where viewers can vote and see live results instantly.

This guide walks you through how to create, send, and visualize poll results during a livestream.

## Step 1: Creating and Publishing a Poll

To initiate a poll, use the `PubSub` class with a `POLL` topic. The poll structure should include a question and multiple options. This message will be published to all participants.



**Kotlin:**

```js
class CreatePollDialog() {

companion object {
    const val POLL_TOPIC = "POLL"
}

fun show() {
    // ... UI setup code ...
    
    dialog.getButton(AlertDialog.BUTTON_POSITIVE).setOnClickListener {
        // Validate inputs
        
        // Create poll object
        val options = mutableListOf(option1, option2)
        if (option3.isNotEmpty()) options.add(option3)
        if (option4.isNotEmpty()) options.add(option4)
        
        val poll = SimplePoll(question, options)
        
        // Publish poll to all participants
        val pubSubPublishOptions = PubSubPublishOptions()
        pubSubPublishOptions.isPersist = true
        liveStream.pubSub.publish(POLL_TOPIC, poll.toJsonString(), pubSubPublishOptions)
        
        // Show results dialog to host
        PollResultsDialog(context, liveStream).show(poll)
        
        dialog.dismiss()
    }
}
}
```

---

**Java:**

```java
public class CreatePollDialog {
public static final String POLL_TOPIC = "POLL";

public CreatePollDialog() {
// default constructor
}

public void show() {
// ... UI setup code ...

dialog.getButton(AlertDialog.BUTTON_POSITIVE).setOnClickListener(v -> {
    // Validate inputs

    // Create poll object
    List<String> options = new ArrayList<>();
    options.add(option1);
    options.add(option2);
    if (!option3.isEmpty()) options.add(option3);
    if (!option4.isEmpty()) options.add(option4);

    SimplePoll poll = new SimplePoll(question, options);

    // Publish poll to all participants
    PubSubPublishOptions pubSubPublishOptions = new PubSubPublishOptions();
    pubSubPublishOptions.setPersist(true);
    liveStream.pubSub.publish(POLL_TOPIC, poll.toJsonString(), pubSubPublishOptions);

    // Show results dialog to host
    new PollResultsDialog(context, liveStream).show(poll);

    dialog.dismiss();
});
  }
}

```


## Step 2: Subscribing to Polls and Displaying Options
Participants can listen to the POLL topic and render voting options dynamically based on the incoming data.


**Kotlin:**

```js
class PollVotingDialog() {

companion object {
    const val POLL_RESPONSE_TOPIC = "POLL_RESPONSE"
}

fun show(poll: SimplePoll) {
    // ... UI setup code ...
    
    // Create option buttons dynamically
    poll.options.forEach { option ->
        val button = Button(context)
        button.text = option
        button.setOnClickListener {
            // Submit vote
            val response = SimplePollResponse(
                pollId = poll.id,
                option = option,
                participantId = liveStream.localParticipant.id,
                participantName = liveStream.localParticipant.displayName
            )
            
            liveStream.pubSub.publish(POLL_RESPONSE_TOPIC, response.toJsonString())
            
            // Disable all buttons after voting
            for (i in 0 until optionsContainer.childCount) {
                optionsContainer.getChildAt(i).isEnabled = false
            }
        }
        
        optionsContainer.addView(button)
    }
}
}
```

---

**Java:**

```java
public class PollVotingDialog {

public static final String POLL_RESPONSE_TOPIC = "POLL_RESPONSE";

public void show(SimplePoll poll) {
    // ... UI setup code ...

    // Create option buttons dynamically
    for (String option : poll.getOptions()) {
        Button button = new Button(context);
        button.setText(option);
        button.setOnClickListener(v -> {
            // Submit vote
            SimplePollResponse response = new SimplePollResponse(
                    poll.getId(),
                    option,
                    liveStream.getLocalParticipant().getId(),
                    liveStream.getLocalParticipant().getDisplayName()
            );

            liveStream.pubSub.publish(POLL_RESPONSE_TOPIC, response.toJsonString());

            // Disable all buttons after voting
            for (int i = 0; i < optionsContainer.getChildCount(); i++) {
                optionsContainer.getChildAt(i).setEnabled(false);
            }
        });

        optionsContainer.addView(button);
    }
}
}
```


## Step 3: Aggregating and Displaying Poll Results
The host can subscribe to the POLL_RESPONSE topic to collect responses and render the result in real-time.

**Kotlin:**

```js
class PollResultsDialog() {

private val pollResults = ConcurrentHashMap<String, Int>()
private var totalVotes = 0

companion object {
    const val POLL_RESPONSE_TOPIC = "POLL_RESPONSE"
}

fun show(poll: SimplePoll) {
    // ... UI setup code ...
    
    // Initialize results map with 0 votes for each option
    poll.options.forEach { option ->
        pollResults[option] = 0
    }
    
    // Create initial result bars
    updateResultBars()
    
    // Listen for poll responses
    responsesListener = object : PubSubMessageListener {
    override fun onMessageReceived(pubSubMessage: PubSubMessage) {
        try {
            val response = SimplePollResponse.fromJsonString(pubSubMessage.message)
            val option = response.option
            
            // Update vote count
            pollResults[option] = (pollResults[option] ?: 0) + 1
            totalVotes++
            
            // Update UI on main thread
            (context as? android.app.Activity)?.runOnUiThread {
                updateResultBars()
            }
        } catch (e: Exception) {
            e.printStackTrace()
        }
    }
    override fun onOldMessagesReceived(messages: List<PubSubMessage>) {
        // Persisted message list
        Log.d("VideoSDK", "messages: $messages")
    }
}
    
    // Subscribe to poll responses
    liveStream.pubSub.subscribe(POLL_RESPONSE_TOPIC, responsesListener)
}

private fun updateResultBars() {
    // Clear previous results
    optionsContainer?.removeAllViews()
    
    // Create result bars for each option
    pollResults.forEach { (option, votes) ->
        val percentage = if (totalVotes > 0) (votes * 100) / totalVotes else 0
        
        // Create progress bar UI showing percentage
        // ... UI code to display results ...
    }
}
}
```

---

**Java:**

```java
import java.util.concurrent.ConcurrentHashMap;
import java.util.Map;

public class PollResultsDialog {

private ConcurrentHashMap<String, Integer> pollResults = new ConcurrentHashMap<>();
private int totalVotes = 0;

public static final String POLL_RESPONSE_TOPIC = "POLL_RESPONSE";

public void show(SimplePoll poll) {
    // ... UI setup code ...

    // Initialize results map with 0 votes for each option
    for (String option : poll.options) {
        pollResults.put(option, 0);
    }

    // Create initial result bars
    updateResultBars();

    // Listen for poll responses
    responsesListener = new PubSubMessageListener() {
        @Override
        public void onMessageReceived(PubSubMessage PubSubMessage) {
            try {
                SimplePollResponse response = SimplePollResponse.fromJsonString(pubSubMessage.message);
                String option = response.option;

                // Update vote count
                pollResults.put(option, pollResults.getOrDefault(option, 0) + 1);
                totalVotes++;

                // Update UI on main thread
                if (context instanceof android.app.Activity) {
                    ((android.app.Activity) context).runOnUiThread(new Runnable() {
                        @Override
                        public void run() {
                            updateResultBars();
                        }
                    });
                }
            } catch (Exception e) {
                e.printStackTrace();
            }
        }

        @Override
        public void onOldMessagesReceived(List<PubSubMessage> messages) {
            // Persisted message list
            Log.d("VideoSDK", "onOldMessagesReceived: " + messages);
        }
    };

    // Subscribe to poll responses
    liveStream.pubSub.subscribe(POLL_RESPONSE_TOPIC, responsesListener);
}

private void updateResultBars() {
    // Clear previous results
    if (optionsContainer != null) {
        optionsContainer.removeAllViews();
    }

    // Create result bars for each option
    for (Map.Entry<String, Integer> entry : pollResults.entrySet()) {
        String option = entry.getKey();
        int votes = entry.getValue();

        int percentage = (totalVotes > 0) ? (votes * 100) / totalVotes : 0;

        // Create progress bar UI showing percentage
        // ... UI code to display results ...
    }
}
}
```


### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [pubSub()](/android/api/sdk-reference/pubsub-class/introduction)


---

<h1> {props.title} </h1>{" "}

### Why we are using JWT based Token ?

Token based authentication allows users to verify their identity by providing generated API key and secret.

We use JWT token for the authentication purpose because Token-based authentication is **widely used** in modern web applications and APIs because it offers several benefits over traditional authentication. For example, it can **reduce the risk of the credentials being misused**, and it allows for **more fine-grained control** over access to resources. Additionally, tokens can be easily revoked or expired, making it easier to manage access rights.

### How to generate Token ?

To manage secured communication, every participant that connects to the meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key` which you can get from [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

#### 1. Generating token from Dashboard

If you are looking to do **testing or for development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for getting token includes generating it from your backend server which will help in **keeping your credentials safe**.
:::

#### 2. Generating token in your backend

- Your server will generate access token using your API key and secret.
  - While generating a token, you can provide **expiration time, permissions and roles** which are discussed later in this section.
- Your client obtains token from your backend server.
- For token validation, client will pass this token to VideoSDK server.
- VideoSDK server will only allow entry in the meeting if the token is valid.

![img2.png](../../static/img/authentication-and-token.png)




Follow our official example repositories to setup token API [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)

### Payload while generating token

```js
{
 apikey: API_KEY, //MANDATORY
 permissions: [`allow_join`], //`ask_join` || `allow_mod` //MANDATORY
 version: 2, //OPTIONAL
 roomId: ROOM_ID, //OPTIONAL,
 participantId: PARTICIPANT_ID, //OPTIONAL
 roles: ['crawler', 'rtc'], //OPTIONAL
}
```

- **`apikey`(Mandatory)**: This must be the API Key generated from the VideoSDK Dashboard. You can get it from [here](https://app.videosdk.live/api-keys).

- **`permissions`(Mandatory)**: By providing the permissions, you can control what a participant can do in the meeting and whether he can join the meeting directly.

  Available permissions are:

  - **`allow_join`**: The participant is **allowed to join** the meeting directly.
  - **`ask_join`**: The participant is required to **ask for permission to join** the meeting. The participant having the permission `allow_join` can accept or reject a participant whenever someone wants to join.
  - **`allow_mod`**: The participant is **allowed to toggle** webcam & mic of other participants.

- **`version`(optional)**: For accessing the [v2 API](/api-reference/realtime-communication/intro), you need to provide `2` as the version value.

  - For passing `roomId`, `participantId` or `roles` parameters in payload, it is essential to set the version value to `2`.

- **`roomId`(optional)**: To provide customised access control, you can make the token applicable to a particular room by including the `roomId` in the payload.

- **`participantId`(optional)**: You can include the `participantId` in the payload to limit the token's access to a particular participant.

- **`roles`(optional)**:

  - **`crawler`**: This role is only for accessing [v2 API](/api-reference/realtime-communication/intro), you can not use this token for running the `Meeting`/`Room`.
  - **`rtc`**: This role is only allowed for running the `Meeting` / `Room`, with this role you can not use [server-side APIs](/api-reference/realtime-communication/intro).

Then, you have to sign this payload with your **`SECRET KEY`** and `jwt` options using the **`HS256 algorithm`**.

### Expiration time

You can set any expiration time to the token. But in the **production environment**, it is recommended to generate a token with **short expiration time** because by any chance if someone gets hold of the token, it won't be valid for a longer period of time.

### What happens if token is expired?

If your token is expired, the user won't be able to join the meeting and all the API calls will give error with message `Token is invalid or expired`.

:::note
Token is validated only once while joining the meeting, so if a person joins the meeting and the token gets expired after that, there won't be any issue in the current meeting.
:::

## How to check validity of token?

1. After generating the token, visit [jwt.io](https://jwt.io) and paste your token in the given area.
2. You will be able to see the payload you passed while generating the token and also be able to see the expiration time and token creation time.

![img1.png](../../static/img/validate-token.png)

## API Settings & Controls

The VideoSDK Dashboard provides a powerful [API Settings](https://app.videosdk.live/api-keys) section where you can configure various services and controls for your meetings. These settings allow you to customize the behavior of different features directly from the dashboard without requiring code changes.

## Audio/Video Configurations

:::note
Runtime configuration from the dashboard has higher precedence than static SDK configurations.
If a value is modified in the dashboard, it will override any previously defined SDK settings for that session.

Example:
Code: Video = HD → Dashboard: Video = Full HD → Applied: Full HD
:::

### Maximum Send Bitrate Per Participant

Control the maximum total upload bandwidth for all media streams from a single participant.

![Maximum Send Bitrate](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.00.11%E2%80%AFPM.png)

**Available Options:**
- **Auto**: Removes the upload bitrate limit (recommended for best quality)
- **SD (800kbps)**: Standard definition bitrate
- **HD (1500kbps)**: High definition bitrate
- **Full HD (3000kbps)**: Full high definition bitrate

:::tip
Setting this to **Auto** provides the best video quality as it removes upload bitrate constraints, allowing adaptive streaming based on network conditions.
:::

## Recording & Streaming Configuration

:::note
Recording and HLS follow a precedence-based configuration model:

API/SDK configuration → Highest priority
Dashboard configuration → Used only when no API values are defined

Any parameters explicitly set via the API will not be overridden by dashboard changes.
:::

### Recording Configuration

Configure recording settings for your meetings including layout, quality, and auto-start options.

![Recording Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.01.00%E2%80%AFPM.png)

**Recording Controls:**
- **Enabled**: Toggle to enable/disable recording functionality
- **Enabled Modes**: Choose between Video & Audio or Audio Only recording
- **Start Recording Automatically**: Auto-start recording when meeting begins
- **Layout Style**: Select Grid layout for recording composition
- **Maximum Tiles In Grid**: Set the number of participants visible in grid (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme for recordings
- **Video Orientation**: Choose between Landscape or Portrait mode
- **Recording Quality**: Select quality level (e.g., HD Medium)
- **Recording Mode**: Choose between Video & Audio or Audio Only

### HLS Streaming Configuration

Configure HTTP Live Streaming (HLS) settings for broadcasting your meetings.

![HLS Streaming Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.02.18%E2%80%AFPM.png)

**HLS Streaming Controls:**
- **Enabled**: Toggle to enable/disable HLS streaming
- **Enabled Modes**: Choose between Video & Audio or Audio Only streaming
- **Auto Start HLS**: Automatically start HLS when meeting begins
- **Record HLS Stream**: Enable recording of the HLS stream
- **Layout Style**: Select Grid layout for stream composition
- **Maximum Tiles In Grid**: Set the number of participants visible (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme
- **HLS Orientation**: Choose between Landscape or Portrait mode
- **HLS Quality**: Select streaming quality (e.g., HD Medium)
- **HLS Streaming Mode**: Choose between Video & Audio or Audio Only

### Additional Service Controls

Enable or disable additional services for your API key.

![Service Controls](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.08%E2%80%AFPM.png)

**Available Services:**
- **RTMP Output**: Enable RTMP streaming to external platforms
- **SIP Integration**: Enable SIP (Session Initiation Protocol) integration for telephony
- **Realtime Translation**: Enable real-time language translation in meetings

### Transcription & Summary

Configure transcription and domain whitelisting for your API key.

![Transcription Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.50%E2%80%AFPM.png)

**Transcription Controls:**
- **Enabled**: Toggle to enable/disable transcription and summary features
- **Whitelist Domain**: Add domain restrictions for API key usage
  - Enter domain names in the format `https://domain.name`
  - Click "Add Domain" to whitelist specific domains
  - Only whitelisted domains can use this API key
  - When no domains are whitelisted, the API key can be used from any domain


---

# Developer Experience Guidelines - Android




---

# Handle Large Rooms - Android




---

# User Experience Guidelines - Android




---

# Chat during Live Stream - Android

Enhance your live stream experience by enabling real-time audience chat using VideoSDK's PubSub class. Whether you’re streaming a webinar, online event, or an interactive session, integrating a chat system lets your viewers engage, ask questions, and react instantly. This guide shows how to build a group or private chat interface for a live stream using the Publish-Subscribe (PubSub) mechanism.

This guide focuses on using PubSub to implement Chat functionality. If you are not familiar with the PubSub mechanism and `PubSub` class , you can [follow this guide](/android/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

## Implementing Chat

### `Group Chat`

1. First step in creating a group chat is choosing the topic which all the participants will publish and subscribe to send and receive the messages. We will be using `CHAT` as the topic for this one.
2. On the send button, publish the message that the sender typed in the `EditText` field.



**Kotlin:**

```js
import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.view.View
import android.widget.EditText
import android.widget.Toast
import androidx.appcompat.widget.Toolbar
import live.videosdk.rtc.android.Meeting
import live.videosdk.rtc.android.listeners.PubSubMessageListener
import live.videosdk.rtc.android.model.PubSubPublishOptions

class ChatActivity : AppCompatActivity() {
  // Meeting
  var meeting: liveStream? = null

  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_chat)

/**
 * Here, we have created 'MainApplication' class, which extends android.app.Application class.
 * It has Meeting property and getter and setter methods of Meeting property.
 * In your android manifest, you must declare the class implementing android.app.Application
 * (add the android:name=".MainApplication" attribute to the existing application tag):
 * In MainActivity.kt, we have set Meeting property.
 *
 * For Example: (MainActivity.kt)
 * var meeting = VideoSDK.initMeeting(context, meetingId, ParticipantName, micEnabled, webcamEnabled, paricipantId, mode, multiStream, customTrack, metaData, signalingBaseUrl)
 * (this.application as MainApplication).meeting = meeting
*/

// Get Meeting
liveStream = (this.application as MainApplication).meeting

findViewById(R.id.btnSend).setOnClickListener(view -> sendMessage());
  }

  private fun sendMessage() {
// get message from EditText
val message: String = etmessage.getText().toString()
if (!TextUtils.isEmpty(message)) {
    val publishOptions = PubSubPublishOptions()
    publishOptions.setPersist(true)

    // Sending the Message using the publish method
    //highlight-next-line
    liveStream!!.pubSub.publish("CHAT", message, publishOptions)

    // Clearing the message input
    etmessage.setText("")
} else {
    Toast.makeText(
        this@ChatActivity, "Please Enter Message",
        Toast.LENGTH_SHORT
    ).show()
}
  }
}
```

---

**Java:**

```js
import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import java.util.List;
import live.videosdk.rtc.android.Meeting;
import live.videosdk.rtc.android.lib.PubSubMessage;
import live.videosdk.rtc.android.listeners.PubSubMessageListener;
import live.videosdk.rtc.android.model.PubSubPublishOptions;

public class ChatActivity extends AppCompatActivity {
  // Meeting
  Meeting liveStream;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_chat);

/**
 * Here, we have created 'MainApplication' class, which extends android.app.Application class.
 * It has Meeting property and getter and setter methods of Meeting property.
 * In your android manifest, you must declare the class implementing android.app.Application
 * (add the android:name=".MainApplication" attribute to the existing application tag):
 * In MainActivity.java, we have set Meeting property.
 *
 * For Example: (MainActivity.java)
 * Meeting meeting = VideoSDK.initMeeting(context, meetingId, ParticipantName, micEnabled, webcamEnabled, participantId, mode, mutliStream, customTrack,metaData, signalingBaseUrl, preferredProtocol);
 * ((MainApplication) this.getApplication()).setMeeting(meeting);
*/

// Get Meeting
liveStream = ((MainApplication) this.getApplication()).getMeeting();

findViewById(R.id.btnSend).setOnClickListener(view -> sendMessage());
  }

  private void sendMessage()
  {
// get message from EditText
String message = etmessage.getText().toString();
if (!message.equals("")) {
    PubSubPublishOptions publishOptions = new PubSubPublishOptions();
    publishOptions.setPersist(true);

    // Sending the Message using the publish method
    //highlight-next-line
    liveStream.pubSub.publish("CHAT", message, publishOptions);

    // Clearing the message input
    etmessage.setText("");
} else {
    Toast.makeText(ChatActivity.this, "Please Enter Message",
            Toast.LENGTH_SHORT).show();
}
  }
}
```

3. Next step would be to display the messages others send. For this we have to `subscribe` to that topic i.e `CHAT` and display all the messages.

**Kotlin:**

```js
class ChatActivity : AppCompatActivity() {

  // PubSubMessageListener
  //highlight-start
val pubSubMessageListener = object : PubSubMessageListener {
    override fun onMessageReceived(message: PubSubMessage) {
        Log.d("#message", "onMessageReceived: ${message.message}")
    }
    override fun onOldMessagesReceived(messages: List<PubSubMessage>) {
        // Persisted message list
        Log.d("#message", "onOldMessagesReceived: $messages")
    }
}
  //highlight-end

  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_chat)

//...

// Subscribe for 'CHAT' topic
//highlight-next-line
liveStream!!.pubSub.subscribe("CHAT", pubSubMessageListener)

  }
}
```

---

**Java:**

```js
public class ChatActivity extends AppCompatActivity {

  // PubSubMessageListener
  //highlight-start
PubSubMessageListener pubSubMessageListener = new PubSubMessageListener() {
    @Override
    public void onMessageReceived(PubSubMessage message) {
        Log.d("#message", "onMessageReceived: " + message.getMessage());
    }
    
    @Override
      public void onOldMessagesReceived(List<PubSubMessage> messages) {
      // Persisted message list
      Log.d("#message", "onOldMessagesReceived: " + messages);
    }
};
  //highlight-end

  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_chat);

//..

// Subscribe for 'CHAT' topic
//highlight-next-line
liveStream.pubSub.subscribe("CHAT", pubSubMessageListener);

  }
}
```

4. Final step in the group chat would be `unsubscribe` to that topic, which you had previously subscribed but no longer needed. Here we are `unsubscribe` to `CHAT` topic on activity destroy.

**Kotlin:**

```js
class ChatActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_chat)

//...
  }

  override fun onDestroy() {
// Unsubscribe for 'CHAT' topic
//highlight-next-line
liveStream!!.pubSub.unsubscribe("CHAT", pubSubMessageListener)
super.onDestroy()
  }
}
```

---

**Java:**

```js
public class ChatActivity extends AppCompatActivity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_chat);

//..
  }

  @Override
  protected void onDestroy() {
// Unsubscribe for 'CHAT' topic
//highlight-next-line
liveStream.pubSub.unsubscribe("CHAT", pubSubMessageListener);
super.onDestroy();
  }
}
```


### `Private Chat` (1:1 between Host and Viewer)

Private messaging is ideal when a host or moderator needs to directly respond to a viewer’s question. This can be achieved using the `sendOnly` property.

**Kotlin:**

```js
class ChatActivity : AppCompatActivity() {

  //..
  
  private fun sendMessage() {
// get message from EditText
val message: String = etmessage.getText().toString()
if (!TextUtils.isEmpty(message)) {
    val publishOptions = PubSubPublishOptions()
    publishOptions.setPersist(true)
    //highlight-start
    // Pass the participantId of the participant to whom you want to send the message.
    var sendOnly: Array<String> = arrayOf("xyz")
    publishOptions.setSendOnly(sendOnly);
    //highlight-end

    // Sending the Message using the publish method
    //highlight-next-line
    liveStream!!.pubSub.publish("CHAT", message, publishOptions)

    // Clearing the message input
    etmessage.setText("")
} else {
    Toast.makeText(
        this@ChatActivity, "Please Enter Message",
        Toast.LENGTH_SHORT
    ).show()
}
  }
}
```

---

**Java:**

```js
public class ChatActivity extends AppCompatActivity {
 
  //...

  private void sendMessage()
  {
// get message from EditText
String message = etmessage.getText().toString();
if (!message.equals("")) {
    PubSubPublishOptions publishOptions = new PubSubPublishOptions();
    publishOptions.setPersist(true);
    //highlight-start
    // Pass the participantId of the participant to whom you want to send the message.
    String[] sendOnly = {
      "xyz" 
    };
    publishOptions.setSendOnly(sendOnly);
    //highlight-end

    // Sending the Message using the publish method
    //highlight-next-line
    liveStream.pubSub.publish("CHAT", message, publishOptions);

    // Clearing the message input
    etmessage.setText("");
} else {
    Toast.makeText(ChatActivity.this, "Please Enter Message",
            Toast.LENGTH_SHORT).show();
}
  }
}
```

### Downloading Chat Messages

All the messages from the PubSub which where published with `persist : true` and can be downloaded as an `.csv` file. This file will be available in the VideoSDK dashboard as well as throught the [Sessions API](/api-reference/realtime-communication/fetch-session-using-sessionid).

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub()](/android/api/sdk-reference/pubsub-class/introduction)


---

# Cloud Proxy - Android


Our SDK features a Cloud Proxy that allows you to manage how your streaming content is routed through different network paths. This feature ensures compliance with various regional internet regulations by restricting traffic to specified proxy servers, based on your needs and the geographical location of users.

This capability is crucial for adhering to local data protection laws and optimizes the streaming experience by overcoming geographical network constraints. By directing user connections to appropriate regional servers, Cloud Proxy enhances overall service performance and reliability.

Cloud Proxy offers three straightforward operating modes to fit different business and firewall requirements:

- **UDP_OVER_TCP (Default)**: In this mode, the connection starts by attempting to establish a UDP connection for media transmission. If that fails, it will automatically shifts to a secure TCP connection, which is compatible with most firewalls.

- **Force UDP**: This mode uses only UDP to send media, ensuring high-quality streams. It's ideal for environments where media quality is critical and the firewall can be configured accordingly.

- **Force TCP**: Only uses TCP for secure media transmission, suitable for strict firewall settings that only permit TCP traffic over centain ports. This might require additional firewall configuration and could affect media quality under poor network conditions.




### In this sequence diagram:
- Client to Proxy Server: The client sends a request to the proxy server, which processes and forwards it based on predefined rules.
- Proxy Server to Destination Server: The proxy server sends the request to the destination server, receives the response, and relays it back to the client.

:::info

Cloud Proxy is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Implementation



**Kotlin:**

```js
val liveStream: Meeting = VideoSDK.initMeeting(
  this@MainActivity, "meetingId", "John Due", true,
  true, null, null, false, null, null,"proxy.yourwebsite.com", VideoSDK.PreferredProtocol.UDP_ONLY
);
```

---

**Java:**

```java
Meeting liveStream = VideoSDK.initMeeting(
  MainActivity.this, "meetingId", "John Due",true,
  true, null, null, false, null,null,"proxy.yourwebsite.com", VideoSDK.PreferredProtocol.UDP_ONLY
);
```
### Parameters
- preferredProtocol:
    - UDP_OVER_TCP (default): Initially the server attempts to establish a connection using UDP, if that fails it automatically switches to TCP protocol.
    - UDP_ONLY: Force UDP protocol
    - TCP_ONLY: Force TCP protocol
- signalingBaseUrl: Proxy URL to origin signaling and media.

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [initMeeting()](/android/api/sdk-reference/initMeeting)


---

# Concept and Architecture - Android

Before diving into the concept, let's understand the VideoSDK, VideoSDK is a software development kit that offers tools and APIs for creating apps that are based on video and audio. It typically includes features such as video and audio calls, chat, cloud recording, simulcasting (RTMP), interactive live streaming (HLS), and many more across a wide range of platforms and devices.

## Concepts

![img.png](../../../../static/img/room-concept.png)

### `1. Meeting / Room`

- Meeting or Room object in the VideoSDK provide a virtual place for participants to interact and engage in real-time voice, video, and screen-sharing sessions. The object is in charge of handling media streams and participant communication.

- Meeting or Room can be uniquely identified by `meetingId` or `roomId`.

### `2. Participant`

- Participant is a VideoSDK object that represents each user/client in the meeting or room and allows them to share audio/video assets.

- `2.1 Local Participant` :
  The local participant is the one that runs on the user's device. The local participant has control over their own media streams, including the ability to start and stop audio and video.

  - The local participant in a meeting/room can also connect with other participants by transmitting and receiving audio and video streams, exchanging chat messages, and more.

- `2.2 Remote Participant` :
  The remote participant receives audio and video streams from the local participant and other remote participants and also has the ability to exchange audio, video, and chat messages with the local participant.

- Each participant in VideoSDK can be uniquely identified by `participantId`.

### `3. MediaStream & Track`

- A mediastream is a collection of audio & video tracks that can be transmitted between participants in real-time.

- A track is a continuous flow of audio or video data and can be thought of as a stream of media frames.

- A mediastream can contain multiple tracks. One video track for the video feed from the camera and one audio track for the audio feed from the microphone. These tracks can be transmitted between participants in VideoSDK Meeting / Room.

### `4. Events / Notifications`

- Events / Notifications can be used to inform users about various activities happening in a Meeting / Room, including participant join/leave and new messages. They can also be used to alert users about any SDK-level errors that occur during a call.

### `5. Session`

- A Session is the instance of an ongoing meeting/room which has one or more participants in it. A single room or meeting can have multiple sessions.
- Each session can be uniquely identified by `sessionId`.

![img.png](../../../../static/img/meeting-session.jpg)

---

![img.png](../../../../static/img/recording-hls-rtmp.png)

### `6. Cloud Recording`

- Cloud recording in VideoSDK refers to the process of recording audio or video content and storing it on a remote server or VideoSDK server.

### `7. Simulcasting (RTMP)`

- RTMP is a popular protocol for live streaming video content from a VideoSDK to platforms such as YouTube, Twitch, Facebook, and others.
- By providing the platform-specific `stream key` and `stream URL`, the VideoSDK can connect to the platform's RTMP server and transmit the live video stream.

### `8. Http Live Streaming (HLS)`

- Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

- In an interactive live stream (HLS), viewers can take part in a variety of activities like live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

## Architecture

This diagram demonstrates end-to-end flow to implement video & audio calls, record calls, and go live on social media.

![Video-sdk-architecture!](/img/video-sdk-archietecture.svg)


---

# Custom Audio Sources - Android

For a high-quality streaming experience, fine-tuning audio tracks becomes essential—especially when delivering content to a broader live audience.

To enhance your live audio pipeline, we've introduced the capability to provide a custom audio track for a hosts's stream both before and during a live session.


## Custom Audio Track

This feature allows you to integrate advanced audio layers like background noise suppression, echo cancellation, and more—so your stream sounds polished and professional to every viewer.

### `How to Create Custom Audio Track ?`

- You can create a Audio Track using `createAudioTrack()` method of `VideoSDK`.

- This method can be used to create audio track using different encoding parameters.

#### Example



**Kotlin:**

```js
val audioCustomTrack: CustomStreamTrack = VideoSDK.createAudioTrack("speech_standard",this)
// `high_quality` | `music_standard`,  Default : `speech_standard`
```

---

**Java:**

```js
CustomStreamTrack audioCustomTrack=VideoSDK.createAudioTrack("speech_standard", this);
// `high_quality` | `music_standard`,  Default : `speech_standard`
```

- `speech_standard` : This config is optimised for normal voice communication.

- `high_quality` : This config is used for getting RAW audio, where you can apply your `noiseConfig`.

- `music_standard` : This config is optimised for communication, where sharing of musical notes such as songs or instrumental sounds, is important.

### `How to Setup Custom Audio Track ?`

The custom track can be set up both before and after the initialization of the meeting.

1. [Setting up a Custom Track during the initialization of a meeting](/android/guide/video-and-audio-calling-api-sdk/render-media/optimize-audio-track#1-setting-up-a-custom-track-during-the-initialization-of-a-meeting)
2. [Setting up a Custom Track with methods](/android/guide/video-and-audio-calling-api-sdk/render-media/optimize-audio-track#2-setting-up-a-custom-track-with-methods)

##### 1. Setup during live stream initialization

If you're starting the stream with the mic enabled `(micEnabled: true)` and wish to use a custom track from the beginning, pass it through the config of MeetingProvider.

:::caution
Custom Track will not apply on `micEnabled: false` configuration.
:::

##### Example

**Kotlin:**

```js
override fun onCreate(savedInstanceState: Bundle?) {
  //..

  val customTracks: MutableMap<String, CustomStreamTrack> = HashMap()

  //highlight-start
  val audioCustomTrack: CustomStreamTrack = VideoSDK.createAudioTrack("high_quality", this)
  customTracks["mic"] = audioCustomTrack  //Key must be "mic"
  //highlight-end

  // create a new meeting instance
  val liveStream = VideoSDK.initMeeting(
this@MainActivity,meetingId,participantName,
//MicEnabled , If true, it will use the passed custom track to turn mic on
true,
//WebcamEnabled
true,
//ParticipantId
null,
//Mode
null,
//MultiStream
false,
//Pass the custom tracks here
//highlight-next-line
customTracks,
//MetaData
null
  )
}
```

---

**Java:**

```js
@Override
protected void onCreate(Bundle savedInstanceState) {
  //..

  Map<String, CustomStreamTrack> customTracks = new HashMap<>();

  //highlight-start
  CustomStreamTrack audioCustomTrack = VideoSDK.createAudioTrack("high_quality", this);
  customTracks.put("mic", audioCustomTrack);  //Key must be "mic"
  //highlight-end

  // create a new meeting instance
  Meeting liveStream = VideoSDK.initMeeting(
  MainActivity.this, meetingId, participantName,
  //MicEnabled , If true, it will use the passed custom track to turn mic on
  true,
  //WebcamEnabled
  true,
  //ParticipantId
  null,
  //Mode
  null,
  //MultiStream
  false,
  //Pass the custom tracks here
  //highlight-next-line
  customTracks,
  //MetaData
  null
  );
}
```

#### 2. Setup dynamically using methods

During the live stream, you can update the audio source by passing the `CustomStreamTrack` in the `unmuteMic()` method of `Meeting`.

You can also pass custom track in `changeMic()` method of `Meeting`.

:::tip
Make sure to call the `muteMic()` method before you create a new track as it may lead to unexpected behavior.
:::

##### Example

**Kotlin:**

```js
try {
  val audioCustomTrack: CustomStreamTrack = VideoSDK.createAudioTrack("high_quality", this)
  liveStream!!.unmuteMic(audioCustomTrack)

  //or
  liveStream!!.changeMic(AppRTCAudioManager.AudioDevice.BLUETOOTH, audioCustomTrack)
} catch (e: JSONException) {
  e.printStackTrace()
}
```

---

**Java:**

```js
try {
  CustomStreamTrack audioCustomTrack = VideoSDK.createAudioTrack("high_quality", this);
  liveStream.unmuteMic(audioCustomTrack);

  //or
  liveStream.changeMic(AppRTCAudioManager.AudioDevice.BLUETOOTH,audioCustomTrack);
}catch (JSONException e) {
  e.printStackTrace();
}
```

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [Custom Audio Track](/android/api/sdk-reference/custom-tracks#custom-audio-track---android)


---

# Custom ScreenShare Sources - Android

To deliver high-quality livestreams, it's essential to fine-tune screen share tracks being broadcasted. Whether you’re hosting a webinar, or going live with a presentation, using custom media tracks gives you better control over stream quality and performance.

## Custom Screen Share Track

This feature enables the customization of screenshare streams with enhanced optimization modes and predefined encoder configuration (resolution + FPS) for specific use cases, which can then be sent to other hosts and audience members.

### `How to Create Custom Screen Share Track ?`

- You can create a Screen Share track using `createScreenShareVideoTrack()` method of `VideoSDK`.
- This method can be used to create video track using different encoding parameters and optimization mode.

#### Example



**Kotlin:**

```javascript
// data is received from onActivityResult method.
VideoSDK.createScreenShareVideoTrack(

  //highlight-next-line
  // This will accept the  height & FPS of video you want to capture.
  "h720p_15fps", //  `h360p_30fps` | `h1080p_30fps` // Default : `h720p_15fps`

  //highlight-next-line
  // It is Intent received from onActivityResult when user provide permission for ScreenShare.
  data,

  //highlight-next-line
  // Pass Conext
  this)

  //highlight-next-line
  //Callback to this listener will be made when track is ready with CustomTrack as parameter
  {
track ->
meeting!!.enableScreenShare(track)
  }
```

---

**Java:**

```javascript
// data is received from onActivityResult method.
VideoSDK.createScreenShareVideoTrack(
  //highlight-next-line
  // This will accept the  height & FPS of video you want to capture.
  "h720p_15fps", //  `h360p_30fps` | `h1080p_30fps` // Default : `h720p_15fps`

  /highlight-next-line
  // It is Intent received from onActivityResult when user provide permission for ScreenShare
  data,

  //highlight-next-line
  // Pass Conext
  this,

  //highlight-next-line
  //Callback to this listener will be made when track is ready with CustomTrack as parameter
  (track)->{meeting.enableScreenShare(track);}
);
```

### `How to Setup Custom Screen Share Track ?`

In order to switch tracks during the meeting, you have to pass the `CustomStreamTrack` in the `enableScreenShare()` method of `Meeting`.

:::note

Make sure to call `disableScreenShare()` before you create a new track as it may lead to unexpected behavior.

:::

##### Example

**Kotlin:**

```javascript
@TargetApi(21)
private fun askPermissionForScreenShare() {
  val mediaProjectionManager = application.getSystemService<Any>(
  Context.MEDIA_PROJECTION_SERVICE
  ) as MediaProjectionManager
  startActivityForResult(
  mediaProjectionManager.createScreenCaptureIntent(), CAPTURE_PERMISSION_REQUEST_CODE
  )
}

@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
  super.onActivityResult(requestCode, resultCode, data)
  if (requestCode != CAPTURE_PERMISSION_REQUEST_CODE) return
  if (resultCode == RESULT_OK) {
//highlight-start
VideoSDK.createScreenShareVideoTrack("h720p_15fps", data, this) { track ->
    liveStream!!.enableScreenShare(track)
}
//highlight-end
  }
}

```

---

**Java:**

```javascript
@TargetApi(21)
private void askPermissionForScreenShare() {
  MediaProjectionManager mediaProjectionManager =
  (MediaProjectionManager) getApplication().getSystemService(
      Context.MEDIA_PROJECTION_SERVICE);
  startActivityForResult(
  mediaProjectionManager.createScreenCaptureIntent(), CAPTURE_PERMISSION_REQUEST_CODE);
}

@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  if (requestCode != CAPTURE_PERMISSION_REQUEST_CODE)
  return;
  if (resultCode == Activity.RESULT_OK) {
//highlight-start
VideoSDK.createScreenShareVideoTrack("h720p_15fps", data, this, (track)->{
    liveStream.enableScreenShare(track);
});
//highlight-end
  }
}

```

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [Custom Video Track](/react/api/sdk-reference/custom-tracks#custom-video-track---react)
- [Custom Screen Share Track](/react/api/sdk-reference/custom-tracks#custom-screen-share-track---react)


---

# Custom Video Sources - Android

To deliver high-quality livestreams, it's essential to fine-tune the video tracks being broadcasted. Whether you’re hosting a webinar, or streaming an event, using custom video tracks gives you better control over stream quality and performance.

## Custom Video Track

This feature can be used to add custom video encoder configurations, optimization mode (whether you want to focus on motion, text or detail of the video) and background removal & video filter from external SDK(e.g., Banuba)and send it to other participants.

### `How to Create a Custom Video Track ?`

- You can create a Video Track using `createCameraVideoTrack()` method of `VideoSDK`.
- This method can be used to create video track using different encoding parameters, camera facing mode, and optimization mode and return `CustomStreamTrack`.

#### Example



**Kotlin:**

```javascript
val videoCustomTrack: CustomStreamTrack = VideoSDK.createCameraVideoTrack(

  // highlight-next-line
  // This will accept the resolution (height x width) of video you want to capture.
  "h720p_w960p", // "h720p_w960p" | "h720p_w1280p" ... // Default : "h480p_w720p"

  // highlight-next-line
  // It will specify whether to use front or back camera for the video track.
  "front", "back",  Default : "front"

  // highlight-next-line
  // We will discuss this parameter in next step.
  CustomStreamTrack.VideoMode.MOTION, // CustomStreamTrack.VideoMode.TEXT, CustomStreamTrack.VideoMode.DETAIL ,  Default : CustomStreamTrack.VideoMode.MOTION

  // highlight-next-line
  // multiStream - we will discuss this parameter in next step.
  false, // true

  // highlight-next-line
  // Pass Context
  this,

  // highlight-next-line
  // This is Optional parameter. We will discuss this parameter in next step.
  observer)
```

---

**Java:**

```javascript
CustomStreamTrack customStreamTrack = VideoSDK.createCameraVideoTrack(

  // highlight-next-line
  // This will accept the resolution (height x width) of video you want to capture.
  "h480p_w640p", // "h720p_w960p" | "h720p_w1280p" ... // Default : "h480p_w640p"

  // highlight-next-line
  // It will specify whether to use front or back camera for the video track.
  "front", // "back,  Default : "front""

  // highlight-next-line
  // We will discuss this parameter in next step.
  CustomStreamTrack.VideoMode.MOTION, // CustomStreamTrack.VideoMode.TEXT, CustomStreamTrack.VideoMode.DETAIL ,  Default : CustomStreamTrack.VideoMode.MOTION

  // highlight-next-line
  // multiStream - we will discuss this parameter in next step.
  false, // true

  // highlight-next-line
  // Pass Context
  this

  // highlight-next-line
  // This is Optional parameter. We will discuss this parameter in next step.
  observer);
```

:::caution
The behavior of custom track configurations is influenced by the capabilities of the device. For example, if you set the encoder configuration to 1080p but the webcam only supports 720p, the encoder configuration will automatically adjust to the highest resolution that the device can handle, which in this case is 720p.
:::

##### What is `optimizationMode`?

- This parameter specifies the optimization mode for the video track being generated.
- `motion` : This type of track focuses more on motion video such as webcam video, movies or video games.
  - It will degrade `resolution` in order to maintain `frame rate`.
- `text` : This type of track focuses on significant sharp edges and areas of consistent color that can change frequently such as presentations or web pages with text content.
  - It will degrade `frame rate` in order to maintain `resolution`.
- `detail` : This type of track focuses more on the details of the video such as, presentations, painting or line art.
  - It will degrade `frame rate` in order to maintain `resolution`.

##### What is `multiStream`?

- By enabling multiStream, your livestream will broadcast multiple resolutions (e.g., 720p, 480p, 360p), allowing viewers to receive the best stream quality based on their network.
The **`multiStream : true`** configuration indicates that VideoSDK, by default, sends multiple resolution video streams to the server. For example, if a user's device capability is 720p, VideoSDK sends streams in 720p, 640p, and 480p resolution. This enables VideoSDK to deliver the appropriate stream to each participant based on their network bandwidth.


<center>

![Multi Stream False](/img/multistream_true.png)

</center>

Setting **`multiStream : false`** restricts VideoSDK to send only one stream, helping to maintain quality by focusing on a single resolution.

<center>

![Multi Stream False](/img/multistream_false.png)

</center>

:::danger
The `setQuality` parameter will not have any effect if multiStream is set to `false`.
:::

### `How to Setup a Custom Video Track ?`

You can plug in your custom video track either before going live or dynamically while the session is ongoing.

1. [Setup during live stream initialization](/react/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track#1-setup-during-live-stream-initialization)
2. [Setup dynamically using methods](/react/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track#2-setup-dynamically-using-methods)

##### 1. Setting up a Custom Track during the initialization of a liveStream

If you're starting the stream with the webcam enabled `(webcamEnabled: true)` and wish to use a custom track from the beginning, pass it through the config of initMeeting as shown below.

:::caution
Custom Track will not apply on the `webcamEnabled: false` configuration.
:::

##### Example

**Kotlin:**

```js
override fun onCreate(savedInstanceState: Bundle?) {
  //..

  //highlight-start
  val customTracks: MutableMap
</center>

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [Custom Video Track](/react/api/sdk-reference/custom-tracks#custom-video-track---react)


---

# Customized Live Stream - Android

VideoSDK is a platform that offers a range of video streaming tools and solutions for content creators, publishers, and developers.

### Custom Template

- Custom template is template for live stream, which allows users to add real-time graphics to their streams.
- With custom templates, users can create unique and engaging video experiences by overlaying graphics, text, images, and animations onto their live streams. These graphics can be customized to match the branding.
- Custom templates enable users to create engaging video content with real-time graphics, with live scoreboards, social media feeds, and other customizations, users can easily create unique and visually appealing streams that stands out from the crowd.

:::note

Custom templates can be used with recordings and RTMP service provided by VideoSDK as well.

:::

### What you can do with Custom Template

Using a custom template, you may create a variety of various modes. Here are a few of the more well-known modes that you can create.

- **`PK Host:`** Host can organise player vs player battle. Below image is example of gaming battle.

- **`Watermark:`** Host can add & update watermark anywhere in the template. In below image we have added VideoSDK watermark on top right side of the screen.

- **`News Mode:`** Host can add dynamic text in lower third banner. in below image we have added some sample text in bottom left of the screen.

![Mobile Custom Template ](https://cdn.videosdk.live/website-resources/docs-resources/mobile_custom_template.png)

## Custom template with VideoSDK

In this section, we will discuss how Custom Templates work with VideoSDK.

- **`Host`**: The host is responsible for starting the live streaming by passing the `templateURL`. The `templateURL` is the URL of the hosted template webpage. The host is also responsible for managing the template, such as changing text, logos, and switching template layout, among other things.

- **`VideoSDK Template Engine`** : The VideoSDK Template Engine accepts and opens the templateURL in the browser. It listens to all the events performed by the Host and enables customization of the template according to the Host's preferences.

- **`Viewer`**: The viewer can stream the content. They can watch the live stream with the added real-time graphics, which makes for a unique and engaging viewing experience.

![custom template](https://cdn.videosdk.live/website-resources/docs-resources/custom_template.png)

### Understanding Template URL

The template URL is the webpage that VideoSDK Template Engine will open while composing the live stream.

The template URL will appear as shown below.

![template url](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_url.png)

The Template URL consists of two parts:

- Your actual page URL, which will look something like `https://example.com/videosdk-template`.
- Query parameters, which will allow the VideoSDK Template Engine to join the meeting when the URL is opened. There are a total of three query parameters:
  - `token`: This will be your token, which will be used to join the meeting.
  - `meetingId`: This will be the meeting ID that will be joined by the VideoSDK Template Engine.
  - `participantId`: This will be the participant ID of the VideoSDK Template Engine, which should be passed while joining the template engine in your template so that the tempalte engine participant is not visible to other participants. **This parameter will be added by the** **VideoSDK**.

:::info

Above mentioned query parameters are mandatory. Apart from these parameters, you can pass any other extra parameters which are required according to your use-case.

:::

### **Creating Template**

**`Step 1:`** Create a new React App using the below command

```js
npx create-react-app videosdk-custom-template
```

:::note

You can use VideoSDK's React or JavaScript SDK to create custom template. Following is the example of building custom template with React SDK.

:::

**`Step 2:`** Install the VideoSDK using the below-mentioned npm command.

Make sure you are in your react app directory before you run this command.

```js
npm install "@videosdk.live/react-sdk"

//For the Participants Video
npm install "react-player"
```

###### App Architecture

![template architechture](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_arch.png)

###### Structure of the Project

```jsx title="Project Structure"
   root
   ├── node_modules
   ├── public
   ├── src
   │    ├── components
   │          ├── MeetingContainer.js
   │          ├── ParticipantsAudioPlayer.js
   │          ├── ParticipantsView.js
   │          ├── Notification.js
   │    ├── icons
   │    ├── App.js
   │    ├── index.js
   ├── package.json
   .
```

**`Step 3:`** Next we will fetch the query parameters, from the URL which we will later use to initialize the meeting

```js title=App.js
function App() {
  const { meetingId, token, participantId } = useMemo(() => {
    //highlight-start
    const location = window.location;

    const urlParams = new URLSearchParams(location.search);

    const paramKeys = {
      meetingId: "meetingId",
      token: "token",
      participantId: "participantId",
    };

    Object.keys(paramKeys).forEach((key) => {
      paramKeys[key] = urlParams.get(key)
        ? decodeURIComponent(urlParams.get(key))
        : null;
    });

    return paramKeys;
    //highlight-end
  }, []);
}
```

**`Step 4:`** Now we will initialize the meeting with the parameters we extracted from the URL. Make sure `joinWithoutUserInteraction` is specified, so that the template engine is able to join directly into the meeting, on the page load.

```js title=App.js
function App(){
//highlight-next-line
...

return meetingId && token && participantId ? (
  <div>
    
    </MeetingProvider>
  </div>
) : null;

}
```

**`Step 5:`** Let us create the `MeetingContainer` which will render the meeting view for us.

- It will also listen to the PubSub messages from the `CHANGE_BACKGROUND` topic, which will change the background color of the meeting.
- It will have `Notification` component which will show any messages share by Host

:::note

We will be using the PubSub mechanism to communicate with the template. You can learn more about [PubSub from here](../video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

:::




```js title=MeetingContainer.js




export const MeetingContainer = () => {
  const { isMeetingJoined, participants, localParticipant } = useMeeting();
  //highlight-next-line
  const { messages } = usePubSub("CHANGE_BACKGROUND");

  const remoteSpeakers = [...participants.values()].filter((participant) => {
    return (
      participant.mode == Constants.modes.SEND_AND_RECV && !participant.local
    );
  });

  return isMeetingJoined ? (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        height: "100vh",
        //highlight-start
        backgroundColor:
          messages.length > 0
            ? messages.at(messages.length - 1).message
            : "#fff",
        //highlight-end
      }}
    >
      //highlight-next-line
      
      <div
        style={{
          display: "grid",
          gridTemplateColumns: remoteSpeakers?.length > 1 ? "1fr 1fr" : "1fr",
          flex: 1,
          maxHeight: `100vh`,
          overflowY: "auto",
          gap: "20px",
          padding: "20px",
          alignItems: "center",
          justifyItems: "center",
        }}
      >
        {[...remoteSpeakers].map((participant) => {
          return (
            //highlight-start
            
            //highlight-end
          );
        })}
      </div>
      //highlight-next-line
      
    </div>
  ) : (
    <div
      style={{
        display: "flex",
        justifyContent: "center",
        alignItems: "center",
        height: "100vh",
      }}
    >
      <div class="loader"></div>
    </div>
  );
};
```

**`Step 6:`** Let us create the `ParticipantView` and `ParticipantsAudioPlayer` which will render the video and audio of the participants respectively.

```js title=ParticipantView.js




export const ParticipantView = (props) => {
  const { webcamStream, webcamOn, displayName, micOn } = useParticipant(
    props.participantId
  );

  const videoStream = useMemo(() => {
    if (webcamOn && webcamStream) {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(webcamStream.track);
      return mediaStream;
    }
  }, [webcamStream, webcamOn]);

  return (
    <div
      style={{
        width: "100%",
        height: "400px",
        maxWidth: "600px",
        display: "flex",
        flex: 1,
        alignItems: "center",
        justifyContent: "center",
        position: "relative",
        backgroundColor: "#1A1C22",
        borderRadius: "10px",
        overflow: "hidden",
      }}
      class="video-cover"
    >
      {webcamOn && webcamStream ? (
        
      ) : (
        <div
          style={{
            fontSize: "50px",
            color: "#fff",
          }}
        >
          {String(displayName).charAt(0).toUpperCase()}
        </div>
      )}
      <div
        style={{
          position: "absolute",
          left: "10px",
          bottom: "10px",
          backgroundColor: "#050A0E",
          color: "#fff",
          padding: "4px",
          borderRadius: "4px",
          alignItems: "center",
          justifyItems: "center",
          display: "flex",
        }}
      >
        {displayName}{" "}
        {!micOn && }
      </div>
    </div>
  );
};
```

```js title=ParticipantsAudioPlayer.js


const ParticipantAudio = ({ participantId }) => {
  const { micOn, micStream, isLocal } = useParticipant(participantId);
  const audioPlayer = useRef();

  useEffect(() => {
    if (!isLocal && audioPlayer.current && micOn && micStream) {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(micStream.track);

      audioPlayer.current.srcObject = mediaStream;
      audioPlayer.current.play().catch((err) => {});
    } else {
      audioPlayer.current.srcObject = null;
    }
  }, [micStream, micOn, isLocal, participantId]);

  return <audio autoPlay playsInline controls={false} ref={audioPlayer} />;
};

export const ParticipantsAudioPlayer = () => {
  const mMeeting = useMeeting();

  const participants = mMeeting?.participants;

  return participants ? (
    [...participants.keys()].map((participantId) => (
      
    ))
  ) : (
    <></>
  );
};
```

**`Step 7:`** Let us create the `Notification` component which will listen to PubSub messages for the topic `SIGNALLING_ONLY_MESSAGE` and show a notification on the lower left corner.

```js title=Notification.js


export const Notification = () => {
  const timeoutRef = useRef(null);
  const handleChatMessage = (msg) => {
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
    }
    setMessage(msg);
    timeoutRef.current = setTimeout(() => {
      setMessage(null);
    }, 3200);
  };
  const [message, setMessage] = useState(null);
  const { publish } = usePubSub("SIGNALLING_ONLY_MESSAGE", {
    onMessageReceived: handleChatMessage,
  });
  useEffect(() => {
    return () => {
      if (timeoutRef.current) {
        clearTimeout(timeoutRef.current);
      }
    };
  }, []);
  return message ? (
    <div
      style={{
        backgroundColor: "#232830",
        padding: "10px",
        textAlign: "center",
        color: "#fff",
        position: "absolute",
        bottom: "50px",
        left: "30px",
        borderRadius: "10px",
        animation: "fadein 0.5s",
      }}
    >
      <strong>
        {message.senderName} says {message.message}
      </strong>
    </div>
  ) : null;
};
```

:::note

For the CSS stylings and animations used in the project, please [refer to this file](https://github.com/videosdk-live/quickstart/blob/main/react-custom-template-manager/src/index.css).

:::

**`Step 9:`** Once tested, you can deploy it using your backend or host it on services like [firebase](https://www.geeksforgeeks.org/how-to-deploy-react-project-on-firebase/) or vercel.

:::tip

You can checkout the github repository for sample custom template we just [created here](https://github.com/videosdk-live/videosdk-custom-recording-template-react-example).

:::

### Setup Livestream Using Custom Template

- To use Custom Template, you will need Host and Viewer setup from where the host will start the livestream and viewer can watch them.

![Android Custom Template Example](https://cdn.videosdk.live/website-resources/docs-resources/android_custom_template.png)

- You can clone this example and run it on your system.

```bash
git clone https://github.com/videosdk-live/quickstart.git
```

- The cloned example will contain two directories under the `android-custom-template-manager` directory which has to runned.

  - **For Kotlin** : `Videosdk_android_kotlin_hls_quickstart`
  - **For Java** : `Videosdk_android_java_hls_quickstart`



**Kotlin:**

```js
cd android-custom-template-manager
cd Videosdk_android_kotlin_hls_quickstart
```

---

**Java:**

```js
cd android-custom-template-manager
cd Videosdk_android_java_hls_quickstart
```

- To use the custom template which we just deployed, we will call the [Start HLS API](https://docs.videosdk.live/api-reference/realtime-communication/start-hlsStream) instead of the `startHls` method from the `Meeting` class. This code has already been added in the example you cloned.

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

**Kotlin:**

```js
btnHls!!.setOnClickListener {
  //Update your Custom Template URL here if you have deployed your own, if not deployed you can use this template from our URL.
  //highlight-start
  val templateUrl =
  "https://lab.videosdk.live/react-custom-template-demo?meetingId=" + meeting!!.meetingId + "&token=" + token
  //highlight-end

  val bodyJson = JSONObject()
  JsonUtils.jsonPut(bodyJson, "roomId", meeting!!.meetingId)
  JsonUtils.jsonPut(bodyJson, "templateUrl", templateUrl)

  val config= new JSONObject()
  JsonUtils.jsonPut(config,"orientation","portrait")
  JsonUtils.jsonPut(bodyJson,"config",config)

  AndroidNetworking.post("https://api.videosdk.live/v2/hls/start")
.addHeaders(
    "Authorization",
    token
) //we will pass the token in the Headers
.addJSONObjectBody(bodyJson)
.build()
.getAsJSONObject(object : JSONObjectRequestListener {
    override fun onResponse(response: JSONObject) {
        try {
            Log.d("TAG", "onResponse: $response") // result will have playbackHlsUrl and livestreamUrl
        } catch (e: Exception) {
            e.printStackTrace()
        }
    }
    override fun onError(anError: ANError) {
        anError.printStackTrace()
        Toast.makeText(
            mContext,
            anError.message,
            Toast.LENGTH_SHORT
        ).show()
    }
})
}
```

---

**Java:**

```js
btnHls.setOnClickListener(v -> {
  //Update your Custom Template URL here if you have deployed your own, if not deployed you can use this template from our URL.
  //highlight-start
  final String templateUrl =
  "https://lab.videosdk.live/react-custom-template-demo?meetingId=" + meeting.getMeetingId() + "&token=" + token;
  //highlight-end

  JSONObject bodyJson = new JSONObject();
  JsonUtils.jsonPut(bodyJson, "roomId", meeting.getMeetingId());
  JsonUtils.jsonPut(bodyJson, "templateUrl", templateUrl);

  JSONObject config= new JSONObject();
  JsonUtils.jsonPut(config,"orientation","portrait");
  JsonUtils.jsonPut(bodyJson,"config",config);

  AndroidNetworking.post("https://api.videosdk.live/v2/hls/start")
.addHeaders("Authorization", token) //we will pass the token in the Headers
.addJSONObjectBody(bodyJson)
.build()
.getAsJSONObject(new JSONObjectRequestListener() {
    @Override
    public void onResponse(JSONObject response) {
        try {
            Log.d("TAG", "onResponse: " + response.toString()); // result will have playbackHlsUrl and livestreamUrl
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
    @Override
    public void onError(ANError anError) {
        anError.printStackTrace();
        Toast.makeText(mContext, anError.getMessage(), Toast.LENGTH_SHORT).show();
    }
});
});
```

- This example has two option on the Host side which will allow them to change the background and send the messages to the viewer.

- Let's give this example a test run.


<div style={{textAlign: 'center'}}>



</div>

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start HLS API](/api-reference/realtime-communication/start-hlsStream)
- [onHlsStateChanged](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onhlsstatechanged)


---

# Manage Audio and Video Devices - Android

This feature allows hosts to switch their microphone, speaker, or camera devices during a live stream. Only hosts (in `SEND_AND_RECV` mode) can change input/output devices, ensuring they maintain control over their audio and video quality, while audience members (in `RECV_ONLY` mode) continue to receive the broadcast seamlessly.

### Changing Input/Output Audio Device

###### `getMics()`

- This method of the `Meeting` class provides a list of all available microphones, which can be shown in a dropdown for selection.

- It returns an array of objects, each containing a `deviceId` and a `label` representing an audio input device.

###### `changeMic()`

- Participant can change the audio device using `changeMic(AppRTCAudioManager.AudioDevice device)` method of `Meeting` class.

- Parameters that can be passed to `changeMic` are

  | Audio Devices                                | Usage                        |
  | -------------------------------------------- | ---------------------------- |
  | AppRTCAudioManager.AudioDevice.BLUETOOTH     | For Bluetooth Device.        |
  | AppRTCAudioManager.AudioDevice.WIRED_HEADSET | For Wired Handset Device.    |
  | AppRTCAudioManager.AudioDevice.SPEAKER_PHONE | For Inbuilt - Speaker Device |
  | AppRTCAudioManager.AudioDevice.EARPIECE      | For Earpiece Device          |

- When participant changes the Mic, `AppRTCAudioManager.AudioManagerEvents()` is triggered which can be set to `Meeting` class by using `setAudioDeviceChangeListener()`.

#### Example



**Kotlin:**

```js
private fun getMics(): MutableSet
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
</manifest>
```

## Changing Camera Input Device


###### `changeWebcam()`

- To change the camera device of the host, you need to call `changeWebcam()` method.

#### Example

**Kotlin:**

```js
  btnWebcam!!.setOnClickListener {
// Change Webcam during liveStream
//highlight-next-line
liveStream!!.changeWebcam()
  }
```

---

**Java:**

```js
  btnWebcam.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
    // Change Webcam during liveStream
    //highlight-next-line
    liveStream.changeWebcam();
  }
  });
```


### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [getMics()](/android/api/sdk-reference/meeting-class/methods#getmics)
- [changeMic()](/android/api/sdk-reference/meeting-class/methods#changemic)
- [changeWebcam()](/android/api/sdk-reference/meeting-class/methods#changewebcam)


---

# Mute / Unmute Mic - Android

This feature allows hosts to communicate with each other during the livestream by enabling or disabling their microphones. While only hosts (participants in SEND_AND_RECV mode) can speak, audience members (in RECV_ONLY mode) can listen to the conversation in real time.

### `unmuteMic()`

- By using the `unmuteMic()` function of the `Meeting` class, the host can publish their audio to other hosts and audience members.

- You can also pass a customised audio track in the `unmuteMic()` method by using [Custom Audio Track](/android/guide/interactive-live-streaming/custom-media-sources/custom-audio-sources).

### `muteMic()`

- By using the `muteMic()` function of the `Meeting` class, the host can stop publishing their audio to other hosts and audience members.

#### Example



**Kotlin:**

```js
  private var micEnabled = false

  btnMic!!.setOnClickListener { _: View? ->
 if (micEnabled) {
  // Muting Mic
  //highlight-next-line
   liveStream!!.muteMic()
   micEnabled=false
 } else {
  // Unmuting Mic
  //highlight-next-line
  liveStream!!.unmuteMic()
  micEnabled=true
 }
  }
```

---

**Java:**

```js
  private boolean micEnabled = false;

  btnMic.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
      if (micEnabled) {
          // Muting Mic
          //highlight-next-line
          liveStream.muteMic();
          micEnabled = false;
      } else {
        // Unmuting Mic
        //highlight-next-line
          liveStream.unmuteMic();
          micEnabled = true;
      }
  }
  });
```

### Events associated with unmuteMic

- Every Participant—including all the hosts and audience members will receive a callback on [`onStreamEnabled()`](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamenabled) of the [`Participant`](/android/api/sdk-reference/participant-class/introduction) with `Stream` object.


### Events associated with muteMic

- Every Participant—including all the hosts and audience members will receive a callback on [`onStreamDisabled()`](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamdisabled) of the [`Participant`](/android/api/sdk-reference/participant-class/introduction) with `Stream` object.


**Kotlin:**

```js
  meeting!!.localParticipant.addEventListener(object : ParticipantEventListener() {
//Callback for when the participant starts a stream
//highlight-start
override fun onStreamEnabled(stream: Stream) {
    if(stream.getKind().equals("audio")){
      Log.d("VideoSDK","Audio Stream On: onStreamEnabled $stream");
    }
}
//highlight-end

//Callback for when the participant stops a stream
//highlight-start
override fun onStreamDisabled(stream: Stream) {
    if(stream.getKind().equals("audio")){
      Log.d("VideoSDK","Audio Stream On: onStreamDisabled $stream");
    }
}
//highlight-end
  });
```

---

**Java:**

```js
  participant.addEventListener(new ParticipantEventListener() {
//Callback for when the participant starts a stream
//highlight-start
@Override
public void onStreamEnabled(Stream stream) {
    if(stream.getKind().equals("audio")){
      Log.d("VideoSDK","Audio Stream On: onStreamEnabled" + stream);
    }
}
//highlight-end

//Callback for when the participant stops a stream
//highlight-start
@Override
public void onStreamDisabled(Stream stream) {
    if(stream.getKind().equals("audio")){
      Log.d("VideoSDK","Audio Stream Off: onStreamDisabled" + stream);
    }
}
//highlight-end
  });
```

## Audio Permissions

- To use the microphone in a live stream, you need to add permission in `app/src/main/AndroidManifest.xml` after `</application>`.

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

- You need to set up a permission request that provides this access.

**Kotlin:**

```js
import android.Manifest
import android.content.pm.PackageManager
import android.os.Bundle
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import androidx.core.app.ActivityCompat
import androidx.core.content.ContextCompat

class LiveStreamActivity : AppCompatActivity() {
private val PERMISSION_REQUEST_CODE: Int = 1;

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_live_stream);

    //highlight-start
    if (checkPermission()) {
        // . write your main code to execute, It will execute if the permission is already given.
    } else {
        requestPermission()
    }
    //highlight-end
}
private fun checkPermission(): Boolean {
    //highlight-next-line
    return ContextCompat.checkSelfPermission(this, Manifest.permission.RECORD_AUDIO) == PackageManager.PERMISSION_GRANTED
}

private fun requestPermission() {
  //highlight-start
    ActivityCompat.requestPermissions(
        this, arrayOf(Manifest.permission.RECORD_AUDIO),
        PERMISSION_REQUEST_CODE
    )
  //highlight-end
}

override
fun onRequestPermissionsResult(
    requestCode: Int,
    permissions: Array<out String>,
    grantResults: IntArray
) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults)
    when (requestCode) {
        PERMISSION_REQUEST_CODE -> if (grantResults.isNotEmpty() && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
            Toast.makeText(applicationContext, "Permission Granted", Toast.LENGTH_SHORT).show()
            // main logic
        } else {
            Toast.makeText(applicationContext, "Permission Denied", Toast.LENGTH_SHORT).show()
        }
    }
}
}
```

---

**Java:**

```js
import androidx.annotation.NonNull;
import androidx.appcompat.app.AppCompatActivity;
import androidx.core.app.ActivityCompat;
import androidx.core.content.ContextCompat;

import android.Manifest;
import android.content.pm.PackageManager;
import android.os.Bundle;
import android.widget.Toast;

import java.util.ArrayList;
import java.util.List;

public class LiveStreamActivity extends AppCompatActivity {

private static final int PERMISSION_REQUEST_CODE = 1;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_live_stream);

    //highlight-start
    if (checkPermission()) {
        // . write your main code to execute, It will execute if the permission is already given.
    } else {
        requestPermission();
    }
    //highlight-end
}

private boolean checkPermission() {
    //highlight-next-line
    return ContextCompat.checkSelfPermission(this, Manifest.permission.RECORD_AUDIO) == PackageManager.PERMISSION_GRANTED;
}

private void requestPermission() {
    List<String> permissionList = new ArrayList<String>();
    String[] permissions = {};
    permissionList.add(Manifest.permission.RECORD_AUDIO);
    //highlight-start
    ActivityCompat.requestPermissions(
            this, permissionList.toArray(permissions),
            PERMISSION_REQUEST_CODE
    );
    //highlight-end
}

@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
    switch (requestCode) {
        case PERMISSION_REQUEST_CODE:
            if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                Toast.makeText(MainActivity.this, "Permission Granted", Toast.LENGTH_SHORT).show();
                // main logic
            } else {
                Toast.makeText(MainActivity.this, "Permission Denied", Toast.LENGTH_SHORT).show();
            }
            break;
    }
}
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [unmuteMic()](/android/api/sdk-reference/meeting-class/methods#unmutemic)
- [muteMic()](/android/api/sdk-reference/meeting-class/methods#mutemic)
- [onStreamEnabled()](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamenabled)
- [onStreamDisabled()](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamdisabled)


---

---
title: On / Off Camera | Video SDK
hide_title: true
hide_table_of_contents: false
description: Camera Controls features quick integrate in Javascript, React JS, Android, IOS, React Native, Flutter with Video SDK to add live video & audio conferencing to your applications.
sidebar_label: On / Off Camera
pagination_label: On / Off Camera
keywords:
  - audio calling
  - video calling
  - real-time communication
  - collaboration
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: on-off-camera
--- 

# On / Off Camera - Android

This feature enables hosts to turn their cameras on or off to share their video stream with other hosts and audience members during the meeting. Only hosts (in `SEND_AND_RECV` mode) can broadcast their camera feed, while audience members (in `RECV_ONLY` mode) can view it in real time.

### `enableWebcam()`

- By using the `enableWebcam()` function of the `Meeting` class, the host can publish their video to to other hosts and audience members.

- You can also pass a customised video track in `enableWebcam()` by using [Custom Video Track](../custom-media-sources/custom-video-sources.md).


- Video stream of the participant can be accessed from the `onStreamEnabled` event of `ParticipantEventListener`.

### `disableWebcam()`

- By using `disableWebcam()` function of `Meeting` class, the host can stop publishing their video to to other hosts and audience members.

#### Example



**Kotlin:**

```js
  btnWebcam!!.setOnClickListener {
if (webcamEnabled) {
  // Disabling camera
  //highlight-next-line
  meeting!!.disableWebcam()
} else {
  // Enabling camera
  //highlight-next-line
  meeting!!.enableWebcam()
}
webcamEnabled=!webcamEnabled
  }
```

---

**Java:**

```js
  btnWebcam.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
    if (webcamEnabled) {
      // Disabling camera
      //highlight-next-line
      liveStream.disableWebcam();
    } else {
      // Enabling camera
      //highlight-next-line
      liveStream.enableWebcam();
    }
    webcamEnabled=!webcamEnabled;
  }
  });
```

:::important
To learn, how to render video in the meeting, follow thisdetailed [guide](/android/guide/video-and-audio-calling-api-sdk/render-media/display-video/render-participant) .
:::

### Events associated with enableWebcam

- Every Participant—including all the hosts and audience members will receive a callback on [`onStreamEnabled()`](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamenabled) event of the [`Participant`](/android/api/sdk-reference/participant-class/introduction) with `Stream` object.

### Events associated with disableWebcam

- Every Participant—including all the hosts and audience members will receive a callback on [`onStreamDisabled()`](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamdisabled) event of the [`Participant`](/android/api/sdk-reference/participant-class/introduction) with `Stream` object.


**Kotlin:**

```js
  liveStream!!.localParticipant.addEventListener(object : ParticipantEventListener() {
//Callback for when the participant starts a stream
//highlight-start
override fun onStreamEnabled(stream: Stream) {
    if(stream.getKind().equals("video")){
      Log.d("VideoSDK","Video Stream On: onStreamEnabled $stream");
    }
}
//highlight-end

//Callback for when the participant stops a stream
//highlight-start
override fun onStreamDisabled(stream: Stream) {
    if(stream.getKind().equals("video")){
      Log.d("VideoSDK","Video Stream On: onStreamDisabled $stream");
    }
}
//highlight-end
  });
```

---

**Java:**

```js
  participant.addEventListener(new ParticipantEventListener() {
//Callback for when the participant starts a stream
//highlight-start
@Override
public void onStreamEnabled(Stream stream) {
    if(stream.getKind().equals("video")){
      Log.d("VideoSDK","Video Stream On: onStreamEnabled" + stream);
    }
}
//highlight-end

//Callback for when the participant stops a stream
//highlight-start
@Override
public void onStreamDisabled(Stream stream) {
    if(stream.getKind().equals("video")){
      Log.d("VideoSDK","Video Stream Off: onStreamDisabled" + stream);
    }
}
//highlight-end
  });
```

### Video Permissions

- To use the camera in a live stream, you need to add permission in `app/src/main/AndroidManifest.xml` after `</application>`.

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

- You need to set up a permission request that provides this access.

**Kotlin:**

```js
import android.Manifest
import android.content.pm.PackageManager
import android.os.Bundle
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import androidx.core.app.ActivityCompat
import androidx.core.content.ContextCompat

class LiveStreamActivity : AppCompatActivity() {
private val PERMISSION_REQUEST_CODE: Int = 1;

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_live_stream);

    //highlight-start
    if (checkPermission()) {
        // . write your main code to execute, It will execute if the permission is already given.
    } else {
        requestPermission()
    }
    //highlight-end
}
private fun checkPermission(): Boolean {
    //highlight-next-line
    return ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA) == PackageManager.PERMISSION_GRANTED
}

private fun requestPermission() {
  //highlight-start
    ActivityCompat.requestPermissions(
        this, arrayOf(Manifest.permission.CAMERA),
        PERMISSION_REQUEST_CODE
    )
  //highlight-end
}

override
fun onRequestPermissionsResult(
    requestCode: Int,
    permissions: Array<out String>,
    grantResults: IntArray
) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults)
    when (requestCode) {
        PERMISSION_REQUEST_CODE -> if (grantResults.isNotEmpty() && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
            Toast.makeText(applicationContext, "Permission Granted", Toast.LENGTH_SHORT).show()
            // main logic
        } else {
            Toast.makeText(applicationContext, "Permission Denied", Toast.LENGTH_SHORT).show()
        }
    }
}
}
```

---

**Java:**

```js
import androidx.annotation.NonNull;
import androidx.appcompat.app.AppCompatActivity;
import androidx.core.app.ActivityCompat;
import androidx.core.content.ContextCompat;

import android.Manifest;
import android.content.pm.PackageManager;
import android.os.Bundle;
import android.widget.Toast;

import java.util.ArrayList;
import java.util.List;

public class LiveStreamActivity extends AppCompatActivity {

private static final int PERMISSION_REQUEST_CODE = 1;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_live_stream);

    //highlight-start
    if (checkPermission()) {
        // . write your main code to execute, It will execute if the permission is already given.
    } else {
        requestPermission();
    }
    //highlight-end
}

private boolean checkPermission() {
    //highlight-next-line
    return ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA) == PackageManager.PERMISSION_GRANTED;
}

private void requestPermission() {
    List<String> permissionList = new ArrayList<String>();
    String[] permissions = {};
    permissionList.add(Manifest.permission.CAMERA);
    //highlight-start
    ActivityCompat.requestPermissions(
            this, permissionList.toArray(permissions),
            PERMISSION_REQUEST_CODE
    );
    //highlight-end
}

@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
    switch (requestCode) {
        case PERMISSION_REQUEST_CODE:
            if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                Toast.makeText(MainActivity.this, "Permission Granted", Toast.LENGTH_SHORT).show();
                // main logic
            } else {
                Toast.makeText(MainActivity.this, "Permission Denied", Toast.LENGTH_SHORT).show();
            }
            break;
    }
}
}
```

:::important
If the app goes to the background, VideoSDK detectes this event based on activity lifecycle and release the camera so that it can be used by other apps. In order to make sure this functionality works properly use  `VideoSDK.setActivityForLifeCycle(activity)` to specify which activity VideoSDK should monitor for lifecycle changes.
:::

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [enableWebcam()](/android/api/sdk-reference/meeting-class/methods#enablewebcam)
- [disableWebcam()](/android/api/sdk-reference/meeting-class/methods#disablewebcam)
- [onStreamEnabled()](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamenabled)
- [onStreamDisabled()](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamdisabled)


---

---
title: Screen Share | Video SDK
hide_title: true
hide_table_of_contents: false
description: Share your Screen features quick integrate in Javascript, React JS, Android, IOS, React Native, Flutter with Video SDK to add live video & audio conferencing to your applications.
sidebar_label: Screen Share
pagination_label: Screen Share
keywords:
  - audio calling
  - video calling
  - real-time communication
  - collaboration
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: screen-share
--- 

# Screen Share - Android

This feature enables hosts to start or stop sharing their screen with other hosts and audience members during the live stream. Only hosts (in `SEND_AND_RECV` mode) can broadcast their screen, while audience members (in `RECV_ONLY` mode) can view it in real time.

### How Screen share works?

- The following diagram shows flow of the screen sharing in android using VideoSDK :

<div style={{textAlign: 'center'}}>

![VideoSDK Android Screenshare Flow Diagram](/img/android/screenshare/flow_diagram.png)

</div>

### `enableScreenShare()`

- By using `enableScreenShare()` function of `Meeting` class,the host can share their mobile screen to other hosts and audience members.

- You can pass customised screenshare track in `enableScreenShare()` by using [Custom Screen Share Track](/android/guide/interactive-live-streaming/custom-media-sources/custom-screenshare-sources).

- Screen Share stream of the participant can be accessed from the `onStreamEnabled` event of `ParticipantEventListener`.

### Screenshare permission

- A participant’s Screen share stream is provided via the `MediaProjection` API. This API is only compatible with `Build.VERSION_CODES.LOLLIPOP` or higher.

- Get an instance of the `MediaProjectionManager` and Call the `createScreenCaptureIntent()` method in an activity. This initiates a prompt dialog for the user to confirm screen projection.

- One will get a prompt dialog like this:

<div style={{textAlign: 'center'}}>

<img
src={require('/img/android/screenshare/user_permission.jpg').default}
alt="user permission"
width="450"
/>

</div>

<br/>

- After permission is received from the user, you can call `enableScreenShare()` method.



**Kotlin:**

```js
private fun enableScreenShare() {
val mediaProjectionManager = application.getSystemService(
    MEDIA_PROJECTION_SERVICE
) as MediaProjectionManager
startActivityForResult(
    mediaProjectionManager.createScreenCaptureIntent(), CAPTURE_PERMISSION_REQUEST_CODE
)
}

public override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode != CAPTURE_PERMISSION_REQUEST_CODE) return
if (resultCode == RESULT_OK) {
    // Enabling screen share
    //highlight-next-line
    liveStream!!.enableScreenShare(data)
}
}
```

---

**Java:**

```js
private void enableScreenShare() {
MediaProjectionManager mediaProjectionManager =
    (MediaProjectionManager) getApplication().getSystemService(
        Context.MEDIA_PROJECTION_SERVICE);
startActivityForResult(
    mediaProjectionManager.createScreenCaptureIntent(), CAPTURE_PERMISSION_REQUEST_CODE);
}

@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
super.onActivityResult(requestCode, resultCode, data);
if (requestCode != CAPTURE_PERMISSION_REQUEST_CODE)
    return;
if (resultCode == Activity.RESULT_OK) {
    // Enabling screen share
    //highlight-next-line
    liveStream.enableScreenShare(data);
}
}
```

### Customise notification

- When a presenter starts screen share, presenter will receive a notification with a pre-defined title and message.

- Notification with pre-defined title and message will look like this:

<div style={{textAlign: 'center'}}>

<img
src={require('/img/android/screenshare/notification.jpg').default}
alt="notification"
width="450"
/>

</div>

- You can Customise those title, message and icon as per your requirements using `<meta-data>` specified in `app/src/main/AndroidManifest.xml`.

```js
<application>
  <meta-data
    android:name="notificationTitle"
    //highlight-next-line
    android:value="@string/notificationTitle"
  />
  <meta-data
    android:name="notificationContent"
    //highlight-next-line
    android:value="@string/notificationContent"
  />
  <meta-data
    android:name="notificationIcon"
    //highlight-next-line
    android:resource="@mipmap/ic_launcher_round"
  />
</application>
```

### `disableScreenShare()`

- By using `disableScreenShare()` function of `Meeting` class,the host can stop sharing their mobile screen to other hosts and audience members.

**Kotlin:**

```js
private fun disableScreenShare() {
// Disabling screen share
//highlight-next-line
liveStream!!.disableScreenShare()
}
```

---

**Java:**

```js
private void disableScreenShare(){
// Disabling screen share
//highlight-next-line
liveStream.disableScreenShare();
}
```

### Events associated with enableScreenShare

- Participant who share their mobile screen will receive a callback on [`onStreamEnabled()`](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamenabled) of the [`Participant`](/android/api/sdk-reference/participant-class/introduction) with `Stream` object.

- While other Participants will receive [`onPresenterChanged()`](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onpresenterchanged) callback of the [`Meeting`](/android/api/sdk-reference/meeting-class/introduction) class with the participantId as `presenterId` who started the screen share.

### Events associated with disableScreenShare

- Participant who shared their mobile screen will receive a callback on [`onStreamDisabled()`](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamdisabled) of the [`Participant`](/android/api/sdk-reference/participant-class/introduction) with `Stream` object.

- While other Participants will receive [`onPresenterChanged()`](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onpresenterchanged) callback of the [`Meeting`](/android/api/sdk-reference/meeting-class/introduction) class with the `presenterId` as `null` indicating there is no presenter.

**Kotlin:**

```js
private fun setLocalListeners() {
liveStream!!.localParticipant.addEventListener(object : ParticipantEventListener() {
    //Callback for when the participant starts a stream
    //highlight-start
    override fun onStreamEnabled(stream: Stream) {
       if (stream.kind.equals("share", ignoreCase = true)) {
          Log.d("VideoSDK","Share Stream On: onStreamEnabled $stream");
        }
    }
    //highlight-end

    //Callback for when the participant stops a stream
    //highlight-start
    override fun onStreamDisabled(stream: Stream) {
        if (stream.kind.equals("share", ignoreCase = true)) {
           Log.d("VideoSDK","Share Stream On: onStreamDisabled $stream");
        }
    }
    //highlight-end
});
}

private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
//Callback for when the presenter changes
//highlight-start
override fun onPresenterChanged(participantId: String) {
    if(!TextUtils.isEmpty(participantId))
    {
      Log.d("VideoSDK","$participantId started screen share");
    }else{
      Log.d("VideoSDK","some one stopped screen share");
    }
}
//highlight-end
}
```

---

**Java:**

```js
private void setLocalListeners() {
liveStream.getLocalParticipant().addEventListener(new ParticipantEventListener() {
    //Callback for when the participant starts a stream
    //highlight-start
    @Override
    public void onStreamEnabled(Stream stream) {
        if (stream.getKind().equalsIgnoreCase("share")) {
            Log.d("VideoSDK","Share Stream On: onStreamEnabled" + stream);
        }
    }
    //highlight-end

    //Callback for when the participant stops a stream
    //highlight-start
    @Override
    public void onStreamDisabled(Stream stream) {
        if (stream.getKind().equalsIgnoreCase("share")) {
            Log.d("VideoSDK","Share Stream Off: onStreamDisabled" + stream);
        }
    }
    //highlight-end
});
}

private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
//Callback for when the presenter changes
//highlight-start
@Override
public void onPresenterChanged(String participantId) {
  if(participantId != null){
    Log.d("VideoSDK",participantId + "started screen share");
  }else{
    Log.d("VideoSDK","some one stopped screen share");
  }
}
//highlight-end
};
```

### Rendering Screen Share Stream

- When a host participant shares their screen, the `onStreamEnabled()` function of the `ParticipantEventListener` is triggered, allowing the `Stream` to be added to a `VideoView`.

**Kotlin:**

```js
private fun setLocalListeners() {
liveStream!!.localParticipant.addEventListener(object : ParticipantEventListener() {
    override fun onStreamEnabled(stream: Stream) {
       if (stream.kind.equals("share", ignoreCase = true)) {
            // display share video
            val videoTrack = stream.track as VideoTrack
            shareView!!.addTrack(videoTrack)
        }
    }
    override fun onStreamDisabled(stream: Stream) {
        if (stream.kind.equals("share", ignoreCase = true)) {
           shareView!!.removeTrack()
        }
    }
});
}
```

---

**Java:**

```js
private void setLocalListeners() {
liveStream.getLocalParticipant().addEventListener(new ParticipantEventListener() {
    @Override
    public void onStreamEnabled(Stream stream) {
        if (stream.getKind().equalsIgnoreCase("share")) {
            // display share video
            VideoTrack videoTrack = (VideoTrack) stream.getTrack();
            shareView.addTrack(videoTrack);
        }
    }
    @Override
    public void onStreamDisabled(Stream stream) {
        if (stream.getKind().equalsIgnoreCase("share")) {
            shareView.removeTrack();
        }
    }
});
}
```


### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [enableScreenShare()](/android/api/sdk-reference/meeting-class/methods#enablescreenshare)
- [disableScreenShare()](/android/api/sdk-reference/meeting-class/methods#disablescreenshare)
- [onStreamEnabled()](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamenabled)
- [onStreamDisabled()](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamdisabled)
- [onPresenterChanged()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onpresenterchanged)


---

# Geo Fencing - Android


Our SDK includes a region geofencing feature to comply with local laws and regulations worldwide. It restricts connections to servers within specified regions, ensuring users connect only to designated areas, regardless of their location. 

This helps meet regional data protection requirements and enhances user experience by addressing geographical network limitations.




### In this sequence diagram:
- User 1 (India) tries to connect to a meeting. In a regular scenario, the meeting would connect to the India region, but due to the geofence configuration, the meeting will connect to North America.

## Considerations
- If the user’s location differs from the chosen region, the network quality between these locations may be poor, affecting audio and video quality.
- Avoid using geofencing unless your scenario requires regional compliance.

:::info

Geo Fencing is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Available Regions
- INDIA
- USA
- UAE
- EUROPE
- SINGAPORE
- AUSTRALIA



---

---
title: Host vs Audience Modes | Video SDK
hide_title: true
hide_table_of_contents: false
description: Understand the differences between Host and Audience modes in Video SDK's Interactive Live Stream (ILS), their capabilities, and how participants transition between them.
sidebar_label: Host vs Audience Modes
pagination_label: Host vs Audience Modes
keywords:
  - audio calling
  - video calling
  - real-time communication
  - collaboration
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: join-meeting
--- 

# Host vs Audience Modes - Android

Before diving into implementation, it's important to understand the two core modes of participation in an `Interactive Live Stream (ILS)` session powered by VideoSDK:

### Mode Architecture

Here’s a visual representation of how these modes function within an ILS session:

![Interactive Live Streaming architecture diagram](https://assets.videosdk.live/images/interactive-live-streaming-architecture.png)


By clearly separating hosts from viewers, and offering seamless transitions between roles, VideoSDK ILS ensures high performance, low latency, and exceptional flexibility for all live streaming scenarios.

:::note

Throughout the rest of this documentation, whenever we mention "Host", we are specifically referring to a participant in the `SEND_AND_RECV` mode. Similarly, when we mention "Audience" or "Viewer", we are referring to participants in the `RECV_ONLY` mode. These distinctions are important, as each mode comes with its own set of capabilities and limitations.

:::

### `1. SEND_AND_RECV` – Host / Co-host Mode

This mode is designed for Hosts or Co-hosts who need to broadcast their audio and video to the audience and potentially interact with other hosts. Following is the list of everything a host is capable of:

- Publish and receive media (audio/video/screen share)
- Participate in conversations with other hosts
- Engage with the audience using chat, polls, reactions, and more
- Moderate the stage and manage participants
- Invite audience members on stage to become temporary broadcasters

🔢 Supports 100+ simultaneous hosts/co-hosts (Need more? Contact support@videosdk.live)

### `2. RECV_ONLY` – Audience Mode

This mode is optimized for audience members who are viewing the live stream and engaging via non-verbal interaction tools. Following is the list of everything audience is capable of:

- Receive media from all active hosts in real time (audio/video/screen share)
- No media publishing – cannot share their own audio/video unless promoted
- Engage via:
  - Live chat
  - Polls and quizzes
  - Reactions (emojis, claps, hearts, etc.)
  - Virtual gifts
  - Hand raise to request stage access

🔢 Scales to 2,000+ real-time viewers (Need more? Contact support@videosdk.live)

### Seamless Transition Between Modes

VideoSDK offers a dynamic role management system, making it easy to transition a participant from audience to stage. If a host invites an audience member on stage, they can seamlessly switch from `RECV_ONLY` mode to `SEND_AND_RECV` mode. This allows them to publish their audio/video and interact like a host or co-host. Once their role is revoked, they can return to the audience mode.



---

# Overview - Android

Interactive Live Streaming (ILS) is a low-latency streaming solution designed for real-time engagement at scale. Unlike traditional streaming protocols like HTTP Live Streaming (HLS), which typically have a delay of 15–30 seconds, ILS offers latency as low as 300 milliseconds—making it ideal for experiences that rely on immediate interaction.

While originally designed for meetings, VideoSDK seamlessly adapts to live streaming—supporting 100+ simultaneous hosts/co-hosts (Need more? Contact support@videosdk.live) and 2,000+ real-time viewers (scalable on request). This flexible architecture empowers dynamic events with multiple speakers, performers, or presenters.

ILS is not just about watching—it's about participating. While hosts and co-hosts can interact via audio/video and screen share, the audience consumes the content in real time and engages through interactive features like chat, polls and virtual gifting.

:::info

If you're already using VideoSDK for meetings, throughout this documentation you will learn how to extend its capabilities to support interactive live streaming.
Much of the core structure remains the same, but you'll discover how to adapt roles, scale the audience, and integrate interactive features to build engaging live stream experiences—all using the familiar tools and APIs you're used to.

:::

## Key Benefits:

- `Ultra-low latency`: Sub-second delivery for seamless interaction

- `Multiple host support`: Up to 100 simultaneous broadcasters

- `Scalable viewer capacity`: Handle up to 2,000 real-time audience members

- `Interactive tools`: Chat, polls, virtual gifts, hand raise, and more

- `Cross-platform compatibility`: Works across mobile, web, and desktop

<div style={{ textAlign: 'center' }}>
    <img
        src="https://cdn.videosdk.live/docs/images/android/ils/overview.png"
        alt="Waiting Screen"
         style={{height: '450px'}}
    />
</div>

### When to Use ILS?

Use Interactive Live Streaming when you need to:

- Run virtual events with multiple speakers
- Engage your audience actively during webinars
- Host fitness or coaching sessions with feedback
- Stream concerts, shows, or ceremonies with real-time reactions
- Organize town halls, investor calls, or product launches
- Facilitate audio rooms for casual or topic-based discussions
- Power social experiences like live meetups, talent shows, or community hangouts

:::info

If your requirement is strictly one-way broadcasting where interactivity is minimal and latency isn't critical (e.g., sports highlights, pre-recorded shows), http live streaming (HLS) may be more appropriate. To learn more about HLS, go through the [documentation](/android/guide/interactive-live-streaming/integrate-hls/overview).

:::


---

# Display Attendees Count - Android

In this guide, we will see how you can display the number of attendees in realtime.

:::note
Before going forward in this guide, do make sure all the attendees join the meeting with mode as `SIGNALLING_ONLY`
:::

- We will get the all the `participants` except local participant using `getParticipants()` method of the the `Meeting` class. With all the participants, we will filter out participants who have joined as a `SIGNALLING_ONLY` and then display that count.



**Kotlin:**

```js
private fun showViewerCount() {
var viewerCount = 1  // start with 1 to count local participant
val participants = meeting!!.participants
for (entry: Map.Entry<String, Participant> in participants.entries) {
    val participant = entry.value
    if (participant.mode == "SIGNALLING_ONLY") {
        viewerCount++
    }
}
this.viewerCount!!.text = viewerCount.toString()
}
```

---

**Java:**

```js
private void showViewerCount() {
int viewerCount = 1; // start with 1 to count local participant
Map<String, Participant> participants = meeting.getParticipants();
for (Map.Entry<String, Participant> entry : participants.entrySet()) {
    Participant participant = entry.getValue();
    if (participant.getMode().equals("SIGNALLING_ONLY")) {
        viewerCount++;
    }
}
this.viewerCount.setText(String.valueOf(viewerCount));
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [getparticipants()](/android/api/sdk-reference/meeting-class/properties#getparticipants)


---

# Invite Guest on Stage - Android

In this guide, we will see how you can request a viewer to join your livestream by using the `changeMode()`.




Let's first have a look at how we will be using the `PubSub` mechanism to acheive the requesting and switching of the participant's mode.

![invite-guest-pubsub](https://cdn.videosdk.live/website-resources/docs-resources/invite_guest_pubsub.png)

:::note
Before going forward in this guide, do make sure all the attendees join the meeting with mode as `SIGNALLING_ONLY` and the host joins with mode as `SEND_AND_RECV`
:::

### Step 1: Loading Viewer List

The host will see a list of participants who have joined as `SIGNALLING_ONLY` along with a button that, when selected, will invite that user to join the livestream.

Here we are using `RecyclerView` to display viewer list with button.

```xml title="layout_viewers_list_view.xml"
<?xml version="1.0" encoding="utf-8"?>


    <androidx.recyclerview.widget.RecyclerView
        android:id="@+id/rvViewersLinearView"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:paddingHorizontal="15sp" />

</LinearLayout>
```

```xml title="item_viewer_list_layout.xml"
<?xml version="1.0" encoding="utf-8"?>


    


</LinearLayout>
```

- Create a recycler view adapter named `ViewerListAdapter` which will show the viewer list. Create `PeerViewHolder` in the adapter which will extend `RecyclerView.ViewHolder`.



**Kotlin:**

```js
class ViewerListAdapter(items: ArrayList

</center>

### Step 2: Requesting a Viewer to Join Livestream

We have a Viewer list ready. Now, let us handle the click event for the `btnRequest`.

We will be using `CHANGE_MODE_ + participantId` as the topic for PubSub.

**Kotlin:**

```js
override fun onBindViewHolder(holder: ViewHolder, position: Int) {
  //...

  holder.btnRequest.setOnClickListener { v: View? ->
val pubSubPublishOptions = PubSubPublishOptions()
pubSubPublishOptions.isPersist = false
//highlight-start
meeting.pubSub.publish(
    "CHANGE_MODE_" + participant!!.id,
    participant.id,
    pubSubPublishOptions
)
//highlight-end
  }
}
```

---

**Java:**

```js
@Override
public void onBindViewHolder(@NonNull ViewHolder holder, int position) {
  //...

  holder.btnRequest.setOnClickListener(v -> {
PubSubPublishOptions pubSubPublishOptions = new PubSubPublishOptions();
pubSubPublishOptions.setPersist(false);
//highloght-next-line
meeting.pubSub.publish("CHANGE_MODE_"+ participant.getId(), participant.getId(), pubSubPublishOptions);
  });
}
```

### Step 3: Showing Viewer Request Dialog

After implementing the Host requesting viewer to join the livestream, let's display the viewer's request dialogue and switch the `SIGNALLING_ONLY` mode to `SEND_AND_RECV`.

**Kotlin:**

```js
meeting!!.addEventListener(object : MeetingEventListener() {
  override fun onMeetingJoined() {
val changeModeListener = object : PubSubMessageListener {
    override fun onMessageReceived(pubSubMessage: PubSubMessage) {
        if (pubSubMessage.message == meeting!!.localParticipant.id) {
          showRequestDialog(pubSubMessage.senderName)
      }
    }
    override fun onOldMessagesReceived(messages: List

</center>

### Step 4: Pin the participant

We need to pin the participant so that he/she can appears on the livestream. To achieve this, we will listen to the callback on the `onParticipantModeChanged` of `Meeting` class.

**Kotlin:**

```js
class ParticipantListAdapter(
items: ArrayList

</div>

<br/>

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Meeting](/android/api/sdk-reference/meeting-class/introduction)
- [pubSub](/android/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub)
- [onParticipantModeChanged()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onparticipantmodechanged)


---

# Manage On-Screen Participants - Android

It is important that only the necessary person are present on the screen when livestream is on. To handle this, we will be using the `pin` and `unpin` methods of the `Participant` class.

:::note
To ensure only the hosts/speakers are shown in the grid, you should use the `SPOTLIGHT` layout and `pin` as the priority when starting the interactive livestream.
:::

Let us first explore two methods that we will be using to manage on-screen participants.

### `pin()`

With these method you can pin any participant's Camera, Screen Share or both. This can be useful to identify the participants based on which you can perform rendering participant grid.

### `unpin()`

With these methods you can unpin any participant's Camera, Screen Share or both. This can be useful to reset pin state of the participant.




### Managing On-Screen Participants

1. If you want to pin all the hosts/speakers automatically, you can do it by listenting to the `onMeetingJoined` callback and `onParticipantModeChanged`, where you can `pin` and `unpin` based on the mode.



**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onMeetingJoined() {
    //highlight-start
    val localParticipant = meeting!!.localParticipant
    //We will pin the participant if mode is SEND_AND_RECV
    if (localParticipant.mode == "SEND_AND_RECV") {
        localParticipant.pin()
    } else {
        localParticipant.unpin()
    }
    //highlight-end
   }

  override fun onParticipantModeChanged(data: JSONObject) {
//highlight-start
val localParticipant = meeting!!.localParticipant
//We will pin the participant if mode is SEND_AND_RECV else unpin him
if(localParticipant.id.equals(data.getString("peerId"))
{
    if(localParticipant.mode == "SEND_AND_RECV")
    {
        localParticipant.pin()
    }else{
        localParticipant.unpin()
    }
}
//highlight-end
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onMeetingJoined() {
//highlight-start
Participant localParticipant = meeting.getLocalParticipant();
//We will pin the participant if mode is SEND_AND_RECV
if (localParticipant.getMode() == "SEND_AND_RECV") {
    localParticipant.pin();
} else {
    localParticipant.unpin();
}
//highlight-end
  }

  @Override
  public void onParticipantModeChanged(JSONObject data) {
//highlight-start
Participant localParticipant = meeting.getLocalParticipant();
//We will pin the participant if mode is SEND_AND_RECV else unpin him
if(localParticipant.getId().equals(data.getString("peerId"))
{
    if(localParticipant.getMode() == "SEND_AND_RECV")
    {
        localParticipant.pin();
    }else{
        localParticipant.unpin();
    }
}
//highlight-end
  }
};

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting.addEventListener(meetingEventListener);
}
```

2. When rendering the participant grid on the Speaker side, make sure to show only the participants who are in `SEND_AND_RECV` mode. You can filter the participants as shown in below example.

**Kotlin:**

```js
 private fun getSpeakerList(): List<Participant?>? {
val speakerList: MutableList<Participant?> = ArrayList()
val participants = meeting!!.participants
for (entry: Map.Entry<String, Participant> in participants.entries) {
    val participant = entry.value
    if (participant.mode == "SEND_AND_RECV") {
        speakerList.add(participant)
    }
}
return speakerList
}
```

---

**Java:**

```js
private List<Participant> getSpeakerList() {
List<Participant> speakerList = new ArrayList();
Map<String, Participant> participants = meeting.getParticipants();
for (Map.Entry<String, Participant> entry : participants.entrySet()) {
    Participant participant = entry.getValue();
    if (participant.getMode().equals("SEND_AND_RECV")) {
        speakerList.add(participant);
    }
}
return speakerList;
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [pin](/android/api/sdk-reference/participant-class/methods#pin)
- [unpin](/android/api/sdk-reference/participant-class/methods#unpin)


---

# Manage Roles - Android

## Roles with VideoSDK

When doing interactive live streaming maintaining the role of users is quite important. To help manage these roles better, VideoSDK allows a participant with two types of modes:

**`1. SEND_AND_RECV`** When a participant is joining with mode set to `SEND_AND_RECV`, we will be able to **publish and consume the media** of other participants and also interact with them using the features like chat, poll etc.

**`2. SIGNALLING_ONLY`** When a participant is joining with mode set to `SIGNALLING_ONLY`, that participant is **not allowed to publish or consume any media** from other participants. Although they can interact with other participants using chat, polls etc.




**_This image is for education purpose_**

![manage-roles](https://cdn.videosdk.live/website-resources/docs-resources/meeting_modes.jpg)

## When to use the Roles?

##### 1. Simple Adaptive Streaming

- Simple Adaptive Streaming (SAS) is a type of livestreaming that requires minimal interaction between the host and viewers.

- It is particularly useful for events with a large number of viewers who prefer not to engage with the host.

- In SAS, each speaker attends a VideoSDK meeting in `SEND_AND_RECV` mode, while viewers can simply watch the livestream using the `playbackHlsUrl` or `livestreamUrl`. Unlike the speakers, viewers do not need to join the meeting in `SEND_AND_RECV` or `SIGNALLING_ONLY` mode. This allows for a seamless streaming experience without any unnecessary interruptions or distractions.
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

**_This video is for education purpose_**


<div style={{textAlign: 'center'}}>



</div>

##### 2. Adaptive Streaming with increased engagement

- If you're looking to increase engagement with your audience during a live streaming event, consider using Adaptive Streaming technology. With this approach, you can incorporate interactive features such as polls and conversations, and give viewers the ability to join and leave the livestream as the host decides.

- To set this up, have all speakers join as `SEND_AND_RECV` mode participants, while the audience joins as `SIGNALLING_ONLY` mode participants. This way, everyone can participate in the interactive elements of the live stream and create a more dynamic and engaging experience for all.

**_This video is for education purpose_**

<div style={{textAlign: 'center'}}>



</div>

## Using roles

When you initialize the meeting, you can set the mode of Participant.



**Kotlin:**

```js
class MainActivity : AppCompatActivity() {

  fun getToken(): String? {
//highlight-next-line
...
  }

  fun getMeetingId(token: String?): String? {
//highlight-next-line
...
  }

 override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)

//We will fetch token and meetingId and store it in local variables
val token: String = getToken()
val meetingId = getMeetingId(token)

// initialize the VideoSDK
VideoSDK.initialize(this@MainActivity)

// set token property of VideoSDK
VideoSDK.config(token)

// highlight-start
// create a new meeting instance
val meeting: Meeting = VideoSDK.initMeeting(
    this@MainActivity, meetingId, "NAME HERE",
    true, true, null,
    //highlight-next-line
    "SEND_AND_RECV", // allowed: SEND_AND_RECV | SIGNALLING_ONLY | RECV_ONLY
    false,
    null,
    null
)
// highlight-end

Log.d("VideoSDK", "onCreate: $meetingId")
  }
}
```

---

**Java:**

```java
public class MainActivity extends AppCompatActivity {

  public String getToken()
  {
//highlight-next-line
...
  }

  public String getMeetingId(String token) {
//highlight-next-line
...
  }

  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

//We will fetch token and meetingId and store it in local variables
String token = getToken();
String meetingId = getMeetingId(token);

// initialize the VideoSDK
VideoSDK.initialize(MainActivity.this);

// set token property of VideoSDK
VideoSDK.config(token);

// highlight-start
// create a new meeting instance
Meeting meeting = VideoSDK.initMeeting(
        MainActivity.this, meetingId, "NAME HERE",
        true, true, null,
        //highlight-next-line
        "SEND_AND_RECV", // allowed: SEND_AND_RECV | SIGNALLING_ONLY | RECV_ONLY
        false,
        null,
        null,
);
// highlight-end

Log.d("VideoSDK", "onCreate: " + meetingId);
  }
}
```

## Getting Participant Mode

You can identify the participants role by using `mode` property from `Participant` class.

**Kotlin:**

```js
override fun onCreate(savedInstanceState: Bundle?) {
  //...

  val localParticipant = meeting!!.localParticipant
  //highlight-next-line
  Log.d("VideoSDK", "Participant mode : " + localParticipant.mode)
}
```

---

**Java:**

```js
@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  Participant localParticipant = meeting.getLocalParticipant();
  //highlight-next-line
  Log.d("VideoSDK", "Participant mode : " + participant.getMode());
}
```

## Changing Participant's Mode

Let's say you are hosting a livestream and you want one of your viewer to join the livestream with you. In this case you can change the mode of the participant using the `changeMode()` of the `Meeting` class.

**Kotlin:**

```js
findViewById<View>(R.id.btnConferenceMode).setOnClickListener { view: View? ->
// change mode to SEND_AND_RECV
//highlight-next-line
meeting!!.changeMode("SEND_AND_RECV")
}

findViewById<View>(R.id.btnViewerMode).setOnClickListener { view: View? ->
// change mode to SIGNALLING_ONLY
//highlight-next-line
meeting!!.changeMode("SIGNALLING_ONLY")
}
```

---

**Java:**

```js
findViewById(R.id.btnConferenceMode).setOnClickListener(view -> {
// change mode to SEND_AND_RECV
//highlight-next-line
meeting.changeMode("SEND_AND_RECV");
});

findViewById(R.id.btnViewerMode).setOnClickListener(view -> {
// change mode to SIGNALLING_ONLY
//highlight-next-line
   meeting.changeMode("SIGNALLING_ONLY");
});
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Meeting](/android/api/sdk-reference/meeting-class/introduction)
- [Participant](/android/api/sdk-reference/participant-class/introduction)
- [changeMode()](/android/api/sdk-reference/meeting-class/methods#changemode)


---

# Interactive Livestream (HLS) - Android

### What is Interactive Livestream (HLS)?

Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

In an interactive live stream (HLS), viewers can take part in a variety of activities like live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

### What is Adaptive Live Streaming?

Livestream experience is important while undertaking interactive live streaming in order to increase audience. To do this, the livestream should be able to respond to the viewer's network bandwidth, and change the stream's resolution as necessary. Therefore, adaptive live streaming refers to a feed that automatically adjusts to a lower or higher resolution dependent on the user's preferences.

### What is Latency?

Latency is the delay between capturing video content and its playback. Key factors that affecting latency :

- **Buffering**: Balance buffer size for smoother playback against latency.
- **Network Conditions**: Efficient servers and network health contribute to lower latency.

Standard HLS has a latency around 5-6 seconds.

### HLS Architecture of VideoSDK

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/mobile_hls.png' />

</center>

When a host starts the interactive live stream, VideoSDK will use a default theme or user specified template to compose and encode a live stream which will be delivered to the viewers through a `M3U8` video file which can be played directly on the viewer end which will adapt to the viewer's network bandwidth.

When using VideoSDK for interactive live stream, you get multiple types of URLs which you can use based on your requirements.

**`1. Standard Streaming:`** This type of streaming is where the user is not allowed to go back in the live and can just stream it.

**`2. Rolling Playback:`** This type of streaming is where the user is allowed to do rewind and do a playback of the complete stream.

**`3. VoD Playback`** With this, users can playback the complete live stream on demand whenever needed.

## Using HLS with VideoSDK

You can use HLS with VideoSDK in two different ways.

#### 1. Simple Adaptive Streaming

When we talk about simple adaptive streaming, we imply that there is hardly any interaction between the hosts and the viewers.

These livestreams are helpful when there are a lot of viewers, and they don't want to engage with the host. In this scenario, every presenter attends a VideoSDK meeting, while every viewer only watches the livestream.

**_This video is for education purpose_**


<div style={{textAlign: 'center'}}>



</div>

#### 2. Adaptive Streaming with increased engagement

When you want to communicate with your audience by enabling polls, conversations, and the ability for viewers to join and leave the livestream based on the host's decision, adaptive streaming with enhanced engagement will be the best fit for you.

In this scenario, both the host and the viewer will have to join a VideoSDK meeting with different roles. To learn more about the roles [follow these guide.](../handling-participants/manage-roles)

**_This video is for education purpose_**

<div style={{textAlign: 'center'}}>



</div>


---

# Setup HLS Player - Android

In this guide, we will add player which will be responsible for playing the HLS stream.
Before starting this guide, make sure you have a VideoSDK meetings setup allowing you to join the room. To learn more about setting up a VideoSDK meeting, follow this [quick start guide](/android/guide/video-and-audio-calling-api-sdk/quick-start).

To play the HLS stream we will be using the [Exoplayer](https://github.com/google/ExoPlayer) library.

### `1. Setup player into your project`

**`Step 1:`** Let's first add ExoPlayer module dependency into the project.

```js title="app/build.gradle"
dependencies {
  implementation 'com.google.android.exoplayer:exoplayer:2.18.5'
  // other app dependencies
  }
```

**`Step 2:`** Now let's add the `StyledPlayerView` which will display livestreaming. And also add the `TextView` which will be shown when there is no active HLS. For these, we will use the `onHlsStateChanged` event from the `MeetingEventListener` abstract class to identify if there is an active HLS.

```xml title="activity_viewer.xml"
<?xml version="1.0" encoding="utf-8"?>


    <com.google.android.exoplayer2.ui.StyledPlayerView
        android:id="@+id/player_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:visibility="gone"
        app:resize_mode="fixed_width"
        app:show_buffering="when_playing"
        app:show_subtitle_button="false"
        app:use_artwork="false"
        app:show_next_button="false"
        app:show_previous_button="false"
        app:use_controller="true"/>

</LinearLayout>
```

### `2. Initialize player and Playing HLS stream`

**`Step 1:`** Now that player is setup, let's initialize player and play the HLS once it becomes playable. For these, we will get the `playbackHlsUrl` and `livestreamUrl` when the `onHlsStateChanged` event of `MeetingEventListener` state changes to `HLS_PLAYABLE`.

- when you receive `HLS_PLAYABLE` status you will receive 2 urls
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

**`Step 2:`** We also need to release player and show `TextView` which shows there is no active HLS. We will release player when the `onHlsStateChanged` event of `MeetingEventListener` state changes to `HLS_STOPPED`.



**Kotlin:**

```js title="ViewerActivity.kt"
class ViewerActivity : AppCompatActivity() {
private val meeting: Meeting? = null
private var playerView: StyledPlayerView? = null
private var waitingLayout: TextView? = null
private var player: ExoPlayer? = null
private var dataSourceFactory: DefaultHttpDataSource.Factory? = null
private val startAutoPlay = true
private var playbackHlsUrl: String? = ""


override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_meeting)
    playerView = findViewById(R.id.player_view)
    waitingLayout = findViewById(R.id.waitingLayout)

    // setup meeting
    //...

    //highlight-next-line
    // add listener to the meeting
    meeting!!.addEventListener(meetingEventListener)
}

private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
    override fun onMeetingJoined() {
        Log.d("VideoSDK", "onMeetingJoined: ")
    }

    override fun onMeetingLeft() {
        Log.d("VideoSDK", "onMeetingLeft: ")
    }

    //highlight-start
    @RequiresApi(api = Build.VERSION_CODES.P)
    override fun onHlsStateChanged(HlsState: JSONObject) {
        if (HlsState.has("status")) {
            try {
                if (HlsState.getString("status") == "HLS_PLAYABLE" && HlsState.has("playbackHlsUrl")) {
                    playbackHlsUrl = HlsState.getString("playbackHlsUrl")
                    waitingLayout!!.visibility = View.GONE
                    playerView!!.visibility = View.VISIBLE
                    // initialize player
                    initializePlayer()
                }
                if (HlsState.getString("status") == "HLS_STOPPED") {
                    // release the player
                    releasePlayer()
                    playbackHlsUrl = null
                    waitingLayout!!.text = "Host has stopped \n the live streaming"
                    waitingLayout!!.visibility = View.VISIBLE
                    playerView!!.visibility = View.GONE
                }
            } catch (e: JSONException) {
                e.printStackTrace()
            }
        }
        //highlight-end
    }
}

private fun initializePlayer() {
    if (player == null) {
        dataSourceFactory = DefaultHttpDataSource.Factory()
        val mediaSource = HlsMediaSource.Factory(dataSourceFactory!!).createMediaSource(
            MediaItem.fromUri(Uri.parse(playbackHlsUrl))
        )
        val playerBuilder = ExoPlayer.Builder( /* context= */this@ViewerActivity)
        player = playerBuilder.build()
        // auto play when player is ready
        player!!.playWhenReady = startAutoPlay
        player!!.setMediaSource(mediaSource)
        // if you want display setting for player then remove this line
        playerView!!.findViewById

<img style={{height: '450px'}} src="https://cdn.videosdk.live/website-resources/docs-resources/android_ils_quickstart_viewer_screen.jpg" />

</center>

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [onHlsStateChanged](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onhlsstatechanged)


---

# Start HLS - Android

Before starting the HLS, the prequisite steps require you to have a VideoSDK Meeting running which you want to use for interactive livestream. To learn more about setting up a interactive live streaming, you can follow the steps [here in the quick start guide.](/android/guide/video-and-audio-calling-api-sdk/quick-start-ILS)

## Starting HLS

Once the user has joined the meeting, `startHls()` can be used to start a interactive livestream of the meeting which can be accessed from the `Meeting` class. This method accepts one parameter:

- `config`: This parameter will define how the interactive livestream layout should look like.



**Kotlin:**

```js
val config = JSONObject()

//highlight-next-line
// Layout Configuration
val layout = JSONObject()
JsonUtils.jsonPut(layout, "type", "GRID") // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
JsonUtils.jsonPut(layout, "priority", "SPEAKER") // "PIN", Default : "SPEAKER"
JsonUtils.jsonPut(layout, "gridSize", 4) // MAX : 25
JsonUtils.jsonPut(config, "layout", layout)

//highlight-next-line
// Theme of interactive livestream layout
JsonUtils.jsonPut(config, "theme", "DARK") //  "LIGHT" | "DEFAULT"

//highlight-next-line
// `mode` is used to either interactive livestream video & audio both or only audio.
JsonUtils.jsonPut(config, "mode", "video-and-audio") // "audio", Default : "video-and-audio"

//highlight-next-line
// Quality of interactive livestream and is only applicable to `video-and-audio` type mode.
JsonUtils.jsonPut(config, "quality", "high") /* Default : "med"
   "low" (SD HLS) | "med" (HD HLS) | "high" (FHD HLS) */

//highlight-start
// This mode refers to orientation of interactive livestream.
// landscape : Start interactive livestream of the meeting in horizontally
// portrait : Start interactive livestream of the meeting in vertically (Best for mobile view)
//highlight-end
JsonUtils.jsonPut(config, "orientation", "portrait") // "landscape",  Default : "landscape"

meeting!!.startHls(config)
```

---

**Java:**

```js
JSONObject config = new JSONObject();

//highlight-next-line
// Layout Configuration
JSONObject layout = new JSONObject();
JsonUtils.jsonPut(layout, "type", "GRID"); // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
JsonUtils.jsonPut(layout, "priority", "SPEAKER");  // "PIN", Default : "SPEAKER"
JsonUtils.jsonPut(layout, "gridSize", 4); // MAX : 25
JsonUtils.jsonPut(config, "layout", layout);

//highlight-next-line
// Theme of interactive livestream layout
JsonUtils.jsonPut(config, "theme", "DARK"); //  "LIGHT" | "DEFAULT"

//highlight-next-line
// `mode` is used to either interactive livestream video & audio both or only audio.
JsonUtils.jsonPut(config, "mode", "video-and-audio"); // "audio", Default : "video-and-audio"

//highlight-next-line
// Quality of interactive livestream and is only applicable to `video-and-audio` type mode.
JsonUtils.jsonPut(config, "quality", "high"); /* Default : "med"
   "low" (SD HLS) | "med" (HD HLS) | "high" (FHD HLS) */

//highlight-start
// This mode refers to orientation of interactive livestream.
// landscape : Start interactive livestream of the meeting in horizontally
// portrait : Start interactive livestream of the meeting in vertically (Best for mobile view)
//highlight-end
JsonUtils.jsonPut(config, "orientation", "portrait"); // "landscape",  Default : "landscape"

meeting.startHls(config);
```

:::note
If you want only the SEND_AND_RECV participants to be seen in the livestream, you can `pin` all the participants in the SEND_AND_RECV mode and start the livestream with the `SPOTLIGHT` layout and `pin` as the `PRIORITY`.

Deprecated: Use SEND_AND_RECV instead of CONFERENCE
:::

### Example

**Kotlin:**

```js
// keep track of hls
findViewById<View>(R.id.btnStartHls).setOnClickListener { view: View? ->
//highlight-start
val config = JSONObject()
val layout = JSONObject()
JsonUtils.jsonPut(layout, "type", "SPOTLIGHT")
JsonUtils.jsonPut(layout, "priority", "PRIORITY")
JsonUtils.jsonPut(layout, "gridSize", 4)
JsonUtils.jsonPut(config, "layout", layout)
JsonUtils.jsonPut(config, "theme", "DARK")
JsonUtils.jsonPut(config, "mode", "video-and-audio")
JsonUtils.jsonPut(config, "quality", "high")
JsonUtils.jsonPut(config, "orientation", "portrait")
//highlight-end

// Start Hls
//highlight-next-line
meeting!!.startHls(config)
}
```

---

**Java:**

```js
findViewById(R.id.btnStartHls).setOnClickListener(view -> {
//highlight-start
JSONObject config = new JSONObject();
JSONObject layout = new JSONObject();
JsonUtils.jsonPut(layout, "type", "SPOTLIGHT");
JsonUtils.jsonPut(layout, "priority", "PRIORITY");
JsonUtils.jsonPut(layout, "gridSize", 4);
JsonUtils.jsonPut(config, "layout", layout);
JsonUtils.jsonPut(config, "theme", "DARK");
JsonUtils.jsonPut(config, "mode", "video-and-audio");
JsonUtils.jsonPut(config, "quality", "high");
JsonUtils.jsonPut(config, "orientation", "portrait");
//highlight-end

// Start Hls
//highlight-next-line
meeting.startHls(config);
});
```

## Understanding Layouts

##### 1. GRID Layout

This layout is default layout if no participants are pinned, it will look same as a normal meeting grid layout, when any participant is pinned that participant will be moved on top of the main screen grid above all non pinned participants

While screenshare as well the main view will contain only screenshare media but the side panel view of participant grid will maintain same order of pinned and unpinned participants.

|                       Grid                        |                     Grid with Screenshare                     |
| :-----------------------------------------------: | :-----------------------------------------------------------: |
| ![prebuilt-grid](/img/prebuilt/prebuilt-grid.png) | ![prebuilt-grid-share](/img/prebuilt/prebuilt-grid-share.png) |

##### 2. SIDEBAR Layout

This layout will have one main screen view and other sidebar grid layout. Only pinned participant will be visible in this layout, all unpinned participants will not be visible in this layout. If more than one participant is pinned then the first participant who was pinned will appear in main screen layout and all other remaining pinned particiapants will be visible in sidebar.

If any pinned participant started screenshare then the screenshare media will be visible in main screen layout and all other pinned participants webcam view will be visible in sidebar

|                         Sidebar                         |                      Sidebar with Screenshare                       |
| :-----------------------------------------------------: | :-----------------------------------------------------------------: |
| ![prebuilt-sidebar](/img/prebuilt/prebuilt-sidebar.png) | ![prebuilt-sidebar-share](/img/prebuilt/prebuilt-sidebar-share.png) |

##### 3. SPOTLIGHT Layout

This layout will only contain main screen layout, multiple pinned participants will be visible in main screen view. Same as `SIDEBAR` layout only pinned participants will be visible in main screen.

If any pinned participant started screenshare then only screenshare view will be visible in main screen, no webcam view will be visible when any pinned participant started screenshare.

|                          Spotlight                          |                       Spotlight with Screenshare                        |
| :---------------------------------------------------------: | :---------------------------------------------------------------------: |
| ![prebuilt-spotlight](/img/prebuilt/prebuilt-spotlight.png) | ![prebuilt-spotlight-share](/img/prebuilt/prebuilt-spotlight-share.png) |

## Event associated with HLS

- **onHlsStateChanged** - Whenever meeting HLS state changes, then `onHlsStateChanged` event will trigger.

- You can get the `livestreamUrl` and `playbackHlsUrl` of the HLS to play it on the Viewer side when the state changes to `HLS_PLAYABLE`.
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onHlsStateChanged(HlsState: JSONObject) {
when (HlsState.getString("status")) {
    "HLS_STARTING" -> Log.d("onHlsStateChanged", "Meeting hls is starting")
    "HLS_STARTED" -> Log.d("onHlsStateChanged", "Meeting hls is started")
    "HLS_PLAYABLE" -> {
        Log.d("onHlsStateChanged", "Meeting hls is playable now")
        //highlight-start
        // on hls playable you will receive playbackHlsUrl and livestreamUrl
        val playbackHlsUrl = HlsState.getString("playbackHlsUrl")
        val livestreamUrl = HlsState.getString("livestreamUrl")
        //highlight-end
    }
    "HLS_STOPPING" -> Log.d("onHlsStateChanged", "Meeting hls is stopping")
    "HLS_STOPPED" -> Log.d("onHlsStateChanged", "Meeting hls is stopped")
}
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onHlsStateChanged(JSONObject HlsState) {
  switch (HlsState.getString("status")) {
      case "HLS_STARTING":
          Log.d("onHlsStateChanged", "Meeting hls is starting");
          break;
      case "HLS_STARTED":
          Log.d("onHlsStateChanged", "Meeting hls is started");
          break;
      case "HLS_PLAYABLE":
          Log.d("onHlsStateChanged", "Meeting hls is playable now");
          //highlight-start
          // on hls started you will receive playbackHlsUrl and livestreamUrl
          String playbackHlsUrl = HlsState.getString("playbackHlsUrl");
          String livestreamUrl = HlsState.getString("livestreamUrl");
          //highlight-end
          break;
      case "HLS_STOPPING":
          Log.d("onHlsStateChanged", "Meeting hls is stopping");
          break;
      case "HLS_STOPPED":
          Log.d("onHlsStateChanged", "Meeting hls is stopped");
          break;
  }
  }
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting.addEventListener(meetingEventListener);
}
```

## Custom Template

With VideoSDK, you can also use your own custom designed layout template to livestream the meetings. In order to use the custom template, you need to create a template for which you can [follow this guide](/react/guide/interactive-live-streaming/custom-template). Once you have setup the template, you can use the [REST API to start](/api-reference/realtime-communication/start-livestream) the livestream with the `templateURL` parameter.

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startHls()](/android/api/sdk-reference/meeting-class/methods#starthls)
- [stopHls()](/android/api/sdk-reference/meeting-class/methods#stophls)
- [onHlsStateChanged](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onhlsstatechanged)


---

# Stop HLS - Android

This could refer to stopping the transmission of an ongoing HLS stream, which would mean the stream is no longer available to viewers.

## Stopping HLS

- `stopHls()` is used to stop interactive livestream of the meeting which can be accessed from the `Meeting` class.



#### Example

**Kotlin:**

```js
findViewById<View>(R.id.btnStopHls).setOnClickListener { view: View? ->
// Stop Hls
//highlight-next-line
meeting!!.stopHls()
}
```

---

**Java:**

```js
findViewById(R.id.btnStopHls).setOnClickListener(view -> {
// Stop Hls
//highlight-next-line
meeting.stopHls();
});
```

## Event associated with HLS

- **onHlsStateChanged** - Whenever meeting HLS state changes, then `onHlsStateChanged` event will trigger.

- You will get `HLS_STOPPING` and `HLS_STOPPED` status on calling `stopHls()`.

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onHlsStateChanged(HlsState: JSONObject) {
when (HlsState.getString("status")) {
    "HLS_STARTING" -> Log.d("onHlsStateChanged", "Meeting hls is starting")
    "HLS_STARTED" -> Log.d("onHlsStateChanged", "Meeting hls is started")
    "HLS_PLAYABLE" -> {
        Log.d("onHlsStateChanged", "Meeting hls is playable now")
         // on hls playable you will receive playbackHlsUrl and livestreamUrl
        val playbackHlsUrl = HlsState.getString("playbackHlsUrl")
        val livestreamUrl = HlsState.getString("livestreamUrl")
    }
        //highlight-start
    "HLS_STOPPING" -> Log.d("onHlsStateChanged", "Meeting hls is stopping")
    "HLS_STOPPED" -> Log.d("onHlsStateChanged", "Meeting hls is stopped")
        //highlight-end

}
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onHlsStateChanged(JSONObject HlsState) {
  switch (HlsState.getString("status")) {
      case "HLS_STARTING":
          Log.d("onHlsStateChanged", "Meeting hls is starting");
          break;
      case "HLS_STARTED":
          Log.d("onHlsStateChanged", "Meeting hls is started");
          break;
      case "HLS_PLAYABLE":
          Log.d("onHlsStateChanged", "Meeting hls is playable now");
          // on hls started you will receive playbackHlsUrl and livestreamUrl
          String playbackHlsUrl = HlsState.getString("playbackHlsUrl");
          String livestreamUrl = HlsState.getString("livestreamUrl");
          break;
          //highlight-start
      case "HLS_STOPPING":
          Log.d("onHlsStateChanged", "Meeting hls is stopping");
          break;
      case "HLS_STOPPED":
          Log.d("onHlsStateChanged", "Meeting hls is stopped");
          break;
          //highlight-end

  }
  }
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting.addEventListener(meetingEventListener);
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startHls()](/android/api/sdk-reference/meeting-class/methods#starthls)
- [stopHls()](/android/api/sdk-reference/meeting-class/methods#stophls)
- [onHlsStateChanged](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onhlsstatechanged)


---

# Integrate Android SDK




---

# Chat using PubSub - Android

For the communication or any kind of messaging in between the participants, VideoSDK provides `pubSub` class which use Publish-Subscribe mechanism and can be used to develope wide varitey of functionalities. For example, participants could use it to send chat messages to each other, share files or other media, or even trigger actions like muting or unmuting audio or video.

Now we will see, how we can use PubSub to implement Chat functionality. If you are not familiar with the PubSub mechanism and `pubSub` class, you can [follow this guide](/android/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

## Implementing Chat

### `Group Chat`

1. First step in creating a group chat is choosing the topic which all the participants will publish and subscribe to send and receive the messages. We will be using `CHAT` as the topic for this one.
2. On the send button, publish the message that the sender typed in the `EditText` field.



**Kotlin:**

```js
import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.view.View
import android.widget.EditText
import android.widget.Toast
import androidx.appcompat.widget.Toolbar
import live.videosdk.rtc.android.Meeting
import live.videosdk.rtc.android.listeners.PubSubMessageListener
import live.videosdk.rtc.android.model.PubSubPublishOptions

class ChatActivity : AppCompatActivity() {
  // Meeting
  var meeting: Meeting? = null

  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_chat)

/**
 * Here, we have created 'MainApplication' class, which extends android.app.Application class.
 * It has Meeting property and getter and setter methods of Meeting property.
 * In your android manifest, you must declare the class implementing android.app.Application
 * (add the android:name=".MainApplication" attribute to the existing application tag):
 * In MainActivity.kt, we have set Meeting property.
 *
 * For Example: (MainActivity.kt)
 * var meeting = VideoSDK.initMeeting(context, meetingId, ParticipantName, micEnabled, webcamEnabled, paricipantId, mode, multiStream, customTrack, metaData, signalingBaseUrl)
 * (this.application as MainApplication).meeting = meeting
*/

// Get Meeting
meeting = (this.application as MainApplication).meeting

findViewById(R.id.btnSend).setOnClickListener(view -> sendMessage());
  }

  private fun sendMessage() {
// get message from EditText
val message: String = etmessage.getText().toString()
if (!TextUtils.isEmpty(message)) {
    val publishOptions = PubSubPublishOptions()
    publishOptions.setPersist(true)

    // Sending the Message using the publish method
    //highlight-next-line
    meeting!!.pubSub.publish("CHAT", message, publishOptions)

    // Clearing the message input
    etmessage.setText("")
} else {
    Toast.makeText(
        this@ChatActivity, "Please Enter Message",
        Toast.LENGTH_SHORT
    ).show()
}
  }
}
```

---

**Java:**

```js
import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import java.util.List;
import live.videosdk.rtc.android.Meeting;
import live.videosdk.rtc.android.lib.PubSubMessage;
import live.videosdk.rtc.android.listeners.PubSubMessageListener;
import live.videosdk.rtc.android.model.PubSubPublishOptions;

public class ChatActivity extends AppCompatActivity {
  // Meeting
  Meeting meeting;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_chat);

/**
 * Here, we have created 'MainApplication' class, which extends android.app.Application class.
 * It has Meeting property and getter and setter methods of Meeting property.
 * In your android manifest, you must declare the class implementing android.app.Application
 * (add the android:name=".MainApplication" attribute to the existing application tag):
 * In MainActivity.java, we have set Meeting property.
 *
 * For Example: (MainActivity.java)
 * Meeting meeting = VideoSDK.initMeeting(context, meetingId, ParticipantName, micEnabled, webcamEnabled, participantId, mode, mutliStream, customTrack,metaData, signalingBaseUrl, preferredProtocol);
 * ((MainApplication) this.getApplication()).setMeeting(meeting);
*/

// Get Meeting
meeting = ((MainApplication) this.getApplication()).getMeeting();

findViewById(R.id.btnSend).setOnClickListener(view -> sendMessage());
  }

  private void sendMessage()
  {
// get message from EditText
String message = etmessage.getText().toString();
if (!message.equals("")) {
    PubSubPublishOptions publishOptions = new PubSubPublishOptions();
    publishOptions.setPersist(true);

    // Sending the Message using the publish method
    //highlight-next-line
    meeting.pubSub.publish("CHAT", message, publishOptions);

    // Clearing the message input
    etmessage.setText("");
} else {
    Toast.makeText(ChatActivity.this, "Please Enter Message",
            Toast.LENGTH_SHORT).show();
}
  }
}
```

3. Next step would be to display the messages others send. For this we have to `subscribe` to that topic i.e `CHAT` and display all the messages.

**Kotlin:**

```js
class ChatActivity : AppCompatActivity() {

  // PubSubMessageListener
  //highlight-start
val pubSubMessageListener = object : PubSubMessageListener {
    override fun onMessageReceived(message: PubSubMessage) {
        Log.d("VideoSDK", "onMessageReceived: ${message.message}")
    }
    override fun onOldMessagesReceived(messages: List<PubSubMessage>) {
        // Persisted message list
        Log.d("VideoSDK", "onOldMessagesReceived: $messages")
    }
}
  //highlight-end

  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_chat)

//...

// Subscribe for 'CHAT' topic
//highlight-next-line
meeting!!.pubSub.subscribe("CHAT", pubSubMessageListener)

  }
}
```

---

**Java:**

```js
public class ChatActivity extends AppCompatActivity {

  // PubSubMessageListener
  //highlight-start
PubSubMessageListener pubSubMessageListener = new PubSubMessageListener() {
    @Override
    public void onMessageReceived(PubSubMessage message) {
        Log.d("VideoSDK", "onMessageReceived: " + message.getMessage());
    }
    
    @Override
      public void onOldMessagesReceived(List<PubSubMessage> messages) {
      // Persisted message list
      Log.d("VideoSDK", "onOldMessagesReceived: " + messages);
    }
};
  //highlight-end

  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_chat);

//..

// Subscribe for 'CHAT' topic
//highlight-next-line
meeting.pubSub.subscribe("CHAT", pubSubMessageListener);

  }
}
```

4. Final step in the group chat would be `unsubscribe` to that topic, which you had previously subscribed but no longer needed. Here we are `unsubscribe` to `CHAT` topic on activity destroy.

**Kotlin:**

```js
class ChatActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_chat)

//...
  }

  override fun onDestroy() {
// Unsubscribe for 'CHAT' topic
//highlight-next-line
meeting!!.pubSub.unsubscribe("CHAT", pubSubMessageListener)
super.onDestroy()
  }
}
```

---

**Java:**

```js
public class ChatActivity extends AppCompatActivity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_chat);

//..
  }

  @Override
  protected void onDestroy() {
// Unsubscribe for 'CHAT' topic
//highlight-next-line
meeting.pubSub.unsubscribe("CHAT", pubSubMessageListener);
super.onDestroy();
  }
}
```

### `Private Chat`

In the above example, if you want to convert into the private chat between two participants, then all you have to do is pass `sendOnly` parameter in `PubSubPublishOptions`.

**Kotlin:**

```js
class ChatActivity : AppCompatActivity() {

  //..
  
  private fun sendMessage() {
// get message from EditText
val message: String = etmessage.getText().toString()
if (!TextUtils.isEmpty(message)) {
    val publishOptions = PubSubPublishOptions()
    publishOptions.setPersist(true)
    //highlight-start
    // Pass the participantId of the participant to whom you want to send the message.
    var sendOnly: Array<String> = arrayOf("xyz")
    publishOptions.setSendOnly(sendOnly);
    //highlight-end

    // Sending the Message using the publish method
    //highlight-next-line
    meeting!!.pubSub.publish("CHAT", message, publishOptions)

    // Clearing the message input
    etmessage.setText("")
} else {
    Toast.makeText(
        this@ChatActivity, "Please Enter Message",
        Toast.LENGTH_SHORT
    ).show()
}
  }
}
```

---

**Java:**

```js
public class ChatActivity extends AppCompatActivity {
 
  //...

  private void sendMessage()
  {
// get message from EditText
String message = etmessage.getText().toString();
if (!message.equals("")) {
    PubSubPublishOptions publishOptions = new PubSubPublishOptions();
    publishOptions.setPersist(true);
    //highlight-start
    // Pass the participantId of the participant to whom you want to send the message.
    String[] sendOnly = {
      "xyz" 
    };
    publishOptions.setSendOnly(sendOnly);
    //highlight-end

    // Sending the Message using the publish method
    //highlight-next-line
    meeting.pubSub.publish("CHAT", message, publishOptions);

    // Clearing the message input
    etmessage.setText("");
} else {
    Toast.makeText(ChatActivity.this, "Please Enter Message",
            Toast.LENGTH_SHORT).show();
}
  }
}
```

### Downloading Chat Messages

All the messages from the PubSub which where published with `persist : true` and can be downloaded as an `.csv` file. This file will be available in the VideoSDK dashboard as well as throught the [Sessions API](/api-reference/realtime-communication/fetch-session-using-sessionid).

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub()](/android/api/sdk-reference/pubsub-class/introduction)


---

# Notify Attendees in Realtime - Android

When doing livestream, you may want to broadcast message to all the viewers at once.

Let us see, how we can use PubSub to implement this functionality. If you are not familiar with the PubSub mechanism, you can [follow this guide](/android/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

### Notifying Attendees

1. We will be publish the message that the sender typed in the `EditText` field to the topic `NOTIFY_ATTENDEES`.



**Kotlin:**

```js

class SpeakerActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
//...
findViewById(R.id.btnSend).setOnClickListener(view -> sendMessage());
  }

  private fun sendMessage() {
// get message from EditText
val message: String = etmessage.getText().toString()
if (!TextUtils.isEmpty(message)) {
    val publishOptions = PubSubPublishOptions()
    publishOptions.setPersist(true)

    // Sending the Message using the publish method
    //highlight-next-line
    meeting!!.pubSub.publish("NOTIFY_ATTENDEES", message, publishOptions)

    // Clearing the message input
    etmessage.setText("")
} else {
    Toast.makeText(
        this@SpeakerActivity, "Please Enter Message",
        Toast.LENGTH_SHORT
    ).show()
}
  }
}
```

---

**Java:**

```js
public class SpeakerActivity extends AppCompatActivity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
//...
findViewById(R.id.btnSend).setOnClickListener(view -> sendMessage());
  }

  private void sendMessage()
  {
// get message from EditText
String message = etmessage.getText().toString();
if (!message.equals("")) {
    PubSubPublishOptions publishOptions = new PubSubPublishOptions();
    publishOptions.setPersist(true);

    // Sending the Message using the publish method
    //highlight-next-line
    meeting.pubSub.publish("NOTIFY_ATTENDEES", message, publishOptions);

    // Clearing the message input
    etmessage.setText("");
} else {
    Toast.makeText(SpeakerActivity.this, "Please Enter Message",
            Toast.LENGTH_SHORT).show();
}
  }
}
```

2. Now let us show an alert to all the viewers displaying the message posted by the speaker.

**Kotlin:**

```js
class ViewerActivity : AppCompatActivity() {

  // PubSubMessageListener
  //highlight-start
val pubSubMessageListener = object : PubSubMessageListener {
    override fun onMessageReceived(message: PubSubMessage) {
        Log.d("VideoSDK", "NOTIFY_ATTENDEE: ${message.message}")
    }
    override fun onOldMessagesReceived(messages: List<PubSubMessage>) {
        // Persisted message list
        Log.d("VideoSDK", "NOTIFY_ATTENDEES: $messages")
    }
}
  //highlight-end

  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_chat)

//...

// Subscribe for 'NOTIFY_ATTENDEES' topic
//highlight-next-line
meeting!!.pubSub.subscribe("NOTIFY_ATTENDEES", pubSubMessageListener)

  }
}
```

---

**Java:**

```js
public class ViewerActivity extends AppCompatActivity {

  // PubSubMessageListener
  //highlight-start
PubSubMessageListener pubSubMessageListener = new PubSubMessageListener() {
    @Override
    public void onMessageReceived(PubSubMessage message) {
        Log.d("VideoSDK", "NOTIFY_ATTENDEE: " + message.getMessage());
    }
    
    @Override
      public void onOldMessagesReceived(List<PubSubMessage> messages) {
      // Persisted message list
      Log.d("VideoSDK", "NOTIFY_ATTENDEES: " + messages);
    }
};
  //highlight-end

  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

//..

// Subscribe for 'NOTIFY_ATTENDEES' topic
//highlight-next-line
meeting.pubSub.subscribe("NOTIFY_ATTENDEES", pubSubMessageListener);

  }
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub()](/android/api/sdk-reference/pubsub-class/introduction)


---

# Raise Hand using PubSub - Android

Let us see, how we can use PubSub to implement Raise Hand functionality. If you are not familiar with the PubSub mechanism and `pubSub` class, you can [follow this guide](/android/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

## Implementing Raise Hand

1. First step in raise hand is choosing the topic which all the participants will publish and subscribe to know some participant raise their hand. We will be using `RAISE_HAND` as the topic for this one.
2. On the raiseHand button, publish any message to that specific topic.



**Kotlin:**

```js
class MainActivity : AppCompatActivity() {

  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)

//...

findViewById(R.id.btnRaiseHand).setOnClickListener(view -> sendRaiseHandMessage());
  }

  private fun sendRaiseHandMessage() {
val publishOptions = PubSubPublishOptions()
publishOptions.setPersist(false)

// Sending the Message using the publish method
//highlight-next-line
meeting!!.pubSub.publish("RAISE_HAND", "Raise Hand", publishOptions)
  }
}
```

---

**Java:**

```js
public class MainActivity extends AppCompatActivity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_chat);

//...

findViewById(R.id.btnRaiseHand).setOnClickListener(view -> sendRaiseHandMessage());
  }

  private void sendRaiseHandMessage()
  {
PubSubPublishOptions publishOptions = new PubSubPublishOptions();
publishOptions.setPersist(false);

// Sending the Message using the publish method
//highlight-next-line
meeting.pubSub.publish("RAISE_HAND", "Raise Hand", publishOptions);
  }
}
```

3. Now let us show an alert to all the participants showing who raised the hand.

**Kotlin:**

```js
class MainActivity : AppCompatActivity() {

  // PubSubMessageListener
  //highlight-start
val pubSubMessageListener = object : PubSubMessageListener {
    override fun onMessageReceived(message: PubSubMessage) {
        Log.d("VideoSDK", "RAISE_HAND: ${message.message}")
    }
    override fun onOldMessagesReceived(messages: List<PubSubMessage>) {
        // Persisted message list
        Log.d("VideoSDK", "RAISE_HAND: $messages")
    }
}
  //highlight-end

  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_chat)

//...

// Subscribe for 'RAISE_HAND' topic
//highlight-next-line
meeting!!.pubSub.subscribe("RAISE_HAND", pubSubMessageListener)
  }
}
```

---

**Java:**

```js
public class MainActivity extends AppCompatActivity {

  // PubSubMessageListener
  //highlight-start
PubSubMessageListener pubSubMessageListener = new PubSubMessageListener() {
    @Override
    public void onMessageReceived(PubSubMessage message) {
        Log.d("VideoSDK", "RAISE_HAND: " + message.getMessage());
    }
    
    @Override
      public void onOldMessagesReceived(List<PubSubMessage> messages) {
      // Persisted message list
      Log.d("VideoSDK", "RAISE_HAND: " + messages);
    }
};
  //highlight-end

  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

//..

// Subscribe for 'RAISE_HAND' topic
//highlight-next-line
meeting.pubSub.subscribe("RAISE_HAND", pubSubMessageListener);
  }
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub()](/android/api/sdk-reference/pubsub-class/introduction)


---

# Reactions - Android

When doing a livestream, one of the way to increase the interaction in between the viewer and speaker is by showing the viewers reaction to all. You might have seen emojis flying around during the livestream happening on instagram.

Lets create a similar flying emoji by using the VideoSDK PubSub mechanism.

### Step 1: Creating a button to send reaction

When `btnReaction` is clicked we will send the emoji name to all the participants using the VideoSDK PubSub mechanism and also shows emoji to localParticipant.



**Kotlin:**

```js
class ILSViewActivity : AppCompatActivity() {

  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
//...
findViewById(R.id.btnReaction).setOnClickListener { v: View? ->
    showEmoji(resources.getDrawable(R.drawable.love_eyes_emoji))
    meeting!!.pubSub.publish("REACTION", "love_eyes", pubSubPublishOptions)
}
  }

  private fun showEmoji(drawable: Drawable?) {
// we will implement this method in step 2
  }
}
```

---

**Java:**

```js
public class ILSViewActivity extends AppCompatActivity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
//...
findViewById(R.id.loveEyes).setOnClickListener(v -> {
    showEmoji(getResources().getDrawable(R.drawable.love_eyes_emoji));
    meeting.pubSub.publish("REACTION", "love_eyes", pubSubPublishOptions);
});
  }

  public void showEmoji(Drawable drawable) {
// we will implement this method in step 2
  }
}
```

### Step 2: Displaying the Reactions to all the users

Here we will listen to the `onMessageReceived` event of `PubSubMessageListener` to know someone send the reactions, and show the flying emoji whenever it triggered.

To Display flyingEmoji, we are using `DirectionGenerator` class to specify direction and `ZeroGravityAnimation` class to give animation to the flyingEmoji.

Copy `DirectionGenerator` and `ZeroGravityAnimation` classes from our [code sample](https://github.com/videosdk-live/videosdk-hls-android-kotlin-example/tree/main/app/src/main/java/live/videosdk/android/hlsdemo/common/reactions).

**Kotlin:**

```js
class ILSViewActivity : AppCompatActivity() {

  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
//...
    val pubSubMessageListener = object : PubSubMessageListener {
    override fun onMessageReceived(message: PubSubMessage) {
        Log.d("VideoSDK", "REACTION: ${message.message}")
    }
    override fun onOldMessagesReceived(messages: List

<img style={{height: '450px'}} src="https://cdn.videosdk.live/website-resources/docs-resources/android_emoji_speaker.gif"/>

</center>

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub()](/android/api/sdk-reference/pubsub-class/introduction)


---

# Introduction

Welcome to the Android Interactive Live Streaming (ILS). Build real-time, low-latency experiences where hosts and audiences connect, interact, and engage seamlessly using VideoSDK.

## Architecture Overview

**Architecture at a Glance** — Hosts join with `SEND_AND_RECV` permissions to broadcast and collaborate, while audiences connect with `RECV_ONLY` access to enjoy the stream without publishing their own media.

![Interactive Live Streaming architecture diagram](https://assets.videosdk.live/images/ils-architecture-live-streaming.png)

## Streaming Modes

**Interactive Live Streaming (ILS):** Low-latency, two-way sessions where hosts and promoted guests publish audio/video, manage roles, and drive rich audience participation.

**HTTP Live Streaming (HLS):** Broadcast delivery tuned for massive audiences with receiver-only playback and CDN scaling, perfect for town halls and one-to-many events.

- [Interactive Live Streaming Quick Start](/android/guide/video-and-audio-calling-api-sdk/quick-start-android-ils): Follow the Kotlin starter to enable backstage control, co-hosting, and moderated audiences.
- [HTTP Live Streaming Quick Start](/android/guide/video-and-audio-calling-api-sdk/quick-start-ILS): Configure VideoSDK's HLS pipeline to broadcast at scale with Android playback clients.


Use the guide below to explore the modular capabilities that help you design each part of this flow.

## Key Features

- [Stage Orchestration](/android/guide/interactive-live-streaming/layout-management/rendering-host-audience-views): Design host layouts, backstage flows, and speaker transitions for Android.
- [Audience Moderation](/android/guide/interactive-live-streaming/audience-management/change-mode): Promote, demote, or remove viewers to keep events high-signal.
- [Advanced Device Control](/android/guide/interactive-live-streaming/device-management/mute-unmute-mic): Switch cameras, microphones, and enable screen sharing across devices.
- [Engagement Tools](/android/guide/interactive-live-streaming/virtual-background): Use chat, reactions, and interactive overlays to keep audiences active.
- [Real-time Analytics](/android/guide/interactive-live-streaming/analytics/understanding-analytics-dashboard): Inspect quality metrics and attendance trends from the analytics toolkit.
- [Recording & Compliance](/android/guide/interactive-live-streaming/recording/Overview): Capture sessions, generate compliance archives, and automate storage.
- [Geo & Network Policies](/android/guide/interactive-live-streaming/geo-fencing): Enforce geographic availability and corporate proxy requirements.
- [Relay & Syndication](/android/guide/interactive-live-streaming/switch-live-stream): Switch Live Stream


## Sample Projects

- [Android ILS Starter](https://github.com/videosdk-live/videosdk-ils-android-sdk-example): Clone the Kotlin sample to explore host, speaker, and viewer flows.
- [Android HLS Broadcast](https://github.com/videosdk-live/videosdk-hls-android-kotlin-example): Scale to massive audiences with the dedicated HLS broadcast sample.


## Quick Start Paths

- [Install the SDK](/android/guide/interactive-live-streaming/integrate-sdk): Configure Gradle, permissions, and VideoSDK dependencies for Android.
- [Configure Tokens](/android/guide/interactive-live-streaming/authentication-and-token): Issue secure access tokens before onboarding real users.
- [Launch the ILS Sample](/android/guide/video-and-audio-calling-api-sdk/run-a-sample-android-ils-project): Run the Android ILS starter to validate host workflows on device and emulator.
- [Broadcast with HLS](/android/guide/video-and-audio-calling-api-sdk/run-a-sample-android-hls-project): Verify large-audience playback using the Android HLS sample.
- [Review Best Practices](/android/guide/interactive-live-streaming/best-practices/developer-experience): Follow platform guidance for performance, permissions, and user experience.
- [Supported Devices](/android/guide/interactive-live-streaming/supported-device-os-architecture): Confirm OS, architecture, and hardware requirements before launch.



---

# Known Issues - Android




---

# Pin/Unpin Participants - Android

In a live stream setup, you often want to control which participant is actively visible on screen — whether it’s the host, a special guest, or someone screen sharing. To manage this dynamically, the `Participant` class provides two key methods:

- `pin()` – Focus on a specific participant’s camera or screen share

- `unpin()` – Remove that focus and return to the default layout

This allows you to programmatically decide who gets the spotlight in your live stream layout.

### `pin()`

The pin() method makes it easy to bring a host camera or screen share front and center in the broadcast layout. Once pinned, you can write the layout logic to place this host in the primary frame, e.g. fullscreen or in a highlighted position.



**Kotlin:**

```js
private fun pinParticipant(participant: Participant) {
participant.pin(null)
Toast.makeText(context, "Participant pinned", Toast.LENGTH_SHORT).show()
}
```

---

**Java:**

```java
private void pinParticipant(Participant participant) {
participant.pin(null);
Toast.makeText(context, "Participant pinned", Toast.LENGTH_SHORT).show();
}
```

### `unpin()`

When a host is no longer the focus (e.g. their segment is over), you can reset their pinned state using unpin(). This allows your live stream UI to revert to a default grid view or automatically promote the next speaker.

**Kotlin:**

```js
private fun unpinParticipant(participant: Participant) {
participant.unpin(null)
Toast.makeText(context, "Participant unpinned", Toast.LENGTH_SHORT).show()
}
```

---

**Java:**

```java
private void unpinParticipant(Participant participant) {
participant.unpin(null);
Toast.makeText(context, "Participant unpinned", Toast.LENGTH_SHORT).show();
}
```

### Events associated with pin/unpin

Following callbacks are received when a host is pinned or unpinned in the livestream.

- All participants-including all the hosts and audience members will receive a callback on the [`onPinStateChanged`](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onparticipantmodechanged) event with the data object containg the peerid of the participant who was pinned, the state and pinnedBy values.

**Kotlin:**

```js
private val meetingEventListener = object : MeetingEventListener() {
override fun onPinStateChanged(pinStateData: JSONObject) {
    try {
        Log.d("VideoSDK", "onPinStateChanged: $pinStateData")

        meeting?.let {
            val peerId = pinStateData.getString("peerId")
            var participant = it.participants[peerId]
            
            if (participant == null) {
                participant = it.localParticipant
            }

            val name = participant?.displayName ?: "Unknown"
            Toast.makeText(this@MainActivity, "Pinned $name", Toast.LENGTH_SHORT).show()
        }
    } catch (e: JSONException) {
        e.printStackTrace()
    }
}
}

```

---

**Java:**

```java
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
@Override
public void onPinStateChanged(JSONObject pinStateData) {
    try {
        Log.d("VideoSDK", "onPinStateChanged: " + pinStateData);
        if (meeting != null) {
            String peerId = pinStateData.getString("peerId");
            Participant participant = meeting.getParticipants().get(peerId);

            if (participant == null) {
                participant = meeting.getLocalParticipant();
            }

            String displayName = participant.getDisplayName();
            Toast.makeText(MainActivity.this, "Pinned " + displayName, Toast.LENGTH_SHORT).show();
        }
    } catch (JSONException e) {
        e.printStackTrace();
    }
}
};
```

:::info

- Based on the `onPinStateChanged` event, you should update your live stream layout for all participants (including the audience) to reflect the current pinned participant.
This means conditionally rendering the pinned participant in the main view or spotlight area across all clients.

:::


## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [pin()](/android/api/sdk-reference/participant-class/methods#pin)
- [unpin()](/android/api/sdk-reference/participant-class/methods#unpin)



---

# Rendering Host and Audience Views - Android 

In a live stream setup, only hosts (participants in `SEND_AND_RECV` mode) can broadcast their audio and video. Audience members (in `RECV_ONLY` mode) are passive viewers who do not share their audio/video.

To ensure optimal performance and a clean user experience, your app should:

- **Render audio and video elements only for hosts** (i.e., participants in `SEND_AND_RECV` mode).
- **Display the total audience count** to give context on viewership without rendering individual audience tiles.

## Filtering and Rendering Hosts

The steps involved in rendering the audio and video of hosts are as follows.

1. [Filtering Hosts and Checking their Mic/Webcam Status](#1-filtering-hosts-and-checking-their-micwebcam-status)
2. [Rendering Video Streams of Hosts](#2-rendering-video-streams-of-hosts)
3. [Rendering Audio Streams of Hosts](#3-rendering-audio)

### `1. Filtering Hosts and Checking their Mic/Webcam Status `

In a live stream, only participants in `SEND_AND_RECV` mode (i.e., hosts) actively share their audio and video. To render their streams, begin by accessing all participants using the `Meeting` class. Then, filter out only those in `SEND_AND_RECV` mode.




**Kotlin:**

```js
private fun showParticipants() {
// Clear existing lists
speakerList?.clear()

// Filter for host participants (SEND_AND_RECV mode)
liveStream?.participants?.values?.forEach { participant ->
    if (participant.mode == "SEND_AND_RECV" && speakerList!!.size < 4) {
        speakerList?.add(participant)
    }
}

// Add local participant if they're a host
if (liveStream?.localParticipant?.mode == "SEND_AND_RECV" && !speakerList!!.contains(liveStream?.localParticipant)) {
    speakerList?.add(0, liveStream?.localParticipant!!)
}

// Update the UI with filtered participants
updateSpeakerGrid()
}

private fun updateSpeakerGrid() {
// Update UI based on number of speakers
when (speakerList?.size) {
    1 -> {
        speakerOneContainer?.visibility = View.VISIBLE
        speakerTwoContainer?.visibility = View.GONE
        speakerThreeContainer?.visibility = View.GONE
        speakerFourContainer?.visibility = View.GONE
        
        // Show first speaker
        showInGUI(speakerList!![0], speakerOneView, speakerOneNameText)
    }
    2 -> {
        speakerOneContainer?.visibility = View.VISIBLE
        speakerTwoContainer?.visibility = View.VISIBLE
        speakerThreeContainer?.visibility = View.GONE
        speakerFourContainer?.visibility = View.GONE
        
        // Show first and second speakers
        showInGUI(speakerList!![0], speakerOneView, speakerOneNameText)
        showInGUI(speakerList!![1], speakerTwoView, speakerTwoNameText)
    }
}
}
```

---

**Java:**

```java
private void showParticipants() {
// Clear existing lists
if (speakerList != null) {
    speakerList.clear();
}

// Filter for host participants (SEND_AND_RECV mode)
if (liveStream != null && liveStream.getParticipants() != null) {
    for (Participant participant : liveStream.getParticipants().values()) {
        if ("SEND_AND_RECV".equals(participant.getMode()) && speakerList.size() < 4) {
            speakerList.add(participant);
        }
    }
}

// Add local participant if they're a host
if (liveStream != null && "SEND_AND_RECV".equals(liveStream.getLocalParticipant().getMode())
        && !speakerList.contains(liveStream.getLocalParticipant())) {
    speakerList.add(0, liveStream.getLocalParticipant());
}

// Update the UI with filtered participants
updateSpeakerGrid();
}

private void updateSpeakerGrid() {
// Update UI based on number of speakers
if (speakerList == null) return;

switch (speakerList.size()) {
    case 1:
        speakerOneContainer.setVisibility(View.VISIBLE);
        speakerTwoContainer.setVisibility(View.GONE);
        speakerThreeContainer.setVisibility(View.GONE);
        speakerFourContainer.setVisibility(View.GONE);

        // Show first speaker
        showInGUI(speakerList.get(0), speakerOneView, speakerOneNameText);
        break;

    case 2:
        speakerOneContainer.setVisibility(View.VISIBLE);
        speakerTwoContainer.setVisibility(View.VISIBLE);
        speakerThreeContainer.setVisibility(View.GONE);
        speakerFourContainer.setVisibility(View.GONE);

        // Show first and second speakers
        showInGUI(speakerList.get(0), speakerOneView, speakerOneNameText);
        showInGUI(speakerList.get(1), speakerTwoView, speakerTwoNameText);
        break;
}
}
```

### `2. Rendering Video Streams of Hosts`

Once you've filtered for participants in `SEND_AND_RECV` mode (i.e., hosts), you can use the `Participant` class to access their real-time data, including their webcamStream, webcamOn, and whether they are the local participant.

For each of these participants, use the `Participant` , which provides real-time information like displayName, micOn, and webcamOn. Display their name along with the current status of their microphone and webcam. If the webcam is off, show a simple placeholder with their name. If it's on, render their video feed. This ensures only hosts are visible to the audience, keeping the experience clean and intentional.

**Kotlin:**

```js
private fun showInGUI(participant: Participant, videoView: VideoView, nameText: TextView) {
// Set participant name
nameText.text = if (participant.id == liveStream?.localParticipant?.id) "You" else participant.displayName

// Get references to status indicators
val micStatusIcon = videoView.findViewById<ImageView>(R.id.ivMicStatus)
val micStatusText = videoView.findViewById<TextView>(R.id.tvMicStatus)
val webcamStatusIcon = videoView.findViewById<ImageView>(R.id.ivWebcamStatus)
val webcamStatusText = videoView.findViewById<TextView>(R.id.tvWebcamStatus)

// Set initial status
updateMicStatus(participant.isMicOn, micStatusIcon, micStatusText)
updateWebcamStatus(participant.isWebcamOn, webcamStatusIcon, webcamStatusText, videoView)

// Add participant listener for status changes
participant.addEventListener(object : ParticipantEventListener() {
    override fun onStreamEnabled(stream: Stream) {
        activity?.runOnUiThread {
            if (stream.kind.equals("video", ignoreCase = true)) {
                // Update webcam status
                updateWebcamStatus(true, webcamStatusIcon, webcamStatusText, videoView)
                
                // Set up video stream
                videoView.visibility = View.VISIBLE
                videoView.setScalingType(RendererCommon.ScalingType.SCALE_ASPECT_FILL)
                
                // Mirror video for local participant
                if (participant.id == liveStream?.localParticipant?.id) {
                    videoView.setMirror(true)
                }
                
                videoView.addTrack(stream.mediaStream, stream.trackId)
            } else if (stream.kind.equals("audio", ignoreCase = true)) {
                // Update mic status
                updateMicStatus(true, micStatusIcon, micStatusText)
            }
        }
    }

    override fun onStreamDisabled(stream: Stream) {
        activity?.runOnUiThread {
            if (stream.kind.equals("video", ignoreCase = true)) {
                // Update webcam status
                updateWebcamStatus(false, webcamStatusIcon, webcamStatusText, videoView)
                
                // Hide video view
                videoView.visibility = View.GONE
            } else if (stream.kind.equals("audio", ignoreCase = true)) {
                // Update mic status
                updateMicStatus(false, micStatusIcon, micStatusText)
            }
        }
    }
})

// Set up initial streams
participant.streams.values.forEach { stream ->
    if (stream.kind.equals("video", ignoreCase = true)) {
        // Set up video stream
        videoView.visibility = View.VISIBLE
        videoView.setScalingType(RendererCommon.ScalingType.SCALE_ASPECT_FILL)
        
        // Mirror video for local participant
        if (participant.id == liveStream?.localParticipant?.id) {
            videoView.setMirror(true)
        }
        
        videoView.addTrack(stream.mediaStream, stream.trackId)
    }
}
}

private fun updateMicStatus(isMicOn: Boolean, micStatusIcon: ImageView, micStatusText: TextView) {
micStatusIcon.setImageResource(if (isMicOn) R.drawable.ic_audio_on else R.drawable.ic_audio_off)
micStatusText.text = if (isMicOn) "On" else "Off"
}

private fun updateWebcamStatus(isWebcamOn: Boolean, webcamStatusIcon: ImageView, webcamStatusText: TextView, videoView: VideoView) {
webcamStatusIcon.setImageResource(if (isWebcamOn) R.drawable.ic_video_camera else R.drawable.ic_video_camera_off)
webcamStatusText.text = if (isWebcamOn) "On" else "Off"

// Show/hide video view based on webcam status
if (isWebcamOn) {
    videoView.visibility = View.VISIBLE
} else {
    videoView.removeTrack()
    videoView.visibility = View.GONE
}
}
```

---

**Java:**

```java
private void showInGUI(Participant participant, VideoView videoView, TextView nameText) {
// Set participant name
if (participant.getId().equals(liveStream.getLocalParticipant().getId())) {
    nameText.setText("You");
} else {
    nameText.setText(participant.getDisplayName());
}

// Get references to status indicators
ImageView micStatusIcon = videoView.findViewById(R.id.ivMicStatus);
TextView micStatusText = videoView.findViewById(R.id.tvMicStatus);
ImageView webcamStatusIcon = videoView.findViewById(R.id.ivWebcamStatus);
TextView webcamStatusText = videoView.findViewById(R.id.tvWebcamStatus);

// Set initial status
updateMicStatus(participant.isMicOn(), micStatusIcon, micStatusText);
updateWebcamStatus(participant.isWebcamOn(), webcamStatusIcon, webcamStatusText, videoView);

// Add participant listener for status changes
participant.addEventListener(new ParticipantEventListener() {
    @Override
    public void onStreamEnabled(Stream stream) {
        if (activity != null) {
            activity.runOnUiThread(() -> {
                if ("video".equalsIgnoreCase(stream.getKind())) {
                    // Update webcam status
                    updateWebcamStatus(true, webcamStatusIcon, webcamStatusText, videoView);

                    // Set up video stream
                    videoView.setVisibility(View.VISIBLE);
                    videoView.setScalingType(RendererCommon.ScalingType.SCALE_ASPECT_FILL);

                    // Mirror video for local participant
                    if (participant.getId().equals(liveStream.getLocalParticipant().getId())) {
                        videoView.setMirror(true);
                    }

                    videoView.addTrack(stream.getMediaStream(), stream.getTrackId());

                } else if ("audio".equalsIgnoreCase(stream.getKind())) {
                    // Update mic status
                    updateMicStatus(true, micStatusIcon, micStatusText);
                }
            });
        }
    }

    @Override
    public void onStreamDisabled(Stream stream) {
        if (activity != null) {
            activity.runOnUiThread(() -> {
                if ("video".equalsIgnoreCase(stream.getKind())) {
                    // Update webcam status
                    updateWebcamStatus(false, webcamStatusIcon, webcamStatusText, videoView);

                    // Hide video view
                    videoView.setVisibility(View.GONE);
                } else if ("audio".equalsIgnoreCase(stream.getKind())) {
                    // Update mic status
                    updateMicStatus(false, micStatusIcon, micStatusText);
                }
            });
        }
    }
});

// Set up initial streams
for (Stream stream : participant.getStreams().values()) {
    if ("video".equalsIgnoreCase(stream.getKind())) {
        // Set up video stream
        videoView.setVisibility(View.VISIBLE);
        videoView.setScalingType(RendererCommon.ScalingType.SCALE_ASPECT_FILL);

        // Mirror video for local participant
        if (participant.getId().equals(liveStream.getLocalParticipant().getId())) {
            videoView.setMirror(true);
        }

        videoView.addTrack(stream.getMediaStream(), stream.getTrackId());
    }
}
}

private void updateMicStatus(boolean isMicOn, ImageView micStatusIcon, TextView micStatusText) {
micStatusIcon.setImageResource(isMicOn ? R.drawable.ic_audio_on : R.drawable.ic_audio_off);
micStatusText.setText(isMicOn ? "On" : "Off");
}

private void updateWebcamStatus(boolean isWebcamOn, ImageView webcamStatusIcon, TextView webcamStatusText, VideoView videoView) {
webcamStatusIcon.setImageResource(isWebcamOn ? R.drawable.ic_video_camera : R.drawable.ic_video_camera_off);
webcamStatusText.setText(isWebcamOn ? "On" : "Off");

// Show/hide video view based on webcam status
if (isWebcamOn) {
    videoView.setVisibility(View.VISIBLE);
} else {
    videoView.removeTrack();
    videoView.setVisibility(View.GONE);
}
}
```


### `3. Rendering Audio Streams of Hosts`

Alongside video rendering, you can also play a participant’s audio whenever their mic is turned on. 

**Kotlin:**

```js
private fun setupAudioControls() {
micButton?.setOnClickListener {
    if (liveStream?.localParticipant?.isMicOn == true) {
        // Turn off microphone
        liveStream?.localParticipant?.disableMic()
        micButton?.setImageResource(R.drawable.ic_audio_off)
    } else {
        // Turn on microphone
        liveStream?.localParticipant?.enableMic()
        micButton?.setImageResource(R.drawable.ic_audio_on)
    }
}
}

liveStream?.addEventListener(object : MeetingEventListener() {
override fun onAudioDeviceChanged(audioDevice: String, availableAudioDevices: Set<String>) {
    // Handle audio device changes (e.g., switching between speaker, earpiece, headphones)
    activity?.runOnUiThread {
        // Update UI based on current audio device
        when (audioDevice) {
            "SPEAKER_PHONE" -> audioOutputButton?.setImageResource(R.drawable.ic_speaker)
            "EARPIECE" -> audioOutputButton?.setImageResource(R.drawable.ic_earpiece)
            "WIRED_HEADSET" -> audioOutputButton?.setImageResource(R.drawable.ic_headset)
            "BLUETOOTH" -> audioOutputButton?.setImageResource(R.drawable.ic_bluetooth)
        }
    }
}
})
```

---

**Java:**

```java
private void setupAudioControls() {
if (micButton != null) {
    micButton.setOnClickListener(v -> {
        if (liveStream != null && liveStream.getLocalParticipant() != null) {
            if (liveStream.getLocalParticipant().isMicOn()) {
                // Turn off microphone
                liveStream.getLocalParticipant().disableMic();
                micButton.setImageResource(R.drawable.ic_audio_off);
            } else {
                // Turn on microphone
                liveStream.getLocalParticipant().enableMic();
                micButton.setImageResource(R.drawable.ic_audio_on);
            }
        }
    });
}
}

private void setupAudioDeviceListener() {
if (liveStream != null) {
liveStream.addEventListener(new MeetingEventListener() {
    @Override
    public void onAudioDeviceChanged(String audioDevice, Set<String> availableAudioDevices) {
        // Handle audio device changes (e.g., switching between speaker, earpiece, headphones)
      activity.runOnUiThread(() -> {
          // Update UI based on current audio device
        switch (audioDevice) {
            case "SPEAKER_PHONE":
                if (audioOutputButton != null)
                    audioOutputButton.setImageResource(R.drawable.ic_speaker);
                break;
            case "EARPIECE":
                if (audioOutputButton != null)
                    audioOutputButton.setImageResource(R.drawable.ic_earpiece);
                break;
            case "WIRED_HEADSET":
                if (audioOutputButton != null)
                    audioOutputButton.setImageResource(R.drawable.ic_headset);
                break;
            case "BLUETOOTH":
                if (audioOutputButton != null)
                    audioOutputButton.setImageResource(R.drawable.ic_bluetooth);
                break;
        }
      });
    }
});
}
}
```


## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [Participant](/android/api/sdk-reference/participant-class/introduction)


---

# Live Captioning for Livestreams - Android

Live captioning enhances your livestreams by converting hosts' speech into text in real-time, boosting accessibility and engagement. Using the `startTranscription()` and `stopTranscription()` methods, you can enable or disable captions on the fly, and display captions dynamically in your UI for all viewers.

Video SDK offers flexible configuration and event-driven updates to help you integrate captions seamlessly into your broadcast layout.

### `startTranscription()`

The `startTranscription()` method, accessible from the `Meeting` class, is used to initiate live captions in a live stream. 

### `stopTranscription()`

The `stopTranscription()` method, accessible from the `Meeting` class, is used to stop the live captions in a live stream.

#### Example



**Kotlin:**

```js
import android.os.Bundle
import android.widget.Button
import androidx.appcompat.app.AppCompatActivity
import live.videosdk.rtc.android.Meeting
import live.videosdk.rtc.android.VideoSDK
import live.videosdk.rtc.android.meeting.SummaryConfig
import live.videosdk.rtc.android.meeting.TranscriptionConfig

class LiveStreamActivity : AppCompatActivity() {

private lateinit var liveStream: Meeting

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_live_stream)

    // Initialize the meeting (replace with actual meeting ID and token)
    liveStream = VideoSDK.initMeeting(... )

    val startCaptionsButton: Button = findViewById(R.id.btn_start_captions)
    val stopCaptionsButton: Button = findViewById(R.id.btn_stop_captions)

    startCaptionsButton.setOnClickListener {
        startRealtimeTranscription()
    }

    stopCaptionsButton.setOnClickListener {
        stopRealtimeTranscription()
    }
}

private fun startRealtimeTranscription() {
    val webhookUrl = "https://www.example.com"

    val summaryConfig = SummaryConfig(
        true,
        "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
    )

    val transcriptionConfig = TranscriptionConfig(
        webhookUrl,
        summaryConfig
    )

    liveStream.startTranscription(transcriptionConfig)
}

private fun stopRealtimeTranscription() {
    liveStream.stopTranscription()
}
}
```

---

**Java:**

```java
public class LiveStreamActivity extends AppCompatActivity {

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_live_stream);

    // Initialize the meeting
    Meeting liveStream = VideoSDK.initMeeting( ...);

    Button startCaptionsButton = findViewById(R.id.btn_start_captions);
    Button stopCaptionsButton = findViewById(R.id.btn_stop_captions);

    startCaptionsButton.setOnClickListener(new View.OnClickListener() {
        @Override
        public void onClick(View v) {
            startRealtimeTranscription();
        }
    });

    stopCaptionsButton.setOnClickListener(new View.OnClickListener() {
        @Override
        public void onClick(View v) {
            stopRealtimeTranscription();
        }
    });
}

private void startRealtimeTranscription() {
    String webhookUrl = "https://www.example.com";

    SummaryConfig summaryConfig = new SummaryConfig(
            true,
            "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
    );

    TranscriptionConfig transcriptionConfig = new TranscriptionConfig(
            webhookUrl,
            summaryConfig
    );

    liveStream.startTranscription(transcriptionConfig);
}

private void stopRealtimeTranscription() {
    liveStream.stopTranscription();
}
}
```


## Events associated with live captioning

- All [participants-including all the hosts and audience members](/android/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a callback on the [`onTranscriptionStateChanged`](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#ontranscriptionstatechanged) event with the current state of the captioning.
- All [participants-including all the hosts and audience members](/android/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a callback on the [`onTranscriptionText`](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#ontranscriptiontext) event with the latest captions whenever a host speaks.

**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onTranscriptionStateChanged(data: JSONObject) {
try {
    val status = data.getString("status")
    val id = data.getString("id")
    when (status) {
        TranscriptionState.TRANSCRIPTION_STARTING.name -> Log.d("onTranscriptionStateChanged", "Realtime Transcription is starting, ID: $id")
        TranscriptionState.TRANSCRIPTION_STARTED.name -> Log.d("onTranscriptionStateChanged", "Realtime Transcription is started, ID: $id")
        TranscriptionState.TRANSCRIPTION_STOPPING.name -> Log.d("onTranscriptionStateChanged", "Realtime Transcription is stopping, ID: $id")
        TranscriptionState.TRANSCRIPTION_STOPPED.name -> Log.d("onTranscriptionStateChanged", "Realtime Transcription is stopped, ID: $id")
        else -> Log.d("onTranscriptionStateChanged", "Unknown transcription state: $status, ID: $id")
    }
} catch (e: JSONException) {
    Log.e("onTranscriptionStateChanged", "Error parsing transcription state", e)
}
  }

  override fun onTranscriptionText(data: TranscriptionText) {
val participantId: String = data.participantId
val participantName: String = data.participantName
val text: String = data.text
val timestamp: Int = data.timestamp
val type: String = data.type

Log.d("onTranscriptionText", "$participantName: $text $timestamp")
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  liveStream!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```java
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
public void onTranscriptionStateChanged(JSONObject data) {
    try {
        String status = data.getString("status");
        String id = data.getString("id");

        if (TranscriptionState.TRANSCRIPTION_STARTING.name().equals(status)) {
            Log.d("onTranscriptionStateChanged", "Realtime Transcription is starting, ID: " + id);
        }
        else if (TranscriptionState.TRANSCRIPTION_STARTED.name().equals(status)) {
            Log.d("onTranscriptionStateChanged", "Realtime Transcription is started, ID: " + id);
        }
        else if (TranscriptionState.TRANSCRIPTION_STOPPING.name().equals(status)) {
            Log.d("onTranscriptionStateChanged", "Realtime Transcription is stopping, ID: " + id);
        }
        else if (TranscriptionState.TRANSCRIPTION_STOPPED.name().equals(status)) {
            Log.d("onTranscriptionStateChanged", "Realtime Transcription is stopped, ID: " + id);
        }
        else {
            Log.d("onTranscriptionStateChanged", "Unknown transcription state: " + status + ", ID: " + id);
        }
    } catch (JSONException e) {
        Log.e("onTranscriptionStateChanged", "Error parsing transcription state", e.getMessage());
    }
}

@Override
public void onTranscriptionText(TranscriptionText data) {
    String participantId = data.getParticipantId();
    String participantName = data.getParticipantName();
    String text = data.getText();
    int timestamp = data.getTimestamp();
    String type = data.getType();

    Log.d("onTranscriptionText", participantName + ": " + text + " " + timestamp);
}
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  liveStream.addEventListener(meetingEventListener);
}
```


### API Reference

The API references for all the methods utilized in this guide are provided below.

- [startTranscription()](/android/api/sdk-reference/meeting-class/methods#starttranscription)
- [stopTranscription()](/android/api/sdk-reference/meeting-class/methods#stoptranscription)
- [onTranscriptionStateChanged](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#ontranscriptionstatechanged)
- [onTranscriptionText](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#ontranscriptiontext)


---

# Reactions during Live Stream - Android

To enhance interaction between viewers and speakers during a livestream, a creative approach is to display viewers' reactions to everyone. This can be achieved by creating a lively atmosphere with flying emojis, similar to the experience seen in livestreams on platforms like Instagram.

This guide explains how to implement this engaging feature using the VideoSDK PubSub mechanism.

## Step 1: Creating a button to send reaction

To implement this functionality, start by creating a button that sends reactions to all users. When `Button` is clicked we will send the emoji name to all the participants using the VideoSDK PubSub mechanism and also shows emoji to host.



**Kotlin:**

```js
class LiveStreamActivity : AppCompatActivity() {

  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
//...
findViewById(R.id.btnReaction).setOnClickListener { v: View? ->
    showEmoji(resources.getDrawable(R.drawable.love_eyes_emoji))
    liveStream!!.pubSub.publish("REACTION", "love_eyes", pubSubPublishOptions)
}
  }

  private fun showEmoji(drawable: Drawable?) {
// we will implement this method in step 2
  }
}
```

---

**Java:**

```js
public class LiveStreamActivity extends AppCompatActivity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
//...
findViewById(R.id.loveEyes).setOnClickListener(v -> {
    showEmoji(getResources().getDrawable(R.drawable.love_eyes_emoji));
    liveStream.pubSub.publish("REACTION", "love_eyes", pubSubPublishOptions);
});
  }

  public void showEmoji(Drawable drawable) {
// we will implement this method in step 2
  }
}
```

## Step 2: Displaying the Reactions to all the users

Here we will listen to the `onMessageReceived` event of `PubSubMessageListener` to know someone send the reactions, and show the flying emoji whenever it triggered.

To Display flyingEmoji, we are using `DirectionGenerator` class to specify direction and `ZeroGravityAnimation` class to give animation to the flyingEmoji.

Copy `DirectionGenerator` and `ZeroGravityAnimation` classes from our [code sample](https://github.com/videosdk-live/videosdk-hls-android-kotlin-example/tree/main/app/src/main/java/live/videosdk/android/hlsdemo/common/reactions).

**Kotlin:**

```js
class LiveStreamActivity : AppCompatActivity() {

  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
//...
val emojiListener = object : PubSubMessageListener {
override fun onMessageReceived(pubSubMessage: PubSubMessage) {
    when (pubSubMessage.message) {
        //Showing other participants reactions
        "loveEyes" -> showEmoji(resources.getDrawable(R.drawable.love_eyes_emoji))
    }
}
override fun onOldMessagesReceived(messages: List

<img style={{height: '450px'}} src="https://cdn.videosdk.live/website-resources/docs-resources/android_emoji_speaker.gif"/>

</center>

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub()](/android/api/sdk-reference/pubsub-class/introduction)


---

Recording meetings is an essential feature that ensures all important discussions, decisions, and interactions are documented for future reference. VideoSDK offers three types of recordings: Meeting Recording, Participant Recording, and Participant Track Recording. Each type serves a specific purpose to cater to different recording needs during a meeting.

## Meeting Recording

Meeting Recording captures the entire meeting, including all participants, audio, video, and shared content. This comprehensive recording is ideal for reviewing the entire meeting, ensuring that nothing is missed. It provides a holistic view of the meeting, capturing every interaction and piece of information shared during the session.

![Meeting Recording](https://cdn.videosdk.live/website-resources/docs-resources/MeetingRecording.png)

## Participant Recording

Participant Recording focuses on individual participants, capturing both their audio and video into a single file. This type of recording is particularly useful for tracking the contributions of specific participants or for scenarios where detailed analysis of an individual’s participation is needed. When a participant mutes their audio or turns off their video, the recording continues but with silenced audio or a black screen, respectively. This ensures a continuous recording without interruptions, reflecting the participant's involvement throughout the meeting.

![Participant Recording](https://cdn.videosdk.live/website-resources/docs-resources/ParticipantRecording.png)

## Participant Track Recording

Participant Track Recording allows you to record specific tracks of a participant, either audio or video, based on user input. This targeted approach is perfect for capturing particular aspects of a participant’s contribution, such as only their audio or only their video. Multiple files are generated whenever there is a change in the track's status (e.g., starting after being muted ), ensuring focused documentation of each continuous segment. This method is especially useful in scenarios where detailed analysis of specific media (audio or video) is required.

![Participant Track Recording](https://cdn.videosdk.live/website-resources/docs-resources/TrackRecording.png)



---

# Geo Tag Meeting Recordings - Android

To ensure compliance for BFSIs doing vKYC, it very important to include the co-ordinates(location) of the customer in the recordings. VideoSDK provides a very customizable solution to implement this feature. You will be using custom templates for this purpose.

We have created a ready to use template for this use case which can be found [here](https://github.com/videosdk-live/videosdk-rtc-react-prebuilt-ui/tree/template/geo-tag-watermark). To integrate this template with your recordings follow the below mentiond instructions.

### Host the template

1. Clone the template repository and switch to the branch `template/geo-tag-watermark`.

```bash
git clone https://github.com/videosdk-live/videosdk-rtc-react-prebuilt-ui.git
cd videosdk-rtc-react-prebuilt-ui
git checkout template/geo-tag-watermark
```

2. Install the dependencies and create a build of the project using below mentioned commands.

```bash
npm install
npm run build
```

3. Host the contents of the build folder on your server and check if the template is up and running.

:::note

If you want to create the complete template from scratch you can [follow this guide.](/android/guide/video-and-audio-calling-api-sdk/live-streaming/custom-template)

:::

### Using the template for recording

1. To use the template that we deployed earlier, we will be using the `templateUrl` feature in the `startRecording` API.
   To generate the template URL, you will have to append the `meetingId`, and `token` has to be added in the query parameters. Also if you are using the template provided above you need to added a few extra paramters mentioned below. Here is the code snippet to generate the URL.

```js
async function main() {
  let meetingId = "Your MeetingID";
  let token = "Your Token";
  const templateUrl = `https://${YOUR Template URL}/?meetingId=${meetingId}&token=${token}&name=recorder&isRecorder=true&joinWithoutUserInteraction=true`;

  console.log(templateUrl);
}

main();
```

2. Now that we have the template URL, we will use this URL to start the recording using the below provided API call.

```js
async function main() {
  let meetingId = "Your MeetingID";
  let token = "Your Token";
  const templateUrl = `https://${YOUR Template URL}/?meetingId=${meetingId}&token=${token}&name=recorder&isRecorder=true&joinWithoutUserInteraction=true`;

  console.log(templateUrl);

  //Using the previouly created template URL and starting the recording using the API.
  const options = {
    method: "POST",
    headers: {
      Authorization: "$YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      roomId: "Your MeetingId",
      templateUrl: templateUrl,
    }),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();
```

### Updating the Geo Tagging Coordinates

We will be using the PubSub feature of VideoSDK to update the data of latitude and longitude. For the predefined template provided by us we are using `GEO_TAG` as topic name. We will be publishing the `participantName`, `latitude` and `longitude` of the participant for whom we want to show in the recording.

:::note

You will have to fetch the longitude and latitude of the participant before sending it using the pubsub.

:::

Here is the code how you will have to publish the message:

```js
function Watermark() {
  const { messages, publish } = usePubSub("GEO_TAG");

  const sendCoordinates = () => {
    publish(
      "GEO TAG DATA",
      { persist: true },
      {
        latitude: "LATITUDE OF PARTICIPANT",
        longitude: "LONGITUDE OF PARTICIPANT",
        participantName: "NAME OF PARTICIPANT",
      }
    );
  };

  return <></>;
}
```

After implementing this, you should get the recording in the following format:

![Geo Tagging Recoridng](https://cdn.videosdk.live/website-resources/docs-resources/geo-tag-recording-template.png)

If you wish to change how UI looks on recording, you can change it by updating the layout in the template itself.

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)
- [Learn more about Custom Templates](/android/guide/video-and-audio-calling-api-sdk/live-streaming/custom-template)


---

You have the option to create presigned URL, allowing you to upload your recordings to AWS, Azure, or GCP securely.
presigned URL provide a secure and temporary way to upload objects to your cloud storage. Instead of sharing your entire credentials, you can create a special URL that allows uploading a specific file for a limited time.

:::important

While presigned URL offer a convenient way to upload files securely, each cloud provider (AWS, Azure, and GCP) might have different restrictions on how they work. It's advisable to refer the respective documentation for **[<u>AWS</u>](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)**, **[<u>Azure</u>](https://learn.microsoft.com/en-us/rest/api/storageservices/delegate-access-with-shared-access-signature)**, and **[<u>GCP</u>](https://cloud.google.com/cdn/docs/using-signed-urls)** to gain a clearer understanding of presigned URL.

:::

### Code Sample

This guide will walk you through the process of generating a presigned URL for uploading recordings to your cloud storage of choice. You can use this generated presigned URL in [Start Recording API](/api-reference/realtime-communication/start-recording#preSignedUrl).



**AWS:**

```js
const { S3Client, PutObjectCommand } = require("@aws-sdk/client-s3");
const { getSignedUrl } = require("@aws-sdk/s3-request-presigner");

const region = <YOUR S3 REGION>;
const bucket = <YOUR S3 BUCKET NAME>;
const key = <YOUR FILE NAME>; // test/abc.mp4
const accessKeyId = <YOUR S3 ACCESS KEY ID>;
const secretAccessKey = <YOUR S3 SECRET ACCESS KEY>;
const expiresIn = <URL EXPIRY IN SECONDS>; // this number should be higher than duraion of recording

const s3Client = new S3Client({
credentials: {
    accessKeyId: accessKeyId,
    secretAccessKey: secretAccessKey,
},
region: region,
});

const createPresignedUrlWithClient = async () => {
const command = new PutObjectCommand({ Bucket: bucket, Key: key });
const preSignedUrl = await getSignedUrl(s3Client, command, { expiresIn: expiresIn });
return preSignedUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await createPresignedUrlWithClient();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

---

**AZURE:**

```js
const { BlobServiceClient, BlobSASPermissions } = require("@azure/storage-blob");

const connectionString = <YOUR AZURE STORAGE CONNECTION STRING>;
const containerName = <YOUR AZURE CONTAINER NAME>;
const blobName = <YOUR AZURE BLOB NAME>;
const startsOn = <YOUR SASURL START TIME>; // (optional, defaults to now)
const expiresOn = <YOUR SASURL EXPIRY TIME>; // expiry time should be higher than duration of recording

const generateSASUrl = async () => {
let blobServiceClient = BlobServiceClient.fromConnectionString(connectionString);
let containerClient = blobServiceClient.getContainerClient(containerName);

await containerClient.createIfNotExists({
    access: "container",
});

const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const sasUrl = await blockBlobClient.generateSasUrl({
    startsOn: startsOn, // sasUrl start time
    expiresOn: expiresOn, // sasUrl expiration time
    permissions: BlobSASPermissions.parse("write"),
});
return sasUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await generateSASUrl();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

---

**GCP:**

```js
const { Storage } = require("@google-cloud/storage");

const projectId = <YOUR GCP PROJECT ID>;
const clientEmail = <YOUR GCP CLIENT EMAIL>;
const privateKey = <YOUR GCP PRIVATE KEY>;
const expires =<URL EXPIRY IN SECONDS>; // this number should be higher than duraion of recording
const bucketName = <YOUR GCP BUCKET NAME>;
const fileName = <YOUR FILE NAME>; // test/abc.mp4

const storage = new Storage({
projectId: projectId,
credentials: {
    client_email: clientEmail,
    private_key: privateKey,
},
});

const generateSignedUrl = async () => {
const options = {
    version: "v4",
    action: "write",
    expires: expires,
    contentType: "video/mp4",
};

const [signedUrl] = storage.bucket(bucketName).file(fileName).getSignedUrl(options);
return signedUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await generateSignedUrl();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)



---

VideoSDK offers individual participant recording, generating a single, continuous file for a participant.

This recording captures the participant's audio and video streams throughout the meeting, regardless of whether they are muted or have their camera turned off. During periods of audio muting or video disengagement, the respective tracks will be silent or display a black screen, respectively.

You can access the recorded files in the developer dashboard or opt to store them in your own cloud storage.

This guide provides an overview of the start and stop functionality for individual participant recording through APIs.


## Start Individual Participant Recording

To start a participant recording, you will have to call `/v2/recordings/participant/start` API with following body parameters.

- `roomId`: RoomId for which the participant recording is to be started
- `participantId`: participantId of the participant to be recorder.
- `fileFormat`: Currently only `webm` is supported as file format. We will add the support for other formats in future.
- `webhookUrl`: The webhook URL where you would like to get the status updates of the recording. To learn more about webhooks refer [here](#participant-track-recording-starting).
- `bucketDirPath`: If you are using your own storage, you can provide the directory path where you want to store the recording. To configure the storage please [refere this quide](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config).

The usual recording path would look like `${sessionId}/${participantId}/${filename}`.



**Kotlin:**

```kotlin
import org.json.JSONObject
import java.io.OutputStream
import java.net.HttpURLConnection
import java.net.URL
import java.io.IOException

fun StartParticipantRecording() {
val roomId = "<YOUR ROOM ID>"
val participantId = "<PARTICIPANT ID>"
val fileFormat = "<YOUR FILE FORMAT>" // (Optional) default: webm
val bucketDirPath = "<YOUR CLOUD STORAGE BUCKET PATH>" // (Optional) test/abc
val webhookUrl = "<YOUR WEBHOOK URL>" // (Optional)

try {
    val url = URL("https://api.videosdk.live/v2/recordings/participant/start")
    val conn = url.openConnection() as HttpURLConnection
    conn.requestMethod = "POST"
    conn.setRequestProperty("Authorization", "$YOUR_TOKEN")
    conn.setRequestProperty("Content-Type", "application/json")
    conn.doOutput = true

    val json = JSONObject()
    json.put("roomId", roomId)
    json.put("participantId", participantId)
    json.put("fileFormat", fileFormat)
    json.put("bucketDirPath", bucketDirPath)
    json.put("webhookUrl", webhookUrl)

    conn.outputStream.use { os: OutputStream ->
        val input = json.toString().toByteArray(Charsets.UTF_8)
        os.write(input, 0, input.size)
    }

    val responseCode = conn.responseCode
    if (responseCode == HttpURLConnection.HTTP_OK) {
        println("Participant Recording started successfully.")
    } else {
        println("Failed to start participant recording.")
    }
} catch (e: Exception) {
    e.printStackTrace()
}
}

```

---

**Java:**

```java
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import org.json.JSONObject;

private void StartParticipantRecording() {
String roomId = "<YOUR ROOM ID>";
String participantId = "<PARTICIPANT ID>";
String fileFormat = "<YOUR FILE FORMAT>"; // (Optional) default: webm
String bucketDirPath = "<YOUR CLOUD STORAGE BUCKET PATH>"; // (Optional) test/abc
String webhookUrl = "<YOUR WEBHOOK URL>"; // (Optional)

try {
    URL url = new URL("https://api.videosdk.live/v2/recordings/participant/start");
    HttpURLConnection conn = (HttpURLConnection) url.openConnection();
    conn.setRequestMethod("POST");
    conn.setRequestProperty("Authorization", "$YOUR_TOKEN");
    conn.setRequestProperty("Content-Type", "application/json");
    conn.setDoOutput(true);

    JSONObject json = new JSONObject();
    json.put("roomId", roomId);
    json.put("participantId", participantId);
    json.put("fileFormat", fileFormat);
    json.put("bucketDirPath", bucketDirPath);
    json.put("webhookUrl", webhookUrl);

    try (OutputStream os = conn.getOutputStream()) {
        byte[] input = json.toString().getBytes("utf-8");
        os.write(input, 0, input.length);
    }

    int responseCode = conn.getResponseCode();
    if (responseCode == HttpURLConnection.HTTP_OK) {
        System.out.println("Participant Recording started successfully.");
    } else {
        System.out.println("Failed to start participant recording.");
    }
} catch (Exception e) {
    e.printStackTrace();
}
}

```

## Stop Individual Participant Recording

To stop a participant recording, you will have to call `/v2/recordings/participant/stop` API with following body parameters.

- `roomId`: RoomId for which the participant recording is to be stopped
- `participantId`: participantId for which the recording is to be stopped.

**Kotlin:**

```kotlin
import org.json.JSONObject
import java.io.OutputStream
import java.net.HttpURLConnection
import java.net.URL

fun StopParticipantRecording() {
val roomId = "<YOUR ROOM ID>"
val participantId = "<PARTICIPANT ID>"

try {
    val url = URL("https://api.videosdk.live/v2/recordings/participant/stop")
    val conn = url.openConnection() as HttpURLConnection
    conn.requestMethod = "POST"
    conn.setRequestProperty("Authorization", "$YOUR_TOKEN")
    conn.setRequestProperty("Content-Type", "application/json")
    conn.doOutput = true

    val json = JSONObject()
    json.put("roomId", roomId)
    json.put("participantId", participantId)

    conn.outputStream.use { os: OutputStream ->
        val input = json.toString().toByteArray(Charsets.UTF_8)
        os.write(input, 0, input.size)
    }

    val responseCode = conn.responseCode
    if (responseCode == HttpURLConnection.HTTP_OK) {
        println("Participant Recording stopped successfully.")
    } else {
        println("Failed to stop participant recording.")
    }
} catch (e: Exception) {
    e.printStackTrace()
}

}

```

---

**Java:**

```java
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import org.json.JSONObject;

private void StopParticipantRecording() {
String roomId = "<YOUR ROOM ID>";
String participantId = "<PARTICIPANT ID>";

try {
    URL url = new URL("https://api.videosdk.live/v2/recordings/participant/stop");
    HttpURLConnection conn = (HttpURLConnection) url.openConnection();
    conn.setRequestMethod("POST");
    conn.setRequestProperty("Authorization", "$YOUR_TOKEN");
    conn.setRequestProperty("Content-Type", "application/json");
    conn.setDoOutput(true);

    JSONObject json = new JSONObject();
    json.put("roomId", roomId);
    json.put("participantId", participantId);

    try (OutputStream os = conn.getOutputStream()) {
        byte[] input = json.toString().getBytes("utf-8");
        os.write(input, 0, input.length);
    }

    int responseCode = conn.getResponseCode();
    if (responseCode == HttpURLConnection.HTTP_OK) {
        System.out.println("Participant Recording stopped successfully.");
    } else {
        System.out.println("Failed to stop participant recording.");
    }
} catch (Exception e) {
    e.printStackTrace();
}
}


```

## Webhook associated with Participant Recording

### participant-recording-starting

- A "Participant Recording Starting" webhook is triggered when the participant recording process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-started

- Participant Recording started webhook will be received when successfully participant recording is started in meeting

###### Example

```javascript
{
    "webhookType": "participant-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopping

- A "Participant Recording Stopping" webhook is triggered when the participant recording end process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopped

- Participant Recording stopped webhook will be received when participant recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "participant-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-recording-failed

- A "Participant Recording Failed" webhook is generated when the participant recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "participant-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
    },
}
```

---

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Participant Recording API](/api-reference/realtime-communication/start-participant-recording)
- [Stop Participant Recording API](/api-reference/realtime-communication/stop-participant-recording)



---

VideoSDK provides participant track recording, creating separate audio or video files for participant.

New files are generated when a participant starts their audio or video again after turning it off (e.g., unmuting the microphone or restarting the camera). This ensures that each file represents a continuous segment of audio or video content.

Once track recording is complete, all audio files for a participant are consolidated into a single directory, as are the video files.


## Start Participant Track Recording

To start a participant track recording, you will have to call `/v2/recordings/participant/track/start` API with following body parameters.

- `roomId`: RoomId for which the participant track recording is to be started
- `participantId`: participantId of the participant to be recorder.
- `kind`: The kind of tracks you want to record.
  - You can pass following values: _`audio`_ | _`video`_ | _`screen_audio`_ | _`screen_video`_
- `fileFormat`: Currently only `webm` is supported as file format. We will add the support for other formats in future.
- `webhookUrl`: The webhook URL where you would like to get the status updates of the recording. To learn more about webhooks refer [here](#participant-track-recording-starting).
- `bucketDirPath`: If you are using your own storage, you can provide the directory path where you want to store the recording. To configure the storage please [refere this quide](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config).

The usual recording path would look like `${sessionId}/${participantId}/${kind}/${filename}`.



**Kotlin:**

```kotlin
import org.json.JSONObject
import java.io.OutputStream
import java.net.HttpURLConnection
import java.net.URL
import java.io.IOException

fun StartTrackRecording() {
val roomId = "<YOUR ROOM ID>"
val participantId = "<PARTICIPANT ID>"
val kind = "<YOUR STREAM KIND>"
val fileFormat = "<YOUR FILE FORMAT>"
val bucketDirPath = "<YOUR CLOUD STORAGE BUCKET PATH>"
val webhookUrl = "<YOUR WEBHOOK URL>"

try {
    val url = URL("https://api.videosdk.live/v2/recordings/participant/track/start")
    val conn = url.openConnection() as HttpURLConnection
    conn.requestMethod = "POST"
    conn.setRequestProperty("Authorization", "$YOUR_TOKEN")
    conn.setRequestProperty("Content-Type", "application/json")
    conn.doOutput = true

    val jsonBody = JSONObject()
    jsonBody.put("roomId", roomId)
    jsonBody.put("participantId", participantId)
    jsonBody.put("kind", kind)
    jsonBody.put("fileFormat", fileFormat)
    jsonBody.put("bucketDirPath", bucketDirPath)
    jsonBody.put("webhookUrl", webhookUrl)

    conn.outputStream.use { os: OutputStream ->
        val input = json.toString().toByteArray(Charsets.UTF_8)
        os.write(input, 0, input.size)
    }

    val responseCode = conn.responseCode
    if (responseCode == HttpURLConnection.HTTP_OK) {
        println("Track Recording started successfully.")
    } else {
        println("Failed to start track recording.")
    }
} catch (e: Exception) {
    e.printStackTrace()
}
}



```

---

**Java:**

```java
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import org.json.JSONObject;

public void StartTrackRecording() {
String roomId = "<YOUR ROOM ID>";
String participantId = "<PARTICIPANT ID>";
String kind = "<YOUR STREAM KIND>";
String fileFormat = "<YOUR FILE FORMAT>";
String bucketDirPath = "<YOUR CLOUD STORAGE BUCKET PATH>";
String webhookUrl = "<YOUR WEBHOOK URL>";

try {
    URL url = new URL("https://api.videosdk.live/v2/recordings/participant/track/start");
    HttpURLConnection conn = (HttpURLConnection) url.openConnection();
    conn.setRequestMethod("POST");
    conn.setRequestProperty("Authorization", "$YOUR_TOKEN");
    conn.setRequestProperty("Content-Type", "application/json");
    conn.setDoOutput(true);

    JSONObject jsonBody = new JSONObject();
    jsonBody.put("roomId", roomId);
    jsonBody.put("participantId", participantId);
    jsonBody.put("kind", kind);
    jsonBody.put("fileFormat", fileFormat);
    jsonBody.put("bucketDirPath", bucketDirPath);
    jsonBody.put("webhookUrl", webhookUrl);

    try (OutputStream os = conn.getOutputStream()) {
    byte[] input = json.toString().getBytes("utf-8");
    os.write(input, 0, input.length);
    }

    int responseCode = conn.getResponseCode();
    if (responseCode == HttpURLConnection.HTTP_OK) {
        System.out.println("Track Recording started successfully.");
    } else {
        System.out.println("Failed to start track recording.");
    }
} catch (Exception e) {
    e.printStackTrace();
}
}

```

## Stop Participant Track Recording

To stop a participant track recording, you will have to call `/v2/recordings/participant/track/stop` API with following body parameters.

- `roomId`: RoomId for which the participant track recording is to be stopped
- `participantId`: participantId for which the recording is to be stopped.
- `kind`: The kind of track recording you want to stop for the given participant.
  - You can pass following values: _`audio`_ | _`video`_ | _`screen_audio`_ | _`screen_video`_

**Kotlin:**

```kotlin
import org.json.JSONObject
import java.io.OutputStream
import java.net.HttpURLConnection
import java.net.URL

fun StopTrackRecording() {
val roomId = "<YOUR ROOM ID>"
val participantId = "<PARTICIPANT ID>"
val kind = "<YOUR STREAM KIND>"

try {
    val url = URL("https://api.videosdk.live/v2/recordings/participant/track/stop")
    val conn = url.openConnection() as HttpURLConnection
    conn.requestMethod = "POST"
    conn.setRequestProperty("Authorization", "$YOUR_TOKEN")
    conn.setRequestProperty("Content-Type", "application/json")
    conn.doOutput = true

    val jsonBody = JSONObject()
    jsonBody.put("roomId", roomId)
    jsonBody.put("participantId", participantId)
    jsonBody.put("kind", kind)

    conn.outputStream.use { os: OutputStream ->
        val input = json.toString().toByteArray(Charsets.UTF_8)
        os.write(input, 0, input.size)
    }

    val responseCode = conn.responseCode
    if (responseCode == HttpURLConnection.HTTP_OK) {
        println("Track Recording stopped successfully.")
    } else {
        println("Failed to stop track recording.")
    }
} catch (e: Exception) {
    e.printStackTrace()
}
}

```

---

**Java:**

```java
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import org.json.JSONObject;

public void StopTrackRecording() {
String roomId = "<YOUR ROOM ID>";
String participantId = "<PARTICIPANT ID>";
String kind = "<YOUR STREAM KIND>";


try {
    URL url = new URL("https://api.videosdk.live/v2/recordings/participant/track/stop");
    HttpURLConnection conn = (HttpURLConnection) url.openConnection();
    conn.setRequestMethod("POST");
    conn.setRequestProperty("Authorization", "$YOUR_TOKEN");
    conn.setRequestProperty("Content-Type", "application/json");
    conn.setDoOutput(true);

    JSONObject jsonBody = new JSONObject();
    jsonBody.put("roomId", roomId);
    jsonBody.put("participantId", participantId);
    jsonBody.put("kind", kind);

    try (OutputStream os = conn.getOutputStream()) {
    byte[] input = json.toString().getBytes("utf-8");
    os.write(input, 0, input.length);
    }

    int responseCode = conn.getResponseCode();
    if (responseCode == HttpURLConnection.HTTP_OK) {
        System.out.println("Track Recording stopped successfully.");
    } else {
        System.out.println("Failed to stop track recording.");
    }
} catch (Exception e) {
    e.printStackTrace();
}
}

```

## Webhook associated with Participant Track Recording

### participant-track-recording-starting

- A "Participant Track Recording Starting" webhook is triggered when the track recording process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-started

- Participant Track Recording started webhook will be received when successfully track recording is started in meeting

###### Example

```javascript
{
    "webhookType": "participant-track-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopping

- A "Participant Track Recording Stopping" webhook is triggered when the track recording end process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopped

- Participant Track Recording stopped webhook will be received when track recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-track-recording-failed

- A "Participant Track Recording Failed" webhook is generated when the track recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Track Recording API](/api-reference/realtime-communication/start-track-recording)
- [Stop Track Recording API](/api-reference/realtime-communication/stop-track-recording)



---

### Storage Configuration

While recording your meetings, you have the flexibility to store them either on VideoSDK's storage or configure your own storage solution such as **`AWS S3 Storage, Azure Blob or GCP Cloud Storage`**. To set up your own storage, you can navigate to the [API section](https://app.videosdk.live/api-keys) in the VideoSDK Dashboard.

- This feature allows you to configure storage provider for your meeting recordings.

- You can configure multiple storage provider with multiple API Keys.

- Currently, we support `AWS S3`, `Azure Blob` and `GCP Cloud Storage`. We will add support for other storage provider soon !!

## Prerequisites

- An active [VideoSDK Developer Account](https://app.videosdk.live)
- `Aws S3`, `Azure Blob Storage` or `GCP Cloud Storage` Credentials

## How to setup ?

### Step 1 : Select Api Key

<div style={{textAlign: 'center'}}>

![Dashboard](/img/tutorial/dashboard/api-key-dashboard.png)

</div>

- Go to [VideoSDK Dashboard](https://app.videosdk.live/api-keys).
- Select API Key for which, you want to set storage configuration.
- Then click on `Storage Config` Icon in Actions.

### Step 2 : Choose Cloud Storage Provider

![Dashboard](/img/tutorial/dashboard/storage-config.png)

- As you can see in the image, there are 3 Cloud Storage Provider (`Aws`, `Azure`, `GCP`).
- You can select a Cloud Storage Provider as per your requirements.

### Step 3 : Configure Bucket or Container

<h4> For Aws S3 Storage </h4>

![Aws S3](/img/tutorial/dashboard/s3.png)

- You will need AWS S3 Bucket. [Learn to create S3 Bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html).

- As you can see in the image, you will need enter `accessKeyId`, `secretAccessKey`, `region`, `bucket`, and `ACL` to setup for Aws S3 Storage.

- Click on `Save` button.

<hr />

<h4> For Azure Blob Storage: </h4>

![Azure Blob](/img/tutorial/dashboard/blob.png)

- You will need Azure Blob Container. [Learn to create Blob Container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal#create-a-container).

- As you can see in the image, you will need to enter `connectionString` and `containerName` to setup for Azure Blob.

- Click on `Save` button.

<hr />

<h4> For Google Cloud Storage: </h4>

<img src="/img/tutorial/dashboard/gcp.png" alt="GCP Cloud Storage" width="436" height="632"/>

1. You will need Google Cloud Storage Bucket. [Learn to create Google Cloud Storage Bucket](https://cloud.google.com/storage/docs/creating-buckets).

2. After creation, click on the <b> &#xFE19; </b>button in the upper right corner and select **`Project settings`**.

3. Under **`IAM and Admin`**, select **`Service Accounts`**. In the service account list, click on the <b> &#xFE19; </b> button for the account just added or created before, and select **`Manage keys`**.

4. Click **`ADD KEY > Create new key`**. Select **`JSON`** in the pop-up box and click **`CREATE`**. A json file is downloaded with the name format `projectId-xxxxxxxx.json`.

5. Open the downloaded json file, which looks like the following example:

```
{
  "type": "service_account",
  "project_id": "videosdk-12345",
  "private_key_id": "yourprivateidkeyyourprivateidkeyyourprivateidkey",
  "private_key": "-----BEGIN PRIVATE KEY-----\nThisisYourPrivateKeyThisisYourPrivateKeyThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\n-----END PRIVATE KEY-----\n",
  "client_email": "xxxx-xxxx@videosdk-12345.iam.gserviceaccount.com",
  "client_id": "123456789012345678901",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/videosdk%40videosdk-404307.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}
```

- As you can see in the image, you will need to enter `Project Id`, `Client Email`, `Bucket`, `Private Key` to setup for Google Cloud Storage Bucket. You can retrieve these details from the json file.

- Click on `Save` button.

### Step 4 : Test

- It's time to test !!
- [Create Room](https://docs.videosdk.live/api-reference/realtime-communication/create-room) with token generated with the API Key, you have configured for.
- Start meeting with the roomId created and Start Recording !!
- Then, you can see that recording will be available in your Bucket or Container.

:::note

- Only a single Recording Storage Config can be possible for a particular Api Key at a time.
- In order to add new Recording Configuration, first you need to delete current configuration.

:::


---

# Recording in Live Stream - Android

This guide will provide an overview of how to implement start and stop Recording during a live stream.

### `startRecording()`

`startRecording()` can be used to start a recording of the meeting which can be accessed from the `Meeting` class. This method accepts four parameters:

- `1. webhookUrl`: This would the webhook URL where you would like to listen to event happening for the recording like starting and stopping of recording. It will be triggered when the recording is completed and stored into server. Read more about webhooks [here](https://en.wikipedia.org/wiki/Webhook)

- `2. awsDirPath`: This parameter accepts the path for the your S3 bucket where you want to store recordings to. To allow us to store recording in your S3 bucket, you will need to fill this form by providing the required values. ([VideoSDK Cloud (AWS S3, Azure Blob or GCP ) Integration](/android/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config))

- `3. config`: This parameter will define how the meeting should be recorded.

- `4. transcription`: This parameter lets you start post transcription for the recording.

:::note

If you don't have a value for `webhookUrl`,`awsDirPath` or `config`, you should pass `null` in place of the missing value. If you pass `null` in `awsDirPath` parameter then by default recordings will be store on the VideoSDK's storage.
:::



**Kotlin:**

```js
val config = JSONObject()

//highlight-next-line
// Layout Configuration
val layout = JSONObject()
JsonUtils.jsonPut(layout, "type", "GRID") // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
JsonUtils.jsonPut(layout, "priority", "SPEAKER") // "PIN", Default : "SPEAKER"
JsonUtils.jsonPut(layout, "gridSize", 4) // MAX : 4
JsonUtils.jsonPut(config, "layout", layout)

//highlight-next-line
// Theme of recording
JsonUtils.jsonPut(config, "theme", "DARK") //  "LIGHT" | "DEFAULT"

//highlight-next-line
// `mode` is used to either record video & audio both or only audio.
JsonUtils.jsonPut(config, "mode", "video-and-audio") // "audio", Default : "video-and-audio"

//highlight-next-line
// Quality of recording and is only applicable to `video-and-audio` type mode.
JsonUtils.jsonPut(config, "quality", "high") /* Default : "med"
   "low" (SD Recording) | "med" (HD Recording) | "high" (FHD Recording) */

//highlight-start
// This mode refers to orientation of recording.
// landscape : Record the meeting in horizontally
// portrait : Record the meeting in vertically (Best for mobile view)
//highlight-end
JsonUtils.jsonPut(config, "orientation", "portrait") // "landscape",  Default : "landscape"

//highlight-next-line
// Post Transcription Configuration
val prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
val summaryConfig = SummaryConfig(true, prompt)
val modelId = "raman_v1"
val transcription = PostTranscriptionConfig(true, summaryConfig, modelId)

meeting.startRecording(null, null, config, transcription)
```

---

**Java:**

```js
JSONObject config = new JSONObject();

//highlight-next-line
// Layout Configuration
JSONObject layout = new JSONObject();
JsonUtils.jsonPut(layout, "type", "GRID"); // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
JsonUtils.jsonPut(layout, "priority", "SPEAKER");  // "PIN", Default : "SPEAKER"
JsonUtils.jsonPut(layout, "gridSize", 4); // MAX : 4
JsonUtils.jsonPut(config, "layout", layout);

//highlight-next-line
// Theme of recording
JsonUtils.jsonPut(config, "theme", "DARK"); //  "LIGHT" | "DEFAULT"

//highlight-next-line
// `mode` is used to either record video & audio both or only audio.
JsonUtils.jsonPut(config, "mode", "video-and-audio"); // "audio", Default : "video-and-audio"

//highlight-next-line
// Quality of recording and is only applicable to `video-and-audio` type mode.
JsonUtils.jsonPut(config, "quality", "high"); /* Default : "med"
   "low" (SD Recording) | "med" (HD Recording) | "high" (FHD Recording) */

//highlight-start
// This mode refers to orientation of recording.
// landscape : Record the meeting in horizontally
// portrait : Record the meeting in vertically (Best for mobile view)
//highlight-end
JsonUtils.jsonPut(config, "orientation", "portrait"); // "landscape",  Default : "landscape"

//highlight-next-line
// Post Transcription Configuration
String prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary";
SummaryConfig summaryConfig = new SummaryConfig(true, prompt);
String modelId = "raman_v1";
PostTranscriptionConfig transcription = new PostTranscriptionConfig(true, summaryConfig, modelId);

meeting.startRecording(null, null, config, transcription);
```

### `stopRecording()`

- `stopRecording()` is used to stop the meeting recording which can be accessed from the `Meeting` class.

#### Example

**Kotlin:**

```js
// keep track of recording
val recording = false

findViewById<View>(R.id.btnRecording).setOnClickListener { view: View? ->
if (!recording) {
  //highlight-start
  val config = JSONObject()
  val layout = JSONObject()
  JsonUtils.jsonPut(layout, "type", "GRID")
  JsonUtils.jsonPut(layout, "priority", "SPEAKER")
  JsonUtils.jsonPut(layout, "gridSize", 4)
  JsonUtils.jsonPut(config, "layout", layout)
  JsonUtils.jsonPut(config, "theme", "DARK")
  JsonUtils.jsonPut(config, "mode", "video-and-audio")
  JsonUtils.jsonPut(config, "quality", "high")
  JsonUtils.jsonPut(config, "orientation", "portrait")
  //highlight-end

  //highlight-next-line
  // Post Transcription Configuration
  val prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
  val summaryConfig = SummaryConfig(true, prompt)
  val modelId = "raman_v1"
  val transcription = PostTranscriptionConfig(true, summaryConfig, modelId)

  // Start Recording
  // If you don't have a `webhookUrl` or `awsDirPath`, you should pass null.
  // If you don't want to enable transcription, you can pass null as parameter.
  //highlight-next-line
  meeting!!.startRecording("YOUR WEB HOOK URL", "AWS Directory Path", config, transcription)
} else {
  // Stop Recording
  //highlight-next-line
  meeting!!.stopRecording()
}
}
```

---

**Java:**

```js
// keep track of recording
boolean recording = false;

findViewById(R.id.btnRecording).setOnClickListener(view -> {
if (!recording) {
  //highlight-start
  JSONObject config = new JSONObject();
  JSONObject layout = new JSONObject();
  JsonUtils.jsonPut(layout, "type", "GRID");
  JsonUtils.jsonPut(layout, "priority", "SPEAKER");
  JsonUtils.jsonPut(layout, "gridSize", 4);
  JsonUtils.jsonPut(config, "layout", layout);
  JsonUtils.jsonPut(config, "theme", "DARK");
  JsonUtils.jsonPut(config, "mode", "video-and-audio");
  JsonUtils.jsonPut(config, "quality", "high");
  JsonUtils.jsonPut(config, "orientation", "portrait");
  //highlight-end

  //highlight-next-line
  // Post Transcription Configuration
  String prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary";
  SummaryConfig summaryConfig = new SummaryConfig(true, prompt);
  String modelId = "raman_v1";
  PostTranscriptionConfig transcription = new PostTranscriptionConfig(true, summaryConfig, modelId);

  // Start Recording
  // If you don't have a `webhookUrl` or `awsDirPath`, you should pass null.
  // If you don't want to enable transcription, you can pass null as parameter.
  //highlight-next-line
  meeting.startRecording("YOUR WEB HOOK URL", "AWS Directory Path", config, transcription);
} else {
  // Stop Recording
  //highlight-next-line
  meeting.stopRecording();
}
});
```

:::important

To initiate automatic recording at the beginning of a `session`, simply provide the `autoStartConfig` feature `recording` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.

:::

### API Reference

The API references for all the methods utilised in this guide are provided below.

- [startRecording()](/android/api/sdk-reference/meeting-class/methods#startrecording)
- [stopRecording()](/android/api/sdk-reference/meeting-class/methods#stoprecording)
- [onRecordingStateChanged](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onrecordingstatechanged)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

# Webhooks and Events - Android

### Event associated with Recording

- **onRecordingStateChanged** - Whenever recording state changes, then `onRecordingStateChanged` event will trigger.



**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onRecordingStateChanged(recordingState: String) {
when (recordingState) {
    "RECORDING_STARTING" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is starting")
    }
    "RECORDING_STARTED" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is started")
    }
    "RECORDING_STOPPING" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is stopping")
    }
    "RECORDING_STOPPED" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is stopped")
    }
}
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  //highlight-next-line
  liveStream!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onRecordingStateChanged(String recordingState) {
  switch (recordingState) {
      case "RECORDING_STARTING":
          Log.d("onRecordingStateChanged", "Meeting recording is starting");
          break;
      case "RECORDING_STARTED":
          Log.d("onRecordingStateChanged", "Meeting recording is started");
          break;
      case "RECORDING_STOPPING":
          Log.d("onRecordingStateChanged", "Meeting recording is stopping");
          break;
      case "RECORDING_STOPPED":
          Log.d("onRecordingStateChanged", "Meeting recording is stopped");
          break;
  }
  }
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  //highlight-next-line
  liveStream.addEventListener(meetingEventListener);
}
```

## Webhook associated with Recording

### recording-starting

- A "Recording Starting" webhook is triggered when the recording process for a meeting is initiated.

###### Example

```javascript
{
    "webhookType": "recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-started

- Recording started webhook will be received when successfully recording is started in meeting

###### Example

```javascript
{
    "webhookType": "recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopping

- A "Recording Stopping" webhook is triggered when the recording end process for a meeting is initiated.

###### Example

```javascript
{
    "webhookType": "recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopped

- Recording stopped webhook will be received when recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
        "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",

    },
}
```

---

### recording-failed

- A "Recording Failed" webhook is generated when the recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```


---

# Relay Media(PK Host) - Android

## Overview

The Relay Media feature enables hosts to relay their media (audio, video, screen share) to one or multiple other live streams. This creates cross-stream interactions similar to "PK battles" or collaborative broadcasts.

This feature allows audiences in one live stream to view and hear hosts from another live stream without changing rooms, creating powerful interactive experiences.

## Key Concepts

- **Media Relay**: The process of transmitting a host's audio/video from one live stream to another
- **Source Meeting**: The original live stream where the host is broadcasting
- **Destination Meeting**: The target live stream(s) where the host's media will be relayed
- **Relay Kinds**: The types of media that can be relayed (video, audio, screen share, etc.)

## Sequence Diagram



## Implementation Guide

### 1. Requesting Media Relay

### `requestMediaRelay()`

**Parameters:**

- `destinationMeetingId` (`String`, **required**) – ID of the target meeting 
- `token` (`String`) – Authentication token for the destination meeting.  
  If you pass `null`, the SDK will use the existing authentication token.
- `kinds` (`Array<String>`) – Media types to relay. If `null`, all media types will be relayed. Options:
  - `"video"` – Camera video
  - `"audio"` – Microphone audio
  - `"share"` – Screen share video



**Kotlin:**

```js
import android.os.Bundle
import android.widget.Button
import androidx.appcompat.app.AppCompatActivity
import live.videosdk.rtc.android.Meeting

class LiveStreamActivity : AppCompatActivity() {
//Initialize  meeting
liveStream = VideoSDK.initMeeting(... )
//...
val switchButton: Button = findViewById(R.id.switchLiveStreamButton)
switchButton.setOnClickListener {
   requestMediaRelayToAnotherMeeting()
}

fun requestMediaRelayToAnotherMeeting() {
val liveStreamId = "liveStream-B"
// Secure token to authenticate the relay meeting
val relayToken = "secureToken123"
// Specify the media types to relay
val mediaTypes = listOf("video", "audio")
// Request media relay
liveStream.requestMediaRelay(liveStreamId, relayToken, mediaTypes)
}
}
```

---

**Java:**

```js

import android.os.Bundle;
import android.view.View;
import android.widget.Button;
import androidx.appcompat.app.AppCompatActivity;
import live.videosdk.rtc.android.Meeting;

public class LiveStreamActivity extends AppCompatActivity {
// Initialize meeting
Meeting liveStream = VideoSDK.initMeeting( ...);
//...
Button switchButton = findViewById(R.id.switchLiveStreamButton);
switchButton.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View v) {
        if (liveStream != null) {
            requestMediaRelayToAnotherMeeting()
        }
    }
});

public void requestMediaRelayToAnotherMeeting() {
// Meeting ID to which you want to relay
String liveStreamId = "liveStream-B";
// Secure token to authenticate the relay meeting
String relayToken = "secureToken123";
// Specify the media types to relay
String[] mediaTypes = new String[]{"video", "audio"};
// Request media relay
liveStream.requestMediaRelay(liveStreamId, relayToken, Arrays.asList(mediaTypes));
}
}
```

### 2. Handling Relay Requests (Destination Meeting)

In the destination liveStream, hosts (participants with `SEND_AND_RECV` mode) will receive relay requests:

**Kotlin:**

```js
import com.google.android.material.dialog.MaterialAlertDialogBuilder
import live.videosdk.rtc.android.Meeting
import live.videosdk.rtc.android.listeners.MeetingEventListener

class LiveStreamView() {
init {
    // initialize initialize
    liveStream = VideoSDK.initMeeting(... )
    // ...
    // Set up media relay request listener
    liveStream.addEventListener(object : MeetingEventListener() {
    override fun onMediaRelayRequestReceived(participantId: String, liveStreamId: String, listener:RelayRequestListener) {
        showRelayRequest(participantId, liveStreamId, listener)
    }
    })
}

private fun showRelayRequest(participantId: String,liveStreamId: String,listener: RelayRequestListener) {
    MaterialAlertDialogBuilder(this@MainActivity)
        .setTitle("Entry Request : $participantId")
        .setMessage("$liveStreamId is requesting to join")
        .setPositiveButton("Approve") { dialog, _ -> listener.accept() }
        .setNegativeButton("Deny") { dialog, _ -> listener.reject() }
        .setCancelable(false)
        .show()
}

}
```

---

**Java:**

```js
import android.app.AlertDialog;

import live.videosdk.rtc.android.Meeting;
import live.videosdk.rtc.android.listeners.MeetingEventListener;

public class LiveStreamView {
//initialize initialize
Meeting liveStream = VideoSDK.initMeeting( ...);
//...

  // Set up media relay request listener
  liveStream.addEventListener(new MeetingEventListener() {
    @Override
    public void onMediaRelayRequestReceived(String participantId, String liveStreamId, RelayRequestListener listener) {
        showRelayRequest(participantId, liveStreamId, listener);
    }
  });

private void showRelayRequest(String participantId, String liveStreamId, RelayRequestListener listener) {
    new MaterialAlertDialogBuilder(MainActivity.this)
            .setTitle("Entry Request :"+ participantId)
            .setMessage(liveStreamId + " is requesting to join")
            .setPositiveButton("Approve", (dialog, which) -> listener.accept())
            .setNegativeButton("Deny", (dialog, which) -> listener.reject())
            .setCancelable(false)
            .show();
}
}
```

### 3. Handling Request Responses (Source Meeting)

In the source liveStream, track the response to your relay requests:

**Kotlin:**

```js
import android.content.Context
import android.widget.Toast
import live.videosdk.rtc.android.Meeting
import live.videosdk.rtc.android.listeners.MeetingEventListener

class LiveStreamView() {
//initialize initialize
liveStream = VideoSDK.initMeeting(... )

init {
    // Set up media relay request response listener
    liveStream.addEventListener(object : MeetingEventListener() {
        override fun onMediaRelayRequestResponse(participantId: String, decision: String) {
            handleMediaRelayResponse(participantId, decision)
        }
    })
}

// Handling the media relay request response
private fun handleMediaRelayResponse(participantId: String, decision: String) {
    if (decision == "accepted") {
        // Relay request accepted by participant
        println("Relay request accepted by $participantId")
    } else {
        // Relay request rejected by participant
        println("Relay request rejected by $participantId")
    }
}
}
```

---

**Java:**

```js
import android.content.Context;
import android.widget.Toast;
import live.videosdk.rtc.android.Meeting;
import live.videosdk.rtc.android.listeners.MeetingEventListener;

public class LiveStreamView {

// initialize meeting
Meeting liveStream = VideoSDK.initMeeting( ...);
// ...
// Set up media relay request response listener
liveStream.addEventListener(new MeetingEventListener() {
    @Override
    public void onMediaRelayRequestResponse(String participantId, String decision) {
        handleMediaRelayResponse(participantId, decision);
    }
});
// Handling the media relay request response
private void handleMediaRelayResponse(String participantId, String decision) {
    if ("accepted".equals(decision)) {
        // Relay request accepted by participant
        System.out.println("Relay request accepted by " + participantId);
    } else {
        // Relay request rejected by participant
        System.out.println("Relay request rejected by " + participantId);
    }
}
}
```

### 4. Tracking Active Relays

When a relay successfully starts:

**Kotlin:**

```js
import android.util.Log
import live.videosdk.rtc.android.Meeting
import live.videosdk.rtc.android.listeners.MeetingEventListener

class LiveStreamView() {
// initialize meeting
liveStream = VideoSDK.initMeeting(... )
// ...
companion object {
    private const val TAG = "LiveStreamView"
}
init {
    // Set up media relay started listener
    liveStream.addEventListener(object : MeetingEventListener() {
        override fun onMediaRelayStarted(liveStreamId: String) {
            handleMediaRelayStarted(liveStreamId)
        }
    })
}
// Called when media relay starts
private fun handleMediaRelayStarted(liveStreamId: String) {
    Log.d(TAG, "Media relay started to $liveStreamId")
    // You can update UI or handle logic here
}
}
```

---

**Java:**

```js
import android.util.Log;
import live.videosdk.rtc.android.Meeting;
import live.videosdk.rtc.android.listeners.MeetingEventListener;

public class LiveStreamView {
// initialize meeting
   Meeting liveStream = VideoSDK.initMeeting( ...);
// ...
// Set up media relay started listener
liveStream.addEventListener(new MeetingEventListener() {
    @Override
    public void onMediaRelayStarted(String liveStreamId) {
        handleMediaRelayStarted(liveStreamId);
    }
});
// Called when media relay starts
private void handleMediaRelayStarted(String liveStreamId) {
    Log.d(TAG, "Media relay started to " + liveStreamId);
    //...
}
}
```

### 5. Stopping Media Relay

To stop an ongoing relay:

### `stopMediaRelay()`

**Parameters:**

- `liveStreamId` (string): ID of the liveStream where the relay should stop

**Kotlin:**

```js
import android.os.Bundle
import android.widget.Button
import androidx.appcompat.app.AppCompatActivity
import live.videosdk.rtc.android.Meeting

class LiveStreamActivity : AppCompatActivity() {
// Initialize meeting 
liveStream = VideoSDK.initMeeting(... )
//..
val stopRelayButton = findViewById<Button>(R.id.btnStopRelay)

stopRelayButton.setOnClickListener {
    handleStopMediaRelay()
}

// Called to stop media relay
private fun handleStopMediaRelay() {
    val liveStreamId = "liveStream-B"
    liveStream.stopMediaRelay(liveStreamId)
}
}
```

---

**Java:**

```js
import android.view.View;
import android.widget.Button;
import live.videosdk.rtc.android.Meeting;

public class LiveStreamView {

private Meeting meeting;
// initialize meeting
Meeting liveStream = VideoSDK.initMeeting( ...);
// ...

// Set click listener for the Stop Media Relay button
stopRelayButton.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View v) {
        handleStopMediaRelay();
    }
});

// Called to stop media relay
private void handleStopMediaRelay() {
    String liveStreamId = "liveStream-B";
    liveStream.stopMediaRelay(liveStreamId);
}
}
```

### 6. Handling Relay Stop Events

When a relay stops for any reason:

**Kotlin:**

```js
import android.util.Log
import live.videosdk.rtc.android.Meeting
import live.videosdk.rtc.android.listeners.MeetingEventListener

class LiveStreamView() {
// initialize meeting
val liveStream = VideoSDK.initMeeting(... )
// ...
companion object {
    private const val TAG = "LiveStreamView"
}

fun setupListeners() {
    liveStream.addEventListener(object : MeetingEventListener() {
        override fun onMediaRelayStopped(liveStreamId: String, reason: String) {
            handleMediaRelayStopped(liveStreamId, reason)
        }
    })
}

private fun handleMediaRelayStopped(liveStreamId: String, reason: String) {
    Log.d(TAG, "Relay to $liveStreamId stopped. Reason: $reason")
    // Update UI based on stop reason
    when (reason) {
        "user_stopped" -> showMessage("You stopped relaying to $liveStreamId")
        "connection_lost" -> showMessage("Relay to $liveStreamId ended due to connection issues")
        else -> showMessage("Relay to $liveStreamId ended: $reason")
    }
}

private fun showMessage(message: String) {
    Log.i(TAG, message)
}
}
```

---

**Java:**

```js
import android.util.Log;
import live.videosdk.rtc.android.Meeting;
import live.videosdk.rtc.android.listeners.MeetingEventListener;

public class LiveStreamView {

private static final String TAG = "LiveStreamView";
// initialize meeting
   Meeting liveStream = VideoSDK.initMeeting( ...);
// ...
public void setupListeners() {
    liveStream.addEventListener(new MeetingEventListener() {
        @Override
        public void onMediaRelayStopped(String liveStreamId, String reason) {
            handleMediaRelayStopped(liveStreamId, reason);
        }
    });
}

private void handleMediaRelayStopped(String liveStreamId, String reason) {
    Log.d(TAG, "Relay to " + liveStreamId + " stopped. Reason: " + reason);
    // Update UI based on stop reason
    switch (reason) {
        case "user_stopped":
            showMessage("You stopped relaying to " + liveStreamId);
            break;
        case "connection_lost":
            showMessage("Relay to " + liveStreamId + " ended due to connection issues");
            break;
        default:
            showMessage("Relay to " + liveStreamId + " ended: " + reason);
    }
}

private void showMessage(String message) {
    Log.i(TAG, message);
}
}
```

### 7. Handling Relay Errors

To handle errors that may occur during relay:

**Kotlin:**

```js
import android.util.Log
import live.videosdk.rtc.android.Meeting
import live.videosdk.rtc.android.listeners.MeetingEventListener

class LiveStreamView() {
// initialize meeting
val liveStream = VideoSDK.initMeeting(... )
// ...
companion object {
    private const val TAG = "LiveStreamView"
}

private fun setupListeners() {
    liveStream.addEventListener(object : MeetingEventListener() {
        override fun onMediaRelayError(liveStreamId: String, error: String) {
            handleMediaRelayError(liveStreamId, error)
        }
    })
}

private fun handleMediaRelayError(liveStreamId: String, error: String) {
    Log.e(TAG, "Relay error to $liveStreamId: $error")
}
}
```

---

**Java:**

```js
import android.util.Log;
import live.videosdk.rtc.android.Meeting;
import live.videosdk.rtc.android.listeners.MeetingEventListener;

public class LiveStreamView {

// initialize meeting
  Meeting liveStream = VideoSDK.initMeeting( ...);

private static final String TAG = "LiveStreamView";

private void setupListeners() {
    liveStream.addEventListener(new MeetingEventListener() {
        @Override
        public void onMediaRelayError(String liveStreamId, String error) {
            handleMediaRelayError(liveStreamId, error);
        }
    });
}

private void handleMediaRelayError(String liveStreamId, String error) {
    Log.e(TAG, "Relay error to " + liveStreamId + ": " + error);
}
}
```

## Use Cases

1.  **Guest Appearances:** Allow popular hosts to make guest appearances in other streams without leaving their audience
2.  **Cross-Stream Competitions:** Create "battles" or competitions between hosts in different streams
3.  **Multi-Location Broadcasting:** Connect hosts from different physical locations into a shared experience
4.  **Expert Commentary:** Bring in subject matter experts to comment on events in another stream

## Troubleshooting

### Common Issues

1.  **Relay Request Not Received**

    - Verify both meetings are active
    - Check that destination liveStream ID is correct
    - Ensure the token has proper permissions

2.  **Media Not Visible After Acceptance**

    - Verify network connectivity
    - Check that appropriate media kinds were specified
    - Ensure the host has enabled their camera/microphone

3.  **Unexpected Relay Termination**

    - Check for network connectivity issues
    - Verify that both meetings remain active
    - Look for error events with specific reasons

## API Reference

- [requestMediaRelay](/android/api/sdk-reference/meeting-class/methods#requestmediarelay)
- [stopMediaRelay](/android/api/sdk-reference/meeting-class/methods#stopmediarelay)
- [onMediaRelayRequestReceived](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmediarelayrequestreceived)
- [onMediaRelayRequestResponse](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmediarelayrequestreceived)
- [onMediaRelayStarted](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmediarelaystarted)
- [onMediaRelayStopped](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmediarelaystopped)
- [onMediaRelayError](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmediarelayerror)



---

# Release Notes - Android




---

---
title: RTMP Livestream - Video SDK Docs
hide_title: false
hide_table_of_contents: false
description: RTMP Livestream features quick integrate in Javascript, React JS, Android, IOS, React Native, Flutter with Video SDK to add live video & audio conferencing to your applications.
sidebar_label: RTMP Livestream
pagination_label: RTMP Livestream
keywords:
  - Start Livestream meeting
  - Stop Livestream meeting
  - audio calling
  - video calling
  - real-time communication
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: rtmp-livestream
--- 

# RTMP Livestream - Android

RTMP is a popular protocol for live streaming video content from a VideoSDK to platforms such as YouTube, Twitch, Facebook, and others.

By providing the platform-specific stream key and stream URL, the VideoSDK can connect to the platform's RTMP server and transmit the live video stream.

VideoSDK allows you to livestream your meeting to platform which support RTMP ingestion just by providing the platform-specific stream key and stream URL, we can connect to the platform's RTMP server and transmit the live video stream.

VideoSDK also allows you to configure the livestream layouts in numerous ways like by simply setting different prebuilt layouts in the configuration or by providing your own custom template to do the livestream according to your layout choice.

This guide will provide an overview of how to implement start and stop RTMP Livestreaming.

### `startLivestream()`

`startLivestream()` method, accessible from the Meeting class, is used to initiate the RTMP livestream. This method accepts the following two parameters:

- `1. outputs`: This parameter accepts a list of `LivestreamOutput` objects which contains the RTMP `url` and `streamKey` of the platforms you want to start the livestream.

- `2. config`: This parameter will define how the livestream layout should look like. You can pass `null` for default layout.



**Kotlin:**

```js
val config = JSONObject()

//highlight-next-line
// Layout Configuration
val layout = JSONObject()
JsonUtils.jsonPut(layout, "type", "GRID") // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
JsonUtils.jsonPut(layout, "priority", "SPEAKER") // "PIN", Default : "SPEAKER"
JsonUtils.jsonPut(layout, "gridSize", 4) // MAX : 4
JsonUtils.jsonPut(config, "layout", layout)

//highlight-next-line
// Theme of livestream layout
JsonUtils.jsonPut(config, "theme", "DARK") //  "LIGHT" | "DEFAULT"

val outputs: MutableList<LivestreamOutput> = ArrayList()
outputs.add(LivestreamOutput(RTMP_URL, RTMP_STREAM_KEY))

liveStream!!.startLivestream(outputs,config)
```

---

**Java:**

```js
JSONObject config = new JSONObject();

//highlight-next-line
// Layout Configuration
JSONObject layout = new JSONObject();
JsonUtils.jsonPut(layout, "type", "GRID"); // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
JsonUtils.jsonPut(layout, "priority", "SPEAKER");  // "PIN", Default : "SPEAKER"
JsonUtils.jsonPut(layout, "gridSize", 4); // MAX : 4
JsonUtils.jsonPut(config, "layout", layout);

//highlight-next-line
// Theme of livestream layout
JsonUtils.jsonPut(config, "theme", "DARK"); //  "LIGHT" | "DEFAULT"

List<LivestreamOutput> outputs = new ArrayList<>();
outputs.add(new LivestreamOutput(RTMP_URL, RTMP_STREAM_KEY));

liveStream.startLivestream(outputs,config);
```

### `stopLivestream()`

- `stopLivestream()` is used to stop the meeting livestream which can be accessed from the `Meeting` class.

#### Example

**Kotlin:**

```js
// keep track of livestream status
val liveStream = false

findViewById<View>(R.id.btnLiveStream).setOnClickListener { view: View? ->
  if (!liveStream) {
//highlight-start
val config = JSONObject()
val layout = JSONObject()
JsonUtils.jsonPut(layout, "type", "GRID")
JsonUtils.jsonPut(layout, "priority", "SPEAKER")
JsonUtils.jsonPut(layout, "gridSize", 4)
JsonUtils.jsonPut(config, "layout", layout)
JsonUtils.jsonPut(config, "theme", "DARK")
//highlight-end

val outputs: MutableList<LivestreamOutput> = ArrayList()
//highlight-next-line
outputs.add(LivestreamOutput(RTMP_URL, RTMP_STREAM_KEY))

// Start LiveStream
//highlight-next-line
liveStream!!.startLivestream(outputs,config)
  } else {
// Stop LiveStream
//highlight-next-line
liveStream!!.stopLivestream()
  }
}
```

---

**Java:**

```js
// keep track of livestream status
boolean liveStream = false;

findViewById(R.id.btnLiveStream).setOnClickListener(view -> {
  if (!liveStream) {
//highlight-start
JSONObject config = new JSONObject();
JSONObject layout = new JSONObject();
JsonUtils.jsonPut(layout, "type", "GRID");
JsonUtils.jsonPut(layout, "priority", "SPEAKER");
JsonUtils.jsonPut(layout, "gridSize", 4);
JsonUtils.jsonPut(config, "layout", layout);
JsonUtils.jsonPut(config, "theme", "DARK");
//highlight-end

List<LivestreamOutput> outputs = new ArrayList<>();
//highlight-next-line
outputs.add(new LivestreamOutput(RTMP_URL, RTMP_STREAM_KEY));

// Start LiveStream
//highlight-next-line
liveStream.startLivestream(outputs,config);
  } else {
// Stop LiveStream
//highlight-next-line
liveStream.stopLivestream();
  }
});
```

## Event associated with Livestream

- **onLivestreamStateChanged** - Whenever meeting livestream state changes, then `onLivestreamStateChanged` event will trigger.

**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onLivestreamStateChanged(livestreamState: String?) {
when (livestreamState) {
  "LIVESTREAM_STARTING" -> Log.d( "LivestreamStateChanged",
      "Meeting livestream is starting"
  )
  "LIVESTREAM_STARTED" -> Log.d( "LivestreamStateChanged",
      "Meeting livestream is started"
  )
  "LIVESTREAM_STOPPING" -> Log.d("LivestreamStateChanged",
      "Meeting livestream is stopping"
  )
  "LIVESTREAM_STOPPED" -> Log.d("LivestreamStateChanged",
      "Meeting livestream is stopped"
  )
}
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  //highlight-next-line
  liveStream!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onLivestreamStateChanged(String livestreamState) {
switch (livestreamState) {
  case "LIVESTREAM_STARTING":
      Log.d("LivestreamStateChanged", "Meeting livestream is starting");
      break;
  case "LIVESTREAM_STARTED":
      Log.d("LivestreamStateChanged", "Meeting livestream is started");
      break;
  case "LIVESTREAM_STOPPING":
      Log.d("LivestreamStateChanged", "Meeting livestream is stopping");
      break;
  case "LIVESTREAM_STOPPED":
      Log.d("LivestreamStateChanged", "Meeting livestream is stopped");
      break;
}
  }
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  //highlight-next-line
  liveStream.addEventListener(meetingEventListener);
}
```

### API Reference

The API references for all the methods utilised in this guide are provided below.

- [startLivestream()](/android/api/sdk-reference/meeting-class/methods#startlivestream)
- [stopLivestream()](/android/api/sdk-reference/meeting-class/methods#stoplivestream)
- [onLivestreamStateChanged](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onlivestreamstatechanged)


---

# Sending Virtual Gifts - Android

Virtual gifting is a powerful monetization and engagement feature that allows viewers to support hosts or speakers during a livestream by sending them digital tokens or "gifts." These gifts can be visually animated and even linked to leaderboards or reward systems.

This guide explains how to implement a secure and real-time virtual gifting experience using your backend server in combination with VideoSDK PubSub.

### How It Works
1. User Action: A viewer taps on a gift button to send a virtual gift to the host.

2. Server Verification:
   - A request is made to your business backend to process the gift.
    - The server authenticates the user, checks their wallet balance, deducts the gift value, and returns a success response.

3. Event Broadcast: Upon success, the client publishes a PubSub message to inform everyone in the meeting (host + other viewers) that a gift has been sent. Clients can then visually show an animation or notification.

### Backend Responsibility

Your backend plays a central role in verifying, validating, and processing gift transactions. It should:
  - Authenticate the request (token/session)
  - Verify if the user has sufficient balance
  - Deduct the gift cost
  - Store the transaction in a database (optional but recommended)
  - Respond with success or failure

### Frontend Implementation

- Sending a Gift (Client to Backend + PubSub)



**Kotlin:**

```js
// Data class for request body
data class GiftRequest(val senderId: String, val hostId: String, val giftType: String)

// Retrofit API interface
interface ApiService {
@POST("send-gift")
suspend fun sendGift(@Body request: GiftRequest): Response<GiftResponse>
}

// Gift sending logic with PubSub
fun sendGift(giftType: String, senderId: String, hostId: String, pubSub: PubSub) {
CoroutineScope(Dispatchers.IO).launch {
    try {
        val response = api.sendGift(GiftRequest(senderId, hostId, giftType))
        if (response.isSuccessful && response.body()?.success == true) {
            pubSub.publish(mapOf("giftType" to giftType, "from" to senderId, "to" to hostId))
        } else {
            Log.e("Gift", "Failed: ${response.body()?.message}")
        }
    } catch (e: Exception) {
        Log.e("Gift", "Error: ${e.message}")
    }
}
}
```

---

**Java:**

```java
// Request model
public class GiftRequest {
public String senderId;
public String hostId;
public String giftType;

public GiftRequest(String senderId, String hostId, String giftType) {
    this.senderId = senderId;
    this.hostId = hostId;
    this.giftType = giftType;
}
}

// Response model
public class GiftResponse {
public boolean success;
public String message;
}

// Retrofit interface
public interface ApiService {
@POST("send-gift")
Call<GiftResponse> sendGift(@Body GiftRequest request);
}

// Gift sending method
public void sendGift(String giftType, String senderId, String hostId, PubSub pubSub) {
GiftRequest request = new GiftRequest(senderId, hostId, giftType);

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://your-api.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .build();

ApiService api = retrofit.create(ApiService.class);

api.sendGift(request).enqueue(new Callback<GiftResponse>() {
    @Override
    public void onResponse(Call<GiftResponse> call, Response<GiftResponse> response) {
        if (response.isSuccessful() && response.body().success) {
            Map<String, String> payload = new HashMap<>();
            payload.put("giftType", giftType);
            payload.put("from", senderId);
            payload.put("to", hostId);
            pubSub.publish(payload);
        } else {
            Log.e("Gift", "Failed: " + (response.body() != null ? response.body().message : "Unknown error"));
        }
    }

    @Override
    public void onFailure(Call<GiftResponse> call, Throwable t) {
        Log.e("Gift", "Error sending gift", t);
    }
});
}
```

- Displaying the Gift (All Clients)

**Kotlin:**

```js
// In your Activity or Fragment
val gifts = mutableListOf<Gift>()

pubSub.onMessage("GIFT") { message ->
val from = message["from"] ?: "Unknown"
val to = message["to"] ?: "Unknown"
val type = message["giftType"] ?: "gift"

val gift = Gift(from = from, to = to, type = type)
gifts.add(gift)

runOnUiThread {
    Toast.makeText(
        this,
        "🎁 $from sent a $type to $to",
        Toast.LENGTH_SHORT
    ).show()
}
}
```

---

**Java:**

```java
// In your Activity or Fragment
List<Gift> gifts = new ArrayList<>();

pubSub.onMessage("GIFT", message -> {
String from = message.get("from");
String to = message.get("to");
String type = message.get("giftType");

Gift gift = new Gift(from, to, type);
gifts.add(gift);

runOnUiThread(() -> {
    Toast.makeText(
        context,
        "🎁 " + from + " sent a " + type + " to " + to,
        Toast.LENGTH_SHORT
    ).show();
});
});
```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [pubSub()](/android/api/sdk-reference/pubsub-class/introduction)


---

# Initialize Live Stream - Android

To configure livestreaming with VideoSDK you require two things, first the `token` which will be used for **Authentication** purpose and a `streamId` which will be used to specify where the hosts and audience will join.

### Generating Token

You can generate a `token` in two ways:

1. **`Temporary Token`** : You can visit [Dashboard's API Key section](https://app.videosdk.live/api-keys) and generate a temporary token from there.

2. **`Server`** : You can setup **JWT** in backend and make an API call to get the token from your server.

To learn more about **Authentication** and token in detail you can follow [this guide](/android/guide/video-and-audio-calling-api-sdk/authentication-and-token).



**Kotlin:**

```js
// With Temporary Token
fun getToken(): String {
  // Update the token here from the VideoSDK dashboard
  // highlight-next-line
  return "YOUR_TOKEN"
}

// Server
fun getToken(): String {
  val token = arrayOfNulls<String>(1)
  // highlight-start
  AndroidNetworking.get("http://localhost:3000/get-token")
  .build()
  .getAsJSONObject(object : JSONObjectRequestListener() {
      fun onResponse(response: JSONObject) {
          try {
              token[0] = response.getString("token")
          } catch (e: JSONException) {
              e.printStackTrace()
          }
      }

      fun onError(anError: ANError) {
          anError.printStackTrace()
      }
  })
  // highlight-end
  return token[0]
}
```

---

**Java:**

```java
// With Temporary Token
public String getToken()
{
  // Update the token here from the VideoSDK dashboard
  // highlight-next-line
  String token = "YOUR_TOKEN";
  return token;
}

// Server
public String getToken()
{
  final String[] token = new String[1];
  // highlight-start
  AndroidNetworking.get("http://localhost:3000/get-token")
  .build()
  .getAsJSONObject(new JSONObjectRequestListener() {
      @Override
      public void onResponse(JSONObject response) {
          try {
              token[0] = response.getString("token");
          } catch (JSONException e) {
              e.printStackTrace();
          }
      }
      @Override
      public void onError(ANError anError) {
          anError.printStackTrace();
      }
  });
  // highlight-end
  return token[0];
}
```

### Generating Stream Id

With the token ready, you can now get the `streamId` from the [VideoSDK's rooms API](/api-reference/realtime-communication/create-room).

**Kotlin:**

```js
fun getStreamId(token: String): String {
  var streamId: String =null;
  // We will use VideoSDK rooms API endpoint to create a streamId
  // highlight-start
  AndroidNetworking.post("https://api.videosdk.live/v2/rooms")
  .addHeaders("Authorization", token) // We will pass the token in the headers
  .build()
  .getAsJSONObject(object : JSONObjectRequestListener() {
      fun onResponse(response: JSONObject) {
          try {
              streamId = response.getString("roomId")
          } catch (e: Exception) {
              e.printStackTrace()
          }
      }

      fun onError(anError: ANError) {
          anError.printStackTrace()
      }
  })
  // highlight-end
  //we will return the streamId which we got from the response of the api
  return streamId
}
```

---

**Java:**

```java
public String getStreamId(String token) {
  final String[] streamId = new String[1];
  // We will use VideoSDK rooms API endpoint to create a streamId
  // highlight-start
  AndroidNetworking.post("https://api.videosdk.live/v2/rooms")
  .addHeaders("Authorization", token) // We will pass the token in the headers
  .build()
  .getAsJSONObject(new JSONObjectRequestListener() {
      @Override
      public void onResponse(JSONObject response) {
          try {
              streamId[0] = response.getString("roomId");
          } catch (Exception e) {
              e.printStackTrace();
          }
      }
      @Override
      public void onError(ANError anError) {
          anError.printStackTrace();
      }
  });
  // highlight-end
  //we will return the streamId which we got from the response of the api
  return streamId[0];
}
```

### Initialization of Live Stream

1. To initialize the live stream , first we have to initialize the VideoSDK.
   We can initialize the VideoSDK using `initialize()` method provided by the SDK.

```js title="initialize"
  VideoSDK.initialize(Context context)
```

2. Next, we have to set token property of VideoSDK class.
   By using `config()` method, you can set the token property of VideoSDK class.

```js title="config"
 VideoSDK.config(String token)
```

3. Now, we can initialize the live stream  using a factory method provided by the SDK called `initMeeting()`.

`initMeeting()` is responsible for initializing the live stream  with the provided configuration, which includes the `streamId`, `name`, `participantId` and many more.

Let's take a deeper look at the available configuration options first.

```js title="initMeeting"
  VideoSDK.initMeeting(
      Context context,  // context of activity
      String MeetingId,  
      String name, // name of participant
      boolean micEnabled, // flag to enable-mic
      boolean webcamEnabled, // flag to enable-webcam
      String participantId,  // id of participant
      String mode, // mode of participant
      boolean multiStream, // multiStream
      Map<String, CustomStreamTrack> customTracks, // map of customTracks
      JSONObject metaData, // metaData
      String signalingBaseUrl // signalingBaseUrl
      PreferredProtocol preferredProtocol //preferredProtocol
  )
```


- **`MeetingId`** :

  - This is a unique identifier that allows participants to join a specific live stream.
  - It will be in the format of `xxx-yyy-zzz` and will be generated using the [VideoSDK's Room API](/api-reference/realtime-communication/create-room).

- **`mode`** :

  - This paramter defines the mode the participant will enter the live stream with.
  - `SEND_AND_RECV`: For hosts/co-hosts who can send and receive media.
  - `RECV_ONLY`: For audience members who can only receive media.​


- **`name`**:

  - This represents the name of the participant in the live streams.
  - It will accept `String` type value.

- **`micEnabled`**:

  - This is a `boolean` flag, indicating whether a participant's microphone will be automatically enabled when they join the live stream. This property will be completely ignored for Audience participants, as they are not allowed to publish their audio.

- **`webcamEnabled`**:

  - This is a `boolean` flag, indicating whether a participant's webcam will be automatically enabled when they join the live stream. This property will be completely ignored for Audience participants, as they are not allowed to publish their video.

- **`metaData`**:

  - If you want to provide additional details about the participants joining the live stream, such as their profile image, you can pass that information in this parameter.
  - It has to be of `Object` type.
  - This is an `OPTIONAL` parameter.

- **`participantId`**:

  - This is a unique identifier for the participant's inside the live stream.

    - It can be used to specify the **unique identifier** which can be linked with **your own database** service.
    - It has to be of `String` type.
    - This is an `OPTIONAL` parameter. By default VideoSDK will generate unique id for each participant.

- **`multistream`**:

  - This is a `boolean` flag, indicating whether the host's media stream should send multiple resolution layers or a single resolution layer.

:::caution
You must ensure that the `participantId` is not repeated in the same livestream. This will enable VideoSDK to eliminate any participant associated with that `participantId`.
:::

With all the configuration options explained, here is how you can initialize the live stream.

**Kotlin:**

```js
class LiveStreamActivity : AppCompatActivity() {

  fun getToken(): String {
//highlight-next-line
...
  }

  fun getStreamId(token: String): String {
//highlight-next-line
...
  }

 override fun onCreate(savedInstanceState: Bundle) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)

// initialize AndroidNetworking to perform Network call
AndroidNetworking.initialize(applicationContext)

//We will fetch token and streamId and store it in local variables
val token: String = getToken()
val streamId = getStreamId(token)

// highlight-start
// initialize the VideoSDK
VideoSDK.initialize(this@MainActivity)

// set token property of VideoSDK
VideoSDK.config(token)

// create a new meeting instance
val liveStream: Meeting = VideoSDK.initMeeting(
    this@MainActivity, streamId, "NAME HERE",
    true, true, null, null, false, null, null
)
// highlight-end

Log.d("VideoSDK", "onCreate: $streamId")
  }
}
```

---

**Java:**

```java
public class LiveStreamActivity extends AppCompatActivity {

  public String getToken()
  {
//highlight-next-line
...
  }

  public String getStreamId(String token) {
//highlight-next-line
...
  }

  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

// initialize AndroidNetworking to perform Network call
AndroidNetworking.initialize(getApplicationContext());

//We will fetch token and streamId and store it in local variables
String token = getToken();
String streamId = getStreamId(token);

// highlight-start
// initialize the VideoSDK
VideoSDK.initialize(MainActivity.this);

// set token property of VideoSDK
VideoSDK.config(token);

// create a new meeting instance
Meeting liveStream = VideoSDK.initMeeting(
        MainActivity.this, streamId, "NAME HERE",
        true, true, null, null, false, null, null
// highlight-end

Log.d("VideoSDK", "onCreate: " + streamId
);
  }
}
```

## API Reference

The API references for all the methods utilised in this guide are provided below.

- [initMeeting](/android/api/sdk-reference/initMeeting)



---

---
title: Join/Leave Live Stream | Video SDK
hide_title: true
hide_table_of_contents: false
description: Easily integrate join and leave functionalities for interactive live streams using Video SDK’s ReactSDK with event handling for participant management.
sidebar_label: Join/Leave Live Stream
pagination_label: Join/Leave Live Stream
keywords:
  - audio calling
  - video calling
  - real-time communication
  - collaboration
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: join-leave-livestream
--- 

# Join Live Stream - Android

Once, the live stream is configured, the next step is to join it. If you have not initialized the live stream yet, you can [follow the guide here.](/android/guide/interactive-live-streaming/setup-livestream/initialize-livestream)

### `join()`

- To join the live stream you can call the `join()` method which is the part of the `Meeting` class of Android SDK.
- This method can be called after the live stream is initialized from the `VideoSdk class`.

### Events associated with Join

Following callbacks are received when a participant is successfully joined.

- [Local Participant](/android/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a [`onMeetingJoined`](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmeetingjoined) event, when successfully joined.
- [Remote Participant](/android/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a [`onParticipantJoined`](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onparticipantjoined) event with the newly joined `Participant` object from the event callback.



**Kotlin:**

```js
class LiveStreamActivity : AppCompatActivity() {
 override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_live_stream);
// initialize the meeting
 liveStream = VideoSDK.initMeeting(... )
...

// join meeting
meeting!!.join()

// Add event listener for listening upcoming events of live stream
// highlight-next-line
meeting!!.addEventListener(meetingEventListener)
  }

  private val meetingEventListener: MeetingEventListener = object : MeetingEventListener(){
//Event to determine if the live stream has been joined
//highlight-start
fun onMeetingJoined() {
    Log.d("VideoSDK", "onMeetingJoined")
}
//highlight-end
/ //Event to determine some other participant has joined
//highlight-start
fun onParticipantJoined(participant: Participant) {
    Log.d("#VideoSDK", participant.displayName + " joined");
}
//highlight-end
  }
}
```

---

**Java:**

```java
public class LiveStreamActivity extends AppCompatActivity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_live_stream);
// initialize the meeting
Meeting liveStream = VideoSDK.initMeeting( ...);
...

// join meeting
meeting.join();

// Add event listener for listening upcoming events of live stream
//highlight-next-line
meeting.addEventListener(meetingEventListener);
  }

  private final MeetingEventListener meetingEventListener=new MeetingEventListener() {
   //Event to determine if the live stream has been joined
@Override
public void onMeetingJoined() {
    Log.d("VideoSDK", "onMeetingJoined");
}
//highlight-end

/ //Event to determine some other participant has joined
//highlight-start
@Override
public void onParticipantJoined(Participant participant) {
    Log.d("#VideoSDK", participant.getDisplayName() + " joined");
}
//highlight-end
  };
}
```

### `leave()`

- To leave the live stream you can call the `leave()` method which is the part of the `Meeting` class of Flutter SDK.


:::note
This method can be called only after the live stream is joined successfully.
:::

### Events associated with the leave() method

Following callbacks are received when a participant leaves the live stream.

- The [Local Participant](/android/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive the [`onMeetingLeft`](/react/api/sdk-reference/use-meeting/events#onmeetingleft) event, once they have successfully left the livestream.
- All the [Remote Participants](/android/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant)—including all the hosts and audience members—will receive the [`onParticipantLeft`](/react/api/sdk-reference/use-meeting/events#onparticipantjoined) event with the `Participant` object of the user who left the livestream.


**Kotlin:**

```javascript
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  //Event to determine if the live stream has been left
  //highlight-start
  override fun onMeetingLeft() {
Log.d("#VideoSDK", "onMeetingleft()")
  }
  //highlight-end

  //Event to determine some other participant has left
  //highlight-start
  override fun onParticipantLeft(participant: Participant) {
Log.d("#VideoSDK", participant.displayName + " left");
  }
  //highlight-end
}
```

---

**Java:**

```javascript
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  //Event to determine if the live stream has been left
  //highlight-start
  @Override
  public void onMeetingLeft() {
Log.d("#VideoSDK", "onMeetingleft()")
  }
  //highlight-end

  //Event to determine some other participant has left
  //highlight-start
  @Override
  public void onParticipantLeft(Participant participant) {
Log.d("#VideoSDK", participant.getDisplayName() + " left");
  }
  //highlight-end
}
```
:::tip
You should call the `leave()` method on the unmount of your main live stream component so that live stream is left once the view is unmounted.
:::

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [initMeeting](/android/api/sdk-reference/initMeeting)
- [join()](/android/api/sdk-reference/meeting-class/methods#join)
- [onMeetingJoined()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmeetingjoined)
- [onParticipantJoined()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onparticipantjoined)
- [leave()](/android/api/sdk-reference/meeting-class/methods#leave)
- [onMeetingLeft()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmeetingleft)
- [onParticipantLeft()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onparticipantleft)


---

# Waiting Screen - Android

To create a smoother and more polished entry experience for audience members, it's important not to immediately render the meeting room when they join. Instead, show a waiting screen until at least one host is present in the room.

### Why This Matters?

- Hosts are typically responsible for driving the meeting, and their presence is essential before audience members should be able to view or interact in the room.

- Allowing audience members (in RECV_ONLY mode) to enter a meeting with no active hosts (in SEND_AND_RECV mode) can result in confusion and a poor user experience.

### Participant Modes

- Hosts must join the meeting with the SEND_AND_RECV mode.
- Audience members should join with the RECV_ONLY mode.

### Implementation Guide

You can achieve this behavior by using the participants list and onParticipantJoined event from the Meeting class.

1. Check if a Host is Present
   On initial render, use the participants object to determine if there's already a host in the room:



**Kotlin:**

```javascript
val hasHost = meeting.getParticipants().values.any { it.mode == "SEND_AND_RECV" }

Log.d("Tag", "Has Host: $hasHost")
```

---

**Java:**

```javascript
boolean hasHost = meeting.getParticipants().values().stream()
.anyMatch(p -> "SEND_AND_RECV".equals(p.getMode()));

Log.d("Tag", "Has Host: " + hasHost);

```

If hasHost is true, render the meeting view. Otherwise, show the waiting screen.

2. Listen for Host Join
   Always listen for the onParticipantJoined event in case a host joins after the audience participant:

**Kotlin:**

```javascript
override fun onParticipantJoined(participant: Participant) {
if (participant.mode == "SEND_AND_RECV") {
    // Show meeting UI
   Log.d("Tag", "Host joined. Show meeting view.")
}
}
```

---

**Java:**

```javascript
@Override
public void onParticipantJoined(Participant participant) {
if ("SEND_AND_RECV".equals(participant.getMode())) {
    // Show meeting UI
    System.out.println("Host joined. Show meeting view.");
}
}
```

This ensures that as soon as a host joins, the waiting audience members are transitioned smoothly into the meeting view.

<div style={{ textAlign: 'center' }}>
    <img 
        src="https://cdn.videosdk.live/docs/images/flutter/ils/waiting_screen_flutter.jpg" 
        alt="Waiting Screen" 
         style={{height: '450px'}}
    />
</div>


---

# Supported Device OS and Architecture

:::note
The following device OS version represent the minimum required version to ensure full support for the listed features.
:::




<br/>

# Supported ABIs





---

# Switch Live Stream - Android

## Overview

The **Switch Live Stream** feature enables users to **seamlessly transition** between live streams without needing to manually disconnect and reconnect. This drastically improves user experience by reducing latency and preserving media and socket connections.

### Previously

1.  Users had to **disconnect** from the current liveStream.
2.  Then **manually connect** to a new liveStream:
    - New socket connection created.
    - New media transports initialized.
    - Delays due to re-connection and media setup.

This led to:

- **Higher latency**
- **Socket transport downtime**
- **Poor experience** for users switching frequently between rooms

### New Behavior with `switchTo`

- Keeps the existing **socket connection** alive
- Reuses or reconfigures existing **media**
- Switches the server-side context to the **new liveStream**

### `switchTo()`

#### **Parameters**

- **liveStreamId** (`string`, required): ID of the new liveStream to join
- **token** (`string`, optional): VideoSDK token for authentication



**Kotlin:**

```js
class LiveStreamActivity : AppCompatActivity() {
//Initialize  meeting
val liveStream = VideoSDK.initMeeting(... )
//...
val switchButton: Button = findViewById(R.id.switchLiveStreamButton)
switchButton.setOnClickListener {
    liveStream?.switchTo("liveStream-xyz-456")
}
}
```

---

**Java:**

```java
public class LiveStreamActivity extends AppCompatActivity {
// Initialize meeting
  Meeting liveStream = VideoSDK.initMeeting( ...);
//...
Button switchButton = findViewById(R.id.switchLiveStreamButton);
switchButton.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View v) {
        if (liveStream != null) {
            liveStream.switchTo("liveStream-xyz-456");
        }
    }
});
}
```

## Important Considerations

### Meeting Status

- **The destination liveStream must be active** before attempting to switch.
- If the destination liveStream is inactive or doesn't exist, the switch will fail.

### Token Management

- **Token Expiry**: Be careful with short-lived tokens when using the switch feature.
  - If you're using short-lived tokens for security reasons, always provide a new token in the `switchTo` method.
  - Tokens that expire during a liveStream can cause unexpected disconnections.
- **Best Practice**: For frequent switches, use tokens with reasonable expiry times or implement a token refresh mechanism.

## API Reference

- [switchTo](/android/api/sdk-reference/meeting-class/methods#switchto)


---

# Virtual Background - Android

Virtual backgrounds enhance your **live stream experience** by allowing you to replace your physical background with a digital image or apply a blur effect. This is ideal for creators and streamers who want to maintain privacy, reduce distractions, or add a personal touch to their broadcast. You can use a preloaded background image or supply your own via a CDN.





## Virtual Background using `MediaEffects` library

The `MediaEffects` library enables the integration of sophisticated virtual background effects within your video applications. By leveraging this library, users can replace their physical backgrounds with custom images or static backdrops, creating a more immersive and engaging experience. 

### Install the library 
You can install our Android library by using Maven Central package repositories.

- Add the dependency in your `app/build.gradle` file.

```js title="app/build.gradle"
dependencies {
	implementation 'live.videosdk:videosdk-media-effects:0.0.2'
	// other app dependencies
}
```
### Apply Virtual Background

- The `applyVideoProcessor()` method of the `VideoSDK` class enables dynamic changes to the video background during a live session.
- This method accepts an instance of the `VideoFrameProcessor` class as its parameter.
- The following classes implement the `VideoFrameProcessor` interface. Depending on your requirements, you can create an instance of the appropriate class and pass it to the `applyVideoProcessor()` method:

    1. `BackgroundImageProcessor` : The `BackgroundImageProcessor` class takes a `Uri` as a parameter and uses it as the video stream background.
    2. `BackgroundBlurProcessor`: The `BackgroundBlurProcessor` class takes a `float` value for the blur radius and a `Context` to apply a blur effect to the video stream background. It supports range between 0 to 25.
    3. `BackgroundColorProcessor`: The `BackgroundColorProcessor` class takes an `int` value for the color and sets it as the background for the video stream.

### Change Virtual Background

- To change the virtual background, users can utilize a set of setters that allow easy switching between a new image, a blur effect, or a solid color. This functionality supports dynamic customization, enhancing the user's video experience by enabling seamless background updates in real-time.

- You can use following setters to change Virtual Background:

    1. `setBackgroundSource(Uri uri)`: This method of the `BackgroundImageProcessor` class takes a `Uri` as a parameter to update the current background image for the video stream.
    2. `setBlurRadius(float opacity)`: This method of the `BackgroundBlurProcessor` class takes a `float` value for the blur radius to adjust the blur effect of the current background.
    3. `setBackgroundColor(int color)`: This method of the `BackgroundColorProcessor` class takes an `int` value as a parameter to update the current background color for the video stream.
### Remove Virtual Background

- The `removeVideoProcessor()` method from the `VideoSDK` class provides users with a convenient way to revert their video background to its original state, removing any previously applied virtual background. This functionality ensures flexibility for users to switch between virtual and real backgrounds as needed.

#### Example



**Kotlin:**

```js
Class LiveStreamActivity : AppCompatActivity() {
private var backgroundImageProcessor: BackgroundImageProcessor? = null
private var backgroundBlurProcessor: BackgroundBlurProcessor? = null
private var backgroundColorProcessor: BackgroundColorProcessor? = null

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    //...

    //To Apply Virtual Background
    findViewById<View>(R.id.applyBackground).setOnClickListener { view: View? ->
        val uri =
            Uri.parse("https://st.depositphotos.com/2605379/52364/i/450/depositphotos_523648932-stock-photo-concrete-rooftop-night-city-view.jpg")
        backgroundImageProcessor = BackgroundImageProcessor(uri)
  //    backgroundBlurProcessor = BackgroundBlurProcessor(25f, this)
  //    backgroundColorProcessor = BackgroundColorProcessor(Color.BLUE)
        VideoSDK.applyVideoProcessor(backgroundColorProcessor)
    }

    //To Change Virtual Background
    findViewById<View>(R.id.changeBackground).setOnClickListener { view: View? ->
        val newUri =
            Uri.parse("https://images.pexels.com/photos/531880/pexels-photo-531880.jpeg?cs=srgb&dl=pexels-pixabay-531880.jpg&fm=jpg")
        backgroundImageProcessor!!.setBackgroundSource(newUri)
  //    backgroundColorProcessor!!.setBackgroundColor(Color.CYAN)
  //    backgroundBlurProcessor!!.setBlurRadius(17f)
    }
    
    //To Remove Virtual Background
    findViewById<View>(R.id.changeBackground).setOnClickListener { view: View? ->
        VideoSDK.removeVideoProcessor()
    }
}
}
```

---

**Java:**

```java
public class LiveStreamActivity extends AppCompatActivity {

private BackgroundImageProcessor backgroundImageProcessor;
private BackgroundBlurProcessor backgroundBlurProcessor;
private BackgroundColorProcessor backgroundColorProcessor;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    //...

    //To Apply Virtual Background
    findViewById(R.id.applyBackground).setOnClickListener(view -> {
        Uri uri = Uri.parse("https://st.depositphotos.com/2605379/52364/i/450/depositphotos_523648932-stock-photo-concrete-rooftop-night-city-view.jpg");
        backgroundImageProcessor = new BackgroundImageProcessor(uri);
    //   backgroundBlurProcessor = new BackgroundBlurProcessor(25,this);
    //   backgroundColorProcessor = new BackgroundColorProcessor(Color.BLUE);
        VideoSDK.applyVideoProcessor(backgroundColorProcessor);
    });

    //To Change Virtual Background
    findViewById(R.id.changeBackground).setOnClickListener(view -> {
        Uri newUri = Uri.parse("https://images.pexels.com/photos/531880/pexels-photo-531880.jpeg?cs=srgb&dl=pexels-pixabay-531880.jpg&fm=jpg");
        backgroundImageProcessor.setBackgroundSource(newUri);
    //    backgroundColorProcessor.setBackgroundColor(Color.CYAN);
    //    backgroundBlurProcessor.setBlurRadius(17);    
    });
    
    //To Remove Virtual Background
    findViewById(R.id.removeBackground).setOnClickListener(view -> {
        VideoSDK.removeVideoProcessor();
    });
}
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [applyVideoProcessor()](/android/api/sdk-reference/videosdk-class/methods#applyvideoprocessor)
- [removeVideoProcessor()](/android/api/sdk-reference/videosdk-class/methods#removevideoprocessor)



---



---

# Overview of SIP with VideoSDK - Android




SIP (Session Initiation Protocol) is extensively employed for setting up and controlling IP-based calls. It facilitates the initiation and termination of user sessions over IP networks, enabling SIP-based systems to connect and exchange voice communications over the internet.

With VideoSDK's SIP Connect feature, you can enable your users to join VideoSDK meetings via VOIP using third-party service providers. This allows for establishing a bridge between participants using our client SDKs and those joining via SIP, enhancing the accessibility and connectivity of your video meetings.

![SIP Architecture](https://cdn.videosdk.live/website-resources/docs-resources/sip-architechture.png)

### Getting SIP Credentials

To use SIP Connect, you will first need to generate the credentials for the SIP. Go to the [VideoSDK dashboard](https://app.videosdk.live) and under the [API Keys](https://app.videosdk.live/api-keys) sections, first enable the SIP for the desired API key after which you will be presented with the SIP `username` and `password` you can use to establish connection with our SIP servers.

![SIP Credentials](https://cdn.videosdk.live/website-resources/docs-resources/sip-get-credentials.gif)

### How to use SIP to join a particular meeting?

Once you have the credentials, you can use any of the softphones like Linphone, Zoiper etc. or use a third party service provider like twilio to connect with a VideoSDK meeting by initiating a SIP call to `sip:<meeting-id>@sip.videosdk.live`

For example if you want to connect to `abcd-abcd-abcd` meeting then the SIP address will look like `sip:abcd-abcd-abcd@sip.videosdk.live`

### Example of Twilio PSTN

To utilize third-party PSTN (Public Switched Telephone Network) providers like Twilio for making calls via SIP (Session Initiation Protocol), follow these steps:

1. Log in to your Twilio account and navigate to the Phone Numbers section.
2. Purchase a phone number and access its configuration settings.
3. Set up a Webhook handler that will initiate a call to the VideoSDK SIP endpoint whenever an incoming call is received on the selected phone number.

![SIP Configuration for Twilio](https://cdn.videosdk.live/website-resources/docs-resources/sip-twilio-config.png)

##### Example for creating Webhook using Express

```js
const express = require("express");
const VoiceResponse = require("twilio").twiml.VoiceResponse;
const urlencoded = require("body-parser").urlencoded;

const app = express();

// Parse incoming POST params with Express middleware
app.use(urlencoded({ extended: false }));

// Webhook route which will be called by twilio when a call is received
app.post("/incoming-call-handler", (request, response) => {
  console.log({ request });
  // Use the Twilio Node.js SDK to build an XML response
  const twiml = new VoiceResponse();

  const dial = twiml.dial();
  dial.sip(
    {
      username: "<User name generated for dashboard>",
      password: "<Password generated from dashboard>",
    },
    "sip:<meetingId>@sip.videosdk.live"
  );

  // Render the response as XML in reply to the webhook request
  response.type("text/xml");
  response.send(twiml.toString());
});

//Start the express app on port 8000
app.listen(8000, () => {
  console.log(`Server listening on port ${8000}.`);
});
```



---

# Build a SIP Integration: VideoSDK & Twilio for Inbound Outbound Calls! Step-by-Step


Imagine joining an online meeting using just your phone—no apps, no browsers, no internet. This powerful option allows participants to connect via traditional telephony, by creating a bridge between phone systems and modern video conferencing platforms. In this post, we’ll explore how to build a SIP integration using VideoSDK and Twilio for both inbound and outbound VoIP calls.



We’ll break down the flow of calls, set up the project, and show you how to bring this functionality to life using Next.js.

## What Is a SIP Integration?

SIP, or Session Initiation Protocol, enables voice and video communications over internet-based networks. With SIP integrations, traditional phone systems can connect to online platforms .

By integrating SIP with VideoSDK’s SIP address and Twilio, you can handle both inbound and outbound calls while linking them to video meetings. This integration is particularly helpful for situations where participants lack internet access, allowing them to simply dial in to join a meeting or receive phone calls initiated by meeting participants.

## Understanding Inbound and Outbound Call Flows

### Inbound Calls

![Inboud Call Flow](https://assets.videosdk.live/images/inbound.png)

Inbound calls are initiated by a user or customer dialing a phone number, such as a Twilio-provisioned number. Here’s how the process works:

1. **User Dialing**: A participant dials the Twilio number tied to the SIP integration.
2. **Call Routing**: Twilio receives the call and notifies your server with call details.
3. **Server Processing**: Your server processes the request and sends an invite SIP request to the VideoSDK SIP address.
4. **Connection Established**: Once validated, the caller is connected to the specific video meeting through VideoSDK.

For example, if a customer wants to join a video conference using their phone, they can call a designated number. Following this process, the integration connects them to the meeting.

### Outbound Calls

![Outbound Call Flow](https://assets.videosdk.live/images/outbound.png)

Outbound calls begin with a participant or agent in an online meeting initiating a call to a customer’s phone. The process involves the following steps:

1. **Call Request Initiated**: A participant requests your server to call a specific phone number.
2. **Server Action**: The server notifies Twilio to establish the call.
3. **User Accepts Call**: When the user accepts, the connection is forwarded to the video meeting through VideoSDK.

This two-way communication ensures smooth interaction between online participants and phone users.

## Step-by-Step Guide to Setting Up the Project

### Prepare the Project Files

1. Create a workspace for the SIP integration project (or open your existing project if you already have one).

```bash
mkdir videosdk-sip-integration && cd videosdk-sip-integration
```

1. Navigate to project directory

```javascript
cd videosdk-sip-integration
```

1. Install dependencies that are required for you application to work

```javascript
npm install
```

### Configure the Environment

1. **Set Up the `.env` File**: Copy the `.env.example` file in the repository and rename it to `.env`.
2. **Add VideoSDK Details**: Obtain the SIP username, password, and authentication token from the [VideoSDK dashboard](https://app.videosdk.live/).
   - Generate an authentication token under “API Keys.”
   - Get your SIP username and password from the “SIP Config” section.
   - Add these details to the `.env` file.
3. **Configure Twilio**: Sign in to your [Twilio console](https://console.twilio.com/).
   - Copy your Twilio phone number, Account SID, and Auth Token.
   - Paste these values into the `.env` file.

```javascript
TWILIO_ACCOUNT_SID=your-twilio-account-sid
TWILIO_AUTH_TOKEN=your-twilio-auth-token
VIDEOSDK_SIP_USERNAME=your-videosdk-sip-username
VIDEOSDK_SIP_PASSWORD=your-videosdk-sip-password
NEXT_PUBLIC_TWILIO_PHONE_NUMBER=your-twilio-phone-number
NEXT_APP_URL=http://localhost:3000 # Replace with your production URL
```

Your `.env` file should now contain all necessary credentials.

### Running the Application

Once the configurations are complete, start the project using the following command:

```bash
npm run dev
```

![demo home page](https://assets.videosdk.live/images/demo.png)

The application will run locally on port 3000.



## Setting Up Call Routing

### Inbound Call Setup

**Define the API URL**: In Twilio’s Active Numbers section, specify your API endpoint (e.g., `/api/webhook/inbound`). Twilio will send incoming call details to this URL.

If hosting locally, tools like `ngrok` or `pinggy` can expose your server to the internet for testing purposes. Replace the localhost URL with the public domain generated by these tools in the Twilio configuration.

![Twilio Dashboard](https://assets.videosdk.live/images/twilio-dashboard.png)

**Handle Calls with VideoSDK**: Once Twilio routes the call, your code forwards the meeting ID to VideoSDK’s SIP address. This connects the caller to the online meeting.

```javascript

// Environment variables
const accountSid = process.env.TWILIO_ACCOUNT_SID || "";
const authToken = process.env.TWILIO_AUTH_TOKEN || "";
const videosdkSipUsername = process.env.VIDEOSDK_SIP_USERNAME || "";
const videosdkSipPassword = process.env.VIDEOSDK_SIP_PASSWORD || "";

const client = twilio(accountSid, authToken);

export async function POST(request: Request): Promise<Response> {
  try {
    const url = new URL(request.url);
    const meetingId = url.searchParams.get("meetingId");

    const twiml = new twilio.twiml.VoiceResponse();
    twiml.say("Welcome to the Video sdk conference. Connecting you now.");
    twiml.dial().sip(
      {
        username: videosdkSipUsername,
        password: videosdkSipPassword,
      },
      `sip:${meetingId}@sip.videosdk.live`
    );

    return new Response(twiml.toString(), {
      headers: {
        "Content-Type": "text/xml",
      },
    });
  } catch (error) {
    console.error("Error processing Twilio webhook:", error);

    // Return TwiML error response
    const twiml = new twilio.twiml.VoiceResponse();
    twiml.say("Sorry, there was an error connecting your call.");

    return new Response(twiml.toString(), {
      headers: {
        "Content-Type": "text/xml",
      },
    });
  }
}
```

### Outbound Call Setup

For outbound calls, the meeting participant in the web app interacts with an API endpoint that sends a request to Twilio. Twilio establishes the call with the provided number, connecting the phone user back to the meeting through VideoSDK.

```javascript

// Environment variables
const accountSid = process.env.TWILIO_ACCOUNT_SID || "";
const authToken = process.env.TWILIO_AUTH_TOKEN || "";
const twilioPhoneNumber = process.env.NEXT_PUBLIC_TWILIO_PHONE_NUMBER || "";

const client = twilio(accountSid, authToken);

export const dynamic = "force-dynamic";

export async function POST(request: Request): Promise<Response> {
  try {
    const { phoneNumber, meetingId } = await request.json();

    if (!phoneNumber) {
      throw new Error("phone number is required!");
    }

    // Make the outbound call
    const call = await client.calls.create({
      to: phoneNumber,
      from: twilioPhoneNumber,
      url: `${process.env.NEXT_APP_URL}/api/webhook/inbound?meetingId=${meetingId}`,
      method: "POST",
    });

    return new Response(JSON.stringify({ success: true, callSid: call.sid }), {
      headers: {
        "Content-Type": "application/json",
      },
    });
  } catch (error) {
    console.error("Error making outbound call:", error);

    return new Response(
      JSON.stringify({
        success: false,
        error: "Failed to initiate call",
      }),
      {
        status: 500,
        headers: {
          "Content-Type": "application/json",
        },
      }
    );
  }
}
```

**Create an Outbound API**: Write an API function to trigger calls using Twilio’s client instancee.g., `/api/webhook/outbound`)

**Trigger Outbound Calls**: Use this API in your application to handle requests for dialing specific numbers.

When the call is accepted, the system routes it to the VideoSDK SIP address, establishing a connection to the meeting.

## Testing the Integration

To test the setup:

1. Make a call to the Twilio number for inbound calls.
   - Ensure the meeting ID and SIP configurations are correctly passed.
2. Initiate an outbound call from a meeting participant to a phone number.
   - Validate that the phone user is successfully connected to the meeting.

Both inbound and outbound calls should work smoothly, demonstrating the bridged connection between telephony and video conferencing.

## Conclusion

Integrating SIP functionality into your project using VideoSDK and Twilio unlocks new possibilities for communication. By enabling inbound and outbound VoIP calls, you can connect traditional phone systems with modern video conferencing platforms.

This guide covered the basics of setting up the integration, routing calls, and ensuring smooth connectivity. If you encounter any issues or need further help, join the VideoSDK Discord community.

Simplify your users’ communication experience—embrace the power of SIP integration.



---

# SIP Connect - Android





SIP (Session Initiation Protocol) is extensively employed for setting up and controlling IP-based calls. It facilitates the initiation and termination of user sessions over IP networks, enabling SIP-based systems to connect and exchange voice communications over the internet.

With VideoSDK's SIP Connect feature, you can enable your users to join VideoSDK meetings via VOIP using third-party service providers. This allows for establishing a bridge between participants using our client SDKs and those joining via SIP, enhancing the accessibility and connectivity of your video meetings.

![SIP Architecture](https://cdn.videosdk.live/website-resources/docs-resources/sip-architechture.png)

### Getting SIP Credentials

To use SIP Connect, you will first need to generate the credentials for the SIP. Go to the [VideoSDK dashboard](https://app.videosdk.live) and under the [API Keys](https://app.videosdk.live/api-keys) sections, first enable the SIP for the desired API key after which you will be presented with the SIP `username` and `password` you can use to establish connection with our SIP servers.

![SIP Credentials](https://cdn.videosdk.live/website-resources/docs-resources/sip-get-credentials.gif)

### How to use SIP to join a particular meeting?

Once you have the credentials, you can use any of the softphones like Linphone, Zoiper etc. or use a third party service provider like twilio to connect with a VideoSDK meeting by initiating a SIP call to `sip:<meeting-id>@sip.videosdk.live`

For example if you want to connect to `abcd-abcd-abcd` meeting then the SIP address will look like `sip:abcd-abcd-abcd@sip.videosdk.live`

### Example of Twilio PSTN

To utilize third-party PSTN (Public Switched Telephone Network) providers like Twilio for making calls via SIP (Session Initiation Protocol), follow these steps:

1. Log in to your Twilio account and navigate to the Phone Numbers section.
2. Purchase a phone number and access its configuration settings.
3. Set up a Webhook handler that will initiate a call to the VideoSDK SIP endpoint whenever an incoming call is received on the selected phone number.

![SIP Configuration for Twilio](https://cdn.videosdk.live/website-resources/docs-resources/sip-twilio-config.png)

##### Example for creating Webhook using Express

```js
const express = require("express");
const VoiceResponse = require("twilio").twiml.VoiceResponse;
const urlencoded = require("body-parser").urlencoded;

const app = express();

// Parse incoming POST params with Express middleware
app.use(urlencoded({ extended: false }));

// Webhook route which will be called by twilio when a call is received
app.post("/incoming-call-handler", (request, response) => {
  console.log({ request });
  // Use the Twilio Node.js SDK to build an XML response
  const twiml = new VoiceResponse();

  const dial = twiml.dial();
  dial.sip(
    {
      username: "<User name generated for dashboard>",
      password: "<Password generated from dashboard>",
    },
    "sip:<meetingId>@sip.videosdk.live"
  );

  // Render the response as XML in reply to the webhook request
  response.type("text/xml");
  response.send(twiml.toString());
});

//Start the express app on port 8000
app.listen(8000, () => {
  console.log(`Server listening on port ${8000}.`);
});
```



---

# Getting Started - Android SDK

Android SDK is natively written SDK using Java. It is compatible with both Java and Kotlin.

## Install an Android SDK

The easiest way to get started is by installing the sdk in your app.

### Step 1: Add the repositories into your project.

- If your Android Studio Version is older than Android Studio Bumblebees, add the repository to project's `build.gradle` file.
- If your are using Android Studio Bumblebees or newer Version, add the repository to `settings.gradle` file.

:::note

You can use imports with Maven Central after rtc-android-sdk version `0.1.12`.

Whether on Maven or Jitpack, the same version numbers always refer to the same SDK.

:::



**Maven Central:**

```js title="build.gradle"
allprojects {
  repositories {
// ...
google()
mavenCentral()
maven { url "https://maven.aliyun.com/repository/jcenter" }
  }
}
```

```js title="settings.gradle"
dependencyResolutionManagement{
  repositories {
// ...
google()
mavenCentral()
maven { url "https://maven.aliyun.com/repository/jcenter" }
  }
}

```

---

**Jitpack:**

```js title="build.gradle"
allprojects {
  repositories {
// ...
google()
maven { url 'https://jitpack.io' }
mavenCentral()
maven { url "https://maven.aliyun.com/repository/jcenter" }
  }
}
```

```js title="settings.gradle"
dependencyResolutionManagement{
  repositories {
// ...
google()
maven { url 'https://jitpack.io' }
mavenCentral()
maven { url "https://maven.aliyun.com/repository/jcenter" }
  }
}

```

### Step 2: Add the dependency in `app/build.gradle`:

```js title="app/build.gradle"
dependencies {
		implementation 'live.videosdk:rtc-android-sdk:0.3.0'

		// other app dependencies
}
```

:::important

Android SDK compatible with armeabi-v7a, arm64-v8a, x86_64 architectures. If you want to run the application in an emulator, choose ABI x86_64 when creating a device.

:::

### Step 3: Add all the following permissions to AndroidManifest.xml

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

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

```

### Step 4: Create MainApplication class with the following code

**Kotlin:**

```js title="MainApplication.kt"
package live.videosdk.demo;

import live.videosdk.rtc.android.VideoSDK;

class MainApplication : Application() {
  override fun onCreate() {
super.onCreate()

VideoSDK.initialize(applicationContext)
  }
}
```

---

**Java:**

```js title="MainApplication.java"
package live.videosdk.demo;

import android.app.Application;

import live.videosdk.rtc.android.VideoSDK;

public class MainApplication extends Application {
@Override
public void onCreate() {
    super.onCreate();

    VideoSDK.initialize(getApplicationContext());
}
}
```

### Step 5: Add MainApplication to AndroidManifest.xml

```js title="AndroidManifest.xml"
<application
    android:name=".MainApplication"
>
  
</application>
```

:::note

Check out official example of Android SDK implementation for Java and Kotlin as mentioned below: 

- For **Java** Code Sample [Click here](https://github.com/videosdk-live/videosdk-rtc-android-java-sdk-example)<br />
- For **Kotlin** Code Sample [Click here](https://github.com/videosdk-live/videosdk-rtc-android-kotlin-sdk-example)

:::


---

<h1> {props.title} </h1>{" "}

### Why we are using JWT based Token ?

Token based authentication allows users to verify their identity by providing generated API key and secret.

We use JWT token for the authentication purpose because Token-based authentication is **widely used** in modern web applications and APIs because it offers several benefits over traditional authentication. For example, it can **reduce the risk of the credentials being misused**, and it allows for **more fine-grained control** over access to resources. Additionally, tokens can be easily revoked or expired, making it easier to manage access rights.

### How to generate Token ?

To manage secured communication, every participant that connects to the meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key` which you can get from [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

#### 1. Generating token from Dashboard

If you are looking to do **testing or for development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for getting token includes generating it from your backend server which will help in **keeping your credentials safe**.
:::

#### 2. Generating token in your backend

- Your server will generate access token using your API key and secret.
  - While generating a token, you can provide **expiration time, permissions and roles** which are discussed later in this section.
- Your client obtains token from your backend server.
- For token validation, client will pass this token to VideoSDK server.
- VideoSDK server will only allow entry in the meeting if the token is valid.

![img2.png](../../static/img/authentication-and-token.png)




Follow our official example repositories to setup token API [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)

### Payload while generating token

```js
{
 apikey: API_KEY, //MANDATORY
 permissions: [`allow_join`], //`ask_join` || `allow_mod` //MANDATORY
 version: 2, //OPTIONAL
 roomId: ROOM_ID, //OPTIONAL,
 participantId: PARTICIPANT_ID, //OPTIONAL
 roles: ['crawler', 'rtc'], //OPTIONAL
}
```

- **`apikey`(Mandatory)**: This must be the API Key generated from the VideoSDK Dashboard. You can get it from [here](https://app.videosdk.live/api-keys).

- **`permissions`(Mandatory)**: By providing the permissions, you can control what a participant can do in the meeting and whether he can join the meeting directly.

  Available permissions are:

  - **`allow_join`**: The participant is **allowed to join** the meeting directly.
  - **`ask_join`**: The participant is required to **ask for permission to join** the meeting. The participant having the permission `allow_join` can accept or reject a participant whenever someone wants to join.
  - **`allow_mod`**: The participant is **allowed to toggle** webcam & mic of other participants.

- **`version`(optional)**: For accessing the [v2 API](/api-reference/realtime-communication/intro), you need to provide `2` as the version value.

  - For passing `roomId`, `participantId` or `roles` parameters in payload, it is essential to set the version value to `2`.

- **`roomId`(optional)**: To provide customised access control, you can make the token applicable to a particular room by including the `roomId` in the payload.

- **`participantId`(optional)**: You can include the `participantId` in the payload to limit the token's access to a particular participant.

- **`roles`(optional)**:

  - **`crawler`**: This role is only for accessing [v2 API](/api-reference/realtime-communication/intro), you can not use this token for running the `Meeting`/`Room`.
  - **`rtc`**: This role is only allowed for running the `Meeting` / `Room`, with this role you can not use [server-side APIs](/api-reference/realtime-communication/intro).

Then, you have to sign this payload with your **`SECRET KEY`** and `jwt` options using the **`HS256 algorithm`**.

### Expiration time

You can set any expiration time to the token. But in the **production environment**, it is recommended to generate a token with **short expiration time** because by any chance if someone gets hold of the token, it won't be valid for a longer period of time.

### What happens if token is expired?

If your token is expired, the user won't be able to join the meeting and all the API calls will give error with message `Token is invalid or expired`.

:::note
Token is validated only once while joining the meeting, so if a person joins the meeting and the token gets expired after that, there won't be any issue in the current meeting.
:::

## How to check validity of token?

1. After generating the token, visit [jwt.io](https://jwt.io) and paste your token in the given area.
2. You will be able to see the payload you passed while generating the token and also be able to see the expiration time and token creation time.

![img1.png](../../static/img/validate-token.png)

## API Settings & Controls

The VideoSDK Dashboard provides a powerful [API Settings](https://app.videosdk.live/api-keys) section where you can configure various services and controls for your meetings. These settings allow you to customize the behavior of different features directly from the dashboard without requiring code changes.

## Audio/Video Configurations

:::note
Runtime configuration from the dashboard has higher precedence than static SDK configurations.
If a value is modified in the dashboard, it will override any previously defined SDK settings for that session.

Example:
Code: Video = HD → Dashboard: Video = Full HD → Applied: Full HD
:::

### Maximum Send Bitrate Per Participant

Control the maximum total upload bandwidth for all media streams from a single participant.

![Maximum Send Bitrate](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.00.11%E2%80%AFPM.png)

**Available Options:**
- **Auto**: Removes the upload bitrate limit (recommended for best quality)
- **SD (800kbps)**: Standard definition bitrate
- **HD (1500kbps)**: High definition bitrate
- **Full HD (3000kbps)**: Full high definition bitrate

:::tip
Setting this to **Auto** provides the best video quality as it removes upload bitrate constraints, allowing adaptive streaming based on network conditions.
:::

## Recording & Streaming Configuration

:::note
Recording and HLS follow a precedence-based configuration model:

API/SDK configuration → Highest priority
Dashboard configuration → Used only when no API values are defined

Any parameters explicitly set via the API will not be overridden by dashboard changes.
:::

### Recording Configuration

Configure recording settings for your meetings including layout, quality, and auto-start options.

![Recording Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.01.00%E2%80%AFPM.png)

**Recording Controls:**
- **Enabled**: Toggle to enable/disable recording functionality
- **Enabled Modes**: Choose between Video & Audio or Audio Only recording
- **Start Recording Automatically**: Auto-start recording when meeting begins
- **Layout Style**: Select Grid layout for recording composition
- **Maximum Tiles In Grid**: Set the number of participants visible in grid (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme for recordings
- **Video Orientation**: Choose between Landscape or Portrait mode
- **Recording Quality**: Select quality level (e.g., HD Medium)
- **Recording Mode**: Choose between Video & Audio or Audio Only

### HLS Streaming Configuration

Configure HTTP Live Streaming (HLS) settings for broadcasting your meetings.

![HLS Streaming Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.02.18%E2%80%AFPM.png)

**HLS Streaming Controls:**
- **Enabled**: Toggle to enable/disable HLS streaming
- **Enabled Modes**: Choose between Video & Audio or Audio Only streaming
- **Auto Start HLS**: Automatically start HLS when meeting begins
- **Record HLS Stream**: Enable recording of the HLS stream
- **Layout Style**: Select Grid layout for stream composition
- **Maximum Tiles In Grid**: Set the number of participants visible (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme
- **HLS Orientation**: Choose between Landscape or Portrait mode
- **HLS Quality**: Select streaming quality (e.g., HD Medium)
- **HLS Streaming Mode**: Choose between Video & Audio or Audio Only

### Additional Service Controls

Enable or disable additional services for your API key.

![Service Controls](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.08%E2%80%AFPM.png)

**Available Services:**
- **RTMP Output**: Enable RTMP streaming to external platforms
- **SIP Integration**: Enable SIP (Session Initiation Protocol) integration for telephony
- **Realtime Translation**: Enable real-time language translation in meetings

### Transcription & Summary

Configure transcription and domain whitelisting for your API key.

![Transcription Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.50%E2%80%AFPM.png)

**Transcription Controls:**
- **Enabled**: Toggle to enable/disable transcription and summary features
- **Whitelist Domain**: Add domain restrictions for API key usage
  - Enter domain names in the format `https://domain.name`
  - Click "Add Domain" to whitelist specific domains
  - Only whitelisted domains can use this API key
  - When no domains are whitelisted, the API key can be used from any domain


---

# Authentication and Token

VideoSDK uses access tokens for authentication. Using our dashboard ([app.videosdk.live](https://app.videosdk.live/)), anyone can generate access tokens tokens with an API key and secret pair.

- Your backend server will generate access tokens using API Key and secret.
- Your client obtains token from your backend server.
- Your client will pass the token to VideoSDK server.
- VideoSDK client sdk will conncts to the VideoSDK server with available token.
- VideoSDK server will validate the token and accpets your incoming connection.

Here is the simple sequence diagram represents the authentication.


## Generate API Key and Secret

Visit, [app.videosdk.live](https://app.videosdk.live/) to gererate API Key and secret.

![Generate API Key from Dashboard](/img/tutorial/generate-api-key.jpg)

## Generate Access Token

For security, every participant that connects to meeting needs a access token. By substituting `apikey` and `permissions` in it.



**node:**

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

// Need to generate from app.videosdk.live
const API_KEY = "API_KEY_GENERATED";
const SECRET_KEY = "API_SECRET_KEY_GENERATED";

jwt.sign(
  {
apikey: API_KEY,
permissions: ["allow_join"], // Permission to join the meeting
  },
  SECRET_KEY,
  {
algorithm: "HS256",
expiresIn: "24h",
jwtid: uuid4(),
  },
  function (err, token) {
console.log(token);
  }
);
```

---

**python:**

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

api_key = 'api_key_generated'
secret_key = 'secret_key_generated'


def generateToken():
expires = 24 * 3600
now = datetime.datetime.utcnow()
exp = now + datetime.timedelta(seconds=expires)
return jwt.encode(payload={
      'apikey': api_key,
      permissions: ["allow_join"]
    }, key=secret_key).decode('utf-8')

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

---

**java:**

```js
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("apikey", "<api_key_generated>");
payload.put("permissions", ["allow_join"]);
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, "<secret_key_generated>".getBytes()).compact();
  }
```

---

**ruby:**

```js
require 'jwt'
require 'securerandom'

$api_key = "api_key_generated"
$secret_key = "secret_key_generated"

def generateToken()
payload = {
  apikey: $api_key,
  permissions: ["allow_join"]
}
token = JWT.encode(payload, $secret_key, 'HS256')
return token
end

puts generateToken
```

---

**php:**

```js
<?php

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

$api_key = "api_key_generated";
$secret_key = "secret_key_generated"

$payload = [
'apikey' => api_key,
'permissions': ["allow_join"],
];

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

Available permissions are:

- **allow_join**: The participant will be permitted entry without request.
- **ask_join**: The participant will not be permitted entry without request.
- **allow_mod**: Allow participant to enable/disable other participant's mic/webcam.


---

# Chat using PubSub - Android

For the communication or any kind of messaging in between the participants, VideoSDK provides `pubSub` class which use Publish-Subscribe mechanism and can be used to develope wide varitey of functionalities. For example, participants could use it to send chat messages to each other, share files or other media, or even trigger actions like muting or unmuting audio or video.

Now we will see, how we can use PubSub to implement Chat functionality. If you are not familiar with the PubSub mechanism and `pubSub` class, you can [follow this guide](./pubsub).

## Implementing Chat

### `Group Chat`

1. First step in creating a group chat is choosing the topic which all the participants will publish and subscribe to send and receive the messages. We will be using `CHAT` as the topic for this one.
2. On the send button, publish the message that the sender typed in the `EditText` field.



**Kotlin:**

```js
import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.view.View
import android.widget.EditText
import android.widget.Toast
import androidx.appcompat.widget.Toolbar
import live.videosdk.rtc.android.Meeting
import live.videosdk.rtc.android.listeners.PubSubMessageListener
import live.videosdk.rtc.android.model.PubSubPublishOptions

class ChatActivity : AppCompatActivity() {
  // Meeting
  var meeting: Meeting? = null

  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_chat)

/**
 * Here, we have created 'MainApplication' class, which extends android.app.Application class.
 * It has Meeting property and getter and setter methods of Meeting property.
 * In your android manifest, you must declare the class implementing android.app.Application
 * (add the android:name=".MainApplication" attribute to the existing application tag):
 * In MainActivity.kt, we have set Meeting property.
 *
 * For Example: (MainActivity.kt)
 * var meeting = VideoSDK.initMeeting(context, meetingId, ParticipantName, micEnabled, webcamEnabled, paricipantId, mode, multiStream, customTrack, metaData, signalingBaseUrl,preferredProtocol)
 * (this.application as MainApplication).meeting = meeting
*/

// Get Meeting
meeting = (this.application as MainApplication).meeting

findViewById(R.id.btnSend).setOnClickListener(view -> sendMessage());
  }

  private fun sendMessage() {
// get message from EditText
val message: String = etmessage.getText().toString()
if (!TextUtils.isEmpty(message)) {
    val publishOptions = PubSubPublishOptions()
    publishOptions.setPersist(true)

    // Sending the Message using the publish method
    //highlight-next-line
    meeting!!.pubSub.publish("CHAT", message, publishOptions)

    // Clearing the message input
    etmessage.setText("")
} else {
    Toast.makeText(
        this@ChatActivity, "Please Enter Message",
        Toast.LENGTH_SHORT
    ).show()
}
  }
}
```

---

**Java:**

```js
import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import java.util.List;
import live.videosdk.rtc.android.Meeting;
import live.videosdk.rtc.android.lib.PubSubMessage;
import live.videosdk.rtc.android.listeners.PubSubMessageListener;
import live.videosdk.rtc.android.model.PubSubPublishOptions;

public class ChatActivity extends AppCompatActivity {
  // Meeting
  Meeting meeting;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_chat);

/**
 * Here, we have created 'MainApplication' class, which extends android.app.Application class.
 * It has Meeting property and getter and setter methods of Meeting property.
 * In your android manifest, you must declare the class implementing android.app.Application
 * (add the android:name=".MainApplication" attribute to the existing application tag):
 * In MainActivity.java, we have set Meeting property.
 *
 * For Example: (MainActivity.java)
 * Meeting meeting = VideoSDK.initMeeting(context, meetingId, ParticipantName, micEnabled, webcamEnabled, participantId, mode, multiStream, customTrack,metaData, signalingBaseUrl,preferredProtocol);
 * ((MainApplication) this.getApplication()).setMeeting(meeting);
*/

// Get Meeting
meeting = ((MainApplication) this.getApplication()).getMeeting();

findViewById(R.id.btnSend).setOnClickListener(view -> sendMessage());
  }

  private void sendMessage()
  {
// get message from EditText
String message = etmessage.getText().toString();
if (!message.equals("")) {
    PubSubPublishOptions publishOptions = new PubSubPublishOptions();
    publishOptions.setPersist(true);

    // Sending the Message using the publish method
    //highlight-next-line
    meeting.pubSub.publish("CHAT", message, publishOptions);

    // Clearing the message input
    etmessage.setText("");
} else {
    Toast.makeText(ChatActivity.this, "Please Enter Message",
            Toast.LENGTH_SHORT).show();
}
  }
}
```

3. Next step would be to display the messages others send. For this we have to `subscribe` to that topic i.e `CHAT` and display all the messages.

**Kotlin:**

```js
class ChatActivity : AppCompatActivity() {

  // PubSubMessageListener
  //highlight-start
val pubSubMessageListener = object : PubSubMessageListener {
    override fun onMessageReceived(message: PubSubMessage) {
        Log.d("VideoSDK", "onMessageReceived: ${message.message}")
    }
    override fun onOldMessagesReceived(messages: List<PubSubMessage>) {
        // Persisted message list
        Log.d("VideoSDK", "onOldMessagesReceived: $messages")
    }
}
  //highlight-end

  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_chat)

//...

// Subscribe for 'CHAT' topic
//highlight-next-line
meeting!!.pubSub.subscribe("CHAT", pubSubMessageListener)
  }
}
```

---

**Java:**

```js
public class ChatActivity extends AppCompatActivity {

  // PubSubMessageListener
  //highlight-start
  PubSubMessageListener pubSubMessageListener = new PubSubMessageListener() {
    @Override
    public void onMessageReceived(PubSubMessage message) {
        Log.d("VideoSDK", "onMessageReceived: " + message.getMessage());
    }
    
    @Override
      public void onOldMessagesReceived(List<PubSubMessage> messages) {
      // Persisted message list
      Log.d("VideoSDK", "onOldMessagesReceived: " + messages);
    }
};
  //highlight-end

  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_chat);

//..

// Subscribe for 'CHAT' topic
//highlight-next-line
meeting.pubSub.subscribe("CHAT", pubSubMessageListener);
  }
}
```

4. Final step in the group chat would be `unsubscribe` to that topic, which you had previously subscribed but no longer needed. Here we are `unsubscribe` to `CHAT` topic on activity destroy.

**Kotlin:**

```js
class ChatActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_chat)

//...
  }

  override fun onDestroy() {
// Unsubscribe for 'CHAT' topic
//highlight-next-line
meeting!!.pubSub.unsubscribe("CHAT", pubSubMessageListener)
super.onDestroy()
  }
}
```

---

**Java:**

```js
public class ChatActivity extends AppCompatActivity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_chat);

//..
  }

  @Override
  protected void onDestroy() {
// Unsubscribe for 'CHAT' topic
//highlight-next-line
meeting.pubSub.unsubscribe("CHAT", pubSubMessageListener);
super.onDestroy();
  }
}
```

### `Private Chat`

In the above example, if you want to convert into the private chat between two participants, then all you have to do is pass `sendOnly` parameter in `PubSubPublishOptions`.

**Kotlin:**

```js
class ChatActivity : AppCompatActivity() {

  //..
  
  private fun sendMessage() {
// get message from EditText
val message: String = etmessage.getText().toString()
if (!TextUtils.isEmpty(message)) {
    val publishOptions = PubSubPublishOptions()
    publishOptions.setPersist(true)
    //highlight-start
    // Pass the participantId of the participant to whom you want to send the message.
    var sendOnly: Array<String> = arrayOf("xyz")
    publishOptions.setSendOnly(sendOnly);
    //highlight-end

    // Sending the Message using the publish method
    //highlight-next-line
    meeting!!.pubSub.publish("CHAT", message, publishOptions)

    // Clearing the message input
    etmessage.setText("")
} else {
    Toast.makeText(
        this@ChatActivity, "Please Enter Message",
        Toast.LENGTH_SHORT
    ).show()
}
  }
}
```

---

**Java:**

```js
public class ChatActivity extends AppCompatActivity {
 
  //...

  private void sendMessage()
  {
// get message from EditText
String message = etmessage.getText().toString();
if (!message.equals("")) {
    PubSubPublishOptions publishOptions = new PubSubPublishOptions();
    publishOptions.setPersist(true);
    //highlight-start
    // Pass the participantId of the participant to whom you want to send the message.
    String[] sendOnly = {
      "xyz" 
    };
    publishOptions.setSendOnly(sendOnly);
    //highlight-end

    // Sending the Message using the publish method
    //highlight-next-line
    meeting.pubSub.publish("CHAT", message, publishOptions);

    // Clearing the message input
    etmessage.setText("");
} else {
    Toast.makeText(ChatActivity.this, "Please Enter Message",
            Toast.LENGTH_SHORT).show();
}
  }
}
```

### Downloading Chat Messages

All the messages from the PubSub which where published with `persist : true` and can be downloaded as an `.csv` file. This file will be available in the VideoSDK dashboard as well as throught the [Sessions API](/api-reference/realtime-communication/fetch-session-using-sessionid).

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub()](/android/api/sdk-reference/pubsub-class/introduction)


---

# PubSub - Android

PubSub is a short acronym for Publish-Subscribe mechanism. This mechanism is used to send and recieve messages from a particular topic. As the name suggests, for someone to send a message, they have to specify the topic and the message which should be published and for someone to receive a message, they should be subscribed to that topic.

Here is a visual to better understand publish-subscribe mechanism.

![pubsub](/img/pubsub.png)

## pubSub

In order to use PubSub in meeting, VideoSDK provides a class `pubSub` which allows you to subscribe to any topic and publish to any topic allowing to pass on messages and instructions during the meeting easily.

### `publish()`

- This method is used for publishing message of specific topic.
- This method can be accessed from the `pubSub` class, which is subclass of `Meeting` class.
- This method will accept following parameters as input:
  - `topic`: This will be the topic for which you are publishing a message.
  - `message`: This will be the actual message to be published. It has to be in `String` format.
  - `options`: This is an object of `PubSubPublishOptions` which specifies the options for publish. `PubSubPublishOptions` has 2 properties.
    - `persist` : `persist` offered the option of keeping the message around for the duration of the session. When `persist` is set to `true`, that message will be retained for upcoming participants and will be available in [VideoSDK Session Dashboard](https://app.videosdk.live/meetings/sessions) with `.CSV` format after completion of session.
    - `sendOnly`: If you want to send a message to specific participants, you can pass their respective `participantId` in form of `String[]`. If you don't provide any IDs or pass a `null` value, the message will be sent to all participants by default. This is optional parameter.
  - `payload`: If you need to include additional information along with a message, you can pass here as `JSONObject`. This is optional parameter.



**Kotlin:**

```js
private fun sendMessage() {
  // publish message
  val options = PubSubPublishOptions()
  options.isPersist = true
  //highlight-next-line
  meeting!!.pubSub.publish("CHAT", "Hello Everyone!", options)
}
```

---

**Java:**

```js
protected void sendMessage() {
  // publish message
  PubSubPublishOptions options = new PubSubPublishOptions();
  options.setPersist(true);
  //highlight-next-line
  meeting.pubSub.publish("CHAT", "Hello Everyone!", options);
}
```

### `subscribe()`

- This method is used to subscribe for particular topic.
- This method will accept two parameters as input:

  - `topic`: This will be the topic to be subscribed.
  - `listener`: This is an object of `PubSubMessageListener`, which listens for old messages & upcoming messages and calls `onOldMessagesReceived` & `onMessageReceived` function, when old messages or new message received.

The object of `PubSubMessage` contains following properties:

- `senderId`: This represents the `participantId` of the participant who send the message.
- `senderName`: This represents the `displayName` of the participant who send the message.
- `message`: This will be the actual message that was send.
- `timestamp`: This wil the timestamp for when the message was published.
- `topic`: This will be the name of the topic message was published to.
- `payload`: This will be the data that you have send with message.

**Kotlin:**

```js
//highlight-start
val pubSubMessageListener = object : PubSubMessageListener {
override fun onMessageReceived(message: PubSubMessage) {
    Log.d("#message", "onMessageReceived: ${message.message}")
}
override fun onOldMessagesReceived(messages: List<PubSubMessage>) {
    // Persisted message list
    Log.d("#message", "onOldMessagesReceived: $messages")
}
}
//highlight-end

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // Subscribe for 'CHAT' topic
  //highlight-next-line
  meeting!!.pubSub.subscribe("CHAT", pubSubMessageListener)
}
```

---

**Java:**

```js
//highlight-start
PubSubMessageListener pubSubMessageListener = new PubSubMessageListener() {
@Override
public void onMessageReceived(PubSubMessage message) {
    Log.d("#message", "onMessageReceived: " + message.getMessage());
}

@Override
  public void onOldMessagesReceived(List<PubSubMessage> messages) {
  // Persisted message list
  Log.d("#message", "onOldMessagesReceived: " + messages);
}
};
//highlight-end

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // Subscribe for 'CHAT' topic
  //highlight-next-line
  meeting.pubSub.subscribe("CHAT",pubSubMessageListener);
}
```

### `unsubscribe()`

- This method is used to unsubscribe for particular topic.
- This method will accept two parameters as input:

  - `topic`: This will be the topic to be unsubscribed.
  - `listener`: This is an object of `PubSubMessageListener`, which was passed in `subscribe()`.

**Kotlin:**

```js
fun unsubscribe() {
  // Unsubscribe 'CHAT' topic
  meeting!!.pubSub.unsubscribe("CHAT", pubSubMessageListener)
}
```

---

**Java:**

```js
public void unsubscribe(){
  // Unsubscribe 'CHAT' topic
  meeting.pubSub.unsubscribe("CHAT", pubSubMessageListener);
}
```

## Applications of usePubSub

PubSub is a very powerful mechanism which can be used to do alot of things which can make your meeting experience much more interactive. Some of the most common usecase that we have come across for the PubSub during a meeting are listed below:

1. [`Chat`](./chat-using-pubsub): You can utilise this to develop various Chat features, such as Private Chat and Group Chat. You can follow our chat [integration guide here](./chat-using-pubsub).
2. `Raise Hand`: You can allow attendees to raise their hands at any time during the meeting, informing everyone else that someone has done so.
3. `Poll`: You may make polls, let users respond to them, and display the results at the end of a poll.
4. `Question Answer Session`: You can also design interactive functionality that is question-and-answer based.

### Downloading PubSub Messages

All the messages from the PubSub which were published with `persist : true` and can be downloaded as an `.csv` file. This file will be available in the VideoSDK dashboard as well as throught the [Sessions API](/api-reference/realtime-communication/fetch-session-using-sessionid).

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub()](/android/api/sdk-reference/pubsub-class/introduction)


---

# Raise Hand using PubSub - Android

Let us see, how we can use PubSub to implement Raise Hand functionality. If you are not familiar with the PubSub mechanism and `pubSub` class, you can [follow this guide](./pubsub).

## Implementing Raise Hand

1. First step in raise hand is choosing the topic which all the participants will publish and subscribe to know some participant raise their hand. We will be using `RAISE_HAND` as the topic for this one.
2. On the raiseHand button, publish any message to that specific topic.



**Kotlin:**

```js
class MainActivity : AppCompatActivity() {

  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)

//...

findViewById(R.id.btnRaiseHand).setOnClickListener(view -> sendRaiseHandMessage());
  }

  private fun sendRaiseHandMessage() {
val publishOptions = PubSubPublishOptions()
publishOptions.setPersist(false)

// Sending the Message using the publish method
//highlight-next-line
meeting!!.pubSub.publish("RAISE_HAND", "Raise Hand", publishOptions)
  }
}
```

---

**Java:**

```js
public class MainActivity extends AppCompatActivity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_chat);

//...

findViewById(R.id.btnRaiseHand).setOnClickListener(view -> sendRaiseHandMessage());
  }

  private void sendRaiseHandMessage()
  {
PubSubPublishOptions publishOptions = new PubSubPublishOptions();
publishOptions.setPersist(false);

// Sending the Message using the publish method
//highlight-next-line
meeting.pubSub.publish("RAISE_HAND", "Raise Hand", publishOptions);
  }
}
```

3. Now let us show an alert to all the participants showing who raised the hand.

**Kotlin:**

```js
class MainActivity : AppCompatActivity() {

  // PubSubMessageListener
  //highlight-start
val pubSubMessageListener = object : PubSubMessageListener {
    override fun onMessageReceived(message: PubSubMessage) {
        Log.d("VideoSDK", "RAISE_HAND: ${message.message}")
    }
    override fun onOldMessagesReceived(messages: List<PubSubMessage>) {
        // Persisted message list
        Log.d("VideoSDK", "RAISE_HAND: $messages")
    }
}
  //highlight-end

  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_chat)

//...

// Subscribe for 'RAISE_HAND' topic
//highlight-next-line
meeting!!.pubSub.subscribe("RAISE_HAND", pubSubMessageListener)
  }
}
```

---

**Java:**

```js
public class MainActivity extends AppCompatActivity {

  // PubSubMessageListener
  //highlight-start
PubSubMessageListener pubSubMessageListener = new PubSubMessageListener() {
    @Override
    public void onMessageReceived(PubSubMessage message) {
        Log.d("VideoSDK", "RAISE_HAND: " + message.getMessage());
    }
    
    @Override
      public void onOldMessagesReceived(List<PubSubMessage> messages) {
      // Persisted message list
      Log.d("VideoSDK", "RAISE_HAND: " + messages);
    }
};
  //highlight-end

  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

//..

// Subscribe for 'RAISE_HAND' topic
//highlight-next-line
meeting.pubSub.subscribe("RAISE_HAND", pubSubMessageListener);
  }
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub()](/android/api/sdk-reference/pubsub-class/introduction)


---

# Realtime Store - Android

The **Realtime Store** allows you to store, update, retrieve, and observe custom key-value data within a meeting — in real time. It acts as a shared data layer across all connected participants, ensuring synchronized states throughout the session.

This is particularly useful for collaborative or stateful meeting experiences such as:

- Pinned messages and flags
- Moderation data (e.g., blocked users)
- Collaborative notes or polls

## `set()`

The `set()` method is used to store or update data in the RealtimeStore. If a key already exists, it will be overwritten with the new value. Passing `null` as the value deletes the key.

### Key Notes

- Supports **String** values only.
- Each key can store up to **1 KB** of data.
- A maximum of **100 keys** are allowed per session.
- Deletion is performed by setting the value to `null`.
- Throws an error if:
  - The key is missing or empty.
  - The request fails.
  - The session exceeds the 100-key limit.

### Parameters

- **`key`** (`String`)  
  The unique key to store the data under.

- **`value`** (`String?`)  
  The string value to be stored. Pass `null` to delete the key.

- **`callback`** (`RealtimeStoreCallback<String>`)  
  The callback will trigger `onSuccess()` or `onError()` with `String` type.

### Example



**Kotlin:**

```kotlin
meeting.realtimeStore.set("YOUR_KEY", message, object : RealtimeStoreCallback<String> {
override fun onSuccess(value: String) {
    Log.d("VideoSDK", "Value: $value")
}

override fun onError(error: String) {
    Log.e("VideoSDK", "Error: $error")
}
})
```

---

**Java:**

```java
meeting.realtimeStore.set("YOUR_KEY", message, new RealtimeStoreCallback<String>() {
@Override
public void onSuccess(String value) {
    Log.d("VideoSDK", "Value: " + value);
}

@Override
public void onError(String error) {
    Log.e("VideoSDK", "Error: " + error);
}
});
```


---

## `get()`

The `get()` method retrieves the current value associated with a given key.

### Key Notes

- Returns the current string value for the given key.
- Useful for fetching shared state when joining a meeting or reloading a view.
- Throws an error if the key is missing/empty or if the request fails.

### Parameters

- **`key`** (`String`)  
  The key whose value you want to retrieve.

- **`callback`** (`RealtimeStoreCallback<String>`)  
The callback will trigger `onSuccess` or `onError` with `String` type.

### Example

**Kotlin:**

```kotlin
meeting.realtimeStore.get("YOUR_KEY", object : RealtimeStoreCallback<String> {
  override fun onSuccess(value: String) {
Log.d("VideoSDK", "Value: $value")
  }

  override fun onError(error: String) {
Log.e("VideoSDK", "Error: $error")
  }
})
```

---

**Java:**

```java
meeting.realtimeStore.get("YOUR_KEY", new RealtimeStoreCallback<String>() {
@Override
public void onSuccess(String value) {
    Log.d("VideoSDK", "value: " + value);
}

@Override
public void onError(String error) {
    Log.e("VideoSDK", "Error: " + error);
}
});
```

---

## `observe()`

The `observe()` method subscribes to real-time updates for a given key. When the key’s value changes, a delegate method on your listener is automatically triggered for all connected participants.

### Key Notes

- You register a listener object that conforms to the `RealtimeStoreListener` protocol.
- The delegate method receives the new value and information about who updated it.
- Ideal for syncing live data like timers, shared notes, or agendas.

### Parameters

- **`key`** (`String`)  
  The key to observe.

- **`callback`** (`RealtimeStoreListener<String>`)  
  The callback will trigger `onValueChanged` with `String` newValue and `Participant` who updated the value.

### Example


**Kotlin:**

```kotlin
val realtimeStoreListener = object : RealtimeStoreListener {
  override fun onValueChanged(newValue: String, updatedBy: Participant?) {
  Log.d("VideoSDK", "onValueChange: Received update from: ${updatedBy.displayName}")
  Log.d("VideoSDK", "onValueChange: Received update from: ${updatedBy.id}")
  Log.d("VideoSDK", "onValueChange: New Value -> $newValue")
  }
}

meeting.realtimeStore.observe(KEY_CHAT_HISTORY, realtimeStoreListener!!)
```

---

**Java:**

```java
private RealtimeStoreListener realtimeStoreListener;

realtimeStoreListener = new RealtimeStoreListener() {

@Override
  public void onValueChanged(String newValue, Participant updatedBy) {
  Log.d("VideoSDK", "onValueChange: Received update from: " + updatedBy.getDisplayName());
  Log.d("VideoSDK", "onValueChange: Received update from: " + updatedBy.getId());
  Log.d("VideoSDK", "onValueChange: New Value -> " + newValue);
  }
};

meeting.realtimeStore.observe(KEY_CHAT_HISTORY, realtimeStoreListener);
```

---

## `stopObserving()`

Stops receiving updates for a specific key and listener combination.

### Key Notes

- Should be called when the listener is no longer needed (e.g., when the view/ui controller is deallocated).

### Parameters

- **`key`** (`String`)  
  The key you want to stop observing.
  
- **`callback`** (`RealtimeStoreListener<String>`)  
  The callback/listener will be removed from list of listeners

### Example

**Kotlin:**

```kotlin
meeting.realtimeStore.stopObserving("YOUR_KEY", realtimeStoreListener)
```

---

**Java:**

```java
meeting.realtimeStore.stopObserving("YOUR_KEY", realtimeStoreListener);
```

---

### Error Handling & Constraints

| Property           | Description                                                                  |
| ------------------ |------------------------------------------------------------------------------|
| **Error Handling** | All errors will be handled in onError() callback. |
| **Payload Size**   | Maximum **1 KB per key**.                                                    |
| **Supported Type** | Only `String` values are supported. Use `null` to delete key.                |
| **Concurrency**    | The latest write overwrites previous values (last write wins)                |
| **Key Limit**      | A maximum of 100 keys are allowed in a single session.                       |


# API Reference

The API references for this page are provided below.


- [set()](/android/api/sdk-reference/realtime-store/methods#set)
- [get()](/android/api/sdk-reference/realtime-store/methods#get)
- [observe()](/android/api/sdk-reference/realtime-store/methods#observe)
- [stopObserving()](/android/api/sdk-reference/realtime-store/methods#stopobserving)


---

# Render Whiteboard - Android

This guide explains how to dynamically render a whiteboard in your Android application.

## Setup WebView

- The whiteboard is rendered using a `WebView` component.
- You can configure the required XML style using the following code

```js

```

## Render the Whiteboard

You can start the whiteboard with `meeting.startWhiteboard()` method, which triggers the `onWhiteboardStarted()` event. The event provides the URL to load in the WebView for rendering. To stop it, call `meeting.stopWhiteboard()`, which triggers the `onWhiteboardStopped()` event.



**Kotlin:**

```js
class MeetingActivity : AppCompatActivity() {

private lateinit var meeting: Meeting
private lateinit var webView: WebView

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_meeting)

    webView = findViewById(R.id.webView)

    // Init and config meeting
    // meeting = ...

    meeting.addEventListener(meetingEventListener);

    val meetingEventListener = object : MeetingEventListener() {
        override fun onWhiteboardStarted(url: String) {
            super.onWhiteboardStarted(url)
            webView.loadUrl(url)
            webView.settings.javaScriptEnabled = true
            webView.webViewClient = WebViewClient()
        }

        override fun onWhiteboardStopped() {
            super.onWhiteboardStopped()
            //...
        }
    }

    findViewById<View>(R.id.btnStartWhiteboard).setOnClickListener {
        meeting.startWhiteboard()
    }

    findViewById<View>(R.id.btnStopWhiteboard).setOnClickListener {
        meeting.stopWhiteboard()
    }
}
}
```

---

**Java:**

```js
public class MeetingActivity extends AppCompatActivity {

private Meeting meeting;
private WebView webView ;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    //...

    webView = findViewById(R.id.webView);
    /* 
    init and config meeting ...
    meeting = //...
    */
    meeting.addEventListener(meetingEventListener);
    
    final MeetingEventListener meetingEventListener = new MeetingEventListener() {
        //...
        @Override
        public void onWhiteboardStarted(String url) {
            super.onWhiteboardStarted(url);
            webView.loadUrl(url);
            webView.getSettings().setJavaScriptEnabled(true);
            webView.setWebViewClient(new WebViewClient());
        }

        @Override
        public void onWhiteboardStopped() {
            super.onWhiteboardStopped();
            //...
        }
    };

    findViewById(R.id.btnStartWhiteboard).setOnClickListener(v -> {
        meeting.startWhiteboard();
    });

    findViewById(R.id.btnStopWhiteboard).setOnClickListener(v -> {
        meeting.stopWhiteboard();
    });
}
}
```


## API Reference

- [startWhiteboard()](/android/api/sdk-reference/meeting-class/methods#startwhiteboard)
- [stopWhiteboard()](/android/api/sdk-reference/meeting-class/methods#stopwhiteboard)
- [onWhiteboardStarted()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onwhiteboardstarted)
- [onWhiteboardStopped()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onwhiteboardstopped)




---

---
title: Upload & Fetch Temporary File | Video SDK
hide_title: true
hide_table_of_contents: false
description: Upload & Fetch Temporary File.
sidebar_label: File Sharing
pagination_label: Upload-Fetch Temporary File
keywords:
  - upload temporary file
  - fetch temporary file
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: upload-fetch-temporary-file
--- 

# Upload and Retrieve the Temporary File - Android

This guide demonstrates how to upload and retrieve files from VideoSDK's temporary file storage system.

### `uploadBase64File()`

- By using the `uploadBase64File()` method of the [`Meeting`](/android/api/sdk-reference/meeting-class/introduction) class, you can upload your file to Videosdk's Temporary storage.

- The `uploadBase64File()` method only works with `base64`. Therefore, it is necessary to convert your file into `base64` format.

- You have to pass `base64Data`,`token`,`fileName` and implementation of `TaskCompletionListener` as parameter in `uploadBase64File()` method.

- When the upload is complete, the `onComplete()` method of `TaskCompletionListener` will provide the corresponding `fileUrl`, which can be used to retrieve the uploaded file.

- If an error occurs during the upload process, the `onError()` method of `TaskCompletionListener` will provide the error details.



**Kotlin:**

```js
private fun uploadFile() {
  val base64Data = "<Your File's base64>" // Convert your file to base64 and pass here
  val token = "<VIDEOSDK_TOKEN>"
  val fileName = "myImage.jpeg" // Provide name with extension here
  meeting!!.uploadBase64File(
base64Data,
token,
fileName,
object : TaskCompletionListener<String?, String?> {
  override fun onComplete(data: String?) {
      Log.d("VideoSDK", "Uploaded file url: $data")
  }

  override fun onError(error: String?) {
      Log.d("VideoSDK", "Error in upload file: $error")
  }
}
  )
}
```

---

**Java:**

```js
private void uploadFile() {
  String base64Data = "<Your File's base64>"; // Convert your file to base64 and pass here
  String token = "<VIDEOSDK_TOKEN>";
  String fileName = "myImage.jpeg"; // Provide name with extension here
  meeting.uploadBase64File(base64Data, token, fileName, new TaskCompletionListener<String, String>() {
@Override
public void onComplete(@Nullable String data) {
    Log.d("VideoSDK", "Uploaded file url: " + data);
}

@Override
public void onError(@Nullable String error) {
    Log.d("VideoSDK", "Error in upload file: " + error);
}
  });
}
```


### `fetchBase64File()`

- By using the `fetchBase64File()` method of the [`Meeting`](/android/api/sdk-reference/meeting-class/introduction) class, you can retrieve your file from Videosdk's Temporary storage.

- To retrieve a file, you need to pass the `fileUrl` (which is returned by the `uploadBase64File()` method), the `token`, and an implementation of the `TaskCompletionListener` as parameters.

- When the fetch operation is complete, the `onComplete()` method of `TaskCompletionListener` will provide the file in `base64` format.

- If an error occurs during the fetch operation, the `onError()` method of `TaskCompletionListener` will provide the error details.

**Kotlin:**

```js
private fun fetchFile() {
  val url = "<Your FileUrl>"  // Provide fileUrl which is returned by uploadBase64File()
  val token = "<VIDEOSDK_TOKEN>"
  meeting.fetchBase64File(url, token, object : TaskCompletionListener<String?, String?> {
  override fun onComplete(data: String?) {
      Log.d("VideoSDK", "Fetched file in base64:$data")
  }

  override fun onError(error: String?) {
      Log.d("VideoSDK", "Error in fetch file: $error")
  }
  })
}
```

---

**Java:**

```js
private void fetchFile() {
  String url = "<Your FileUrl>";  // Provide fileUrl which is returned by uploadBase64File()
  String token = "<VIDEOSDK_TOKEN>";
  meeting.fetchBase64File(url, token, new TaskCompletionListener<String, String>() {
  @Override
  public void onComplete(@Nullable String data) {
      Log.d("VideoSDK", "Fetched file in base64:" + data);
  }

  @Override
  public void onError(@Nullable String error) {
      Log.d("VideoSDK", "Error in fetch file: " + error);
  }
  });
}
```


:::note

The file stored in the system will be automatically deleted once the current room/meeting comes to an end.

:::

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [uploadBase64File()](/android/api/sdk-reference/meeting-class/methods#uploadbase64file)
- [fetchBase64File()](/android/api/sdk-reference/meeting-class/methods#fetchbase64file)

---

# Whiteboard - Android

The Whiteboard is an interactive, shared canvas that enables users to collaborate in real-time within your Android application. It allows multiple participants to draw, write, and add annotations simultaneously, making it ideal for meetings, presentations, brainstorming sessions, and other collaborative activities.

This documentation will guide you on how to start and stop the whiteboard, and handle the necessary events to ensure a smooth user experience.

## `startWhiteboard()`

- To start the whiteboard session, you can call the `startWhiteboard()` method of the `meeting` class, which initializes the whiteboard and makes it available for user interaction.

### Events associated with startWhiteboard

- All participants will receive the `onWhiteboardStarted` event from the `MeetingEventListener` when the whiteboard starts successfully. This event provides a URL that can be used to render and interact with the whiteboard within the app.

- The whiteboard URL can be displayed using a `WebView` component, allowing participants to interact seamlessly within the app. For detailed instructions on rendering the whiteboard, refer to this [guide](/android/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/render-whiteboard).




**Kotlin:**

```js
val meetingEventListener = object : MeetingEventListener() {
override fun onWhiteboardStarted(url: String) {
    super.onWhiteboardStarted(url)
    //...
}
//...
meeting!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```js
final MeetingEventListener meetingEventListener = new MeetingEventListener() {
@Override
public void onWhiteboardStarted(String url) {
    super.onWhiteboardStarted(url);
    //...
}
//...
meeting!!.addEventListener(meetingEventListener)
};
```

## `stopWhiteboard()`

- To end the whiteboard session, you can call the `stopWhiteboard()` method of the `meeting` class, which terminates the active whiteboard and cleans up any resources associated with it.

### Events associated with stopWhiteboard

- All participants will receive the `onWhiteboardStopped` event from the `MeetingEventListener` when the whiteboard session is successfully terminated. This event signals that the whiteboard is no longer available for interaction within the app.

**Kotlin:**

```js
val meetingEventListener = object : MeetingEventListener() {
override fun onWhiteboardStopped() {
    super.onWhiteboardStopped()
    //...
}
//...
meeting!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```js
final MeetingEventListener meetingEventListener = new MeetingEventListener() {
@Override
public void onWhiteboardStopped() {
    super.onWhiteboardStopped();
    //...
}
//...
meeting!!.addEventListener(meetingEventListener)
};
```


## API Reference

- [startWhiteboard()](/android/api/sdk-reference/meeting-class/methods#startwhiteboard)
- [stopWhiteboard()](/android/api/sdk-reference/meeting-class/methods#stopwhiteboard)
- [onWhiteboardStarted()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onwhiteboardstarted)
- [onWhiteboardStopped()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onwhiteboardstopped)




---

# What is SurfaceViewRender ?

`SurfaceViewRender` is a very powerful component of `WebRTC` since it is used to display the video stream on a SurfaceView. You can use `SurfaceViewRender` to show video of participant in your screen.

Here's the lifecycle of a SurfaceViewRenderer:

<div style={{textAlign: 'center'}}>

<img style={{height: '200px'}} src="/img/android/VideoView/life-cycle.png" />

</div>

Which means:

1. The SurfaceViewRenderer must be first initialised after being created and before it can be use at all. It starts a render thread.

2. `addSink()` needs to be called when you are having VideoTrack to render. addSink is method of `VideoTrack` that you want to add to it. You have to pass `surfaceViewRender` as parameter.

3. `removeSink()` should only be called when you're done showing the video. Another method of `VideoTrack`, and it takes the `surfaceViewRenderer` as a parameter.

4. Release at last to allow the render thread to terminate. This function should be called before the activity is destroyed and/or before init it again.

#### Mistakes you might make and stuck :

###### 1. Not initialised surfaceViewRender

The video never appears since a render thread was never start and you will see black view.

###### 2. Init it again before releasing it.

If you are not releasing surfaceViewRender before calling `init()` again, you will get this error.

```js
java.lang.IllegalStateException: svrParticipant Already initialized
        at org.webrtc.EglRenderer.init(EglRenderer.java:212)
```

###### 3. Two videos render on same SurfaceViewRender

If you called `addSink()` on the same `SurfaceViewRenderer` for two different tracks and did not call `removeSink` before that, then you will see two different videos on same SurfaceViewRenderer with flickers which would look like this :


<div style={{textAlign: 'center'}}>



</div>

<br/>

Too complicated right? However, VideoSDK makes it simple for you. You can use `VideoView` instead of `SurfaceViewRenderer`.

:::info

- If you want to use `VideoView`, please update SDK version to `0.1.13` or higher.

:::

### VideoView

`VideoView` provides a better abstraction to render live video and handles edge cases like managing init state, render more than one videos on same surfaceViewRender.

### Methods

1. **addTrack(VideoTrack videoTrack)** - `addTrack` will initialised SurfaceViewRender for you and render videoTrack that you provided.

2. **removeTrack()** - `removeTrack` should only be called when you're done showing the video.

3. **releaseSurfaceViewRenderer()** - `releaseSurfaceViewRenderer` should be called before the activity is destroyed.

#### How to use VideoView ?

##### Layout

```js
// <org.webrtc.SurfaceViewRenderer
//        android:id="@+id/svrParticipant"
//        android:layout_width="match_parent"
//        android:layout_height="match_parent" />

<live.videosdk.rtc.android.VideoView
  android:id="@+id/participantView"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
/>
```

##### Initalising and adding video track



**Kotlin:**

```js
// svrParticipant.init(PeerConnectionUtils.getEglContext(), null)
// var track = stream.getTrack() as VideoTrack
// track!!.addSink(svrParticipant)

val track = stream.track as VideoTrack
participantView!!.addTrack(track);
```

---

**Java:**

```js
// svrParticipant.init(PeerConnectionUtils.getEglContext(), null);
// VideoTrack track = (VideoTrack) stream.getTrack();
// track.addSink(svrParticipant);

VideoTrack track = (VideoTrack) stream.getTrack();
participantView.addTrack(track);
```

##### removeTrack

**Kotlin:**

```js
// var track = stream.track as VideoTrack
// track!!.removeSink(svrParticipant);

participantView.removeTrack();
```

---

**Java:**

```js
// VideoTrack track = (VideoTrack) stream.getTrack();
// if (track != null) track.removeSink(svrParticipant);

participantView.removeTrack();
```

#### release

**Kotlin:**

```js
override fun onDestroy() {
    participantView.releaseSurfaceViewRenderer()
    super.onDestroy()
}
```

---

**Java:**

```js
@Override
protected void onDestroy() {
participantView.releaseSurfaceViewRenderer();
super.onDestroy();
}
```


---

# Concept and Architecture - Android

Before diving into the concept, let's understand the VideoSDK, VideoSDK is a software development kit that offers tools and APIs for creating apps that are based on video and audio. It typically includes features such as video and audio calls, chat, cloud recording, simulcasting (RTMP), interactive live streaming (HLS), and many more across a wide range of platforms and devices.

## Concepts

![img.png](../../../../static/img/room-concept.png)

### `1. Meeting / Room`

- Meeting or Room object in the VideoSDK provide a virtual place for participants to interact and engage in real-time voice, video, and screen-sharing sessions. The object is in charge of handling media streams and participant communication.

- Meeting or Room can be uniquely identified by `meetingId` or `roomId`.

### `2. Participant`

- Participant is a VideoSDK object that represents each user/client in the meeting or room and allows them to share audio/video assets.

- `2.1 Local Participant` :
  The local participant is the one that runs on the user's device. The local participant has control over their own media streams, including the ability to start and stop audio and video.

  - The local participant in a meeting/room can also connect with other participants by transmitting and receiving audio and video streams, exchanging chat messages, and more.

- `2.2 Remote Participant` :
  The remote participant receives audio and video streams from the local participant and other remote participants and also has the ability to exchange audio, video, and chat messages with the local participant.

- Each participant in VideoSDK can be uniquely identified by `participantId`.

### `3. MediaStream & Track`

- A mediastream is a collection of audio & video tracks that can be transmitted between participants in real-time.

- A track is a continuous flow of audio or video data and can be thought of as a stream of media frames.

- A mediastream can contain multiple tracks. One video track for the video feed from the camera and one audio track for the audio feed from the microphone. These tracks can be transmitted between participants in VideoSDK Meeting / Room.

### `4. Events / Notifications`

- Events / Notifications can be used to inform users about various activities happening in a Meeting / Room, including participant join/leave and new messages. They can also be used to alert users about any SDK-level errors that occur during a call.

### `5. Session`

- A Session is the instance of an ongoing meeting/room which has one or more participants in it. A single room or meeting can have multiple sessions.
- Each session can be uniquely identified by `sessionId`.

![img.png](../../../../static/img/meeting-session.jpg)

---

![img.png](../../../../static/img/recording-hls-rtmp.png)

### `6. Cloud Recording`

- Cloud recording in VideoSDK refers to the process of recording audio or video content and storing it on a remote server or VideoSDK server.

### `7. Simulcasting (RTMP)`

- RTMP is a popular protocol for live streaming video content from a VideoSDK to platforms such as YouTube, Twitch, Facebook, and others.
- By providing the platform-specific `stream key` and `stream URL`, the VideoSDK can connect to the platform's RTMP server and transmit the live video stream.

### `8. Http Live Streaming (HLS)`

- Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

- In an interactive live stream (HLS), viewers can take part in a variety of activities like live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

## Architecture

This diagram demonstrates end-to-end flow to implement video & audio calls, record calls, and go live on social media.

![Video-sdk-architecture!](/img/video-sdk-archietecture.svg)


---

# Mute All Participants - Android

If you are the host or moderator of a video conference, you may want to mute all the participants at once. This can be useful in various scenarios, such as when you want to deliver a presentation or when there is background noise that is causing distractions.

- To achieve this, you have to iterate over the list of participants from the `Meeting` class and call `disableMic` method from `Participant` class.



**Kotlin:**

```js
btnMuteAllParticipant!!.setOnClickListener { _: View? ->
  var participants: Iterator<Participant> = meeting.participants.values.iterator()
  for (i in 0 until meeting.participants.size) {
  val participant = participants.next()
  participant.disableMic()
  }
}
```

---

**Java:**

```js
btnMuteAllParticipant.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
final Iterator<Participant> participants = meeting.getParticipants().values().iterator();
for (int i = 0; i < meeting.getParticipants().size(); i++) {
  final Participant participant = participants.next();
  participant.disableMic();
}
  }
});
```

:::note
Participant who will be muting other participants should have permission **`allow_mod`** passed in the token. To know more about permissions [**visit here**](/android/guide/video-and-audio-calling-api-sdk/authentication-and-token).
:::

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [disableMic()](/android/api/sdk-reference/participant-class/methods#disablemic)


---

# Toggle Remote Participant Media - Android

When hosting a meeting, it's important that the host of the meeting should be able to request someone's Mic or Camera to be turned on or should be able to turn them off.

:::note
Participant who will be controlling other participant's mic and camera should have permission **`allow_mod`** passed in the token. To know more about permissions [**visit here**](/android/guide/video-and-audio-calling-api-sdk/authentication-and-token).
:::

Before we discuss the methods and events associated with this functionality, here is how the flow would look like.

![img1](../../../../../static/img/toggle-remote-media.png)

## Methods

### `enableMic()`

- If you wish to turn **on** the microphone of a participant, you will be calling the `enableMic()` from the `Participant` class.

- When this method is called, the participant whose microphone is requested will receive the `onMicRequested` event with the `participantId` of the participant who requested it and two callback functions `accept` and `reject` which should be called based on decision made by the user.

- **Example:** Meeting is running with **Participant A** and **Participant B**. Now **Participant A** wants to Enable Mic of **Participant B**, so **Participant A** will use `enableMic()` function to request **Participant B**, after that **Participant B** recieve the `onMicRequested` event, from there user can either accept or reject the incoming request.

### `enableWebcam()`

- If you wish to turn **on** the camera of a participant, you will be calling the `enableWebcam()` from the `Participant` class.

- When this method is called, the participant whose camera is requested will receive the `onWebcamRequested` event with the `participantId` of the participant who requested it and two callback functions `accept` and `reject` which should be called based on decision made by the user.

- **Example:** Meeting is running with **Participant A** and **Participant B**. Now **Participant A** wants to Enable Webcam of **Participant B**, so **Participant A** will use `enableWebcam()` function to request **Participant B**, after that **Participant B** recieve the `onWebcamRequested` event, from there user can either accept or reject the incoming request.

### `disableMic()`

- If you wish to turn **off** the microphone of a participant, you will be calling the `disableMic()` from the `Participant` class.
- This will disable the microphone of the participant.

### `disableWebcam()`

- If you wish to turn **off** the camera of a participant, you will be calling the `disableWebcam()` from the `Participant` class.
- This will disable the camera of the participant.

#### Example



**Kotlin:**

```js
btnEnableWebcam!!.setOnClickListener { _: View? ->
  // This will emit an event called "onWebcamRequested" to that particular participant
  participant!!.enableWebcam()
}

btnEnableMic!!.setOnClickListener { _: View? ->
  // This will emit an event called "onMicRequested" to that particular participant
  participant!!.enableMic()
}

btnDisableWebcam!!.setOnClickListener { _: View? ->
  // This will disable the webcam of that particular participant
  participant.disableWebcam()
}

btnDisableWebcam!!.setOnClickListener { _: View? ->
  // This will disable the mic of that particular participant
  participant.disableMic()
}
```

---

**Java:**

```js
btnEnableWebcam.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
  // This will emit an event called "onWebcamRequested" to that particular participant
  participant.enableWebcam();
}
});

btnEnableMic.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
  // This will emit an event called "onMicRequested" to that particular participant
  participant.enableMic();
}
});

btnDisableWebcam.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
  // This will disable the webcam of that particular participant
  participant.disableWebcam();
}
});

btnDisableMic.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
  // This will disable the mic of that particular participant
  participant.disableMic();
}
});
```

## Events

### `onWebcamRequested`

This event will be emitted to the `Participant B` when any other `Participant A` requests to enable webcam of that participant (`Participant B`). This event handler will receieve following two arguments:

- `participantId` - ParticipantId of the requesting participant
- `listener`: MicRequestListener \{ accept: Method; reject: Method }

### `onMicRequested`

This event will be emitted to the `Participant B` when any other `Participant A` requests to enable mic of that participant (`Participant B`). This event handler will receieve following two arguments:

- `participantId` - ParticipantId of the requesting participant
- `listener`: MicRequestListener \{ accept: Method; reject: Method }

###### Usage

**Kotlin:**

```javascript
override fun onMicRequested(participantId: String, listener: MicRequestListener) {
  // callback function to accept the request
  listener.accept()

  // callback function to reject the request
  listener.reject()
}

override fun onWebcamRequested(participantId: String, listener: WebcamRequestListener) {
  // callback function to accept the request
  listener.accept()

  // callback function to reject the request
  listener.reject()
}
```

---

**Java:**

```javascript
@Override
public void onMicRequested(String participantId, MicRequestListener listener) {
  // callback function to accept the request
  listener.accept();

  // callback function to reject the request
  listener.reject();
}

@Override
public void onWebcamRequested(String participantId, WebcamRequestListener listener) {
  // callback function to accept the request
  listener.accept();

  // callback function to reject the request
  listener.reject();
}
```

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [enableMic()](/android/api/sdk-reference/participant-class/methods#enablemic)
- [disableMic()](/android/api/sdk-reference/participant-class/methods#disablemic)
- [enableWebcam()](/android/api/sdk-reference/participant-class/methods#enablewebcam)
- [disableWebcam()](/android/api/sdk-reference/participant-class/methods#disablewebcam)
- [onMicRequested()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmicrequested)
- [onWebcamRequested()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onwebcamrequested)


---

# Remove Participant - Android

This feature in a meeting allows the meeting host or organizer to remove a participant from the meeting. This can be helpful in situations where a participant is causing a disturbance, is behaving inappropriately, or is not following meeting guidelines.

VideoSDK provide three ways to remove participant from meeting.

1. [Using SDK](#1-using-sdk)
2. [Using VideoSDK Dashboard](#2-using-videosdk-dashboard)
3. [Using Rest API](#3-using-rest-api)

## 1. Using SDK

### `remove()`

Remove participant allows removing participant while session is on-going. This can be helpful when moderation in particular meeting is required.



**Kotlin:**

```js
btnRemoveParticipant!!.setOnClickListener { _: View? ->
  val remoteParticipantId = "<participant-id>"
  // Get specific participant instance
  val participant = meeting!!.participants[remoteParticipantId]
  // Remove participant from active session
  // This will emit an event called "onParticipantLeft" for that particular participant
  participant!!.remove()
}
```

---

**Java:**

```js
btnRemoveParticipant.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
String remoteParticipantId = "<participant-id>";
// Get specific participant instance
Participant participant = meeting.getParticipants().get(remoteParticipantId);
// Remove participant from active session
// This will emit an event called "onParticipantLeft" for that particular participant
participant.remove();
  }
});
```

### Events associated with remove

Following callbacks are received when a participant is removed from the meeting.

- Participant who was removed from the meeting will receive a callback on the [`onMeetingLeft`](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmeetingleft).
- All other [remote participants](../concept-and-architecture#2-participant) will receive a callback [`onParticipantLeft`](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onparticipantleft) with Participant object.

## 2. Using VideoSDK Dashboard

- You can go the session page on [VideoSDK Dashboard](https://app.videosdk.live/meetings/sessions) and select the meeting you can to remove a participant from.
- And then from the participants list you can remove any participant you want.


<div style={{textAlign: 'center'}}>



</div>

## 3. Using Rest API

- You can also remove the particular participant from the meeting [using the REST API](/api-reference/realtime-communication/remove-participant).
- To use this method, you should have the `sessionId` of the meeting and `participantId` of the participant who is supposed to be removed.

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [remove()](/android/api/sdk-reference/participant-class/methods#remove)
- [onMeetingLeft()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmeetingleft)
- [onParticipantLeft()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onparticipantleft)


---

# How to intergrate Banuba SDK with Android Video SDK?

Use Banuba SDK with Android SDK to enhance video calls with real-time face filters and virtual backgrounds.

### Step 1: Banuba Token

- To start working with the Banuba SDK into your project, you need to have the client token. To receive the client token please fill form on [banuba.com](https://www.banuba.com/)

### Step 2: Add Banuba SDK dependencies

- With the client token, you will also receive the Banuba SDK archive for Android which contains Banuba Effect Player (compiled Android library project with .aar extension), Banuba SDK (compiled Android library project with .aar extension) and example filters located under effects folder.

- Create `libs` directory in your project and add `banuba_effect_player.aar`, `banuba_sdk.aar` files.

<div style={{textAlign: 'center'}}>

![Banuba SDK dependency .aar files](/img/android/banuba/banuba_dependency.png)

</div>

- Open build.gradle (Module: app) and add Banuba SDK dependencies.

```js title="app/build.gradle"
dependencies {
  // Banuba SDK dependencies
   implementation fileTree(dir: 'libs', include: ['*.aar'])

  // other app dependencies
  }
```

### Step 3: Add effects into your project

- Create `effects` folder under `assets` directory in your project and add filters that you want to use in the `effects` folder.You can download test effects here: [Effects](https://docs.banuba.com/face-ar-sdk-v1/overview/demo_face_filters)

<div style={{textAlign: 'center'}}>

![Banuba SDK effects folder](/img/android/banuba/banuba_effects.png)

</div>

### Step 4: Integrate Banuba

1. Create one interface named `IVideoFrameProcessor` and a class named `BanubaProcessor` in your project and copy paste code from the [example](https://github.com/videosdk-live/videosdk-rtc-android-sdk-banuba-example).

2. Update your Banuba client token into `BanubaProcessor.java` file.

```js title="BanubaProcessor.java"
public class BanubaProcessor implements IVideoFrameProcessor {
    //...
    public static final String KEY = "place_your_token_here";
    //...
}
```

3. Create instance of `CapturerObserver` class and pass into VideoSDK.createCameraVideoTrack() method. To know more about createCameraVideoTrack() method please visit [CustomVideoTrack](../features/custom-track/custom-video-track.md).

4. Copy paste method named `initVideoFrameProcessor(VideoSource videosource,CustomStreamTrack videoCustomTrack)` from the [example](https://github.com/videosdk-live/videosdk-rtc-android-sdk-banuba-example). into your Activity and call it after creating `CustomStreamTrack` for video.

### Step 5: Use filters in Meeting

- If you want to use video filters from start of the meeting, you can pass `CustomStreamTrack` in the `initMeeting`.

- Also you can use video filters during the meeting by passing the `CustomStreamTrack` in the `enableWebcam()` method of Meeting.

:::tip

Stuck anywhere? Check out this [Code Sample of Banuba Intergation with Android-SDK](https://github.com/videosdk-live/videosdk-rtc-android-sdk-banuba-example.git) on GitHub

:::


---

# Camera Controls - Android

Whenever any participant wants to start/stop broadcasting their video to other participant in a meeting, they can simply do it with VideoSDK Meeting.

This guide will provide an overview of how to implement enable, disable and switch webcam features in a meeting.

1. **Enable Camera** - By using `enableWebcam()` function, a participant can publish camera stream to other participants.
2. **Disable Camera** - By using `disableWebcam()` function, a participant can stop publishing camera stream to other participants.
3. **Switch Camera** - By using `changeWebcam()` function, a participant can stream from front / rear camera during the meeting.This function is only applicable for Mobile devices.

### Enable, Disable And Switch Webcam



**Kotlin:**

```js
  btnWebcam!!.setOnClickListener {

// Toggle participant webcam in meeting
if (webcamEnabled) {
  meeting!!.disableWebcam()
} else {
  meeting!!.enableWebcam()
}

// Change Webcam in Meeting
meeting!!.changeWebcam()
  }
```

---

**Java:**

```js
  btnWebcam.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {

    // Toggle participant webcam in meeting
    if (webcamEnabled) {
      meeting.disableWebcam();
    } else {
      meeting.enableWebcam();
    }

     // Change Webcam in Meeting
    meeting.changeWebcam();
  }
  });
```

### Events

**Event associated with `enableWebcam()`:**

- Every Participant will receive a callback on [`onStreamEnabled()`](../../../api/sdk-reference/participant-class/participant-event-listener-class.md#onstreamenabled) of the [`Participant`](../../../api/sdk-reference/participant-class//introduction.md) with `Stream` object.

**Event associated with `disableWebcam()`:**

- Every Participant will receive a callback on [`onStreamDisabled()`](../../../api/sdk-reference/participant-class/participant-event-listener-class.md#onstreamenabled) of the [`Participant`](../../../api/sdk-reference/participant-class//introduction.md) with `Stream` object.

**Kotlin:**

```js
  meeting!!.localParticipant.addEventListener(object : ParticipantEventListener() {
override fun onStreamEnabled(stream: Stream) {
    //

    if(stream.getKind().equals("video")){
      //participant turned on video
      //Render participant video
    }
}

override fun onStreamDisabled(stream: Stream) {
    //

    if(stream.getKind().equals("video")){
      //participant turned off video
      //remove participant video
    }
}
  });
```

---

**Java:**

```js
  participant.addEventListener(new ParticipantEventListener() {
@Override
public void onStreamEnabled(Stream stream) {
    //
    if(stream.getKind().equals("video")){
      //participant turned on video
      //Render participant video
    }
}

@Override
public void onStreamDisabled(Stream stream) {
    //
    if(stream.getKind().equals("video")){
      //participant turned off video
      //remove participant video
    }
}
  });
```


---

# Custom Audio Track - React Native

We have introduced the ability to pass a custom Audio track for the Audio of the participants with different encoder configuration.

## Creating a Custom Audio Track

- You can create a Audio Track using `createAudioTrack()` method of `VideoSDK`.
- This method can be used to create audio track using different encoding parameters.

### Parameters

- **encoderConfig**:

  - type: `String`
  - required: `true`
  - default: `speech_standard`
  - Allowed values : `speech_low_quality` | `speech_standard` | `music_standard` | `standard_stereo` | `high_quality` | `high_quality_stereo`
  - It will be the encoder configuration you want to use for Audio Track.

- **context**

  - type: `Context`
  - required: `true`
  - Pass the Android Context for this parameter.

#### Returns

- `CustomStreamTrack`

### Example



**Kotlin:**

```js
try {
  val audioCustomTrack: CustomStreamTrack = VideoSDK.createAudioTrack("high_quality",this)
} catch (e: JSONException) {
   e.printStackTrace()
}
```

---

**Java:**

```js
try {
  CustomStreamTrack audioCustomTrack=VideoSDK.createAudioTrack("high_quality", this);
}catch (JSONException e) {
  e.printStackTrace();
}
```

## Using Custom Audio Track

### Custom Track while initializing the meeting

If you are passing `micEnabled: true` in the `initMeeting` of `VideoSDK` and want to use custom tracks from start of the meeting, you can pass custom track in the `initMeeting` as shown below.

**Kotlin:**

```js
override fun onCreate(savedInstanceState: Bundle?) {
//..

val customTracks: MutableMap<String, CustomStreamTrack> = HashMap()

val audioCustomTrack: CustomStreamTrack = VideoSDK.createAudioTrack("high_quality", this)
customTracks["mic"] = audioCustomTrack  //Key must be "mic"

// create a new meeting instance
val meeting = VideoSDK.initMeeting(
  this@MainActivity,meetingId,participantName,
  //MicEnabled , If true, it will use the passed custom track to turn mic on
  true,
  //WebcamEnabled
  true,
  //ParticipantId
  null,
  //Mode
  null,
  //Pass the custom tracks here
  customTracks
)
}
```

---

**Java:**

```js
@Override
protected void onCreate(Bundle savedInstanceState) {
//..

Map<String, CustomStreamTrack> customTracks = new HashMap<>();

CustomStreamTrack audioCustomTrack = VideoSDK.createAudioTrack("high_quality", this);
customTracks.put("mic", audioCustomTrack);  //Key must be "mic"

// create a new meeting instance
Meeting meeting = VideoSDK.initMeeting(
    MainActivity.this, meetingId, participantName,
   //MicEnabled , If true, it will use the passed custom track to turn mic on
    true,
    //WebcamEnabled
    true,
    //ParticipantId
    null,
    //Mode
    null,
    //Pass the custom tracks here
    customTracks
);

}
```

### Custom Track with `unmuteMic()`

In order to switch tracks during the meeting, you have to pass the `CustomStreamTrack` in the `unmuteMic()` method of `Meeting`.

You can also pass custom track in `changeMic()` method of `Meeting`.

:::note

Make sure to call `muteMic()` before you create a new track as it may lead to unexpected behavior.

:::

**Kotlin:**

```js
try {
  val audioCustomTrack: CustomStreamTrack = VideoSDK.createAudioTrack("high_quality", this)
  meeting!!.unmuteMic(audioCustomTrack)

  //or
  meeting!!.changeMic(AppRTCAudioManager.AudioDevice.BLUETOOTH, audioCustomTrack)
} catch (e: JSONException) {
  e.printStackTrace()
}

```

---

**Java:**

```js
try {
  CustomStreamTrack audioCustomTrack = VideoSDK.createAudioTrack("high_quality", this);
  meeting.unmuteMic(audioCustomTrack);

  //or
  meeting.changeMic(AppRTCAudioManager.AudioDevice.BLUETOOTH,audioCustomTrack);
}catch (JSONException e) {
  e.printStackTrace();
}

```


---

# Custom Screen Share Track - React Native

We have introduced the ability to pass a custom Screen Share track while sharing the screen of participants. This feature can be used to add custom video encoder config,background removal & video filter from external SDK(e.g., [Banuba](https://www.banuba.com/)) and send it to other participants.

## Creating a Custom Screen Share Track

- You can create a Screen Share track using `createScreenShareVideoTrack()` method of `VideoSDK`.
- This method can be used to create screen share track using different encoding parameters.

### Parameters

- **encoderConfig**:

  - type: `String`
  - required: `true`
  - default: `h720p_15fps`
  - Allowed values : `h360p_30fps` | `h720p_5fps` | `h720p_15fps` | `h1080p_15fps` | `h1080p_30fps`
  - It will be the encoderConfigs you can want to use for the Screen Share Track.

:::note

Above mentioned encoder configurations are valid for both, landscape as well as portrait mode.

:::

- **data**

  - type: `Intent`
  - required: `true`
  - It is Intent received from onActivityResult when user provide permission for ScreenShare.

- **context**

  - type: `Context`
  - required: `true`
  - Pass the Android Context for this parameter.

- **listener**
  - type: `CustomTrackListener`
  - required: `true`
  - Callback to this listener will be made when track is ready with CustomTrack as parameter.

### Example



**Kotlin:**

```javascript
// data is received from onActivityResult method.
VideoSDK.createScreenShareVideoTrack("h720p_5fps", data, this) { track ->
meeting!!.enableScreenShare(track)
}
```

---

**Java:**

```javascript
// data is received from onActivityResult method.
VideoSDK.createScreenShareVideoTrack("h720p_5fps", data, this, (track)->{
meeting.enableScreenShare(track);
});
```

## Using Custom Screen Share Track

### Custom Track with `enableScreenShare()`

In order to switch tracks during the meeting, you have to pass the `CustomStreamTrack` in the `enableScreenShare()` method of `Meeting`.

:::note

Make sure to call `disableScreenShare()` before you create a new track as it may lead to unexpected behavior.

:::

**Kotlin:**

```javascript
@TargetApi(21)
private fun askPermissionForScreenShare() {
val mediaProjectionManager = application.getSystemService<Any>(
    Context.MEDIA_PROJECTION_SERVICE
) as MediaProjectionManager
startActivityForResult(
    mediaProjectionManager.createScreenCaptureIntent(), CAPTURE_PERMISSION_REQUEST_CODE
)
}

@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode != CAPTURE_PERMISSION_REQUEST_CODE) return
if (resultCode == RESULT_OK) {
    VideoSDK.createScreenShareVideoTrack("h720p_5fps", data, this) { track ->
        meeting!!.enableScreenShare(track)
    }
}
}

```

---

**Java:**

```javascript
@TargetApi(21)
private void askPermissionForScreenShare() {
MediaProjectionManager mediaProjectionManager =
    (MediaProjectionManager) getApplication().getSystemService(
        Context.MEDIA_PROJECTION_SERVICE);
startActivityForResult(
    mediaProjectionManager.createScreenCaptureIntent(), CAPTURE_PERMISSION_REQUEST_CODE);
}

@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
super.onActivityResult(requestCode, resultCode, data);
if (requestCode != CAPTURE_PERMISSION_REQUEST_CODE)
    return;
if (resultCode == Activity.RESULT_OK) {
    VideoSDK.createScreenShareVideoTrack("h720p_5fps", data, this, (track)->{
        meeting.enableScreenShare(track);
    });
}
}

```


---

# Custom Video Track - React Native

We have introduced the ability to pass a custom video track for the video of the participants. This feature can be used to add custom video encoder config, optimization mode (whether you want to focus on **motion**, **text** or **detail** of the video) and background removal & video filter from external SDK(e.g., [Banuba](https://www.banuba.com/))and send it to other participants.

## Creating a Custom Video Track

- You can create a Video Track using `createCameraVideoTrack()` method of `VideoSDK`.
- This method can be used to create video track using different encoding parameters & camera facing mode.

### Parameters

- **encoderConfig**:

  - type: `String`
  - required: `true`
  - default: `h480p_w640p`
  - Allowed values : `h144p_w176p` | `h240p_w320p` | `h480p_w640p` | `h480p_w720p` | `h720p_w960p` | `h1080p_w1440p` | `h720p_w1280p`
  - It will be the encoderConfigs you can want to use for the Video Track.

:::note

Above mentioned encoder configurations are valid for both, landscape as well as portrait mode.

:::

- **facingMode**:

  - type: `String`
  - required: `true`
  - Allowed values : `front` | `back`
  - It will specify wheater to use front or back camera for the video track.

- **optimizationMode**

  - type: `CustomStreamTrack.VideoMode`
  - required: `true`
  - Allowed values: `motion` | `text` | `detail`
  - It will specify the optimization mode for the video track being generated.

- **context**:

  - type: `Context`
  - required: `true`
  - Pass the Android Context for this parameter.

- **observer**:

  - type: `CapturerObserver`
  - required: `false`
  - If you want to use video filter from external SDK(e.g., [Banuba](https://www.banuba.com/)) then pass instance of `CapturerObserver` in this parameter.

:::note

For Banuba integraion with VideoSDK, please visit [Banuba Intergation with VideoSDK](../../video-processor/banuba-integration.md)

:::

#### Returns

- `CustomStreamTrack`

### Example



**Kotlin:**

```javascript
val videoCustomTrack: CustomStreamTrack = VideoSDK.createCameraVideoTrack("h240p_w320p", "front", CustomStreamTrack.VideoMode.MOTION, this)
```

---

**Java:**

```javascript
CustomStreamTrack customStreamTrack = VideoSDK.createCameraVideoTrack("h240p_w320p", "front", CustomStreamTrack.VideoMode.MOTION, this);
```

## Using Custom Video Track

### Custom Track while initializing the meeting

If you are passing `webcamEnabled: true` in the `initMeeting` of `VideoSDK` and want to use custom tracks from start of the meeting, you can pass custom track in the `initMeeting` as shown below.

**Kotlin:**

```js
override fun onCreate(savedInstanceState: Bundle?) {
//..

val customTracks: MutableMap<String, CustomStreamTrack> = HashMap()
val videoCustomTrack: CustomStreamTrack =
VideoSDK.createCameraVideoTrack("h240p_w320p", "back", false, CustomStreamTrack.VideoMode.MOTION, this)
customTracks["video"] = videoCustomTrack  //Key must be "video"

 // create a new meeting instance
val meeting = VideoSDK.initMeeting(
  this@MainActivity, meetingId, participantName,
  //MicEnabled
  true,
  //WebcamEnabled , If true, it will use the passed custom track to turn webcam on
  true,
  // ParticipantId
  null,
  // Mode
  null,
  //Pass the custom tracks here
  customTracks
)
}
```

---

**Java:**

```js
@Override
protected void onCreate(Bundle savedInstanceState) {
//..

Map<String, CustomStreamTrack> customTracks = new HashMap<>();

CustomStreamTrack videoCustomTrack = VideoSDK.createCameraVideoTrack("h240p_w320p", "back", CustomStreamTrack.VideoMode.MOTION, this);
customTracks.put("video", videoCustomTrack);  //Key must be "video"

// create a new meeting instance
Meeting meeting = VideoSDK.initMeeting(
    MainActivity.this, meetingId, participantName,
   //MicEnabled
    true,
    //WebcamEnabled , If true, it will use the passed custom track to turn webcam on
    true,
    // ParticipantId
    null,
    // Mode
    null,
    //Pass the custom tracks here
    customTracks
    );
}
```

### Custom Track with `enableWebcam()`

In order to switch tracks during the meeting, you have to pass the `CustomStreamTrack` in the `enableWebcam()` method of `Meeting`.

:::note

Make sure to call `disableWebcam()` before you create a new track as it may lead to unexpected behavior.

:::

**Kotlin:**

```javascript
val customStreamTrack: CustomStreamTrack = VideoSDK.createCameraVideoTrack("h240p_w320p", "back", CustomStreamTrack.VideoMode.MOTION, this)
meeting!!.enableWebcam(customStreamTrack)
```

---

**Java:**

```javascript
CustomStreamTrack customStreamTrack=VideoSDK.createCameraVideoTrack("h240p_w320p", "back", CustomStreamTrack.VideoMode.MOTION, this);
meeting.enableWebcam(customStreamTrack);
```


---

# Error Event - Android

This event is helpful for development level troubleshooting while integrating SDK.

Whenever any invalid configuration provided or server/network errors arise, this event will trigger with a specific error code and message.

This event can ease your development process.

We have depicted a specific constant with code and message in the below table.

| Constant                              | Code | Message                                                                                                                     |
| ------------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------- |
| **INVALID_API_KEY**                   | 4001 | `apikey` provided in the token is empty or invalid, please verify it on the dashboard.                                      |
| **INVALID_TOKEN**                     | 4002 | `token` is empty or invalid or might have expired.                                                                          |
| **INVALID_MEETING_ID**                | 4003 | `meetingId` is empty or invalid, please verify it or generate new meetingId using the API.                                  |
| **INVALID_PARTICIPANT_ID**            | 4004 | `participantId` is empty or invalid, it shouldn't contain any whitespaces.                                                  |
| **DUPLICATE_PARTICIPANT**             | 4005 | Leaving meeting, since this `participantId` joined from another device.                                                     |
| **ACCOUNT_DEACTIVATED**               | 4006 | It seems your account is deactivated by VideoSDK for some reason, you can reach out to us at `support@videosdk.live`.       |
| **ACCOUNT_DISCONTINUED**              | 4007 | Server will respond you with specific message.\_                                                                            |
| **INVALID_PERMISSIONS**               | 4008 | `permissions` provided in the token are invalid, please don't use `allow_join` or `allow_mod` with `ask_join`.              |
| **START_RECORDING_FAILED**            | 4011 | Recording start request failed due to an unknown error.                                                                     |
| **STOP_RECORDING_FAILED**             | 4012 | Recording stop request failed due to an unknown error.                                                                      |
| **START_LIVESTREAM_FAILED**           | 4013 | Livestream start request failed due to an unknown error.                                                                    |
| **STOP_LIVESTREAM_FAILED**            | 4014 | Livestream stop request failed due to an unknown error.                                                                     |
| **MAX_SPEAKER_LIMIT_REACHED_ON_ORGANIZATION**    | 4026 | You have reached max speaker limit on organization. To increase contact at support@videosdk.live".                                                               |
| **MAX_VIEWER_LIMIT_REACHED_ON_ORGANIZATION**    | 4027 | You have reached max viewer limit on organization. To increase contact at support@videosdk.live".                                                               |
| **MAX_RECORDING_LIMIT_REACHED_ON_ORGANIZATION**    | 4028 | You have reached max limit of recording on organization. To increase contact at support@videosdk.live.                                                               |
| **MAX_HLS_LIMIT_REACHED_ON_ORGANIZATION**    | 4029 | You have reached max limit of hls on organization. To increase contact at support@videosdk.live.                                                               |
| **MAX_LIVESTREAM_LIMIT_REACHED_ON_ORGANIZATION**    | 4030 | You have reached max limit of livestream on organization. To increase contact at support@videosdk.live.                                                               |
| **INVALID_LIVESTREAM_CONFIG**         | 4015 | Livestream 'outputs' configuration provided was invalid.                                                                    |
| **PREV_RECORDING_PROCESSING**         | 4018 | Previous recording session is being processed, please try again after few seconds.                                          |
| **RECORDING_FAILED**                  | 5001 | Recording stopped due to an unknown error.                                                                                  |
| **LIVESTREAM_FAILED**                 | 5002 | Livestream stopped due to an unknown error.                                                                                 |
| **RECORDING_DURATION_LIMIT_REACHED**  | 5004 | Recording has been automatically stopped by the system, due to max duration limit of 2 hours reached for a single Recording |
| **LIVESTREAM_DURATION_LIMIT_REACHED** | 5005 | Livestream has been automatically stopped by the system, due to max duration limit of 2 hours reached for a single RTMP     |
| **HLS_DURATION_LIMIT_REACHED**        | 5006 | Hls has been automatically stopped by the system, due to max duration limit of 2 hours reached for a single HLS             |

### Event Code



**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
//..
override fun onError(error: JSONObject) {
try {
    val errorCodes: JSONObject = VideoSDK.getErrorCodes()
    val code = error.getInt("code")
    if (code == errorCodes.getInt("START_LIVESTREAM_FAILED")) {
        Log.d("#error", "Error is: " + error["message"])
    } else if (code == errorCodes.getInt("START_RECORDING_FAILED")) {
        Log.d("#error", "Error is: " + error["message"])
    }
} catch (e: Exception) {
        e.printStackTrace()
    }
}
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
//..
@Override
public void onError(JSONObject error) {
    try {
        JSONObject errorCodes = VideoSDK.getErrorCodes();
        int code = error.getInt("code");
        if (code == errorCodes.getInt("START_LIVESTREAM_FAILED")) {
            Log.d("#error", "Error is: " + error.get("message"));
        }else if(code == errorCodes.getInt("START_RECORDING_FAILED"))
        {
            Log.d("#error", "Error is: " + error.get("message"));
        }
    } catch (Exception e) {
        e.printStackTrace();
    }
}
};
```


---

# External Call Detection - Android

External call detection feature in VideoSDK let you know, participant is on the call during meeting.

Whenever local participant accept the incoming call or place outgoing call, `externalcall-started` event will trigger.`externalcall-started` event only received by localParticipant.

For example, the meeting is running with **Alice** and **Bob**. Whenever **Alice** receives the call or she call someone, **Alice** will receive `externalcall-started` event.

We can access `externalcall-started` event through [meeting object](/android/guide/video-and-audio-calling-api-sdk/features/start-join-meeting).

### externalcall-started Event



**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
 // ...
override fun onExternalCallStarted() {
  Log.d("#meeting", "onExternalCallAnswered")
}
};
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
 // ...
@Override
public void onExternalCallStarted() {
    Log.d("#meeting", "onExternalCallStarted");
}
};
```


---

# Go Live On Social Media - Android

This feature allows participant to broadcast meeting on various social media platforms such as Facebook or Youtube.
This guide will provide an overview of how participant can start and stop broadcasting meeting.

1. **Start LiveStream** - By using `startLivestream()` function, a participant can start broadcasting meeting on various platforms by provding url and stream keys as an argument.
2. **Stop LiveStream** - By using `stopLivestream()` function, a participant can stop broadcasting on all platforms.

### Start And Stop Live Stream



**Kotlin:**

```js
private val YOUTUBE_RTMP_URL: String? = null
private val YOUTUBE_RTMP_STREAM_KEY: String? = null

//
findViewById<View>(R.id.btnLivestream).setOnClickListener {
if (!livestreaming) {
    if (YOUTUBE_RTMP_URL == null || YOUTUBE_RTMP_STREAM_KEY == null) {
        throw Error("RTMP url or stream key missing.")
    }
    val outputs: MutableList<LivestreamOutput> = ArrayList()
    outputs.add(LivestreamOutput(YOUTUBE_RTMP_URL, YOUTUBE_RTMP_STREAM_KEY))

    meeting!!.startLivestream(outputs)
} else {
    meeting!!.stopLivestream()
}
}
```

---

**Java:**

```js
private static final String YOUTUBE_RTMP_URL = null;
private static final String YOUTUBE_RTMP_STREAM_KEY = null;

//
findViewById(R.id.btnLivestream).setOnClickListener(view -> {
if (!livestreaming) {
    if (YOUTUBE_RTMP_URL == null || YOUTUBE_RTMP_STREAM_KEY == null) {
        throw new Error("RTMP url or stream key missing.");
    }

    List<LivestreamOutput> outputs = new ArrayList<>();
    outputs.add(new LivestreamOutput(YOUTUBE_RTMP_URL, YOUTUBE_RTMP_STREAM_KEY));

    meeting.startLivestream(outputs);
} else {
    meeting.stopLivestream();
}
});
```

### Events

- **onLiveStreamStateChanged** - A `onLiveStreamStateChanged` event will be triggered any time the broadcasting state of a meeting changes.

**Kotlin:**

```js
object : MeetingEventListener() {
  override fun onLivestreamStateChanged(livestreamState: String?) {
when (livestreamState) {
    "LIVESTREAM_STARTING" -> Log.d( "LivestreamStateChanged",
        "Meeting livestream is starting"
    )
    "LIVESTREAM_STARTED" -> Log.d( "LivestreamStateChanged",
        "Meeting livestream is started"
    )
    "LIVESTREAM_STOPPING" -> Log.d("LivestreamStateChanged",
        "Meeting livestream is stopping"
    )
    "LIVESTREAM_STOPPED" -> Log.d("LivestreamStateChanged",
        "Meeting livestream is stopped"
    )
}
  }

}
```

---

**Java:**

```js
new MeetingEventListener() {
  @Override
  public void onLivestreamStateChanged(String livestreamState) {
  switch (livestreamState) {
      case "LIVESTREAM_STARTING":
          Log.d("LivestreamStateChanged", "Meeting livestream is starting");
          break;
      case "LIVESTREAM_STARTED":
          Log.d("LivestreamStateChanged", "Meeting livestream is started");
          break;
      case "LIVESTREAM_STOPPING":
          Log.d("LivestreamStateChanged", "Meeting livestream is stopping");
          break;
      case "LIVESTREAM_STOPPED":
          Log.d("LivestreamStateChanged", "Meeting livestream is stopped");
          break;
  }
  }
}
```


---

# Leave or End Meeting - Android

Whenever participant wishes to end their communication in the meeting, they can simply leave the meeting.

This guide will provide an overview of how to implement leave or end feature in VideoSDK meetings.

1. **Leave** - By using `leave()` function, only a participant will leave/exit the meeting, the rest of the meeting will continue with other participants.
2. **End** - By using `end()` function, meeting will end for each and every participant. So, use this function according to your use cases.

### Leave And End Meeting



**Kotlin:**

```js
  btnLeave!!.setOnClickListener { _: View? ->
meeting!!.leave()
  }

  btnEnd!!.setOnClickListener { _: View? ->
meeting!!.end()
  }
```

---

**Java:**

```js
  btnLeave.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
    meeting.leave();
  }
  });

  btnEnd.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
    meeting.end();
  }
  });
```

### Events

**Events associated with `leave()`:**

- Local participant will receive a callback on[`onMeetingLeft`](../../../api/sdk-reference/meeting-class/meeting-event-listener-class.md#onmeetingleft) of `Meeting`.
- All remote participants will receive a callback [`onParticipantLeft`](../../../api/sdk-reference/meeting-class/meeting-event-listener-class.md#onparticipantleft) with Participant object.

**Event associated with `end()`:**

- All remote participants and local participant will receive a callback on [`onParticipantLeft`](../../../api/sdk-reference/meeting-class/meeting-event-listener-class.md#onparticipantleft) with Participant object.

**Kotlin:**

```javascript
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  override fun onMeetingLeft() {
Log.d("#meeting", "onMeetingleft()")
  }

  override fun onParticipantLeft(participant: Participant) {
Log.d("#meeting", participant.displayName + " left");
  }
}
```

---

**Java:**

```javascript
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onMeetingLeft() {
Log.d("#meeting", "onMeetingleft()")
  }

  @Override
  public void onParticipantLeft(Participant participant) {
Log.d("#meeting", participant.getDisplayName() + " left");
  }
}
```


---

# Manage Participants - Android

## 1. Local Participant (self)

Local participant is used to consume your video & audio streams.
it contains information about local participant such as displayName, id, quality and streams Map.

You can acces localParticipant from the [meeting object](/android/guide/video-and-audio-calling-api-sdk/features/start-join-meeting#2-initialization).

### Participant object properties

| Property Name | Type          | Description                                            |
| ------------- | ------------- | ------------------------------------------------------ |
| id            | string        | Unique id of the participant.                          |
| displayName   | string        | The name you define during the meeting initialization. |
| local         | boolean       | Indicates the participant is local or not.             |
| quality       | string        | Indicates the participant streams quality.             |
| Streams       | Map of Stream | Returns Video & Audio Streams.                         |

### Stream Object properties

| Property Name | Type   | Description        |
| ------------- | ------ | ------------------ |
| id            | string | Unique id          |
| codec         | string | Video/Audio codec. |
| kind          | string | Stream Kind.       |
| track         | string | MediaStreamTrack   |

## 2. Other Participants (Except You)

Other participants Map is used to get all the participants (except you) in the meeting at any given time.

Other participants Map contains same properties as [LocalParticipant](/android/guide/video-and-audio-calling-api-sdk/features/manage-participants#participant-object-properties).

### Local And Other Participants

```xml title="activity_main.xml"
  <live.videosdk.rtc.android.VideoView
      android:id="@+id/localView"
      android:layout_width="80dp"
      android:layout_height="100dp"
      android:layout_gravity="end" />

  <androidx.recyclerview.widget.RecyclerView
      android:id="@+id/rvParticipants"
      android:layout_width="match_parent"
      android:layout_height="match_parent" />
```

:::info

- Here the participant's video is displayed using `VideoView`, but you may also use `SurfaceViewRender` for the same.
- For `VideoView`, SDK version should be `0.1.13` or higher.
- To know more about `VideoView`, please visit [here](/android/guide/video-and-audio-calling-api-sdk/components/videoView)

:::



**Kotlin:**

```js title="MainActivity.kt"
  import live.videosdk.rtc.android.VideoView
  import org.webrtc.VideoTrack

  private fun displayLocalParticipant() {
var localView: VideoView = findViewById(R.id.localView)

// display local video when stream available
meeting!!.localParticipant.addEventListener(
   object : ParticipantEventListener() {
     override fun onStreamEnabled(stream: Stream) {
       if (stream.kind.equals("video", ignoreCase = true)) {
         val videoTrack = stream.track as VideoTrack
         localView.addTrack(videoTrack)
        }
     }
  }
)
  }

  private fun displayRemoteParticipants() {
val rvParticipants = findViewById

</FrameLayout>
```

**Kotlin:**

```js title="ParticipantAdapter.kt"

class ParticipantAdapter(meeting: Meeting) : RecyclerView.Adapter<ParticipantAdapter.PeerViewHolder>() {
private val participants: MutableList<Participant> = ArrayList()
private var containerHeight = 0

init {
    participants.add(meeting.localParticipant)
    meeting.addEventListener(object : MeetingEventListener() {
        override fun onParticipantJoined(participant: Participant) {
            participants.add(participant)
            notifyItemInserted(participants.size - 1)
        }

        override fun onParticipantLeft(participant: Participant) {
            // remove participant from grid
        }
    })
}

override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): PeerViewHolder {
    containerHeight = parent.height
    return PeerViewHolder(
        LayoutInflater.from(parent.context)
            .inflate(R.layout.item_remote_peer, parent, false)
    )
}

override fun onBindViewHolder(holder: PeerViewHolder, position: Int) {
    val participant = participants[position]

    val layoutParams = holder.itemView.layoutParams
    layoutParams.height = containerHeight / 3
    holder.itemView.layoutParams = layoutParams

    for ((_, stream) in participant.streams) {
        if (stream.kind.equals("video", ignoreCase = true)) {
            val videoTrack = stream.track as VideoTrack
            holder.participantView.addTrack(videoTrack)
            break
        }
    }

    participant.addEventListener(object : ParticipantEventListener() {
        override fun onStreamEnabled(stream: Stream) {
            if (stream.kind.equals("video", ignoreCase = true)) {
                val videoTrack = stream.track as VideoTrack
                holder.participantView.addTrack(videoTrack)
            }
        }
    })
}

override fun getItemCount(): Int {
    return participants.size
}

class PeerViewHolder(view: View) : RecyclerView.ViewHolder(view) {
    var participantView: VideoView = view.findViewById(R.id.participantView)
}
}

```

Please refer the [example code](https://github.com/videosdk-live/videosdk-rtc-android-kotlin-sdk-example) on Github for more details.

---

**Java:**

```js title="ParticipantAdapter.java"

public class ParticipantAdapter extends RecyclerView.Adapter<ParticipantAdapter.PeerViewHolder> {

private final List<Participant> participants = new ArrayList<>();
private int containerHeight;

public ParticipantAdapter(Meeting meeting) {
    Handler mHandler = new Handler(Looper.getMainLooper());

    meeting.addEventListener(new MeetingEventListener() {
        @Override
        public void onParticipantJoined(Participant participant) {
            participants.add(participant);
            mHandler.post(() -> notifyItemInserted(participants.size() - 1));
        }

        @Override
        public void onParticipantLeft(Participant participant) {
            // remove participant from grid
        }
    });
}

@NonNull
@Override
public PeerViewHolder onCreateViewHolder(@NonNull ViewGroup parent, int viewType) {
    containerHeight = parent.getHeight();

    return new PeerViewHolder(LayoutInflater.from(parent.getContext())
            .inflate(R.layout.item_remote_peer, parent, false));
}

@Override
public void onBindViewHolder(@NonNull PeerViewHolder holder, int position) {
    final Participant participant = participants.get(position);

    ViewGroup.LayoutParams layoutParams = holder.itemView.getLayoutParams();
    layoutParams.height = containerHeight / 3;
    holder.itemView.setLayoutParams(layoutParams);

    for (Map.Entry<String, Stream> entry : participant.getStreams().entrySet()) {
        Stream stream = entry.getValue();
        if (stream.getKind().equalsIgnoreCase("video")) {
            VideoTrack videoTrack = (VideoTrack) stream.getTrack();
            holder.participantView.addTrack(videoTrack);
            break;
        }
    }

    participant.addEventListener(new ParticipantEventListener() {
        @Override
        public void onStreamEnabled(Stream stream) {
            if (stream.getKind().equalsIgnoreCase("video")) {
                VideoTrack videoTrack = (VideoTrack) stream.getTrack();
                holder.participantView.addTrack(videoTrack);
            }
        }
    });

}

@Override
public int getItemCount() {
    return participants.size();
}

static class PeerViewHolder extends RecyclerView.ViewHolder {
    public VideoView participantView;
    public View itemView;

    PeerViewHolder(@NonNull View view) {
        super(view);

        itemView = view;

        participantView = view.findViewById(R.id.participantView);
    }
}
}
```

Please refer the [example code](https://github.com/videosdk-live/videosdk-rtc-android-java-sdk-example/blob/master/app/src/main/java/live/videosdk/rtc/android/java) on Github for more details.

## 3. Participant Related Events

1. **onParticipantJoined** - Whenever any new participant join the meeting, `onParticipantJoined` event will trigger. For example, the meeting is running with **Alice** and **Bob**, then **Eve** join that meeting, after that `onParticipantJoined` event trigger and return the [participant object](/android/guide/video-and-audio-calling-api-sdk/features/manage-participants#participant-object-properties).

2. **onParticipantLeft** - Whenever any participant leave/exit the meeting, `onParticipantLeft` event will trigger.For example, the meeting is running with **Alice** and **Bob**, then **Bob** leave that meeting, after that `onParticipantLeft` event trigger and return the [participant object](/android/guide/video-and-audio-calling-api-sdk/features/manage-participants#participant-object-properties)

3. **onPresenterChanged** - Whenever any participant present/screenshare their screen/window in meeting, `onPresenterChanged` event will trigger and return the presenter `participantId`.

4. **onStreamEnabled** - Whenever any participant enabled mic/webcam in meeting, `onStreamEnabled` event will trigger and return [Stream](/android/guide/video-and-audio-calling-api-sdk/features/manage-participants#stream-object-properties).

5. **onStreamDisabled** - Whenever any participant disabled mic/webcam in meeting, `onStreamDisabled` event will trigger and return [Stream](/android/guide/video-and-audio-calling-api-sdk/features/manage-participants#stream-object-properties).

**Kotlin:**

```js
 meeting.addEventListener(object : MeetingEventListener() {
override fun onParticipantJoined(participant: Participant) {
    participant.addEventListener(object : ParticipantEventListener() {
            override fun onStreamEnabled(stream: Stream) {
                if (stream.kind.equals("video", ignoreCase = true)) {
                     // participant video enabled
                } else if (stream.kind.equals("audio", ignoreCase = true)) {
                     // participant mic enabled
                }
            }
            override fun onStreamDisabled(stream: Stream) {
                if (stream.kind.equals("video", ignoreCase = true)) {
                     // participant video disabled
                } else if (stream.kind.equals("audio", ignoreCase = true)) {
                    // participant mic disabled
                }
            }
    })
}

override fun onParticipantLeft(participant: Participant) {
    Toast.makeText(this@MainActivity, participant.displayName + " left", Toast.LENGTH_SHORT).show()
}

override fun onPresenterChanged(presenterId: String) {
    Toast.makeText(this@MainActivity, presenterId + " started presenting", Toast.LENGTH_SHORT).show()
}
 })
```

---

**Java:**

```js
 meeting.addEventListener(new MeetingEventListener() {
@Override
public void onParticipantJoined(Participant participant) {
  participant.addEventListener(new ParticipantEventListener() {
      @Override
      public void onStreamEnabled(Stream stream) {
          if (stream.getKind().equalsIgnoreCase("video")) {
              // participant video enabled
          } else if (stream.getKind().equalsIgnoreCase("audio")) {
              // participant mic enabled
          }
      }

      @Override
      public void onStreamDisabled(Stream stream) {
          if (stream.getKind().equalsIgnoreCase("video")) {
              // participant video disabled
          } else if (stream.getKind().equalsIgnoreCase("audio")) {
              // participant mic disabled
          }
      }
  });
}

@Override
public void onParticipantLeft(Participant participant) {
  Toast
    .makeText(
      MainActivity.this,
      participant.getDisplayName() + " left",
      Toast.LENGTH_SHORT
    )
    .show();
}
@Override
public void onPresenterChanged(String presenterId) {
  Toast
    .makeText(
      MainActivity.this,
      presenterId + " started presenting",
      Toast.LENGTH_SHORT
    )
    .show();
}
 });
```


---

# Mic Controls - Android

Whenever any participant wants to start / stop broadcasting their audio to other participant in meeting, they can simply do it with VideoSDK Meeting.

This guide will provide an overview of how to use enable and disable Mic in a meeting.

1. **Enable Mic** - By using `unmuteMic()` function, a participant can publish audio to other participants.
2. **Disable Mic** - By using `muteMic()` function, a participant can stop publishing audio to other participants.

### 1. Enable, Disable Mic



**Kotlin:**

```js
  private var micEnabled = false

  btnMic!!.setOnClickListener { _: View? ->
// Toggle participant mic in meeting
 if (micEnabled) {
   meeting!!.muteMic()
   micEnabled=false
 } else {
  meeting!!.unmuteMic()
  micEnabled=true
 }
  }
```

---

**Java:**

```js
  private boolean micEnabled = false;

  btnMic.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
      // Toggle participant mic in meeting
      if (micEnabled) {
          meeting.muteMic();
          micEnabled = false;
      } else {
          meeting.unmuteMic();
          micEnabled = true;
      }
  }
  });
```

### Events

**Event associated with `unmuteMic()`:**

- Every Participant will receive a callback on [`onStreamEnabled()`](../../../api/sdk-reference/participant-class/participant-event-listener-class.md#onstreamenabled) of the [`Participant`](../../../api/sdk-reference/participant-class//introduction.md) with `Stream` object.

**Event associated with `muteMic()`:**

- Every Participant will receive a callback on [`onStreamDisabled()`](../../../api/sdk-reference/participant-class/participant-event-listener-class.md#onstreamenabled) of the [`Participant`](../../../api/sdk-reference/participant-class//introduction.md) with `Stream` object.

**Kotlin:**

```js
  meeting!!.localParticipant.addEventListener(object : ParticipantEventListener() {
override fun onStreamEnabled(stream: Stream) {
    //
    if(stream.getKind().equals("audio")){
      //participant turned on audio
    }
}

override fun onStreamDisabled(stream: Stream) {
    //
    if(stream.getKind().equals("audio")){
      //participant turned off audio
    }
}
  });
```

---

**Java:**

```js
  participant.addEventListener(new ParticipantEventListener() {
@Override
public void onStreamEnabled(Stream stream) {
    //
    if(stream.getKind().equals("audio")){
      //participant turned on audio
    }
}

@Override
public void onStreamDisabled(Stream stream) {
    //
    if(stream.getKind().equals("audio")){
      //participant turned off audio
    }
}
  });
```

### 2. Change Audio Device

#### Get all audio Devices

- By using `meeting.getMics()` function, a participant can get all the connected mics.

**Kotlin:**

```js
  private fun getMics(): MutableSet
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
//...
</manifest>
```


---

# Pause/Resume Video Stream - Android

Whenver you wish to stop/resume downlaod stream(webcam, screenShare and mic) of participant, you can simply do it by using `pause`, `resume` methods.

## Pause video stream

- `pause()` method is used for pause stream(webcam, screenShare and mic) of a particular participant.



**Kotlin:**

```js
  btnPause!!.setOnClickListener { _: View? ->
for ((_, stream) in participant.streams) {
  stream.pause()
}
  }
```

---

**Java:**

```js
  btnPause.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
    for (Map.Entry<String, Stream> entry : participant.getStreams().entrySet()) {
            Stream stream = entry.getValue();
            stream.pause();
    }
  }
  });
```

## Resume video stream

- `resume()` method is used to resume stream(webcam, screenShare and mic) of a particular participant.

**Kotlin:**

```js
  btnResume!!.setOnClickListener { _: View? ->
for ((_, stream) in participant.streams) {
  stream.resume()
}
  }
```

---

**Java:**

```js
  btnResume.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
    for (Map.Entry<String, Stream> entry : participant.getStreams().entrySet()) {
        Stream stream = entry.getValue();
        stream.resume();
    }
  }
  });
```


---

# Pin Participants - Android

In any meeting with large number of participants, if you want to show only one or two participant(s) on main screen then you can pin that perticipants so that viewers can only focus upon that participants only.

This guide will provide an overview of how to pin or unpin any participants in a meeting.

:::note
`pin()` and `unpin()` functions will take `string` or `null` as an argument. Pin will be effective for both webcam and screenshare of that participant.

Suppose you want to pin or unpin only webcam of that participant then you can pass `CAM`, else if you want to pin or unpin only screenshare of that participant then you can pass `SHARE`.

You can also pass `SHARE_AND_CAM` if you want to `pin` or `unpin` both webcam and screenshare media of that user, or passing `null` or nothing as an argument will also work in the same way.

If any participant's webcam is pinned but not screenshare, then calling `pin("SHARE")` the new pinState of that participant will be `{ cam: true, share: true }`.  
:::

### Pin And Unpin a Participant



**Kotlin:**

```js
  // Pin both webcam and screenshare of that participant
  meeting!!.participants[participantId].pin("SHARE_AND_CAM")

  // Pin webcam of that participant
  meeting!!.participants[participantId].pin("CAM")

  // Pin screenshare of that participant
  meeting!!.participants[participantId].pin("SHARE")

  //
  // Unpin both webcam and screenshare of that participant
  meeting!!.participants[participantId].unpin("SHARE_AND_CAM");

  // Unpin webcam of that participant
  meeting!!.participants[participantId].unpin("CAM");

  // Unpin screenshare of that participant
  meeting!!.participants[participantId].unpin("SHARE");
```

---

**Java:**

```js
// Pin both webcam and screenshare of that participant
meeting.getParticipants().get(participantId).pin("SHARE_AND_CAM");

// Pin webcam of that participant
meeting.getParticipants().get(participantId).pin("CAM");

// Pin screenshare of that participant
meeting.getParticipants().get(participantId).pin("SHARE");

//
// Unpin both webcam and screenshare of that participant
meeting.getParticipants().get(participantId).unpin(null);

// Unpin webcam of that participant
meeting.getParticipants().get(participantId).unpin("CAM");

// Unpin screenshare of that participant
meeting.getParticipants().get(participantId).unpin("SHARE");
```

### onPinStateChanged Event

Whenever any participant got pinned or unpinned by any participant, `onPinStateChanged` event will be triggered.

**Kotlin:**

```javascript
 override fun onPinStateChanged(pinStateData: JSONObject?) {
   Log.d("onPinStateChanged: ", pinStateData.getString("peerId")) // id of participant who were pinned
   Log.d("onPinStateChanged: ", pinStateData.getJSONObject("state")) // { cam: true, share: true }
   Log.d("onPinStateChanged: ", pinStateData.getString("pinnedBy")) // id of participant who pinned that participant
  }
```

---

**Java:**

```javascript
@Override
  public void onPinStateChanged(JSONObject pinStateData) {
Log.d("onPinStateChanged: ", pinStateData.getString("peerId")); // id of participant who were pinned
Log.d("onPinStateChanged: ", pinStateData.getJSONObject("state")); // { cam: true, share: true }
Log.d("onPinStateChanged: ", pinStateData.getString("pinnedBy")); // id of participant who pinned that participant
  }

```


---

# PubSub - Android

PubSub feature allows the participant to send and receive messages of the topics which he has subscribed.

## Methods

### publish()

This method is use for publishing message of specific topic.

#### Syntax

```js
public void publish(String topic, String message, PubSubPublishOptions options)
```

| Parameter Name | Type                 | Description                                                                                                                                       |
| -------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| topic          | String               | This should be the topic for which you are publishing a message.                                                                                  |
| message        | String               | This is the actual message, which will be published to participants, who had subscribed to a particular topic.                                    |
| options        | PubSubPublishOptions | This is an object of PubSubPublishOptions, which provides an option, such as `persist`, which persists message history for upcoming participants. |

#### Example



**Kotlin:**

```js
private fun sendMessage() {
  val options = PubSubPublishOptions()
  options.isPersist = true
  meeting!!.pubSub.publish("CHAT", "Hello from Android", options)
}
```

---

**Java:**

```js
protected void sendMessage() {
  PubSubPublishOptions options = new PubSubPublishOptions();
  options.setPersist(true);
  meeting.pubSub.publish("CHAT", "Hello from Android", options);
}
```

### subscribe()

This method is used to subscribe for particular topic. This method returns a list of messages which were sent earlier.

#### Syntax

```js
public List<PubSubMessage> subscribe(String topic, PubSubMessageListener listener)
```

| Parameter Name | Type                  | Description                                                                                                                                      |
| -------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| topic          | String                | This should be the topic to be subscribed.                                                                                                       |
| listener       | PubSubMessageListener | This is an object of PubSubMessageListener, which listens for upcoming messages and calls onMessageReceived function, when new message received. |

#### Example

**Kotlin:**

```js
val pubSubMessageListener = object : PubSubMessageListener {
override fun onMessageReceived(message: PubSubMessage) {
    Log.d("#message", "onMessageReceived: ${message.message}")
}
override fun onOldMessagesReceived(messages: List<PubSubMessage>) {
    // Persisted message list
    Log.d("#message", "onOldMessagesReceived: $messages")
}
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...
  
  // Subscribe for 'CHAT' topic
  meeting!!.pubSub.subscribe("CHAT", pubSubMessageListener)

}
```

---

**Java:**

```js
PubSubMessageListener pubSubMessageListener = new PubSubMessageListener() {
@Override
public void onMessageReceived(PubSubMessage message) {
    Log.d("#message", "onMessageReceived: " + message.getMessage());
}

@Override
  public void onOldMessagesReceived(List<PubSubMessage> messages) {
  // Persisted message list
  Log.d("#message", "onOldMessagesReceived: " + messages);
}
};

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // Subscribe for 'CHAT' topic
  meeting.pubSub.subscribe("CHAT",pubSubMessageListener);

}
```

### unsubscribe()

This method is used to unsubscribe the message topic.

#### Syntax

```js
public void unsubscribe(String topic, PubSubMessageListener listener)
```

| Parameter Name | Type                  | Description                                                                    |
| -------------- | --------------------- | ------------------------------------------------------------------------------ |
| topic          | String                | This should be the topic to be unsubscribed.                                   |
| listener       | PubSubMessageListener | This is an object of PubSubMessageListener, which was passed in `subscribe()`. |

#### Example

**Kotlin:**

```js
fun unsubscribe() {
  // Unsubscribe 'CHAT' topic
  meeting!!.pubSub.unsubscribe("CHAT", pubSubMessageListener)
}
```

---

**Java:**

```js
public void unsubscribe(){
  // Unsubscribe 'CHAT' topic
  meeting.pubSub.unsubscribe("CHAT", pubSubMessageListener);
}
```

## Sample Code

**Kotlin:**

```js
package live.videosdk.rtc.android.kotlin

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.view.View
import android.widget.EditText
import android.widget.Toast
import androidx.appcompat.widget.Toolbar
import androidx.recyclerview.widget.LinearLayoutManager
import androidx.recyclerview.widget.RecyclerView
import live.videosdk.rtc.android.Meeting
import live.videosdk.rtc.android.listeners.PubSubMessageListener
import live.videosdk.rtc.android.model.PubSubPublishOptions

class ChatActivity : AppCompatActivity() {

// Meeting
var meeting: Meeting? = null

// PubSubMessageListener
    val pubSubMessageListener = object : PubSubMessageListener {
    override fun onMessageReceived(message: PubSubMessage) {
        Log.d("#message", "onMessageReceived: ${message.message}")
    }
    override fun onOldMessagesReceived(messages: List<PubSubMessage>) {
        // Persisted message list
        Log.d("#message", "onOldMessagesReceived: $messages")
    }
}

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_chat)

    /**
     * Here, we have created 'MainApplication' class, which extends android.app.Application class.
     * It has Meeting property and getter and setter methods of Meeting property.
     * In your android manifest, you must declare the class implementing android.app.Application (add the android:name=".MainApplication" attribute to the existing application tag):
     * In MainActivity.kt, we have set Meeting property.
     *
     * For Example: (MainActivity.kt)
     * var meeting = VideoSDK.initMeeting(context, meetingId, ParticipantName, micEnabled, webcamEnabled, paricipantId, mode, customTrack, metaData,signalingBaseUrl,preferredProtocol)
     * (this.application as MainApplication).meeting = meeting
    */

    // Get Meeting
    meeting = (this.application as MainApplication).meeting

    // Subscribe for 'CHAT' topic
    meeting!!.pubSub.subscribe("CHAT", pubSubMessageListener)

    sendMessage()
}

private fun sendMessage() {
  val options = PubSubPublishOptions()
  options.isPersist = true
  meeting!!.pubSub.publish("CHAT", "Hello from Android", options)
}

override fun onDestroy() {
  // Unsubscribe for 'CHAT' topic
  meeting!!.pubSub.unsubscribe("CHAT", pubSubMessageListener)
  super.onDestroy()
}
}
```

---

**Java:**

```js
package live.videosdk.rtc.android.java;

import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;
import java.util.List;
import live.videosdk.rtc.android.Meeting;
import live.videosdk.rtc.android.lib.PubSubMessage;
import live.videosdk.rtc.android.listeners.PubSubMessageListener;
import live.videosdk.rtc.android.model.PubSubPublishOptions;

public class ChatActivity extends AppCompatActivity {

// Meeting
Meeting meeting;

// PubSubMessageListener
PubSubMessageListener pubSubMessageListener = new PubSubMessageListener() {
    @Override
    public void onMessageReceived(PubSubMessage message) {
        Log.d("#message", "onMessageReceived: " + message.getMessage());
    }
    
    @Override
      public void onOldMessagesReceived(List<PubSubMessage> messages) {
      // Persisted message list
      Log.d("#message", "onOldMessagesReceived: " + messages);
    }
};

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_chat);

    /**
     * Here, we have created 'MainApplication' class, which extends android.app.Application class.
     * It has Meeting property and getter and setter methods of Meeting property.
     * In your android manifest, you must declare the class implementing android.app.Application (add the android:name=".MainApplication" attribute to the existing application tag):
     * In MainActivity.java, we have set Meeting property.
     *
     * For Example: (MainActivity.java)
     * Meeting meeting = VideoSDK.initMeeting(context, meetingId, ParticipantName, micEnabled, webcamEnabled, participantId, mode, customTrack, metaData, signalingBaseUrl,preferredProtocol);
     * ((MainApplication) this.getApplication()).setMeeting(meeting);
    */

    // Get Meeting
    meeting = ((MainApplication) this.getApplication()).getMeeting();

    // Subscribe for 'CHAT' topic
    List<PubSubMessage> pubSubMessageList = meeting.pubSub.subscribe("CHAT", pubSubMessageListener);

    sendMessage();
}

protected void sendMessage() {
  PubSubPublishOptions publishOptions = new PubSubPublishOptions();
  publishOptions.setPersist(true);
  meeting.pubSub.publish("CHAT", "Hello from Android", publishOptions);
}

@Override
protected void onDestroy() {
  // Unsubscribe for 'CHAT' topic
  meeting.pubSub.unsubscribe("CHAT", pubSubMessageListener);
  super.onDestroy();
}
}
```


---

# Record Meeting - Android

Record meeting allows participants to record video & audio during the meeting. The recording files are available in developer dashboard.
Any participant can start / stop recording any time during the meeting.

This guide will provide an overview of how to implement start and stop Meeting Recording.

1. **Start Recording** - By using `startRecording()` function, a participant can start meeting recording.
2. **Stop Recording** - By using `stopRecording()` function, a participant can stop meeting recording.

### Start And Stop Recording



**Kotlin:**

```js
// TODO: change webhookUrl
val webhookUrl = "<webhook-url-here>"

// keep track of recording
val recording = false

findViewById<View>(R.id.btnRecording).setOnClickListener { view: View? ->
if (!recording) {
    meeting!!.startRecording(webhookUrl)
} else {
    meeting!!.stopRecording()
}
}
```

---

**Java:**

```js
// TODO: change webhookUrl
String webhookUrl = "<webhook-url-here>";

// keep track of recording
boolean recording = false;

findViewById(R.id.btnRecording).setOnClickListener(view -> {
if (!recording) {
    meeting.startRecording(webhookUrl);
} else {
    meeting.stopRecording();
}
});
```

### Events

- **onRecordingStateChanged** - A `onRecordingStateChanged` event will be triggered any time the recording state of a meeting changes.

**Kotlin:**

```js
object : MeetingEventListener() {
  override fun onRecordingStateChanged(recordingState: String) {
when (recordingState) {
    "RECORDING_STARTING" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is starting")
    }
    "RECORDING_STARTED" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is started")
    }
    "RECORDING_STOPPING" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is stopping")
    }
    "RECORDING_STOPPED" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is stopped")
    }
}
  }
}
```

---

**Java:**

```js
new MeetingEventListener() {
  @Override
  public void onRecordingStateChanged(String recordingState) {
  switch (recordingState) {
      case "RECORDING_STARTING":
          Log.d("onRecordingStateChanged", "Meeting recording is starting");
          break;
      case "RECORDING_STARTED":
          Log.d("onRecordingStateChanged", "Meeting recording is started");
          break;
      case "RECORDING_STOPPING":
          Log.d("onRecordingStateChanged", "Meeting recording is stopping");
          break;
      case "RECORDING_STOPPED":
          Log.d("onRecordingStateChanged", "Meeting recording is stopped");
          break;
  }
  }
}
```


---

# Remove Participant - Android

Remove participant allows removing participant while session is on-going. This can be helpful when moderation in particular meeting is required.



**Kotlin:**

```js
val participant = meeting!!.participants.get("<participant-id>")

// This will emit an event called "onParticipantLeft" to that particular participant
participant.remove()
```

---

**Java:**

```js
Participant participant = meeting.getParticipants().get("<participant-id>");

// Remove participant from active session
// This will emit an event called "onParticipantLeft" to that particular participant
participant.remove();
```

### Events

**onParticipantLeft** - Removing participant will trigger `onParticipantLeft` event.

**Kotlin:**

```javascript
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {

  override fun onParticipantLeft(participant: Participant) {
// Triggers when a participant is removed or leaves the meeting.
Log.d("#meeting", participant.displayName + " left");
  }
}
```

---

**Java:**

```javascript
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onParticipantLeft(Participant participant) {
// Triggers when a participant is removed or leaves the meeting.
Log.d("#meeting", participant.getDisplayName() + " left");
  }
}
```


---

# Share Your Screen - Android

- Whenever any participant wants to share a complete screen of mobile, they can simply do it with VideoSDK Meeting.

- This guide will provide an overview of how to enable or disable Screen Share in a meeting.

## How Screen share works?

- The following diagram shows flow of the screen sharing in android using VideoSDK:

<div style={{textAlign: 'center'}}>

![VideoSDK Android Screenshare Flow Diagram](/img/android/screenshare/flow_diagram.png)

</div>

## Enable Screen Share

- A participant’s Screen share stream is provided via the `MediaProjection` API. This API is only compatible with `Build.VERSION_CODES.LOLLIPOP` or higher.

- Get an instance of the `MediaProjectionManager` and Call the `createScreenCaptureIntent()` method in an activity. This initiates a prompt dialog for the user to confirm screen projection.

- One will get a prompt dialog like this:

<div style={{textAlign: 'center'}}>

<img
src={require('/img/android/screenshare/user_permission.jpg').default}
alt="user permission"
width="450"
/>

</div>

<br/>

- After permission is received from the user, call `meeting.enableScreenShare()` method.



**Kotlin:**

```js
private fun enableScreenShare() {
val mediaProjectionManager = application.getSystemService(
    MEDIA_PROJECTION_SERVICE
) as MediaProjectionManager
startActivityForResult(
    mediaProjectionManager.createScreenCaptureIntent(), CAPTURE_PERMISSION_REQUEST_CODE
)
}

public override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode != CAPTURE_PERMISSION_REQUEST_CODE) return
if (resultCode == RESULT_OK) {
    meeting!!.enableScreenShare(data)
}
}
```

---

**Java:**

```js
private void enableScreenShare() {
MediaProjectionManager mediaProjectionManager =
    (MediaProjectionManager) getApplication().getSystemService(
        Context.MEDIA_PROJECTION_SERVICE);
startActivityForResult(
    mediaProjectionManager.createScreenCaptureIntent(), CAPTURE_PERMISSION_REQUEST_CODE);
}

@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
super.onActivityResult(requestCode, resultCode, data);
if (requestCode != CAPTURE_PERMISSION_REQUEST_CODE)
    return;
if (resultCode == Activity.RESULT_OK) {
    meeting.enableScreenShare(data);
}
}
```

### Customise notification

- When a presenter starts screen share, presenter will receive a notification with a pre-defined title and message.

- Notification with pre-defined title and message will look like this:

<div style={{textAlign: 'center'}}>

<img
src={require('/img/android/screenshare/notification.jpg').default}
alt="notification"
width="450"
/>

</div>

- You can Customise those title, message and icon as per your requirements using `<meta-data>` specified in `app/src/main/AndroidManifest.xml`.

```js
<application>
  <meta-data
    android:name="notificationTitle"
    android:value="@string/notificationTitle"
  />
  <meta-data
    android:name="notificationContent"
    android:value="@string/notificationContent"
  />
  <meta-data
    android:name="notificationIcon"
    android:resource="@mipmap/ic_launcher_round"
  />
</application>
```

## Disable Screen Share

By using `meeting.disableScreenShare()` function, a participant can stop publishing screen stream to other participants.

**Kotlin:**

```js
private fun disableScreenShare() {
meeting!!.disableScreenShare()
}
```

---

**Java:**

```js
private void disableScreenShare(){
meeting.disableScreenShare();
}
```

## Display Screen Share Stream

#### Local Participant

When a Local participant share the screen, `onStreamEnabled()` of `ParticipantEventListener` is triggered with the `Stream` which can be added to a `VideoView`.

**Kotlin:**

```js
private fun setLocalListeners() {
meeting!!.localParticipant.addEventListener(object : ParticipantEventListener() {
    override fun onStreamEnabled(stream: Stream) {
       if (stream.kind.equals("share", ignoreCase = true)) {
            // display share video
            val videoTrack = stream.track as VideoTrack
            shareView!!.addTrack(videoTrack)
        }
    }
    override fun onStreamDisabled(stream: Stream) {
        if (stream.kind.equals("share", ignoreCase = true)) {
           shareView!!.removeTrack()
        }
    }
});
}
```

---

**Java:**

```js
private void setLocalListeners() {
meeting.getLocalParticipant().addEventListener(new ParticipantEventListener() {
    @Override
    public void onStreamEnabled(Stream stream) {
        if (stream.getKind().equalsIgnoreCase("share")) {
            // display share video
            VideoTrack videoTrack = (VideoTrack) stream.getTrack();
            shareView.addTrack(videoTrack);
        }
    }
    @Override
    public void onStreamDisabled(Stream stream) {
        if (stream.getKind().equalsIgnoreCase("share")) {
            shareView.removeTrack();
        }
    }
});
}
```

#### Other Participants

When other participant(Except you) share their screen, `onPresenterChanged()` in the `MeetingEventListener` is triggered with the `participantId` of the screen share.

**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
override fun onPresenterChanged(participantId: String) {
    updatePresenter(participantId)
}
}

//Getting the stream from the participantId
private fun updatePresenter(participantId: String?) {
// find participant
val participant = meeting!!.participants.get(participantId) ?: return

// find share stream in participant
var shareStream: Stream? = null
for (stream: Stream in participant.streams.values) {
    if ((stream.kind == "share")) {
        shareStream = stream
        break
    }
}
if (shareStream == null) return

// display share video
val videoTrack = shareStream.track as VideoTrack
shareView!!.addTrack(videoTrack)

// listen for share stop event
participant.addEventListener(object : ParticipantEventListener() {
    override fun onStreamDisabled(stream: Stream) {
        if ((stream.kind == "share")) {
            shareView!!.removeTrack()
        }
    }
})
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
//Triggered when Presenter changes
@Override
public void onPresenterChanged(String participantId) {
    updatePresenter(participantId);
}
};

//Getting the stream from the participantId
private void updatePresenter(String participantId) {
// find participant
Participant participant = meeting.getParticipants().get(participantId);
if (participant == null) return;

// find share stream in participant
Stream shareStream = null;
for (Stream stream: participant.getStreams().values()) {
    if (stream.getKind().equals("share")) {
        shareStream = stream;
        break;
    }
}
if (shareStream == null) return;

// display share video
VideoTrack videoTrack = (VideoTrack) shareStream.getTrack();
shareView.addTrack(videoTrack)

// listen for share stop event
participant.addEventListener(new ParticipantEventListener() {
    @Override
    public void onStreamDisabled(Stream stream) {
        if (stream.getKind().equals("share")) {
            shareView.removeTrack();
        }
    }
});
}
```

:::info

- Here screenShare stream is displayed using `VideoView`, but you may also use `SurfaceViewRender` for the same.
- For `VideoView`, SDK version should be `0.1.13` or higher.
- To know more about `VideoView`, please visit [here](/android/guide/video-and-audio-calling-api-sdk/components/videoView)

:::


---

# Set Participant Video Quality - Android

This feature allows participants to set other participant's video quality during the meeting.

:::info

MultiStream is not supported by the Android SDK. Use `customTrack` instead of `setQuality()` if you want to change participant's quality who joined using our Android SDK.

To know more about customTrack visit [here](/android/guide/video-and-audio-calling-api-sdk/features/custom-track/custom-video-track)

:::

## Set Quality

- `setQuality` method will accept `low`, `med` or `high` as string parameter.



**Kotlin:**

```js
private fun setQuality()
{
  val participants: Iterator<Participant> = meeting!!.participants.values.iterator()
  for (i in 0 until meeting!!.participants.size) {
val participant = participants.next()

participant.quality = "low"
//or
participant.quality = "med"
//or
participant.quality = "high"
  }
}
```

---

**Java:**

```js
private void setQuality() {
  final Iterator<Participant> participants = meeting.getParticipants().values().iterator();

  for (int i = 0; i < meeting.getParticipants().size(); i++) {
Participant participant = participants.next();

participant.setQuality("low");
//or
participant.setQuality("med");
//or
participant.setQuality("high");
  }
}
```


---

# Set Viewport - Android

When you are working with Video Calling, video quality is the most important part of communication. When a participant is shown on the screen, consuming multiple high quality although not required, will result in more memory and CPU usage of the device, eventually degrading quality.

The way to optimze around these situation is to consume the video quality which is required to fit the view of a particular participant, resulting in better quality, less usage of network bandwith and providing a better experience.

Viewport is the size of window or visible area in which video for the participant is shown. We can optimize the consuming video quality based on the viewport size of the participant. For example if the viewport size of a particular participant view is `480x360`, VideoSDK will download a `480x360` stream. If a participant on screen is present in bigger size, VideoSDK will provide a higher quality video for that particular participant only.


<div style={{textAlign: 'center'}}>



</div>

<br/>

:::info

MultiStream is not supported by the Android SDK. Use `customTrack` instead of `setViewPort()` if you want to change participant's quality who joined using our Android SDK.

To know more about customTrack visit [here](/android/guide/video-and-audio-calling-api-sdk/features/custom-track/custom-video-track)

:::

### setViewPort()

`setViewPort()` can be used to achieve the best optimization of the video. This method is called with the `width` and `height` of the participant view on the `Participant` object and VideoSDK will handle the rest.

##### Parameters

- `width`

  - type: `int`
  - Width of the participant view for which the quliaty of video is to be adjusted.

- `height`
  - type: `int`
  - Height of the participant view for which the quliaty of video is to be adjusted.

### Example



**Kotlin:**

```js
class ParticipantAdapter(meeting: Meeting) : RecyclerView.Adapter<ParticipantAdapter.PeerViewHolder() {

  //Your variables here

  override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): PeerViewHolder {
containerHeight = parent.height
return PeerViewHolder(
  LayoutInflater.from(parent.context)
    .inflate(R.layout.item_remote_peer, parent, false)
)
  }

  override fun onBindViewHolder(holder: PeerViewHolder, position: Int) {
val participant = participants[position]

//View updates here

//Update Consuming quality using setViewPort
participant.setViewPort(holder.itemView.getWidth(), holder.itemView.getHeight());
  }
}

```

---

**Java:**

```js

public class ParticipantAdapter extends RecyclerView.Adapter<ParticipantAdapter.PeerViewHolder> {

  //Your variables here

  @NonNull
  @Override
  public PeerViewHolder onCreateViewHolder(@NonNull ViewGroup parent, int viewType) {
containerHeight = parent.getHeight();

return new PeerViewHolder(LayoutInflater.from(parent.getContext())
        .inflate(R.layout.item_remote_peer, parent, false));
  }

  @Override
  public void onBindViewHolder(@NonNull PeerViewHolder holder, int position) {
final Participant participant = participants.get(position);

//View updates here

//Update Consuming quality using setViewPort
participant.setViewPort(holder.itemView.getWidth(), holder.itemView.getHeight());
  }
}

```

The complete usage of this method can be seen here in the [code sample](https://github.com/videosdk-live/videosdk-rtc-android-java-sdk-example/blob/master/app/src/main/java/live/videosdk/rtc/android/java/ParticipantAdapter.java#L134)


---

# Speaker Indication - Android

Speaker indication feature in VideoSDK let you know, which participant is active speaker in a meeting.

Whenever any participant speaks in meeting, `onSpeakerChanged` event will trigger.

For example, the meeting is running with **Alice** and **Bob**. Whenever any of them speaks, `onSpeakerChanged` event will trigger and return the speaker `participantId`.

We can access `onSpeakerChanged` event through [meeting object](../../../api/sdk-reference/meeting-class/introduction.md).

### onSpeakerChanged Event



**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
 // ...
override fun onSpeakerChanged(participantId: String?) {
    Toast.makeText(this@MainActivity, "active Speaker Id" + participantId, Toast.LENGTH_SHORT).show();
    super.onSpeakerChanged(participantId)
}
};
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
 // ...
@Override
public void onSpeakerChanged(String participantId) {
    Toast.makeText(MainActivity.this, "active Speaker Id" + participantId, Toast.LENGTH_SHORT).show();
    super.onSpeakerChanged(participantId);
}
};
```


---

# Start or Join Meeting - Android

<div style={{display:'flex',flexDirection:'row',alignItems:'stretch',}}>
<div style={{}}>
<p>After the successful installation of VideoSDK, the next step is to integrate VideoSDK features with your webApp/MobileApp.</p>

<p>To Communicate with other participant's audio or video call, you will need to join the meeting.</p>

<p>This guide will provide an overview of how to configure, initialize and join a VideoSDK meeting.</p>

</div>
<div>
<img src="/img/gif/new-meeting.gif"/>
</div>

</div>

## 1. Configuration

To configure a meeting, you will need [generated token](/android/guide/video-and-audio-calling-api-sdk/server-setup) and [meetingId](/api-reference/realtime-communication/create-room), we had discussed in [Server Setup](/android/guide/video-and-audio-calling-api-sdk/server-setup).
This code snippet calls API from local server

**Scenario 1** - Suppose you **don't have** any meetingId, you can simply generate meetingId by invoking `create-meeting` API.

**Scenario 2** - Suppose you **have** meetingId, now you don't have to call `create-meeting` API to generate meetingId, instead you can call `validate-meeting` API to validate meetingId.

**Token generation API is necessary for both scenario.**



**Kotlin:**

```js
package live.videosdk.rtc.android.java;

import com.androidnetworking.AndroidNetworking;
import com.androidnetworking.error.ANError;
import com.androidnetworking.interfaces.JSONObjectRequestListener;
import org.json.JSONException;
import org.json.JSONObject;

class JoinActivity : AppCompatActivity() {
  private val apiServerUrl = "http://localhost:9000"

  // ...
  // onCreate() and other methods
  private fun getToken(@Nullable meetingId: String?) {
AndroidNetworking
  .get("$apiServerUrl/get-token")
  .build()
  .getAsJSONObject(
    object : JSONObjectRequestListener {
      override fun onResponse(response: JSONObject) {
        try
        {
          token = response.getString("token")
          if (meetingId == null) {
            createMeeting(token)
          } else {
            joinMeeting(token, meetingId)
          }
        } catch (e: JSONException) {
          e.printStackTrace()
        }
      }

      override fun onError(anError: ANError) {
        anError.printStackTrace()
      }
    }
  )
  }

  private fun createMeeting(token: String) {
AndroidNetworking
  .post("$apiServerUrl/create-meeting")
  .addBodyParameter("token", token)
  .build()
  .getAsJSONObject(
    object : JSONObjectRequestListener {
      override fun onResponse(response: JSONObject) {
        try {
          // final String meetingId = response.getString("meetingId");

          // Intent intent = new Intent(JoinActivity.this, MainActivity.class);
          // intent.putExtra("token", token);
          // intent.putExtra("meetingId", meetingId);

          // startActivity(intent);
        } catch (e: JSONException) {
            e.printStackTrace()
        }
      }

      override fun onError(anError: ANError) {
        anError.printStackTrace()
      }
    }
  )
  }

  private fun joinMeeting(token: String, meetingId: String) {
AndroidNetworking
  .post("$apiServerUrl/validate-meeting/{meetingId}")
  .addPathParameter("meetingId", meetingId)
  .addBodyParameter("token", token)
  .build()
  .getAsJSONObject(
    object : JSONObjectRequestListener {
      override fun onResponse(response: JSONObject) {
        // Intent intent = new Intent(JoinActivity.this, MainActivity.class);
        // intent.putExtra("token", token);
        // intent.putExtra("meetingId", meetingId);

        // startActivity(intent);
      }

      override fun onError(anError: ANError) {
        anError.printStackTrace()
      }
    }
  )
  }
}

```

---

**Java:**

```js
package live.videosdk.rtc.android.java;

import com.androidnetworking.AndroidNetworking;
import com.androidnetworking.error.ANError;
import com.androidnetworking.interfaces.JSONObjectRequestListener;
import org.json.JSONException;
import org.json.JSONObject;

public class JoinActivity extends AppCompatActivity {
  private String apiServerUrl = "http://localhost:9000";

  // ...
  // onCreate() and other methods

  private void getToken(@Nullable String meetingId) {
AndroidNetworking
  .get(apiServerUrl + "/get-token")
  .build()
  .getAsJSONObject(
    new JSONObjectRequestListener() {
      @Override
      public void onResponse(JSONObject response) {
        try {
          String token = response.getString("token");

          if (meetingId == null) {
            createMeeting(token);
          } else {
            joinMeeting(token, meetingId);
          }
        } catch (JSONException e) {
          e.printStackTrace();
        }
      }

      @Override
      public void onError(ANError anError) {
        anError.printStackTrace();
      }
    }
  );
  }

  private void createMeeting(String token) {
AndroidNetworking
  .post(apiServerUrl + "/create-meeting")
  .addBodyParameter("token", token)
  .build()
  .getAsJSONObject(
    new JSONObjectRequestListener() {
      @Override
      public void onResponse(JSONObject response) {
        try {
          // final String meetingId = response.getString("meetingId");

          // Intent intent = new Intent(JoinActivity.this, MainActivity.class);
          // intent.putExtra("token", token);
          // intent.putExtra("meetingId", meetingId);

          // startActivity(intent);
        } catch (JSONException e) {
          e.printStackTrace();
        }
      }

      @Override
      public void onError(ANError anError) {
        anError.printStackTrace();
      }
    }
  );
  }

  private void joinMeeting(String token, String meetingId) {
AndroidNetworking
  .post(apiServerUrl + "/validate-meeting/{meetingId}")
  .addPathParameter("meetingId", meetingId)
  .addBodyParameter("token", token)
  .build()
  .getAsJSONObject(
    new JSONObjectRequestListener() {
      @Override
      public void onResponse(JSONObject response) {
        // Intent intent = new Intent(JoinActivity.this, MainActivity.class);
        // intent.putExtra("token", token);
        // intent.putExtra("meetingId", meetingId);

        // startActivity(intent);
      }

      @Override
      public void onError(ANError anError) {
        anError.printStackTrace();
      }
    }
  );
  }
}

```

## 2. Initialization




<div style={{display:'flex',flexDirection:'row',alignItems:'stretch',}}>
<div style={{}}>
<p>
After configuration, you will have to Initialize 
<p>
meeting by providing name, meetingId, micEnabled, webcamEnabled & maxResolution.
</p>
</p>

<p>
NOTE : For React & React native developer, you have

<p>to be familiar with hooks concept. You can understand hooks concept on <a href={'https://reactjs.org/docs/hooks-intro.html'}>React Hooks</a>.</p>

</p>
</div>
<div>
<img src="/img/gif/add-participant.gif"/>
</div>

</div>

**Kotlin:**

```js
import live.videosdk.rtc.android.VideoSDK;
import live.videosdk.rtc.android.Meeting;

class MainActivity : AppCompatActivity() {
  private var meeting: Meeting? = null

  override fun onCreate(savedInstanceState: Bundle?) {
// Configure parameters
val token = intent.getStringExtra("token")
val meetingId = intent.getStringExtra("meetingId")
val participantName = "John Doe"
val micEnabled = true
val webcamEnabled = true
val paticipantId="demo@123"  // If you passed `null` then SDK will create an Id by itself and will use that id.
val mode="SEND_AND_RECV"

// Configure authentication token
VideoSDK.config(token)

// create a new meeting instance
meeting = VideoSDK.initMeeting(
  this@MainActivity,
  meetingId,
  participantName,
  micEnabled,
  webcamEnabled,
  paticipantId,
  mode,
  null
)
  }
}

```

---

**Java:**

```js
import live.videosdk.rtc.android.VideoSDK;
import live.videosdk.rtc.android.Meeting;

public class MainActivity extends AppCompatActivity {
private Meeting meeting;

@Override
protected void onCreate(Bundle savedInstanceState) {

    // Configure parameters
    final String token = getIntent().getStringExtra("token");
    final String meetingId = getIntent().getStringExtra("meetingId");
    final String participantName = "John Doe";
    final boolean micEnabled = true;
    final boolean webcamEnabled = true;
    final String participantId = "demo@123"; // If you passed `null` then SDK will create an Id by itself and will use that id.
    final String mode="SEND_AND_RECV";

    // Configure authentication token
    VideoSDK.config(token);

    // create a new meeting instance
    meeting = VideoSDK.initMeeting(
            MainActivity.this,
            meetingId,
            participantName,
            micEnabled,
            webcamEnabled,
            participantId,
            mode,
            null
    );
}
}

```

## 3. Join

<div style={{display:'flex',flexDirection:'row',alignItems:'stretch',}}>
<div style={{}}>
<p>
After configuration & initialization, the third step is to call join() to join a meeting.
</p>

<p>
After joining, you will be able to Manage Participant in a meeting.
</p>

</div>
<div>
<img src="/img/gif/join-meeting.gif"/>
</div>

</div>

**Kotlin:**

```js
// After receiving mic and webcam access permissions
// join the meeting
meeting!!.join()
```

---

**Java:**

```js
// After receiving mic and webcam access permissions
// join the meeting
meeting.join();
```

## Events

Following events are emitted on the `meeting` when it is successfully joined.

- Local Participant will receive a [`onMeetingJoined`](../../../api/sdk-reference/meeting-class/meeting-event-listener-class.md#onmeetingjoined) event when successfully joined.
- Remote Participant will receive a [`onParticipantJoined`](../../../api/sdk-reference/meeting-class/meeting-event-listener-class.md#onparticipantjoined) event with the newly joined [`Participant`](../../../api/sdk-reference/participant-class/introduction.md) object from the event callback.

**Kotlin:**

```javascript
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  override fun onMeetingJoined() {
Log.d("#meeting", "onMeetingJoined()")
  }

  override fun onParticipantJoined(participant: Participant) {
Log.d("#meeting", participant.displayName + " left");
  }
}
```

---

**Java:**

```javascript
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {

  @Override
  public void onMeetingJoined() {
Log.d("#meeting", "onMeetingJoined()");
  }

  @Override
  public void onParticipantJoined(Participant participant) {
Log.d("#meeting", participant.getDisplayName() + " left");
  }
}
```


---

# Toggle Participant Media - Android

Control other participant's webcam and mic.
For better idea, let's understand this with a real case scenario

**Scenario 1 (Online Class)** - In this scenario, the lecturer(Local Participant) will control the student's(Other Participant) webcam and mic as per his/her needs.

**Scenario 2 (Online Events)** - In this scenario, the event hosts will control the audience webcam and mic when someone wants to speak.

This guide will provide an overview of how to control other participant webcam and mic in a meeting.

1. **Enable Webcam of Participant** - By using `enableWebcam()` function, a `onWebcamRequested` event will trigger on requested participant side.

   **Example** : Meeting is running with **User A** and **User B**. Now **User A** wants to Enable Webcam of **User B**, so **User A** will use `enableWebcam()` function to request **User B**, after that **User B** recieve the `onWebcamRequested` event, from there user can either accept or reject the incoming request.

2. **Disable Webcam of Participant** - By using `disableWebcam()` function, webcam of that participant will be turned off.

   **Example** : **User A** wants to Disable Webcam of **User B**, so **User A** will use `disableWebcam()` function to Disable it without any request.

3. **Enable Mic of Participant** - By using `enableMic()` function, a `onMicRequested` event will trigger on requested participant side.

   **Example** : Meeting is running with **User A** and **User B**. Now **User A** wants to Enable Mic of **User B**, so **User A** will use `enableMic()` function to request **User B**, after that **User B** will receive the `onMicRequested` event, from there user can either accept or reject the incoming request.

4. **Disable Mic of Participant** - By using `disableMic()` function, Mic of that participant will disable.

   **Example** : **User A** wants to Disable Mic of **User B**, so **User A** will use `disableMic()` function to Disable it without any request.

:::note

To achieve this feature, you need to pass `allow_join` persmission while genearting token for meeting initialization. After that you will be able to access participant media methods.

[How to apply permission while generating token?](/android/guide/video-and-audio-calling-api-sdk/server-setup)

:::

### Request Media Methods



**Kotlin:**

```js
val participant = meeting!!.participants.get("<participant-id>")

// This will emit an event called "onWebcamRequested" to that particular participant
participant.enableWebcam()

// This will directly disable webcam of particular participant
participant.disableWebcam()

// This will emit an event called "onMicRequested" to that particular participant
participant.enableMic()

// This will directly disable mic of particular participant
participant.disableMic()
```

---

**Java:**

```js
Participant participant = meeting.getParticipants().get("<participant-id>");

// This will emit an event called "onWebcamRequested" to that particular participant
participant.enableWebcam();

// This will directly disable webcam of particular participant
participant.disableWebcam();

// This will emit an event called "onMicRequested" to that particular participant
participant.enableMic();

// This will directly disable mic of particular participant
participant.disableMic();
```

### Manage Requested Media Events

1. **onWebcamRequested** - This event will be emitted to the participant `B` when any other participant `A` requests to enable webcam of that participant `B`. This event handler will receieve following three arguments:

   - `accept()` - Callback function to accept the request.
   - `reject()` - Callback function to reject the request.

<div style={{height: "10px"}}></div>

2. **onMicRequested** - This event will be emitted to the participant `B` when any other participant `A` requests to enable mic of that participant `B`. This event handler will receieve following three arguments:

   - `accept()` - Callback function to accept the request.
   - `reject()` - Callback function to reject the request.

**Kotlin:**

```js
object : MeetingEventListener() {
  override fun onMicRequested(participantId: String, listener: MicRequestListener) {
  // TODO: show dialog before accepting request
  listener.accept()
  }

  override fun onWebcamRequested(participantId: String, listener: WebcamRequestListener) {
  // TODO: show dialog before accepting request
  listener.accept()
  }
}
```

---

**Java:**

```js
new MeetingEventListener() {
  @Override
  public void onMicRequested(String participantId, MicRequestListener listener) {
  // TODO: show dialog before accepting request
  listener.accept();
  }

  @Override
  public void onWebcamRequested(String participantId, WebcamRequestListener listener) {
  // TODO: show dialog before accepting request
  listener.accept();
  }
}
```


---

# Cloud Proxy - Android


Our SDK features a Cloud Proxy that allows you to manage how your streaming content is routed through different network paths. This feature ensures compliance with various regional internet regulations by restricting traffic to specified proxy servers, based on your needs and the geographical location of users.

This capability is crucial for adhering to local data protection laws and optimizes the streaming experience by overcoming geographical network constraints. By directing user connections to appropriate regional servers, Cloud Proxy enhances overall service performance and reliability.

Cloud Proxy offers three straightforward operating modes to fit different business and firewall requirements:

- **UDP_OVER_TCP (Default)**: In this mode, the connection starts by attempting to establish a UDP connection for media transmission. If that fails, it will automatically shifts to a secure TCP connection, which is compatible with most firewalls.

- **Force UDP**: This mode uses only UDP to send media, ensuring high-quality streams. It's ideal for environments where media quality is critical and the firewall can be configured accordingly.

- **Force TCP**: Only uses TCP for secure media transmission, suitable for strict firewall settings that only permit TCP traffic over centain ports. This might require additional firewall configuration and could affect media quality under poor network conditions.




### In this sequence diagram:
- Client to Proxy Server: The client sends a request to the proxy server, which processes and forwards it based on predefined rules.
- Proxy Server to Destination Server: The proxy server sends the request to the destination server, receives the response, and relays it back to the client.

:::info

Cloud Proxy is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Implementation



**Kotlin:**

```js
val meeting: Meeting = VideoSDK.initMeeting(
  this@MainActivity, "meetingId", "John Due", true,
  true, null, null, false, null, null,"proxy.yourwebsite.com", VideoSDK.PreferredProtocol.UDP_ONLY
);
```

---

**Java:**

```java
Meeting meeting = VideoSDK.initMeeting(
  MainActivity.this, "meetingId", "John Due",true,
  true, null, null, false, null,null,"proxy.yourwebsite.com", VideoSDK.PreferredProtocol.UDP_ONLY
);
```
### Parameters
- preferredProtocol:
    - UDP_OVER_TCP (default): Initially the server attempts to establish a connection using UDP, if that fails it automatically switches to TCP protocol.
    - UDP_ONLY: Force UDP protocol
    - TCP_ONLY: Force TCP protocol
- signalingBaseUrl: Proxy URL to origin signaling and media.

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [initMeeting()](/android/api/sdk-reference/initMeeting)


---

# Geo Fencing - Android


Our SDK includes a region geofencing feature to comply with local laws and regulations worldwide. It restricts connections to servers within specified regions, ensuring users connect only to designated areas, regardless of their location. 

This helps meet regional data protection requirements and enhances user experience by addressing geographical network limitations.




### In this sequence diagram:
- User 1 (India) tries to connect to a meeting. In a regular scenario, the meeting would connect to the India region, but due to the geofence configuration, the meeting will connect to North America.

## Considerations
- If the user’s location differs from the chosen region, the network quality between these locations may be poor, affecting audio and video quality.
- Avoid using geofencing unless your scenario requires regional compliance.

:::info

Geo Fencing is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Available Regions
- INDIA
- USA
- UAE
- EUROPE
- SINGAPORE
- AUSTRALIA



---

# Geo IP Restrictions  - Android


Our SDK features Geo IP Restriction to ensure adherence to location-based access controls. It determines the user's location using their IP address and allows or restricts content based on geographic rules. This is essential for businesses needing to comply with international content distribution laws or provide localized services.

By implementing Geo IP Restriction, you can control who accesses your services based on where they are, ensuring compliance with legal regulations and enhancing security. This feature also improves the user experience by ensuring content relevance and availability is tailored to the user's location.




### In this sequence diagram:
- User 1 (India) attempts to connect to a meeting that is geo-restricted to only allow connections from North America. The server denies the connection due to the geographic restrictions.
- User 2 (North America) successfully connects because their location complies with the geo-restricted rules set on the meeting.


## Considerations
- Avoid using geo ip restriction unless your scenario requires regional or VPN/Proxy restrictions.

:::info

Geo IP Restriction is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Available Regions
- INDIA
- USA
- UAE
- EUROPE
- SINGAPORE
- AUSTRALIA



---

# Error Events - Android

VideoSDK provides `onError` event which will notify you of any error happening during the meeting.

### onError

- This event will be triggered whenever any invalid configuration provided or server/network errors arise, this event will trigger with a specific error code and message.
- This event is helpful for development level troubleshooting while integrating SDK.
- You can implement this method of the abstract Class `MeetingEventListener` and add the listener to `Meeting` class using the `addEventListener()` method of `Meeting` Class.

### Example

Here is the usage of the event mentioned in this page.



**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  //..
  override fun onError(error: JSONObject) {
  try {
  val errorCodes: JSONObject = VideoSDK.getErrorCodes()
  val code = error.getInt("code")
  Log.d("#error", "Error is: " + error["message"])
  } catch (e: Exception) {
      e.printStackTrace()
  }
  }
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  //..
  @Override
  public void onError(JSONObject error) {
  try {
      JSONObject errorCodes = VideoSDK.getErrorCodes();
      int code = error.getInt("code");
      Log.d("#error", "Error is: " + error.get("message"));
  } catch (Exception e) {
      e.printStackTrace();
  }
  }
};
```

### Error Codes

We have depicted a specific constant with code and message in the below table.



### 1. Errors associated with Organization 

This table lists errors that occur due to the configuration and limitations within your organization’s account. These include account status, participant limits, and add-on service availability.

| Type                                   | Code  | Message                                             |
|----------------------------------------|-------|-----------------------------------------------------|
| ACCOUNT_DEACTIVATED                   | 4006  | Your account has been deactivated. Please contact VideoSDK support. |
| ACCOUNT_DISCONTINUED                  | 4007  | Your account has been discontinued. Please reach out to support for more details. |
| MAX_PARTICIPANT_REACHED               | 4009  | You have reached the maximum participant limit for this meeting. |
| MAX_SPEAKER_REACHED                   | 4010  | The maximum number of speakers for this meeting has been reached. |
| MAX_SPEAKER_LIMIT_REACHED_ON_ORGANIZATION | 4026  | Your organization has reached the maximum number of speakers allowed. |
| MAX_VIEWER_LIMIT_REACHED_ON_ORGANIZATION | 4027  | Your organization has reached the maximum number of viewers allowed. |
| ADD_ON_SERVICES_DISABLED              | 4021  | Add-On services have been disabled. Please contact support to enable them. |
| MAX_RECORDING_LIMIT_REACHED_ON_ORGANIZATION              | 4028  | You have reached max limit of recording on organization. To increase contact at support@videosdk.live |
| MAX_HLS_LIMIT_REACHED_ON_ORGANIZATION  | 4029  | You have reached max limit of hls on organization. To increase contact at support@videosdk.live |
| MAX_LIVESTREAM_LIMIT_REACHED_ON_ORGANIZATION  | 4030  | You have reached max limit of livestream on organization. To increase contact at support@videosdk.live |

### 2. Errors associated with Token

Errors listed here are related to issues with the API key, authentication tokens, or permissions assigned to users. These errors can occur when tokens are missing, expired, or improperly configured.

| Type                                    | Code  | Message                                                |
|-----------------------------------------|-------|--------------------------------------------------------|
| INVALID_API_KEY                        | 4001  | The provided API key is either missing or invalid. |
| INVALID_TOKEN                          | 4002  | The provided token is empty, invalid, or has expired. |
| INVALID_PERMISSIONS                    | 4008  | The permissions in the token are incorrect. Please verify them. |
| UNAUTHORIZED_MEETING_ID                | 4022  | The provided token is not authorized for this meeting ID. |
| UNAUTHORIZED_PARTICIPANT_ID            | 4023  | The provided token is not authorized for this participant ID. |
| UNAUTHORIZED_ROLE                      | 4024  | The role specified in the token is not valid for joining this meeting. |
| UNAUTHORIZED_REQUEST                      | 4025 | Your request does not match the security configuration. |

### 3. Errors associated with Meeting and Participant

This table lists errors resulting from invalid or missing meeting or participant details, including cases where a participant attempts to join with a duplicate ID.

| Type                    | Code  | Message                                         |
|-------------------------|-------|-------------------------------------------------|
| INVALID_MEETING_ID      | 4003  | The meeting ID provided is either invalid or missing. |
| INVALID_PARTICIPANT_ID  | 4004  | The participant ID is either invalid or missing. |
| DUPLICATE_PARTICIPANT   | 4005  | This participant has joined from another device. |

### 4. Errors associated with Add-on Service

This section addresses errors that occur while using VideoSDK's add-on services such as recording, livestreaming, HLS streaming, and transcription.

### Recording-related errors

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_RECORDING_FAILED      | 4011  | Failed to start recording. Please try again.   |
| STOP_RECORDING_FAILED       | 4012  | Failed to stop recording. Please try again.    |
| RECORDING_FAILED            | 5001  | Recording was stopped due to an error.         |
| START_PARTICIPANT_RECORDING_FAILED | 4035 | Failed to start participant recording. Please check the request. |
| STOP_PARTICIPANT_RECORDING_FAILED  | 4036 | Failed to stop participant recording. |
| PARTICIPANT_RECORDING_FAILED       | 5012 | Participant recording has stopped due to an error. |
| START_TRACK_RECORDING_FAILED | 4037 | Failed to start track recording.                |
| STOP_TRACK_RECORDING_FAILED  | 4038 | Failed to stop track recording.                 |
| TRACK_RECORDING_FAILED  | 5013 | Track recording stopped due to an unknown error.                 |
| PREV_RECORDING_PROCESSING  | 4018 | Previous recording session is being processed, please try again after few seconds.                 |
| RECORDING_DURATION_LIMIT_REACHED | 5004 | Recording stopped due to maximum duration being reached. |

### Livestream-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| INVALID_LIVESTREAM_CONFIG           | 4015  | Livestream 'outputs' configuration provided was invalid            |
| START_LIVESTREAM_FAILED     | 4013  | Failed to start livestream. Please try again.  |
| STOP_LIVESTREAM_FAILED      | 4014  | Failed to stop livestream. Please try again.   |
| LIVESTREAM_FAILED           | 5002  | Livestream stopped due to an error.            |
| PREV_RTMP_RECORDING_PROCESSING | 4019 | Previous RTMP recording session is being processed, please try again after few seconds! |
| LIVESTREAM_DURATION_LIMIT_REACHED | 5005 | Livestream stopped due to maximum duration being reached. |

### HLS-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_HLS_FAILED            | 4016  | Failed to start HLS stream.                    |
| STOP_HLS_FAILED             | 4017  | Failed to stop HLS stream.                     |
| HLS_FAILED                  | 5003  | HLS streaming stopped due to an error.         |
| PREV_HLS_STREAMING_PROCESSING | 4020 | Previous HLS streaming session is still being processed. |
| HLS_DURATION_LIMIT_REACHED  | 5006  | HLS stream stopped due to maximum duration being reached. |

### Transcription-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_TRANSCRIPTION_FAILED  | 4031  | Failed to start transcription. Please try again. |
| STOP_TRANSCRIPTION_FAILED   | 4032  | Failed to stop transcription.                  |
| TRANSCRIPTION_FAILED        | 5007  | Transcription stopped due to an error.         |

### 5.Errors associated with Media

These errors involve media access, device availability, or permission-related issues affecting camera, microphone, and screen sharing.

### Device access-related errors

| Type                                      | Code  | Message                                          |
|-------------------------------------------|-------|--------------------------------------------------|
| ERROR_CAMERA_ACCESS  | 3002  | Something went wrong. Unable to access camera. |
| ERROR_MIC_ACCESS_DENIED  | 3003  | It seems like microphone access was denied or dismissed. To proceed, kindly grant access through your device's settings. |
| ERROR_CAMERA_ACCESS_DENIED | 3004 | It seems like camera access was denied or dismissed. To proceed, kindly grant access through your device's settings. |

### 6.Errors associated with Track

These errors occur when there are issues with video or audio tracks, such as disconnections or invalid custom tracks.

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| ERROR_CUSTOM_SCREEN_SHARE_TRACK_ENDED      | 3005  | The provided custom track is in an ended state. Please try again with new custom track. |
| ERROR_CUSTOM_SCREEN_SHARE_TRACK_DISPOSED      | 3006  | The provided custom track was disposed. Please try again with new custom track. |
| ERROR_CHANGE_WEBCAM      | 3007  | Something went wrong, and the camera could not be changed. Please try again. |

### 7.Errors associated with Actions

Below error is triggered when an action is attempted before joining a meeting.

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| ERROR_ACTION_PERFORMED_BEFORE_MEETING_JOINED     | 3001  | Oops! Something went wrong. The room was in a connecting state, and during that time, an action encountered an issue. Please try again after joining a meeting. |

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onError()](/android/api/sdk-reference/error-codes)


---

# External Call Detection Event - Android

External call detection event in VideoSDK let you know, participant is on the call during meeting.

Whenever local participant accept the incoming call or place outgoing call, `externalcall-started` event will trigger.`externalcall-started` event only received by localParticipant.

For example, the meeting is running with **Alice** and **Bob**. Whenever **Alice** receives the call or she call someone, **Alice** will receive `externalcall-started` event.

We can access `externalcall-started` event through `Meeting` class.

### externalcall-started Event



**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
 // ...
override fun onExternalCallStarted() {
  Log.d("#VideoSDK", "onExternalCallAnswered")
}
};

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
 // ...
@Override
public void onExternalCallStarted() {
    Log.d("#VideoSDK", "onExternalCallStarted");
}
};

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting.addEventListener(meetingEventListener);
}
```


---

# HLS Events - Android

VideoSDK provides `onHlsStateChanged` event which will notify you of the current state of HLS for the meeting.

### onHlsStateChanged

- This event will be triggered when the meeting's HLS status changed.
- You can implement this method of the abstract Class `MeetingEventListener` and add the listener to `Meeting` class using the `addEventListener()` method of `Meeting` Class.
- when you receive `HLS_PLAYABLE` status you will receive 2 urls in response
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

### Example

Here is the usage of the event mentioned in this page.



**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onHlsStateChanged(HlsState: JSONObject) {
when (HlsState.getString("status")) {
    "HLS_STARTING" -> Log.d("onHlsStateChanged", "Meeting hls is starting")
    "HLS_STARTED" -> Log.d("onHlsStateChanged", "Meeting hls is started")
    "HLS_PLAYABLE" -> {
        Log.d("onHlsStateChanged", "Meeting hls is playable now")
        // on hls playable you will receive playbackHlsUrl and livestreamUrl
        val playbackHlsUrl = HlsState.getString("playbackHlsUrl")
        val livestreamUrl = HlsState.getString("livestreamUrl")
    }
    "HLS_STOPPING" -> Log.d("onHlsStateChanged", "Meeting hls is stopping")
    "HLS_STOPPED" -> Log.d("onHlsStateChanged", "Meeting hls is stopped")
}
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onHlsStateChanged(JSONObject HlsState) {
  switch (HlsState.getString("status")) {
      case "HLS_STARTING":
          Log.d("onHlsStateChanged", "Meeting hls is starting");
          break;
      case "HLS_STARTED":
          Log.d("onHlsStateChanged", "Meeting hls is started");
          break;
      case "HLS_PLAYABLE":
          Log.d("onHlsStateChanged", "Meeting hls is playable now");
          // on hls started you will receive playbackHlsUrl and livestreamUrl
          String playbackHlsUrl = HlsState.getString("playbackHlsUrl");
          String livestreamUrl = HlsState.getString("livestreamUrl");
          break;
      case "HLS_STOPPING":
          Log.d("onHlsStateChanged", "Meeting hls is stopping");
          break;
      case "HLS_STOPPED":
          Log.d("onHlsStateChanged", "Meeting hls is stopped");
          break;
  }
  }
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting.addEventListener(meetingEventListener);
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onHlsStateChanged()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onhlsstatechanged)


---

# Media Events - Android

VideoSDK provides multiple types of events which can be listened to know the about the participant's media status in the meeting.

You can implement all the methods of `ParticipantEventListener` abstract Class and add the listener to `Participant` class using the `addEventListener()` method of `Participant` Class.

Here are the events which specifically relate to the stream.

### onStreamEnabled

- This event is triggered whenever a participant's video, audio or screen share stream is enabled.

### onStreamDisabled

- This event is triggered whenever a participant's video, audio or screen share stream is disabled.

### Example

Here is the usage of all the events mentioned in this page.



**Kotlin:**

```js
participant.addEventListener(object : ParticipantEventListener() {
  override fun onStreamEnabled(stream: Stream) {
Log.d("VideoSDK","onStreamEnabled $stream");
  }

  override fun onStreamDisabled(stream: Stream) {
Log.d("VideoSDK","onStreamDisabled $stream");
  }
});
```

---

**Java:**

```js
participant.addEventListener(new ParticipantEventListener() {
  @Override
  public void onStreamEnabled(Stream stream) {
Log.d("VideoSDK","onStreamEnabled" + stream);
  }

  @Override
  public void onStreamDisabled(Stream stream) {
Log.d("VideoSDK","onStreamDisabled" + stream);
  }
});
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onStreamEnabled()](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamenabled)
- [onStreamDisabled()](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamdisabled)


---

# Meeting Connection Events - Android

VideoSDK provides `onMeetingStateChanged` event which will notify you of the current connection state of the meeting.

### onMeetingStateChanged

- This event will be triggered when state of meeting changes.
- It will pass **`state`** as an event callback parameter which will indicate current state of the meeting.
- All available states are :
  - **CONNECTING**: The meeting is in the process of establishing a connection.
  - **CONNECTED**: The meeting has successfully connected.
  - **RECONNECTING**: The meeting is trying to reconnect after the connection was lost.
  - **DISCONNECTED**: The meeting has been disconnected.

- You can implement this method of the abstract Class `MeetingEventListener` and add the listener to `Meeting` class using the `addEventListener()` method of `Meeting` Class.

### Example

Here is the usage of the event mentioned in this page.



**Kotlin:**

```javascript
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onMeetingStateChanged(state: MeetingState) {
when (state) {
    MeetingState.CONNECTING -> {
        Log.d("onMeetingStateChanged", "Meeting is Connecting")
    }
    MeetingState.CONNECTED -> {
        Log.d("onMeetingStateChanged", "Meeting is Connected")
    }
    MeetingState.RECONNECTING -> {
        Log.d("onMeetingStateChanged", "Meeting is RECONNECTING")
    }
    MeetingState.DISCONNECTED -> {
        Log.d("onMeetingStateChanged", "Meeting is Disconnected")
    }
}
  }

}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```javascript
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onMeetingStateChanged(MeetingState state) {
  switch (state) {
  case CONNECTING:
      Log.d("onMeetingStateChanged: ", "Meeting is Connecting");
      break;
  case CONNECTED:
      Log.d("onMeetingStateChanged: ", "Meeting is Connected");
      break;
  case RECONNECTING:
      Log.d("onMeetingStateChanged: ", "Meeting is RECONNECTING");
      break;
  case DISCONNECTED:
      Log.d("onMeetingStateChanged: ", "Meeting is disconnected");
      break;
  }
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting.addEventListener(meetingEventListener);
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onMeetingStateChanged()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmeetingstatechanged)


---

# Meeting Events - Android

VideoSDK provides multiple types of events which can be listened to know the current state of the meeting.

You can implement all the methods of `MeetingEventListener` abstract Class and add the listener to `Meeting` class using the `addEventListener()` method of `Meeting` Class.

Here are the events which specifically relate to the meeting.

### onMeetingJoined

- This event is triggered when the meeting is successfully joined.

### onMeetingLeft

- This event is triggered when the meeting is left.

### onSpeakerChanged

- This event is triggered when the active speaker in the meeting gets changed.

### onPresenterChanged

- This event is triggered when the presenter in the meeting gets changed.

### Example

Here is the usage of all the events mentioned in this page.



**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onMeetingJoined() {
  Log.d("VideoSDK", "onMeetingJoined: ")
  }

  override fun onMeetingLeft() {
  Log.d("VideoSDK", "onMeetingLeft: ")
  }

  override fun onSpeakerChanged(participantId: String) {
  Log.d("VideoSDK", "onSpeakerChanged: $participantId")
  }

  override fun onPresenterChanged(participantId: String) {
  Log.d("VideoSDK", "onPresenterChanged: $participantId")
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onMeetingJoined() {
Log.d("VideoSDK", "onMeetingJoined: ");
  }

  @Override
  public void onMeetingLeft() {
Log.d("VideoSDK", "onMeetingLeft: ");
  }

  @Override
  public void onSpeakerChanged(String participantId) {
Log.d("VideoSDK", "onSpeakerChanged: " + participantId);
  }

  @Override
  public void onPresenterChanged(String participantId) {
Log.d("VideoSDK", "onPresenterChanged: " + participantId);
  }
};

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting.addEventListener(meetingEventListener);
}
```

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onMeetingJoined()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmeetingjoined)
- [onMeetingLeft()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmeetingleft)
- [onSpeakerChanged()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onspeakerchanged)
- [onPresenterChanged()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onpresenterchanged)


---

# Participant Events - Android

VideoSDK provides multiple types of events which can be listened to know the about the participants in the meeting.

You can implement all the methods of `MeetingEventListener` abstract Class and add the listener to `Meeting` class using the `addEventListener()` method of `Meeting` Class.

Here are the events which specifically relate to the participants.

### onParticipantJoined

- This event is triggered when someone joins the meeting and return the `Participant` object as parameter.

### onParticipantLeft

- This event is triggered when the someone leaves the meeting.

### onWebcamRequested

- This event will be triggered to the participant `B` when any other participant `A` requests to enable webcam of participant `B`.
- On accepting the request, webcam of participant `B` will be enabled.

### onMicRequested

- This event will be triggered to the participant `B` when any other participant `A` requests to enable mic of participant `B`.
- On accepting the request, mic of participant `B` will be enabled.
- This event can be subscribed from the `useMeeting` hook.

### Example

Here is the usage of all the events mentioned in this page.



**Kotlin:**

```javascript
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onParticipantJoined(participant: Participant) {
Log.d("VideoSDK", participant.displayName + " joined");
  }

  override fun onParticipantLeft(participant: Participant) {
Log.d("VideoSDK", participant.displayName + " left");
  }

  override fun onWebcamRequested(participantId: String, listener: WebcamRequestListener) {

// participantId, will be the id of participant who requested to enable mic

// if accept request
listener.accept()

// if reject request
listener.reject()
  }

  override fun onMicRequested(participantId: String, listener: MicRequestListener) {

// participantId, will be the id of participant who requested to enable mic

// if accept request
listener.accept()

// if reject request
listener.reject()
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```javascript
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onParticipantJoined(Participant participant) {
  Log.d("VideoSDK", participant.getDisplayName() + " joined");
  }

  @Override
  public void onParticipantLeft(Participant participant) {
  Log.d("VideoSDK", participant.getDisplayName() + " left");
  }

  @Override
  public void onWebcamRequested(String participantId, WebcamRequestListener listener) {

// participantId, will be the id of participant who requested to enable webcam

// if accept request
listener.accept();

// if reject request
listener.reject();
  }

  @Override
  public void onMicRequested(String participantId, MicRequestListener listener) {

// participantId, will be the id of participant who requested to enable mic

// if accept request
listener.accept();

// if reject request
listener.reject();
 }
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting.addEventListener(meetingEventListener);
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onParticipantJoined()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onparticipantjoined)
- [onParticipantLeft()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onparticipantleft)
- [onWebcamRequested()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onwebcamrequested)
- [onMicRequested()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmicrequested)


---

# Recording Events - Android

VideoSDK provides `onRecordingStateChanged` event which will notify you of the current state of recording for the meeting.

### onRecordingStateChanged

- This event will be triggered when the meeting's recording status changed.
- You can implement this method of the abstract Class `MeetingEventListener` and add the listener to `Meeting` class using the `addEventListener()` method of `Meeting` Class.

### Example

Here is the usage of the event mentioned in this page.



**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onRecordingStateChanged(recordingState: String) {
when (recordingState) {
    "RECORDING_STARTING" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is starting")
    }
    "RECORDING_STARTED" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is started")
    }
    "RECORDING_STOPPING" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is stopping")
    }
    "RECORDING_STOPPED" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is stopped")
    }
}
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onRecordingStateChanged(String recordingState) {
  switch (recordingState) {
      case "RECORDING_STARTING":
          Log.d("onRecordingStateChanged", "Meeting recording is starting");
          break;
      case "RECORDING_STARTED":
          Log.d("onRecordingStateChanged", "Meeting recording is started");
          break;
      case "RECORDING_STOPPING":
          Log.d("onRecordingStateChanged", "Meeting recording is stopping");
          break;
      case "RECORDING_STOPPED":
          Log.d("onRecordingStateChanged", "Meeting recording is stopped");
          break;
  }
  }
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting.addEventListener(meetingEventListener);
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onRecordingStateChanged()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onrecordingstatechanged)


---

# RTMP Events - Android

VideoSDK provides `onLivestreamStateChanged` event which will notify you of the current state of livestream for the meeting.

### onLivestreamStateChanged

- This event will be triggered when the meeting's livestream status changed.
- You can implement this method of the abstract Class `MeetingEventListener` and add the listener to `Meeting` class using the `addEventListener()` method of `Meeting` Class.

### Example

Here is the usage of the event mentioned in this page.



**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onLivestreamStateChanged(livestreamState: String?) {
when (livestreamState) {
  "LIVESTREAM_STARTING" -> Log.d( "LivestreamStateChanged",
      "Meeting livestream is starting"
  )
  "LIVESTREAM_STARTED" -> Log.d( "LivestreamStateChanged",
      "Meeting livestream is started"
  )
  "LIVESTREAM_STOPPING" -> Log.d("LivestreamStateChanged",
      "Meeting livestream is stopping"
  )
  "LIVESTREAM_STOPPED" -> Log.d("LivestreamStateChanged",
      "Meeting livestream is stopped"
  )
}
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onLivestreamStateChanged(String livestreamState) {
switch (livestreamState) {
  case "LIVESTREAM_STARTING":
      Log.d("LivestreamStateChanged", "Meeting livestream is starting");
      break;
  case "LIVESTREAM_STARTED":
      Log.d("LivestreamStateChanged", "Meeting livestream is started");
      break;
  case "LIVESTREAM_STOPPING":
      Log.d("LivestreamStateChanged", "Meeting livestream is stopping");
      break;
  case "LIVESTREAM_STOPPED":
      Log.d("LivestreamStateChanged", "Meeting livestream is stopped");
      break;
}
  }
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting.addEventListener(meetingEventListener);
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onLivestreamStateChanged()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onlivestreamstatechanged)


---

## Steps


<div class="container guide-steps-block">
  <div class="row ">
    <div class="col col--6">
      
    </div>
     <div class="col col--6">
      
    </div>
  </div>
  <div class="row ">
   <div class="col col--6" >
      
    </div>
    <div class="col col--6">
      
    </div>
  </div>
  <div class="row ">
   <div class="col col--6" >
      
    </div>
    <div class="col col--6">
      
    </div>
  </div>
</div>

## Architecture

This diagram demonstrates end-to-end flow to implement video & audio calling, record calls and go-live on social media.

![Video-sdk-architecture!](/img/video-sdk-archietecture.svg)


---

# Active Speaker Indication - Android

Active Speaker indication feature in VideoSDK let you know, which participant in a meeting is active speaker. This feature can be particularly useful in larger meetings or webinars, where there may be many participants and it can be difficult to tell who is speaking.

Whenever any participant speaks in meeting, `onSpeakerChanged` event will trigger with the participant id of the active speaker.

For example, the meeting is running with **Alice** and **Bob**. Whenever any of them speaks, `onSpeakerChanged` event will trigger and return the speaker `participantId`.

### Event



**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
override fun onSpeakerChanged(participantId: String?) {
    Toast.makeText(this@MainActivity, "Active Speaker participantId" + participantId, Toast.LENGTH_SHORT).show();
    super.onSpeakerChanged(participantId)
}
};
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
@Override
public void onSpeakerChanged(String participantId) {
    Toast.makeText(MainActivity.this, "Active Speaker participantId" + participantId, Toast.LENGTH_SHORT).show();
    super.onSpeakerChanged(participantId);
}
};
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onSpeakerChanged()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onspeakerchanged)


---

# Background Handling - Android

On **Android**, when your app moves to the **background**, the platform imposes restrictions—especially on accessing the **microphone** and **camera**.

Starting with **Android 14 and above**, these restrictions have become even stricter:

- Background microphone and camera usage is restricted.
- Battery optimization policies are more aggressive, often terminating background processes.

For seamless media transmission in **VideoSDK**, you must handle these restrictions carefully by configuring the right permissions and using a **foreground service**.

Alternatively, if you prefer not to implement a foreground service, you can use [Picture-in-Picture (PiP)](../render-media/picture-in-picture) mode. PiP enables the app to remain visible in a small floating window, helping bypass some background restrictions while keeping media active.

If these steps aren’t correctly implemented, the app will lose the ability to send or receive media when backgrounded, disrupting core communication features.

## Background Handling

Running video and audio capture in the background on Android presents multiple challenges:

- Limited access to the microphone and camera when the app is backgrounded (usually capped at ~60 seconds). 
- **Device/OEM-specific optimizations** that aggressively kill background processes.

To address these challenges, your app should run a **foreground service** so Android recognizes it as actively running. This ensures consistent microphone and camera access even while the app is minimized.  



Update your `AndroidManifest.xml` to declare permissions and the foreground service:  

```xml title="AndroidManifest.xml"
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA"/>
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>


  <application>
    <service android:name=".ForegroundService"
    android:foregroundServiceType="camera|microphone"
    android:stopWithTask="true" />
  </application>
</manifest>
```




Implement a foreground service that shows a persistent notification and keeps audio/video capture running:



**Kotlin:**

```js title="ForegroundService.kt"
package com.example.example

import android.app.*
import android.content.Intent
import android.os.Build
import android.os.IBinder
import android.util.Log
import androidx.core.app.NotificationCompat
import com.example.example.MainApplication
import com.example.example.R

class ForegroundService : Service() {

  companion object {
const val NOTIFICATION_ID = 1001
const val CHANNEL_ID = "AppChannelID"
private const val TAG = "ForegroundService"

// Actions
const val ACTION_START = "com.example.example.START_FOREGROUND_SERVICE"
const val ACTION_STOP = "com.example.example.STOP_FOREGROUND_SERVICE"
  }

  override fun onCreate() {
super.onCreate()
Log.d(TAG, "Service onCreate")
createNotificationChannel()
  }

  override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
Log.d(TAG, "Service onStartCommand")

when (intent?.action) {
  ACTION_START -> {
    startForegroundService()
  }
  ACTION_STOP -> {
    stopForegroundService()
  }
  else -> {
    // Default action - start the service
    startForegroundService()
  }
}

return START_STICKY
  }

  override fun onBind(intent: Intent?): IBinder? {
return null
  }

  override fun onDestroy() {
super.onDestroy()
Log.d(TAG, "Service onDestroy")
  }

  private fun startForegroundService() {
Log.d(TAG, "Starting foreground service")

try {
  val notification = createNotification()
  startForeground(NOTIFICATION_ID, notification)
  Log.d(TAG, "Foreground service started successfully")
} catch (e: SecurityException) {
  Log.e(TAG, "Security exception while starting foreground service", e)
  // This usually means missing permissions
  throw e
} catch (e: Exception) {
  Log.e(TAG, "Error starting foreground service", e)
  throw e
}
  }

  fun stopForegroundService() {
Log.d(TAG, "Stopping foreground service")
stopForeground(true)
stopSelf()
  }

  private fun createNotification(): Notification {
val notificationIntent = Intent(this, MainApplication::class.java)
val pendingIntent = PendingIntent.getActivity(
  this,
  0,
  notificationIntent,
  PendingIntent.FLAG_IMMUTABLE
)

return NotificationCompat.Builder(this, CHANNEL_ID)
  .setContentTitle("Foreground Service")
  .setContentText("Camera and microphone are active")
  .setSmallIcon(R.mipmap.ic_launcher)
  .setContentIntent(pendingIntent)
  .setPriority(NotificationCompat.PRIORITY_LOW)
  .setOngoing(true)
  .build()
  }

  private fun createNotificationChannel() {
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
  val channel = NotificationChannel(
    CHANNEL_ID,
    "Foreground Service",
    NotificationManager.IMPORTANCE_LOW
  ).apply {
    description = "Channel for foreground service notifications"
    setShowBadge(false)
    enableLights(false)
    enableVibration(false)
  }

  val notificationManager = getSystemService(NotificationManager::class.java)
  notificationManager?.createNotificationChannel(channel)
  Log.d(TAG, "Notification channel created")
}
  }
}
```

---

**Java:**

```js title="ForegroundService.java"
package com.example.example;

import android.app.Notification;
import android.app.NotificationChannel;
import android.app.NotificationManager;
import android.app.PendingIntent;
import android.app.Service;
import android.content.Intent;
import android.os.Build;
import android.os.IBinder;
import android.util.Log;

import androidx.core.app.NotificationCompat;

import com.example.example.MainApplication;
import com.example.example.R;

public class ForegroundService extends Service {

  private static final String TAG = "ForegroundService";
  public static final int NOTIFICATION_ID = 1001;
  public static final String CHANNEL_ID = "AppChannelID";

  // Actions
  public static final String ACTION_START = "com.example.example.START_FOREGROUND_SERVICE";
  public static final String ACTION_STOP = "com.example.example.STOP_FOREGROUND_SERVICE";

  @Override
  public void onCreate() {
super.onCreate();
Log.d(TAG, "Service onCreate");
createNotificationChannel();
  }

  @Override
  public int onStartCommand(Intent intent, int flags, int startId) {
Log.d(TAG, "Service onStartCommand");

if (intent != null) {
  switch (intent.getAction()) {
    case ACTION_START:
      startForegroundService();
      break;
    case ACTION_STOP:
      stopForegroundService();
      break;
    default:
      // Default action - start the service
      startForegroundService();
      break;
  }
} else {
  // Default action - start the service
  startForegroundService();
}

return START_STICKY;
  }

  @Override
  public IBinder onBind(Intent intent) {
return null;
  }

  @Override
  public void onDestroy() {
super.onDestroy();
Log.d(TAG, "Service onDestroy");
  }

  private void startForegroundService() {
Log.d(TAG, "Starting foreground service");

try {
  Notification notification = createNotification();
  startForeground(NOTIFICATION_ID, notification);
  Log.d(TAG, "Foreground service started successfully");
} catch (SecurityException e) {
  Log.e(TAG, "Security exception while starting foreground service", e);
  // This usually means missing permissions
  throw e;
} catch (Exception e) {
  Log.e(TAG, "Error starting foreground service", e);
  throw e;
}
  }

  public void stopForegroundService() {
Log.d(TAG, "Stopping foreground service");
stopForeground(true);
stopSelf();
  }

  private Notification createNotification() {
Intent notificationIntent = new Intent(this, MainApplication.class);
PendingIntent pendingIntent = PendingIntent.getActivity(
  this,
  0,
  notificationIntent,
  PendingIntent.FLAG_IMMUTABLE
);

return new NotificationCompat.Builder(this, CHANNEL_ID)
  .setContentTitle("Foreground Service")
  .setContentText("Camera and microphone are active")
  .setSmallIcon(R.mipmap.ic_launcher)
  .setContentIntent(pendingIntent)
  .setPriority(NotificationCompat.PRIORITY_LOW)
  .setOngoing(true)
  .build();
  }

  private void createNotificationChannel() {
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
  NotificationChannel channel = new NotificationChannel(
    CHANNEL_ID,
    "Foreground Service",
    NotificationManager.IMPORTANCE_LOW
  );
  channel.setDescription("Channel for foreground service notifications");
  channel.setShowBadge(false);
  channel.enableLights(false);
  channel.enableVibration(false);

  NotificationManager notificationManager = (NotificationManager) getSystemService(NotificationManager.class);
  if (notificationManager != null) {
    notificationManager.createNotificationChannel(channel);
    Log.d(TAG, "Notification channel created");
  }
}
  }
}
```





By default, **VideoSDK automatically stops the camera** when the app goes into the background.
To prevent this, you need to **disable automatic activity lifecycle handling** by calling `setEnableActivityLifecycle(false)` before initialize `videosdk`.

**Kotlin:**

```js title="MainApplication.kt"
package com.example.example

import android.app.Application
import live.videosdk.rtc.android.VideoSDK
import com.androidnetworking.AndroidNetworking

class MainApplication : Application() {
  override fun onCreate() {
super.onCreate()
//highlight-next-line
VideoSDK.setEnableActivityLifecycle(false)
VideoSDK.initialize(applicationContext)
AndroidNetworking.initialize(applicationContext)
  }
}
```

---

**Java:**

```js title="MainApplication.java"
package com.example.example;

import android.app.Application;
import com.androidnetworking.AndroidNetworking;
import live.videosdk.rtc.android.VideoSDK;

public class MainApplication extends Application {

  @Override
  public void onCreate() {
super.onCreate();
//highlight-next-line
VideoSDK.setEnableActivityLifecycle(false);
VideoSDK.initialize(getApplicationContext());
AndroidNetworking.initialize(getApplicationContext());
  }
}
```





Start the foreground service automatically when a meeting begins and stop it once the user leaves the meeting.

**Kotlin:**

```js title="MeetingActivity.kt"
class MeetingActivity : AppCompatActivity() {

  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_meeting)

val token = intent.getStringExtra("token")
val meetingId = intent.getStringExtra("meetingId")
val participantName = "John Doe"

VideoSDK.config(token)

meeting = VideoSDK.initMeeting(
  this@MeetingActivity, meetingId, participantName,
  true, true, null, null, false, null, null)

//highlight-next-line
// Add event listener for listening upcoming events
meeting!!.addEventListener(meetingEventListener)

meeting!!.join()
  }

  //highlight-next-line
  // creating the MeetingEventListener
  private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
override fun onMeetingJoined() {
  //highlight-next-line
  // start foreground service
  startService(Intent(applicationContext, ForegroundService::class.java).apply {
    action = ForegroundService.ACTION_START
  })
}

override fun onMeetingLeft() {
  //highlight-next-line
  // Stop foreground service
  startService(Intent(applicationContext, ForegroundService::class.java).apply {
    action = ForegroundService.ACTION_STOP
  })
}
  }
}
```

---

**Java:**

```js title="MeetingActivity.java"
public class MeetingActivity extends AppCompatActivity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_meeting);

final String token = getIntent().getStringExtra("token");
final String meetingId = getIntent().getStringExtra("meetingId");
final String participantName = "John Doe";

VideoSDK.config(token);

meeting = VideoSDK.initMeeting(
        MeetingActivity.this, meetingId, participantName,
        true, true, null, null, false, null, null);

//highlight-next-line
// Add event listener for listening upcoming events
meeting.addEventListener(meetingEventListener);

meeting.join();
  }

  //highlight-next-line
  // creating the MeetingEventListener
  private final MeetingEventListener meetingEventListener = new MeetingEventListener() {

@Override
public void onMeetingJoined() {
  //highlight-next-line
  // start foreground service
  Intent serviceIntent = new Intent(getApplicationContext(), ForegroundService.class);
  serviceIntent.setAction(ForegroundService.ACTION_START);
  startService(serviceIntent);
}

@Override
public void onMeetingLeft() {
  //highlight-next-line
  // stop foreground service
  Intent serviceIntent = new Intent(getApplicationContext(), ForegroundService.class);
  serviceIntent.setAction(ForegroundService.ACTION_STOP);
  startService(serviceIntent);
}
  };
}
```




:::note 
In above code `com.example.example` is our package name kindly replace with yours. 
:::

---

# Change Input/Output Device - Android

During the meeting at any point a participant wishes to switch his/her audio or video device, it can be done using the below mentioned methods.

## Changing Input/Output Audio Device

### `getMics()`

- The `getMics()` method will return a list of all available microphones that are connected to the mobile device.

- This method will return a Set of `AppRTCAudioManager.AudioDevice`.



**Kotlin:**

```js
  private fun getMics(): MutableSet
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
</manifest>
```

## Changing Camera Input Device

### `changeWebcam()`

- By using `changeWebcam()` function, a participant can stream from front / rear camera during the meeting.

#### Example

**Kotlin:**

```js
  btnWebcam!!.setOnClickListener {
// Change Webcam during Meeting
//highlight-next-line
meeting!!.changeWebcam()
  }
```

---

**Java:**

```js
  btnWebcam.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
    // Change Webcam during Meeting
    //highlight-next-line
    meeting.changeWebcam();
  }
  });
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [getMics()](/android/api/sdk-reference/meeting-class/methods#getmics)
- [changeMic()](/android/api/sdk-reference/meeting-class/methods#changemic)
- [changeWebcam()](/android/api/sdk-reference/meeting-class/methods#changewebcam)


---

# Image Capturer - Android

This guide provides instructions on capturing images of participants from a video stream.

This capability proves particularly valuable in Video KYC scenarios, enabling the capture of images where users can hold up their identity for verification.

### `captureImage()`

- By using the `captureImage()` method of the `Participant` class, you can capture image of a local participant from their video stream.
- You have the option to specify the desired height and width in the `captureImage()` method; however, these parameters are optional. If not provided, the VideoSDK will automatically use the dimensions of the local participant's webcamStream.
- You need to pass an implementation of `TaskCompletionListener` as a parameter in the `captureImage()` method. This listener will handle the result of the image capture task.
- When the image capture task is complete, the `onComplete()` method will provide the image in the form of a `base64` string. If an error occurs, the `onError()` method will provide the error details.



**Kotlin:**

```js
private fun imageCapture() {
  meeting!!.localParticipant.
.captureImage(400, 400, object : TaskCompletionListener<String?, String?> {
  override fun onComplete(data: String?) {
      Log.d("VideoSDK", "capturedImage in base64 format: $data")
  }

  override fun onError(error: String?) {
      Log.d("VideoSDK", "Error in imageCapture $error")
  }
  })
}
```

---

**Java:**

```js
private void imageCapture() {
  meeting.getLocalParticipant().captureImage(400, 400, new TaskCompletionListener<String,String>() {
@Override
public void onComplete(@Nullable String data) {
    Log.d("VideoSDK", "capturedImage in base64 format: " + data);
}

@Override
public void onError(@Nullable String error) {
    Log.d("VideoSDK", "Error in imageCapture " + error);
}
  });
}
```

:::note

You can only capture an image of the local participant. If you called `captureImage()` method on a remote participant, you will receive an error. To capture an image of a remote participant, refer to the documentation below.

:::

### How to capture image of a remote participant ?

- Before proceeding, it's crucial to understand [VideoSDK's temporary file storage system](/android/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/upload-fetch-temporary-file) and the underlying [pubsub mechanism](/android/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

- Here's a break down of the steps, using the names Participant A and Participant B for clarity:

#### Step 1 : Initiate Image Capture Request

- In this step, you have to first send a request to Participant B, whose image you want to capture, using pubsub.
- In order to do that, you have to publish a message. Here, `IMAGE_CAPTURE` pubsub topic is used.
- Also, you will be using the `sendOnly` property of the `PubSubPublishOptions` class. Therefore, the request will be sent to that participant only.

**Kotlin:**

```js
class MainActivity : AppCompatActivity() {

  //..

  private fun sendRequest(participantId: String) {
if (participantId != meeting.localParticipant.id) {
  val publishOptions = PubSubPublishOptions()
  publishOptions.isPersist = false
  //highlight-start
  // Pass the participantId of the participant whose image you want to capture
  // Here, it will be Participant B's id, as you want to capture the the image of Participant B
  val sendOnly = arrayOf(participantId)
  publishOptions.setSendOnly(sendOnly)
  //highlight-end

  // send request to participant using the publish method
  //highlight-next-line
  meeting.pubSub.publish("IMAGE_CAPTURE", "Sending request to capture image", publishOptions)
}
  }
}
```

---

**Java:**

```js
public class MainActivity extends AppCompatActivity {

  //...

  private void sendRequest(String participantId) {
if (!participantId.equals(meeting.getLocalParticipant().getId())) {
  PubSubPublishOptions publishOptions = new PubSubPublishOptions();
  publishOptions.setPersist(false);
  //highlight-start
  // Pass the participantId of the participant whose image you want to capture
  // Here, it will be Participant B's id, as you want to capture the the image of Participant B
  String[] sendOnly = {participantId};
  publishOptions.setSendOnly(sendOnly);
  //highlight-end

  // send request to participant using the publish method
  //highlight-next-line
  meeting.pubSub.publish("IMAGE_CAPTURE", "Sending request to capture image", publishOptions);
}
  }
}
```

#### Step 2 : Capture and Upload File

- To capture an image from a remote participant [Participant B], you will filter out the request from the `onMessageReceived` event of the `PubSubMessageListener`. For that, you need to subscribe to a topic called `IMAGE_CAPTURE`. When you receive an image capture request, you will capture the image using the `captureImage()` method of the `Participant` class.

**Kotlin:**

```js
class MainActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)

//...

// add listener to meeting
//highlight-next-line
meeting!!.addEventListener(meetingEventListener)
  }

  private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {

override fun onMeetingJoined() {
  Log.d("#meeting", "onMeetingJoined()")
  val pubSubMessageListener =
    PubSubMessageListener { message ->
      if (message.senderId != meeting!!.localParticipant.id) {
        //highlight-start
        // capture and store image when message received
        captureAndStoreImage(message.senderId)
        //highlight-end
      }
    }
  // subscribe for 'IMAGE_CAPTURE' topic to receive request
  //highlight-next-line
  meeting!!.pubSub.subscribe("IMAGE_CAPTURE", pubSubMessageListener)
}

//...
  }

  private fun captureAndStoreImage(senderId: String) {
//highlight-start
// capture image
meeting!!.localParticipant
  .captureImage(object : TaskCompletionListener<String?, String?> {
    override fun onComplete(@Nullable base64Data: String?) {
        Log.d("VideoSDK", "capturedImage in base64 format: $base64Data")
    }

    override fun onError(@Nullable error: String?) {
        Log.d("VideoSDK", "Error in image capture: $error")
    }
})
//highlight-end
  }
}
```

---

**Java:**

```js
public class MainActivity extends AppCompatActivity {
 @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

//...

// add listener to meeting
//highlight-next-line
meeting.addEventListener(meetingEventListener);
  }

   private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onMeetingJoined() {
    Log.d("#meeting", "onMeetingJoined()");

    PubSubMessageListener pubSubMessageListener = new PubSubMessageListener() {
      @Override
      public void onMessageReceived(PubSubMessage message) {
        if (!message.getSenderId().equals(meeting.getLocalParticipant().getId()))
        {
          //highlight-start
          // capture and store image when message received
          captureAndStoreImage(message.getSenderId());
          //highlight-end
        }
      }
    }
    // subscribe for 'IMAGE_CAPTURE' topic to receive request
    //highlight-next-line
    meeting.pubSub.subscribe("IMAGE_CAPTURE", pubSubMessageListener);
  }

  //...
};

  private void captureAndStoreImage(String senderId) {
//highlight-start
// capture image
meeting.getLocalParticipant().captureImage(new TaskCompletionListener<String, String>() {
  @Override
  public void onComplete(@Nullable String base64Data) {
    Log.d("VideoSDK", "capturedImage in base64 format: " + base64Data);
  }

  @Override
  public void onError(@Nullable String error) {
      Log.d("VideoSDK", "Error in image capture: " + error);
  }
});
//highlight-end
  }
}
```

- After capturing the image of the remote participant, you need to store this image in VideoSDK's temporary file storage system. This will allow you to send the image to the participant who initiated the request.
- Utilize the `uploadBase64File()` method of the `Meeting` class to store the captured image in VideoSDK's temporary file storage system.
- When the upload is complete, the `onComplete()` method of `TaskCompletionListener` will provide the corresponding `fileUrl`, which can be used to retrieve the uploaded file.
- If an error occurs during the upload process, the `onError()` method of `TaskCompletionListener` will provide the error details.

**Kotlin:**

```js
class MainActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
//...
  }

  private fun captureAndStoreImage(senderId: String) {
// listener for file-upload
val fileUploadListener: TaskCompletionListener<String, String> =
  object : TaskCompletionListener<String?, String?> {
    override fun onComplete(@Nullable fileUrl: String?) {
      //highlight-next-line
      Log.d("VideoSDK", "Uploaded file url: $fileUrl")
    }

    override fun onError(@Nullable error: String?) {
      Log.d("VideoSDK", "Error in upload file: $error")
    }
}

// capture image
meeting!!.localParticipant
  .captureImage(object : TaskCompletionListener<String?, String?> {
    override fun onComplete(@Nullable base64Data: String?) {
      Log.d("VideoSDK", "capturedImage in base64 format: $base64Data")
      val token = "<VIDEOSDK_TOKEN>"
      val fileName = "myCapture.jpeg" // specify a name for image file with extension
      //highlight-start
      // upload image to videosdk storage system
      meeting!!.uploadBase64File(base64Data, token, fileName, fileUploadListener)
      //highlight-end
    }

    override fun onError(@Nullable error: String?) {
        Log.d("VideoSDK", "Error in image capture: $error")
    }
  })
  }
}
```

---

**Java:**

```js
public class MainActivity extends AppCompatActivity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
//...
  }

  private void captureAndStoreImage(String senderId) {
// listener for file-upload
TaskCompletionListener<String, String> fileUploadListener = new TaskCompletionListener<>() {
  @Override
  public void onComplete(@Nullable String fileUrl) {
    //highlight-next-line
    Log.d("VideoSDK", "Uploaded file url: " + fileUrl);
  }

  @Override
  public void onError(@Nullable String error) {
    Log.d("VideoSDK", "Error in upload file: " + error);
  }
};

// capture image
meeting.getLocalParticipant().captureImage(new TaskCompletionListener<String, String>() {
    @Override
    public void onComplete(@Nullable String base64Data) {
      Log.d("VideoSDK", "capturedImage in base64 format: " + base64Data);
      String token = "<VIDEOSDK_TOKEN>";
      String fileName = "myCapture.jpeg"; // specify a name for image file with extension
      //highlight-start
      // upload image to videosdk storage system
      meeting.uploadBase64File(base64Data, token, fileName, fileUploadListener);
      //highlight-end
    }

    @Override
    public void onError(@Nullable String error) {
        Log.d("VideoSDK", "Error in image capture: " + error);
    }
});
  }
}
```

- Next, the `fileUrl` is sent back to the participant who initiated the request using the `IMAGE_TRANSFER` topic.

**Kotlin:**

```js
class MainActivity : AppCompatActivity() {

  //..

  private fun captureAndStoreImage(senderId: String) {
// listener for file-upload
val fileUploadListener: TaskCompletionListener<String, String> =
  object : TaskCompletionListener<String?, String?> {
    override fun onComplete(@Nullable fileUrl: String?) {
      //highlight-start
      Log.d("VideoSDK", "Uploaded file url: $fileUrl")
      imageTransfer(fileUrl, senderId)
      //highlight-end
    }

    override fun onError(@Nullable error: String?) {
      Log.d("VideoSDK", "Error in upload file: $error")
    }
}

//...
  }

  private fun imageTransfer(fileUrl: String?, senderId: String) {
val publishOptions = PubSubPublishOptions()
publishOptions.isPersist = false
//highlight-start
// Pass the participantId who initiated the request
val sendOnly = arrayOf(senderId)
publishOptions.setSendOnly(sendOnly)
//highlight-end

// send fileUrl to the participant who request for image using the publish method
//highlight-next-line
meeting!!.pubSub.publish("IMAGE_TRANSFER", fileUrl, publishOptions)
  }
}
```

---

**Java:**

```js
public class MainActivity extends AppCompatActivity {

  //...

  private void captureAndStoreImage(String senderId) {
  // listener for file-upload
  TaskCompletionListener<String, String> fileUploadListener = new TaskCompletionListener<>() {
      @Override
      public void onComplete(@Nullable String fileUrl) {
        //highlight-start
        Log.d("VideoSDK", "Uploaded file url: " + fileUrl);
        imageTransfer(fileUrl, senderId);
        //highlight-end
      }

      @Override
      public void onError(@Nullable String error) {
        Log.d("VideoSDK", "Error in upload file: " + error);
      }
  };

  //...

}

private void imageTransfer(String fileUrl,String senderId) {
  PubSubPublishOptions publishOptions = new PubSubPublishOptions();
  publishOptions.setPersist(false);
  //highlight-start
  // Pass the participantId who initiated the request
  String[] sendOnly = {senderId};
  publishOptions.setSendOnly(sendOnly);
  //highlight-end

  // send fileUrl to the participant who request for image using the publish method
  //highlight-next-line
  meeting.pubSub.publish("IMAGE_TRANSFER", fileUrl, publishOptions);
}
}
```

#### Step 3 : Fetch and Display Image

- To display a captured image, the `showCapturedImage()` method is used. Here's how it works:

- Within the `showCapturedImage()` method, subscribe to the `IMAGE_TRANSFER` topic to receive the `fileUrl` associated with the captured image.

- Once the `fileUrl` is obtained, use the `fetchBase64File()` method from the `Meeting` class to retrieve the file in `base64` format from VideoSDK's temporary storage.

**Kotlin:**

```js
class MainActivity : AppCompatActivity() {

  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

showCapturedImage()
  }

  private fun showCapturedImage() {
val pubSubMessageListener =
  PubSubMessageListener { message: PubSubMessage ->
    if (message.senderId != meeting!!.localParticipant.id) {
      // fetch the image when message received
      val url = message.message
      val token = "<VIDEOSDK_TOKEN>"
      meeting!!.fetchBase64File(
        url,
        token,
        object : TaskCompletionListener<String?, String?> {
          override fun onComplete(@Nullable base64Data: String?) {
              // here is your image in the form of base64
              Log.d("VideoSDK", "Fetched file in base64:$base64Data")
              // coverting base64 to bitmap to display an image in the imageView
              val capturedImage =
                  findViewById<ImageView>(R.id.capturedImage)
              val decodedString: ByteArray =
                  Base64.decode(base64Data, Base64.DEFAULT)
              val decodedByte =
                  BitmapFactory.decodeByteArray(
                      decodedString,
                      0,
                      decodedString.size
                  )
              capturedImage.setImageBitmap(decodedByte)
          }

          override fun onError(@Nullable error: String?) {
              Log.d("VideoSDK", "Error in fetch file: $error")
          }
        }
      )
    }
  }

// Subscribe for 'IMAGE_TRANSFER' topic to receive fileUrl
meeting!!.pubSub.subscribe("IMAGE_TRANSFER", pubSubMessageListener)
  }
}
```

---

**Java:**

```js
public class MainActivity extends AppCompatActivity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

//...

showCapturedImage();
  }

  private void showCapturedImage(){
PubSubMessageListener pubSubMessageListener = message -> {
  if (!message.getSenderId().equals(meeting.getLocalParticipant().getId())) {
    // fetch the image when message received
    String url = message.getMessage();
    String token = "<VIDEOSDK_TOKEN>";
    meeting.fetchBase64File(url, token, new TaskCompletionListener<String, String>() {
      @Override
      public void onComplete(@Nullable String base64Data) {
        // here is your image in the form of base64
        Log.d("VideoSDK", "Fetched file in base64:" + base64Data);
        // coverting base64 to bitmap to display an image in the imageView
        ImageView capturedImage = findViewById(R.id.capturedImage);
        byte[] decodedString = Base64.decode(base64Data, Base64.DEFAULT);
        Bitmap decodedByte = BitmapFactory.decodeByteArray(decodedString, 0, decodedString.length);
        capturedImage.setImageBitmap(decodedByte);
      }

      @Override
      public void onError(@Nullable String error) {
          Log.d("VideoSDK", "Error in fetch file: " + error);
      }
    });
  }
};

// Subscribe for 'IMAGE_TRANSFER' topic to receive fileUrl
meeting.pubSub.subscribe("IMAGE_TRANSFER", pubSubMessageListener);
  }
}
```

:::note

The file stored in the [VideoSDK's temporary file storage system](/react/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/upload-fetch-temporary-file) will be automatically deleted once the current room/meeting comes to an end.

:::

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [captureImage()](/android/api/sdk-reference/participant-class/methods#captureimage)
- [pubSub()](/android/api/sdk-reference/pubsub-class/introduction)
- [uploadBase64File()](/android/api/sdk-reference/meeting-class/methods#uploadbase64file)
- [fetchBase64File()](/android/api/sdk-reference/meeting-class/methods#fetchbase64file)


---

# Mute / Unmute Mic - Android

Muting and Unmuting your microphone refers to turning your microphone off and on, respectively.

When you mute your microphone, you prevent any sound from your microphone from being transmitted to other meeting participants, while unmuting it allows others to hear you.

### `unmuteMic()`

- By using `unmuteMic()` function of `Meeting` class, local participant can publish audio to other participants.

  - You can call this method when the local participant is not broadcasting any audio to others.

- You can pass customised audio track in `unmuteMic()` by using [Custom Audio Track](/android/guide/video-and-audio-calling-api-sdk/render-media/optimize-audio-track).

- Audio stream of the participant can be accessed from the `onStreamEnabled` event of `ParticipantEventListener`.

### `muteMic()`

- By using `muteMic()` function of `Meeting` class, local participant can stop publish audio to other participants.

- You can call this method when the local participant is broadcasting any audio to others.

#### Example



**Kotlin:**

```js
  private var micEnabled = false

  btnMic!!.setOnClickListener { _: View? ->
 if (micEnabled) {
  // Muting Mic
  //highlight-next-line
   meeting!!.muteMic()
   micEnabled=false
 } else {
  // Unmuting Mic
  //highlight-next-line
  meeting!!.unmuteMic()
  micEnabled=true
 }
  }
```

---

**Java:**

```js
  private boolean micEnabled = false;

  btnMic.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
      if (micEnabled) {
          // Muting Mic
          //highlight-next-line
          meeting.muteMic();
          micEnabled = false;
      } else {
        // Unmuting Mic
        //highlight-next-line
          meeting.unmuteMic();
          micEnabled = true;
      }
  }
  });
```

### Events associated with `unmuteMic`

- Every Participant will receive a callback on [`onStreamEnabled()`](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamenabled) of the [`Participant`](/android/api/sdk-reference/participant-class/introduction) with `Stream` object.

### Events associated with `muteMic`

- Every Participant will receive a callback on [`onStreamDisabled()`](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamdisabled) of the [`Participant`](/android/api/sdk-reference/participant-class/introduction) with `Stream` object.

**Kotlin:**

```js
  meeting!!.localParticipant.addEventListener(object : ParticipantEventListener() {
//Callback for when the participant starts a stream
//highlight-start
override fun onStreamEnabled(stream: Stream) {
    if(stream.getKind().equals("audio")){
      Log.d("VideoSDK","Audio Stream On: onStreamEnabled $stream");
    }
}
//highlight-end

//Callback for when the participant stops a stream
//highlight-start
override fun onStreamDisabled(stream: Stream) {
    if(stream.getKind().equals("audio")){
      Log.d("VideoSDK","Audio Stream On: onStreamDisabled $stream");
    }
}
//highlight-end
  });
```

---

**Java:**

```js
  participant.addEventListener(new ParticipantEventListener() {
//Callback for when the participant starts a stream
//highlight-start
@Override
public void onStreamEnabled(Stream stream) {
    if(stream.getKind().equals("audio")){
      Log.d("VideoSDK","Audio Stream On: onStreamEnabled" + stream);
    }
}
//highlight-end

//Callback for when the participant stops a stream
//highlight-start
@Override
public void onStreamDisabled(Stream stream) {
    if(stream.getKind().equals("audio")){
      Log.d("VideoSDK","Audio Stream Off: onStreamDisabled" + stream);
    }
}
//highlight-end
  });
```

## Audio Permissions

- To use the microphone in a meeting, you need to add permission in `app/src/main/AndroidManifest.xml` after `</application>`.

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

- You need to set up a permission request that provides this access.

**Kotlin:**

```js
import android.Manifest
import android.content.pm.PackageManager
import android.os.Bundle
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import androidx.core.app.ActivityCompat
import androidx.core.content.ContextCompat

class MainActivity : AppCompatActivity() {
private val PERMISSION_REQUEST_CODE: Int = 1;

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    //highlight-start
    if (checkPermission()) {
        // . write your main code to execute, It will execute if the permission is already given.
    } else {
        requestPermission()
    }
    //highlight-end
}
private fun checkPermission(): Boolean {
    //highlight-next-line
    return ContextCompat.checkSelfPermission(this, Manifest.permission.RECORD_AUDIO) == PackageManager.PERMISSION_GRANTED
}

private fun requestPermission() {
  //highlight-start
    ActivityCompat.requestPermissions(
        this, arrayOf(Manifest.permission.RECORD_AUDIO),
        PERMISSION_REQUEST_CODE
    )
  //highlight-end
}

override
fun onRequestPermissionsResult(
    requestCode: Int,
    permissions: Array<out String>,
    grantResults: IntArray
) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults)
    when (requestCode) {
        PERMISSION_REQUEST_CODE -> if (grantResults.isNotEmpty() && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
            Toast.makeText(applicationContext, "Permission Granted", Toast.LENGTH_SHORT).show()
            // main logic
        } else {
            Toast.makeText(applicationContext, "Permission Denied", Toast.LENGTH_SHORT).show()
        }
    }
}
}
```

---

**Java:**

```js
import androidx.annotation.NonNull;
import androidx.appcompat.app.AppCompatActivity;
import androidx.core.app.ActivityCompat;
import androidx.core.content.ContextCompat;

import android.Manifest;
import android.content.pm.PackageManager;
import android.os.Bundle;
import android.widget.Toast;

import java.util.ArrayList;
import java.util.List;

public class MainActivity extends AppCompatActivity {

private static final int PERMISSION_REQUEST_CODE = 1;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    //highlight-start
    if (checkPermission()) {
        // . write your main code to execute, It will execute if the permission is already given.
    } else {
        requestPermission();
    }
    //highlight-end
}

private boolean checkPermission() {
    //highlight-next-line
    return ContextCompat.checkSelfPermission(this, Manifest.permission.RECORD_AUDIO) == PackageManager.PERMISSION_GRANTED;
}

private void requestPermission() {
    List<String> permissionList = new ArrayList<String>();
    String[] permissions = {};
    permissionList.add(Manifest.permission.RECORD_AUDIO);
    //highlight-start
    ActivityCompat.requestPermissions(
            this, permissionList.toArray(permissions),
            PERMISSION_REQUEST_CODE
    );
    //highlight-end
}

@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
    switch (requestCode) {
        case PERMISSION_REQUEST_CODE:
            if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                Toast.makeText(MainActivity.this, "Permission Granted", Toast.LENGTH_SHORT).show();
                // main logic
            } else {
                Toast.makeText(MainActivity.this, "Permission Denied", Toast.LENGTH_SHORT).show();
            }
            break;
    }
}
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [unmuteMic()](/android/api/sdk-reference/meeting-class/methods#unmutemic)
- [muteMic()](/android/api/sdk-reference/meeting-class/methods#mutemic)
- [onStreamEnabled()](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamenabled)
- [onStreamDisabled()](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamdisabled)


---

# On / Off Camera - Android

Any participant can turn on or off his camera in the meeting using below methods.

### `enableWebcam()`

- By using `enableWebcam()` function of `Meeting` class, local participant can publish video to other participants.

- You can call this method when the local participant is not broadcasting any video to others.

- You can pass customised video track in `enableWebcam()` by using [Custom Video Track](/android/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track#custom-video-track).

- Video stream of the participant can be accessed from the `onStreamEnabled` event of `ParticipantEventListener`.

### `disableWebcam()`

- By using `disableWebcam()` function of `Meeting` class, local participant can stop publish video to other participants.

- You can call this method when the local participant is broadcasting any video to others.

#### Example



**Kotlin:**

```js
  btnWebcam!!.setOnClickListener {
if (webcamEnabled) {
  // Disabling camera
  //highlight-next-line
  meeting!!.disableWebcam()
} else {
  // Enabling camera
  //highlight-next-line
  meeting!!.enableWebcam()
}
webcamEnabled=!webcamEnabled
  }
```

---

**Java:**

```js
  btnWebcam.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
    if (webcamEnabled) {
      // Disabling camera
      //highlight-next-line
      meeting.disableWebcam();
    } else {
      // Enabling camera
      //highlight-next-line
      meeting.enableWebcam();
    }
    webcamEnabled=!webcamEnabled;
  }
  });
```

:::important
To learn, how to render video in the meeting, [follow this](/android/guide/video-and-audio-calling-api-sdk/render-media/display-video/render-participant) detailed guide.
:::

### Events associated with `enableWebcam`

- Every Participant will receive a callback on [`onStreamEnabled()`](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamenabled) of the [`Participant`](/android/api/sdk-reference/participant-class/introduction) with `Stream` object.

### Events associated with `disableWebcam`

- Every Participant will receive a callback on [`onStreamDisabled()`](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamdisabled) of the [`Participant`](/android/api/sdk-reference/participant-class/introduction) with `Stream` object.

**Kotlin:**

```js
  meeting!!.localParticipant.addEventListener(object : ParticipantEventListener() {
//Callback for when the participant starts a stream
//highlight-start
override fun onStreamEnabled(stream: Stream) {
    if(stream.getKind().equals("video")){
      Log.d("VideoSDK","Video Stream On: onStreamEnabled $stream");
    }
}
//highlight-end

//Callback for when the participant stops a stream
//highlight-start
override fun onStreamDisabled(stream: Stream) {
    if(stream.getKind().equals("video")){
      Log.d("VideoSDK","Video Stream On: onStreamDisabled $stream");
    }
}
//highlight-end
  });
```

---

**Java:**

```js
  participant.addEventListener(new ParticipantEventListener() {
//Callback for when the participant starts a stream
//highlight-start
@Override
public void onStreamEnabled(Stream stream) {
    if(stream.getKind().equals("video")){
      Log.d("VideoSDK","Video Stream On: onStreamEnabled" + stream);
    }
}
//highlight-end

//Callback for when the participant stops a stream
//highlight-start
@Override
public void onStreamDisabled(Stream stream) {
    if(stream.getKind().equals("video")){
      Log.d("VideoSDK","Video Stream Off: onStreamDisabled" + stream);
    }
}
//highlight-end
  });
```

### Video Permissions

- To use the camera in a meeting, you need to add permission in `app/src/main/AndroidManifest.xml` after `</application>`.

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

- You need to set up a permission request that provides this access.

**Kotlin:**

```js
import android.Manifest
import android.content.pm.PackageManager
import android.os.Bundle
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import androidx.core.app.ActivityCompat
import androidx.core.content.ContextCompat

class MainActivity : AppCompatActivity() {
private val PERMISSION_REQUEST_CODE: Int = 1;

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    //highlight-start
    if (checkPermission()) {
        // . write your main code to execute, It will execute if the permission is already given.
    } else {
        requestPermission()
    }
    //highlight-end
}
private fun checkPermission(): Boolean {
    //highlight-next-line
    return ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA) == PackageManager.PERMISSION_GRANTED
}

private fun requestPermission() {
  //highlight-start
    ActivityCompat.requestPermissions(
        this, arrayOf(Manifest.permission.CAMERA),
        PERMISSION_REQUEST_CODE
    )
  //highlight-end
}

override
fun onRequestPermissionsResult(
    requestCode: Int,
    permissions: Array<out String>,
    grantResults: IntArray
) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults)
    when (requestCode) {
        PERMISSION_REQUEST_CODE -> if (grantResults.isNotEmpty() && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
            Toast.makeText(applicationContext, "Permission Granted", Toast.LENGTH_SHORT).show()
            // main logic
        } else {
            Toast.makeText(applicationContext, "Permission Denied", Toast.LENGTH_SHORT).show()
        }
    }
}
}
```

---

**Java:**

```js
import androidx.annotation.NonNull;
import androidx.appcompat.app.AppCompatActivity;
import androidx.core.app.ActivityCompat;
import androidx.core.content.ContextCompat;

import android.Manifest;
import android.content.pm.PackageManager;
import android.os.Bundle;
import android.widget.Toast;

import java.util.ArrayList;
import java.util.List;

public class MainActivity extends AppCompatActivity {

private static final int PERMISSION_REQUEST_CODE = 1;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    //highlight-start
    if (checkPermission()) {
        // . write your main code to execute, It will execute if the permission is already given.
    } else {
        requestPermission();
    }
    //highlight-end
}

private boolean checkPermission() {
    //highlight-next-line
    return ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA) == PackageManager.PERMISSION_GRANTED;
}

private void requestPermission() {
    List<String> permissionList = new ArrayList<String>();
    String[] permissions = {};
    permissionList.add(Manifest.permission.CAMERA);
    //highlight-start
    ActivityCompat.requestPermissions(
            this, permissionList.toArray(permissions),
            PERMISSION_REQUEST_CODE
    );
    //highlight-end
}

@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
    switch (requestCode) {
        case PERMISSION_REQUEST_CODE:
            if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                Toast.makeText(MainActivity.this, "Permission Granted", Toast.LENGTH_SHORT).show();
                // main logic
            } else {
                Toast.makeText(MainActivity.this, "Permission Denied", Toast.LENGTH_SHORT).show();
            }
            break;
    }
}
}
```

:::important
If the app goes to the background, VideoSDK detectes this event based on activity lifecycle and release the camera so that it can be used by other apps. In order to make sure this functionality works properly use  `VideoSDK.setActivityForLifeCycle(activity)` to specify which activity VideoSDK should monitor for lifecycle changes.
:::

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [enableWebcam()](/android/api/sdk-reference/meeting-class/methods#enablewebcam)
- [disableWebcam()](/android/api/sdk-reference/meeting-class/methods#disablewebcam)
- [onStreamEnabled()](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamenabled)
- [onStreamDisabled()](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamdisabled)


---

# Screen Share - Android

Screen sharing in a meeting is the process of sharing your mobile screen with other participants in the meeting. It allows everyone in the meeting to see exactly what you are seeing on your screen, which can be helpful for presentations, demonstrations, or collaborations.

## How Screen share works?

- The following diagram shows flow of the screen sharing in android using VideoSDK :

<div style={{textAlign: 'center'}}>

![VideoSDK Android Screenshare Flow Diagram](/img/android/screenshare/flow_diagram.png)

</div>

### `enableScreenShare()`

- By using `enableScreenShare()` function of `Meeting` class, local participant can share his/her mobile screen to other participants.

- You can pass customised screenshare track in `enableScreenShare()` by using [Custom Screen Share Track](/android/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track#custom-screen-share-track).

- Screen Share stream of the participant can be accessed from the `onStreamEnabled` event of `ParticipantEventListener`.


### System Audio with Screen Share

- System Audio Sharing during screen sharing, allowing users to share both the screen and the audio from their device simultaneously.
- `Boolean enableAudio`: In the `enableScreenShare()` method, the second parameter, `enableAudio`, is a flag that controls whether system audio is shared. Set it to `true` to include system audio with the screen share, or `false` to share only the screen without audio.
- Ensure that you request the necessary permissions (`android.permission.RECORD_AUDIO`) for screen sharing and system audio capture on the user's device. The required permissions may vary based on the Android version and device manufacturer.
- Devices running `Android 9` (`API Level 28`) or below will not support the System Audio sharing feature.

    :::note
    System audio will only work when the microphone is on. If the microphone is muted, the system audio will also be muted.
    :::

### Screenshare permission

- A participant’s Screen share stream is provided via the `MediaProjection` API. This API is only compatible with `Build.VERSION_CODES.LOLLIPOP` or higher.

- Get an instance of the `MediaProjectionManager` and Call the `createScreenCaptureIntent()` method in an activity. This initiates a prompt dialog for the user to confirm screen projection.

- One will get a prompt dialog like this:

<div style={{textAlign: 'center'}}>

<img
src={require('/img/android/screenshare/user_permission.jpg').default}
alt="user permission"
width="450"
/>

</div>

<br/>

- After permission is received from the user, you can call `enableScreenShare()` method.



**Kotlin:**

```js
private fun enableScreenShare() {
val mediaProjectionManager = application.getSystemService(
    MEDIA_PROJECTION_SERVICE
) as MediaProjectionManager
startActivityForResult(
    mediaProjectionManager.createScreenCaptureIntent(), CAPTURE_PERMISSION_REQUEST_CODE
)
}

public override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode != CAPTURE_PERMISSION_REQUEST_CODE) return
if (resultCode == RESULT_OK) {
    // Enabling screen share
    //highlight-next-line
    meeting!!.enableScreenShare(data, true) // enableAudio = true: Enables system audio sharing
}
}
```

---

**Java:**

```js
private void enableScreenShare() {
MediaProjectionManager mediaProjectionManager =
    (MediaProjectionManager) getApplication().getSystemService(
        Context.MEDIA_PROJECTION_SERVICE);
startActivityForResult(
    mediaProjectionManager.createScreenCaptureIntent(), CAPTURE_PERMISSION_REQUEST_CODE);
}

@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
super.onActivityResult(requestCode, resultCode, data);
if (requestCode != CAPTURE_PERMISSION_REQUEST_CODE)
    return;
if (resultCode == Activity.RESULT_OK) {
    // Enabling screen share
    //highlight-next-line
    meeting.enableScreenShare(data , true); // enableAudio = true: Enables system audio sharing
}
}
```

### Customise notification

- When a presenter starts screen share, presenter will receive a notification with a pre-defined title and message.

- Notification with pre-defined title and message will look like this:

<div style={{textAlign: 'center'}}>

<img
src={require('/img/android/screenshare/notification.jpg').default}
alt="notification"
width="450"
/>

</div>

- You can Customise those title, message and icon as per your requirements using `<meta-data>` specified in `app/src/main/AndroidManifest.xml`.

```js
<application>
  <meta-data
    android:name="notificationTitle"
    //highlight-next-line
    android:value="@string/notificationTitle"
  />
  <meta-data
    android:name="notificationContent"
    //highlight-next-line
    android:value="@string/notificationContent"
  />
  <meta-data
    android:name="notificationIcon"
    //highlight-next-line
    android:resource="@mipmap/ic_launcher_round"
  />
</application>
```

### `disableScreenShare()`

- By using `disableScreenShare()` function of `Meeting` class, local participant can stop sharing his/her mobile screen to other participants.

**Kotlin:**

```js
private fun disableScreenShare() {
// Disabling screen share
//highlight-next-line
meeting!!.disableScreenShare()
}
```

---

**Java:**

```js
private void disableScreenShare(){
// Disabling screen share
//highlight-next-line
meeting.disableScreenShare();
}
```

### Events associated with enableScreenShare

- Participant who share their mobile screen will receive a callback on [`onStreamEnabled()`](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamenabled) of the [`Participant`](/android/api/sdk-reference/participant-class/introduction) with `Stream` object.

- While other Participants will receive [`onPresenterChanged()`](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onpresenterchanged) callback of the [`Meeting`](/android/api/sdk-reference/meeting-class/introduction) class with the participantId as `presenterId` who started the screen share.

### Events associated with disableScreenShare

- Participant who shared their mobile screen will receive a callback on [`onStreamDisabled()`](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamdisabled) of the [`Participant`](/android/api/sdk-reference/participant-class/introduction) with `Stream` object.

- While other Participants will receive [`onPresenterChanged()`](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onpresenterchanged) callback of the [`Meeting`](/android/api/sdk-reference/meeting-class/introduction) class with the `presenterId` as `null` indicating there is no presenter.

**Kotlin:**

```js
private fun setLocalListeners() {
meeting!!.localParticipant.addEventListener(object : ParticipantEventListener() {
    //Callback for when the participant starts a stream
    //highlight-start
    override fun onStreamEnabled(stream: Stream) {
       if (stream.kind.equals("share", ignoreCase = true)) {
          Log.d("VideoSDK","Share Stream On: onStreamEnabled $stream");
        }
    }
    //highlight-end

    //Callback for when the participant stops a stream
    //highlight-start
    override fun onStreamDisabled(stream: Stream) {
        if (stream.kind.equals("share", ignoreCase = true)) {
           Log.d("VideoSDK","Share Stream On: onStreamDisabled $stream");
        }
    }
    //highlight-end
});
}

private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
//Callback for when the presenter changes
//highlight-start
override fun onPresenterChanged(participantId: String) {
    if(!TextUtils.isEmpty(participantId))
    {
      Log.d("VideoSDK","$participantId started screen share");
    }else{
      Log.d("VideoSDK","some one stopped screen share");
    }
}
//highlight-end
}
```

---

**Java:**

```js
private void setLocalListeners() {
meeting.getLocalParticipant().addEventListener(new ParticipantEventListener() {
    //Callback for when the participant starts a stream
    //highlight-start
    @Override
    public void onStreamEnabled(Stream stream) {
        if (stream.getKind().equalsIgnoreCase("share")) {
            Log.d("VideoSDK","Share Stream On: onStreamEnabled" + stream);
        }
    }
    //highlight-end

    //Callback for when the participant stops a stream
    //highlight-start
    @Override
    public void onStreamDisabled(Stream stream) {
        if (stream.getKind().equalsIgnoreCase("share")) {
            Log.d("VideoSDK","Share Stream Off: onStreamDisabled" + stream);
        }
    }
    //highlight-end
});
}

private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
//Callback for when the presenter changes
//highlight-start
@Override
public void onPresenterChanged(String participantId) {
  if(participantId != null){
    Log.d("VideoSDK",participantId + "started screen share");
  }else{
    Log.d("VideoSDK","some one stopped screen share");
  }
}
//highlight-end
};
```

### Rendering Screen Share Stream

- When a local participant shares their screen, the `onStreamEnabled()` function of the `ParticipantEventListener` is triggered, allowing the `Stream` to be added to a `VideoView`.

**Kotlin:**

```js
private fun setLocalListeners() {
meeting!!.localParticipant.addEventListener(object : ParticipantEventListener() {
    override fun onStreamEnabled(stream: Stream) {
       if (stream.kind.equals("share", ignoreCase = true)) {
            // display share video
            val videoTrack = stream.track as VideoTrack
            shareView!!.addTrack(videoTrack)
        }
    }
    override fun onStreamDisabled(stream: Stream) {
        if (stream.kind.equals("share", ignoreCase = true)) {
           shareView!!.removeTrack()
        }
    }
});
}
```

---

**Java:**

```js
private void setLocalListeners() {
meeting.getLocalParticipant().addEventListener(new ParticipantEventListener() {
    @Override
    public void onStreamEnabled(Stream stream) {
        if (stream.getKind().equalsIgnoreCase("share")) {
            // display share video
            VideoTrack videoTrack = (VideoTrack) stream.getTrack();
            shareView.addTrack(videoTrack);
        }
    }
    @Override
    public void onStreamDisabled(Stream stream) {
        if (stream.getKind().equalsIgnoreCase("share")) {
            shareView.removeTrack();
        }
    }
});
}
```


- When another participant (excluding the local participant) shares their screen, the `onPresenterChanged()` function in the `MeetingEventListener` is triggered, providing the `participantId` of the screen sharer.

**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
override fun onPresenterChanged(participantId: String) {
    updatePresenter(participantId)
}
}

//Getting the stream from the participantId
private fun updatePresenter(participantId: String?) {
// find participant
val participant = meeting!!.participants.get(participantId) ?: return

// find share stream in participant
var shareStream: Stream? = null
for (stream: Stream in participant.streams.values) {
    if ((stream.kind == "share")) {
        shareStream = stream
        break
    }
}
if (shareStream == null) return

// display share video
val videoTrack = shareStream.track as VideoTrack
shareView!!.addTrack(videoTrack)

// listen for share stop event
participant.addEventListener(object : ParticipantEventListener() {
    override fun onStreamDisabled(stream: Stream) {
        if ((stream.kind == "share")) {
            shareView!!.removeTrack()
        }
    }
})
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
//Triggered when Presenter changes
@Override
public void onPresenterChanged(String participantId) {
    updatePresenter(participantId);
}
};

//Getting the stream from the participantId
private void updatePresenter(String participantId) {
// find participant
Participant participant = meeting.getParticipants().get(participantId);
if (participant == null) return;

// find share stream in participant
Stream shareStream = null;
for (Stream stream: participant.getStreams().values()) {
    if (stream.getKind().equals("share")) {
        shareStream = stream;
        break;
    }
}
if (shareStream == null) return;

// display share video
VideoTrack videoTrack = (VideoTrack) shareStream.getTrack();
shareView.addTrack(videoTrack)

// listen for share stop event
participant.addEventListener(new ParticipantEventListener() {
    @Override
    public void onStreamDisabled(Stream stream) {
        if (stream.getKind().equals("share")) {
            shareView.removeTrack();
        }
    }
});
}
```

:::info

- Here screenShare stream is displayed using `VideoView`, but you may also use `SurfaceViewRender` for the same.
- For `VideoView`, SDK version should be `0.1.13` or higher.
- To know more about `VideoView`, please visit [here](/android/guide/video-and-audio-calling-api-sdk/render-media/display-video/understand-videoView-component)

:::

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [enableScreenShare()](/android/api/sdk-reference/meeting-class/methods#enablescreenshare)
- [disableScreenShare()](/android/api/sdk-reference/meeting-class/methods#disablescreenshare)
- [onStreamEnabled()](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamenabled)
- [onStreamDisabled()](/android/api/sdk-reference/participant-class/participant-event-listener-class#onstreamdisabled)
- [onPresenterChanged()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onpresenterchanged)


---

# Integrate Android SDK




---

# Known Issues - Android




---

https://sdk.videosdk.live/js-sdk/0.2.6/videosdk.jsVideoSDK offers a range of video streaming tools and solutions for content creators, publishers, and developers.

- A custom template is a specialized layout for a live stream that allows users to integrate real-time graphics into their broadcasts.

- With custom templates, users can enhance their video content by overlaying graphics, text, images, and animations onto their live streams. These elements can be customized to align with specific branding requirements.

- By leveraging custom templates, users can craft dynamic and engaging video experiences. Whether incorporating live scoreboards, social media feeds, or other personalized elements, users have the flexibility to create visually appealing streams that stand out and capture audience attention.

:::note

Custom templates can also be used with recordings and RTMP service provided by VideoSDK.

:::

### What you can do with Custom Template

By utilizing a custom template, you have the flexibility to create various modes for your live stream. Here are some popular modes that you can design:

- **`PK Host:`** The host can organize a player vs. player battle, as illustrated in the example of a gaming battle shown below.

![pk host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_pk_battle.png)

- **`Watermark:`** The host has the ability to add and update watermarks anywhere in the template; for instance, the image below features a VideoSDK watermark on the top right side of the screen.

![watermark host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_water_mark.png)

- **`News Mode:`** Additionally, the host can incorporate dynamic text in the lower third banner, as demonstrated by the sample text in the bottom left of the screen.

![news mode](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_news_live.png)

### Custom template with VideoSDK

In this section, we will discuss how Custom Templates work with VideoSDK.

- **`Host`**: The host initiates live streaming by providing the `templateURL`. The `templateURL` is the URL of the hosted template webpage. The host is also responsible for managing the template, including tasks such as altering text, logos, and switching template layouts.

- **`VideoSDK Template Engine`** : The VideoSDK Template Engine accepts and opens the templateURL in the browser, actively listening to all events initiated by the Host. It facilitates the customization of the template in accordance with the host's preferences.

- **`Viewer`**: Viewers can stream the content, experiencing the live stream with added real-time graphics. This feature contributes to a distinctive and engaging viewing experience.

![custom template](https://cdn.videosdk.live/website-resources/docs-resources/custom_template.png)

### Understanding Template URL

The template URL is a webpage that VideoSDK Template Engine will open while composing the live stream.

It will appear as shown below.

![template url](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_url.png)

The Template URL comprises of two essential parts:

- Your actual page URL, resembling something like `https://example.com/videosdk-template`.
- Query parameters, designed to enable the VideoSDK Template Engine to seamlessly join the meeting upon opening the URL. There are three key query parameters in total:
  - `token`: Your token, serving as the authentication key to join the meeting.
  - `meetingId`: The meeting Id of the meeting that the VideoSDK Template Engine will join.
  - `participantId`: The participant ID of the VideoSDK Template Engine. This should be included when joining the template engine in your template, ensuring that the template engine participant remains invisible to other participants. **This parameter is automatically added by the VideoSDK**.

:::info

Above mentioned query parameters are mandatory. Apart from these parameters, you can pass any other extra parameters which are required according to your use-case.

:::

### **Creating Template**

**`Step 1:`** Import VideoSDK using `<script>` tag or install it using the below-mentioned npm command.
Make sure you are in your app directory before you run this command.



**Tab:**

" label="<script>" default>

```html
<html>
  <head></head>
  <body>
// highlight-next-line
<script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
  </body>
</html>
```

---

**npm:**

```bash
npm install @videosdk.live/js-sdk
```

---

**yarn:**

```bash
yarn add @videosdk.live/js-sdk
```

:::note

You can use VideoSDK's React or JavaScript SDK to create custom template. Following is the example of building custom template with JavaScript SDK.

:::

###### Structure of the Project

```jsx title="Project Structure"
  root
   ├── index.html
   ├── index.js
```

**`Step 2:`** Craft a user interface (UI) tailored for your live stream presentation.

```html title="index.html"
<!DOCTYPE html>
<html>
  <head> </head>

  <body>
    <div id="textDiv">Starting live stream...</div>

    
    <div class="row" id="videoContainer"></div>

    <script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
    <script src="index.js"></script>
  </body>
</html>
```

**`Step 3:`** Next, fetch the query parameters, from the URL which will be later used to initialize the meeting and get the elements from DOM.

```js title=index.js
const url = window.location;
const urlParams = new URLSearchParams(url.search);

const meetingId = urlParams.get("meetingId");
const token = urlParams.get("token");
const participantId = urlParams.get("participantId");

const videoContainer = document.getElementById("videoContainer");
const textDiv = document.getElementById("textDiv");
```

**`Step 4:`** Subsequently, initialize the meeting with the parameters that were extracted from the URL. Ensure direct initialization so that the template engine seamlessly joins the meeting upon page load.

```js title=index.js
window.VideoSDK.config(token);

const meeting = window.VideoSDK.initMeeting({
  meetingId: meetingId, // required
  name: "recorder", // required
  micEnabled: false,
  webcamEnabled: false,
  participantId: participantId,
});

meeting.join();

meeting.on("meeting-joined", () => {
  textDiv.style.display = "none";
});
```

**`Step 5:`** Next step is to create the container that will render the meeting view on the `participant-joined` event.

```js title=index.js
//  participant joined
meeting.on("participant-joined", (participant) => {
  let videoElement = createVideoElement(
    participant.id,
    participant.displayName
  );
  let audioElement = createAudioElement(participant.id);

  participant.on("stream-enabled", (stream) => {
    setTrack(stream, audioElement, participant, false);
  });
  videoContainer.appendChild(videoElement);
  videoContainer.appendChild(audioElement);
});

// participants left
meeting.on("participant-left", (participant) => {
  let vElement = document.getElementById(`f-${participant.id}`);
  vElement.remove(vElement);

  let aElement = document.getElementById(`a-${participant.id}`);
  aElement.remove(aElement);
});

// creating video element
function createVideoElement(pId, name) {
  let videoFrame = document.createElement("div");
  videoFrame.setAttribute("id", `f-${pId}`);

  //create video
  let videoElement = document.createElement("video");
  videoElement.classList.add("video-frame");
  videoElement.setAttribute("id", `v-${pId}`);
  videoElement.setAttribute("playsinline", true);
  videoElement.setAttribute("width", "300");
  videoElement.muted = true;
  videoFrame.appendChild(videoElement);

  let displayName = document.createElement("div");
  displayName.innerHTML = `Name : ${name}`;
  videoFrame.appendChild(displayName);

  return videoFrame;
}

// creating audio element
function createAudioElement(pId) {
  let audioElement = document.createElement("audio");
  audioElement.setAttribute("autoPlay", "false");
  audioElement.setAttribute("playsInline", "true");
  audioElement.setAttribute("controls", "false");
  audioElement.setAttribute("id", `a-${pId}`);
  audioElement.style.display = "none";
  return audioElement;
}

// setting media track
function setTrack(stream, audioElement, participant, isLocal) {
  if (stream.kind == "video") {
    isWebCamOn = true;
    const mediaStream = new MediaStream();
    mediaStream.addTrack(stream.track);
    let videoElm = document.getElementById(`v-${participant.id}`);
    videoElm.srcObject = mediaStream;
    videoElm
      .play()
      .catch((error) =>
        console.error("videoElem.current.play() failed", error)
      );
  }
  if (stream.kind == "audio") {
    if (isLocal) {
      isMicOn = true;
    } else {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(stream.track);
      audioElement.srcObject = mediaStream;
      audioElement
        .play()
        .catch((error) => console.error("audioElem.play() failed", error));
    }
  }
}
```

**`Step 6:`** Now, listen to PubSub messages from the `CHANGE_BACKGROUND` topic, triggering a change in the meeting's background color accordingly.

:::note

The PubSub mechanism is utilized to communicate with the template. You can learn more about [PubSub from here](/javascript/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

:::

```js title=index.js
meeting.on("meeting-joined", () => {
  //  ...

  meeting.pubSub.subscribe("CHANGE_BACKGROUND", (data) => {
    let { message } = data;
    document.body.style.backgroundColor = message;
  });
});
```

**`Step 7:`** Once tested, you can deploy it using your backend or host it on services like [firebase](https://www.geeksforgeeks.org/how-to-deploy-react-project-on-firebase/) or vercel.

:::tip

You can checkout the github repository for sample custom template [created here](https://github.com/videosdk-live/videosdk-custom-recording-template-js-example).

:::

### Setup Livestream Using Custom Template

- To utilize Custom Templates with Livestream, you need to establish both the Host and Viewer setups. The Host initiates the livestream, while Viewers can watch the broadcast.

![template manager](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_manager.png)

- To understand custom templates, clone this example and run it on your system.

```bash
git clone https://github.com/videosdk-live/videosdk-custom-recording-template-js-example.git
```

- You can utilize this custom template in [Start Recording API](/api-reference/realtime-communication/start-recording), [Start HLS API](/api-reference/realtime-communication/start-hlsStream) and [Start Livestream API](/api-reference/realtime-communication/start-livestream). Here is the example of HLS.
- To utilize the custom template that has been deployed, invoke the [Start HLS API](https://docs.videosdk.live/api-reference/realtime-communication/start-hlsStream) instead of the `startHls` method from the `Meeting` class. The necessary code has already been incorporated in the cloned example above.

:::important

You can create your own custom template manager in JavaScript. In this example, we are using one for better understanding.

:::

```js
<button
  onClick={async () => {
    const url = `https://api.videosdk.live/v2/hls/start`;
    //Update your Custom Template URL here if you have deployed your own, if not deployed you can use this template from our URL.
    //highlight-next-line
    const templateUrl = `https://lab.videosdk.live/js-template-demo/?meetingId=${meetingId}&token=${authToken}`;
    const options = {
      method: "POST",
      headers: {
        Authorization: authToken,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        roomId: meetingId,
        templateUrl: templateUrl,
      }),
    };

    const result = await fetch(url, options)
      .then((response) => response.json()) // result will have playbackHlsUrl and livestreamUrl
      .catch((error) => console.error("error", error));
  }}
>
  Start HLS
</button>
```

- In this example, the host has two options on their side, enabling them to change the background and send messages to the viewers.

- Given below is a test run of the example.


<div style={{textAlign: 'center'}}>



</div>

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)
- [Start HLS API](/api-reference/realtime-communication/start-hlsStream)
- [Start Livestream API](/api-reference/realtime-communication/start-livestream)
- [recordingState](/react/api/sdk-reference/use-meeting/properties#recordingstate)
- [hlsState](/react/api/sdk-reference/use-meeting/properties#hlsstate)
- [livestreamState](/react/api/sdk-reference/use-meeting/properties#livestreamstate)
- [hlsUrls](/react/api/sdk-reference/use-meeting/properties#hlsurls)
- [onRecordingStateChanged](/react/api/sdk-reference/use-meeting/events#onrecordingstatechanged)
- [onHlsStateChanged](/react/api/sdk-reference/use-meeting/events#onhlsstatechanged)
- [onLivestreamStateChanged](/react/api/sdk-reference/use-meeting/events#onlivestreamstatechanged)



---

# Interactive Livestream (HLS) - Android

Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

In an interactive live stream (HLS), viewers can take part in a variety of activities like live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/mobile_hls.png' />

</center>

VideoSDK also allows you to configure the interactive livestream layouts in numerous ways like by simply setting different prebuilt layouts in the configuration or by providing your own custom template to do the livestream according to your layout choice.

This guide will provide an overview of how to implement start and stop Interactive live streaming (HLS).

:::important

To initiate automatic Interactive live streaming (HLS) at the beginning of a `session`, simply provide the `autoStartConfig` feature `hls` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.

:::

### `startHls()`

`startHls()` can be used to start a interactive livestream of the meeting which can be accessed from the `Meeting` class. This method accepts two parameter:

- `config`: This parameter will define how the interactive livestream layout should look like.

- `transcription`: This parameter lets you start post transcription for the Livestreaming.



**Kotlin:**

```js
val config = JSONObject()

//highlight-next-line
// Layout Configuration
val layout = JSONObject()
JsonUtils.jsonPut(layout, "type", "GRID") // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
JsonUtils.jsonPut(layout, "priority", "SPEAKER") // "PIN", Default : "SPEAKER"
JsonUtils.jsonPut(layout, "gridSize", 4) // MAX : 25
JsonUtils.jsonPut(config, "layout", layout)

//highlight-next-line
// Theme of interactive livestream layout
JsonUtils.jsonPut(config, "theme", "DARK") //  "LIGHT" | "DEFAULT"

//highlight-next-line
// `mode` is used to either interactive livestream video & audio both or only audio.
JsonUtils.jsonPut(config, "mode", "video-and-audio") // "audio", Default : "video-and-audio"

//highlight-next-line
// Quality of interactive livestream and is only applicable to `video-and-audio` type mode.
JsonUtils.jsonPut(config, "quality", "high") /* Default : "med"
   "low" (SD HLS) | "med" (HD HLS) | "high" (FHD HLS) */

//highlight-start
// This mode refers to orientation of interactive livestream.
// landscape : Start interactive livestream of the meeting in horizontally
// portrait : Start interactive livestream of the meeting in vertically (Best for mobile view)
//highlight-end
JsonUtils.jsonPut(config, "orientation", "portrait") // "landscape",  Default : "landscape"

//highlight-next-line
// Post Transcription Configuration
val prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
val summaryConfig = SummaryConfig(true, prompt)
val modelId = "raman_v1"
val transcription = PostTranscriptionConfig(true, summaryConfig, modelId)

meeting.startHls(config, transcription)
```

---

**Java:**

```js
JSONObject config = new JSONObject();

//highlight-next-line
// Layout Configuration
JSONObject layout = new JSONObject();
JsonUtils.jsonPut(layout, "type", "GRID"); // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
JsonUtils.jsonPut(layout, "priority", "SPEAKER");  // "PIN", Default : "SPEAKER"
JsonUtils.jsonPut(layout, "gridSize", 4); // MAX : 25
JsonUtils.jsonPut(config, "layout", layout);

//highlight-next-line
// Theme of interactive livestream layout
JsonUtils.jsonPut(config, "theme", "DARK"); //  "LIGHT" | "DEFAULT"

//highlight-next-line
// `mode` is used to either interactive livestream video & audio both or only audio.
JsonUtils.jsonPut(config, "mode", "video-and-audio"); // "audio", Default : "video-and-audio"

//highlight-next-line
// Quality of interactive livestream and is only applicable to `video-and-audio` type mode.
JsonUtils.jsonPut(config, "quality", "high"); /* Default : "med"
   "low" (SD HLS) | "med" (HD HLS) | "high" (FHD HLS) */

//highlight-start
// This mode refers to orientation of interactive livestream.
// landscape : Start interactive livestream of the meeting in horizontally
// portrait : Start interactive livestream of the meeting in vertically (Best for mobile view)
//highlight-end
JsonUtils.jsonPut(config, "orientation", "portrait"); // "landscape",  Default : "landscape"

//highlight-next-line
// Post Transcription Configuration
String prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary";
SummaryConfig summaryConfig = new SummaryConfig(true, prompt);
String modelId = "raman_v1";
PostTranscriptionConfig transcription = new PostTranscriptionConfig(true, summaryConfig, modelId);

meeting.startHls(config, transcription);
```

### `stopHls()`

- `stopHls()` is used to stop interactive livestream of the meeting which can be accessed from the `Meeting` class.

#### Example

**Kotlin:**

```js
// keep track of hls
val hls = false

findViewById<View>(R.id.btnHls).setOnClickListener { view: View? ->
  if (!hls) {
//highlight-start
val config = JSONObject()
val layout = JSONObject()
JsonUtils.jsonPut(layout, "type", "GRID")
JsonUtils.jsonPut(layout, "priority", "SPEAKER")
JsonUtils.jsonPut(layout, "gridSize", 4)
JsonUtils.jsonPut(config, "layout", layout)
JsonUtils.jsonPut(config, "theme", "DARK")
JsonUtils.jsonPut(config, "mode", "video-and-audio")
JsonUtils.jsonPut(config, "quality", "high")
JsonUtils.jsonPut(config, "orientation", "portrait")
//highlight-end

//highlight-next-line
// Post Transcription Configuration
val prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
val summaryConfig = SummaryConfig(true, prompt)
val modelId = "raman_v1"
val transcription = PostTranscriptionConfig(true, summaryConfig, modelId)

// Start Hls
//highlight-next-line
meeting!!.startHls(config)
  } else {
// Stop Hls
//highlight-next-line
meeting!!.stopHls()
  }
}
```

---

**Java:**

```js
// keep track of hls
boolean hls = false;

findViewById(R.id.btnHls).setOnClickListener(view -> {
  if (!hls) {
//highlight-start
JSONObject config = new JSONObject();
JSONObject layout = new JSONObject();
JsonUtils.jsonPut(layout, "type", "GRID");
JsonUtils.jsonPut(layout, "priority", "SPEAKER");
JsonUtils.jsonPut(layout, "gridSize", 4);
JsonUtils.jsonPut(config, "layout", layout);
JsonUtils.jsonPut(config, "theme", "DARK");
JsonUtils.jsonPut(config, "mode", "video-and-audio");
JsonUtils.jsonPut(config, "quality", "high");
JsonUtils.jsonPut(config, "orientation", "portrait");
//highlight-end

//highlight-next-line
// Post Transcription Configuration
String prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary";
SummaryConfig summaryConfig = new SummaryConfig(true, prompt);
String modelId = "raman_v1";
PostTranscriptionConfig transcription = new PostTranscriptionConfig(true, summaryConfig, modelId);

// Start Hls
//highlight-next-line
meeting.startHls(config);
  } else {
// Stop Hls
//highlight-next-line
meeting.stopHls();
  }
});
```

:::tip
If you want to learn more about the Interactive Livestream and how you can implement it in your own platform, you can checkout this [guide](/android/guide/interactive-live-streaming/integrate-hls/overview).
:::

### Event associated with HLS

- **onHlsStateChanged** - Whenever meeting HLS state changes, then `onHlsStateChanged` event will trigger.

- You can get the `playbackHlsUrl` and `livestreamUrl` of the HLS to play it on the Viewer side when the state changes to `HLS_PLAYABLE`.
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onHlsStateChanged(HlsState: JSONObject) {
when (HlsState.getString("status")) {
    "HLS_STARTING" -> Log.d("onHlsStateChanged", "Meeting hls is starting")
    "HLS_STARTED" -> Log.d("onHlsStateChanged", "Meeting hls is started")
    "HLS_PLAYABLE" -> {
        Log.d("onHlsStateChanged", "Meeting hls is playable now")
        //highlight-start
         // on hls playable you will receive playbackHlsUrl and livestreamUrl
        val playbackHlsUrl = HlsState.getString("playbackHlsUrl")
        val livestreamUrl = HlsState.getString("livestreamUrl")
        //highlight-end
    }
    "HLS_STOPPING" -> Log.d("onHlsStateChanged", "Meeting hls is stopping")
    "HLS_STOPPED" -> Log.d("onHlsStateChanged", "Meeting hls is stopped")
}
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onHlsStateChanged(JSONObject HlsState) {
  switch (HlsState.getString("status")) {
      case "HLS_STARTING":
          Log.d("onHlsStateChanged", "Meeting hls is starting");
          break;
      case "HLS_STARTED":
          Log.d("onHlsStateChanged", "Meeting hls is started");
          break;
      case "HLS_PLAYABLE":
          Log.d("onHlsStateChanged", "Meeting hls is playable now");
          //highlight-start
          // on hls started you will receive playbackHlsUrl and livestreamUrl
          String playbackHlsUrl = HlsState.getString("playbackHlsUrl");
          String livestreamUrl = HlsState.getString("livestreamUrl");
          //highlight-end
          break;
      case "HLS_STOPPING":
          Log.d("onHlsStateChanged", "Meeting hls is stopping");
          break;
      case "HLS_STOPPED":
          Log.d("onHlsStateChanged", "Meeting hls is stopped");
          break;
  }
  }
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting.addEventListener(meetingEventListener);
}
```

### API Reference

The API references for all the methods utilised in this guide are provided below.

- [startHls()](/android/api/sdk-reference/meeting-class/methods#starthls)
- [stopHls()](/android/api/sdk-reference/meeting-class/methods#stophls)
- [onHlsStateChanged](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onhlsstatechanged)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

# RTMP Livestream - Android

RTMP is a popular protocol for live streaming video content from a VideoSDK to platforms such as YouTube, Twitch, Facebook, and others.

By providing the platform-specific stream key and stream URL, the VideoSDK can connect to the platform's RTMP server and transmit the live video stream.

VideoSDK allows you to livestream your meeting to platform which support RTMP ingestion just by providing the platform-specific stream key and stream URL, we can connect to the platform's RTMP server and transmit the live video stream.

VideoSDK also allows you to configure the livestream layouts in numerous ways like by simply setting different prebuilt layouts in the configuration or by providing your own custom template to do the livestream according to your layout choice.

This guide will provide an overview of how to implement start and stop RTMP Livestreaming.

### `startLivestream()`

`startLivestream()` can be used to start a RTMP livestream of the meeting which can be accessed from the `Meeting` class. This method accepts two parameters:

- `1. outputs`: This parameter accepts a list of `LivestreamOutput` objects which contains the RTMP `url` and `streamKey` of the platforms you want to start the livestream.

- `2. config`: This parameter will define how the livestream layout should look like. You can pass `null` for default layout.



**Kotlin:**

```js
val config = JSONObject()

//highlight-next-line
// Layout Configuration
val layout = JSONObject()
JsonUtils.jsonPut(layout, "type", "GRID") // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
JsonUtils.jsonPut(layout, "priority", "SPEAKER") // "PIN", Default : "SPEAKER"
JsonUtils.jsonPut(layout, "gridSize", 4) // MAX : 4
JsonUtils.jsonPut(config, "layout", layout)

//highlight-next-line
// Theme of livestream layout
JsonUtils.jsonPut(config, "theme", "DARK") //  "LIGHT" | "DEFAULT"

val outputs: MutableList<LivestreamOutput> = ArrayList()
outputs.add(LivestreamOutput(RTMP_URL, RTMP_STREAM_KEY))

meeting!!.startLivestream(outputs,config)
```

---

**Java:**

```js
JSONObject config = new JSONObject();

//highlight-next-line
// Layout Configuration
JSONObject layout = new JSONObject();
JsonUtils.jsonPut(layout, "type", "GRID"); // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
JsonUtils.jsonPut(layout, "priority", "SPEAKER");  // "PIN", Default : "SPEAKER"
JsonUtils.jsonPut(layout, "gridSize", 4); // MAX : 4
JsonUtils.jsonPut(config, "layout", layout);

//highlight-next-line
// Theme of livestream layout
JsonUtils.jsonPut(config, "theme", "DARK"); //  "LIGHT" | "DEFAULT"

List<LivestreamOutput> outputs = new ArrayList<>();
outputs.add(new LivestreamOutput(RTMP_URL, RTMP_STREAM_KEY));

meeting.startLivestream(outputs,config);
```

### `stopLivestream()`

- `stopLivestream()` is used to stop the meeting livestream which can be accessed from the `Meeting` class.

#### Example

**Kotlin:**

```js
// keep track of livestream status
val liveStream = false

findViewById<View>(R.id.btnLiveStream).setOnClickListener { view: View? ->
  if (!liveStream) {
//highlight-start
val config = JSONObject()
val layout = JSONObject()
JsonUtils.jsonPut(layout, "type", "GRID")
JsonUtils.jsonPut(layout, "priority", "SPEAKER")
JsonUtils.jsonPut(layout, "gridSize", 4)
JsonUtils.jsonPut(config, "layout", layout)
JsonUtils.jsonPut(config, "theme", "DARK")
//highlight-end

val outputs: MutableList<LivestreamOutput> = ArrayList()
//highlight-next-line
outputs.add(LivestreamOutput(RTMP_URL, RTMP_STREAM_KEY))

// Start LiveStream
//highlight-next-line
meeting!!.startLivestream(outputs,config)
  } else {
// Stop LiveStream
//highlight-next-line
meeting!!.stopLivestream()
  }
}
```

---

**Java:**

```js
// keep track of livestream status
boolean liveStream = false;

findViewById(R.id.btnLiveStream).setOnClickListener(view -> {
  if (!liveStream) {
//highlight-start
JSONObject config = new JSONObject();
JSONObject layout = new JSONObject();
JsonUtils.jsonPut(layout, "type", "GRID");
JsonUtils.jsonPut(layout, "priority", "SPEAKER");
JsonUtils.jsonPut(layout, "gridSize", 4);
JsonUtils.jsonPut(config, "layout", layout);
JsonUtils.jsonPut(config, "theme", "DARK");
//highlight-end

List<LivestreamOutput> outputs = new ArrayList<>();
//highlight-next-line
outputs.add(new LivestreamOutput(RTMP_URL, RTMP_STREAM_KEY));

// Start LiveStream
//highlight-next-line
meeting.startLivestream(outputs,config);
  } else {
// Stop LiveStream
//highlight-next-line
meeting.stopLivestream();
  }
});
```

## Event associated with Livestream

- **onLivestreamStateChanged** - Whenever meeting livestream state changes, then `onLivestreamStateChanged` event will trigger.

**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onLivestreamStateChanged(livestreamState: String?) {
when (livestreamState) {
  "LIVESTREAM_STARTING" -> Log.d( "LivestreamStateChanged",
      "Meeting livestream is starting"
  )
  "LIVESTREAM_STARTED" -> Log.d( "LivestreamStateChanged",
      "Meeting livestream is started"
  )
  "LIVESTREAM_STOPPING" -> Log.d("LivestreamStateChanged",
      "Meeting livestream is stopping"
  )
  "LIVESTREAM_STOPPED" -> Log.d("LivestreamStateChanged",
      "Meeting livestream is stopped"
  )
}
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onLivestreamStateChanged(String livestreamState) {
switch (livestreamState) {
  case "LIVESTREAM_STARTING":
      Log.d("LivestreamStateChanged", "Meeting livestream is starting");
      break;
  case "LIVESTREAM_STARTED":
      Log.d("LivestreamStateChanged", "Meeting livestream is started");
      break;
  case "LIVESTREAM_STOPPING":
      Log.d("LivestreamStateChanged", "Meeting livestream is stopping");
      break;
  case "LIVESTREAM_STOPPED":
      Log.d("LivestreamStateChanged", "Meeting livestream is stopped");
      break;
}
  }
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting.addEventListener(meetingEventListener);
}
```

### API Reference

The API references for all the methods utilised in this guide are provided below.

- [startLivestream()](/android/api/sdk-reference/meeting-class/methods#startlivestream)
- [stopLivestream()](/android/api/sdk-reference/meeting-class/methods#stoplivestream)
- [onLivestreamStateChanged](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onlivestreamstatechanged)


---

# Quick Start for Http Live Streaming(HLS) in Android



VideoSDK empowers you to seamlessly integrate the Http Live Streaming(HLS) feature into your React Native application within minutes.

In this quickstart, you'll explore this feature of VideoSDK. Follow the step-by-step guide to integrate it within your application.

:::info

For low-latency interactive live streaming (under 100ms), follow this [documentation](./quick-start-android-ils.md).
:::

## Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

- Java Development Kit.
- Android Studio 3.0 or later.
- Android SDK API Level 21 or higher.
- A mobile device that runs Android 5.0 or later.

:::important

One should have a VideoSDK account to generate token.
Visit VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate token

:::

## Getting Started with the Code!

Follow the steps to create the environment necessary to add video calls into your app. Also you can find the code sample for [quickstart here](https://github.com/videosdk-live/quickstart/tree/main/android-hls).




### Create new Android Project

For a new project in **Android Studio**, create a **Phone and Tablet** Android project with an **Empty Activity**.

![VideoSDK Android Quick Start New Project](/img/quick-start/android_newProject.png)

:::caution
After creating the project, Android Studio automatically starts gradle sync. Ensure that the sync succeeds before you continue.
:::

### Integrate Video SDK



**Maven Central:**

```js title="settings.gradle"
dependencyResolutionManagement{
  repositories {
// ...
google()
mavenCentral()
maven { url "https://maven.aliyun.com/repository/jcenter" }
  }
}
```

---

**Jitpack:**

```js title="settings.gradle"
dependencyResolutionManagement{
  repositories {
// ...
google()
maven { url 'https://jitpack.io' }
mavenCentral()
maven { url "https://maven.aliyun.com/repository/jcenter" }
  }
}
```

- Add the following dependency in your app's `app/build.gradle`.

```js title="app/build.gradle"
dependencies {
  implementation 'live.videosdk:rtc-android-sdk:0.3.0'

  // library to perform Network call to generate a meeting id
  implementation 'com.amitshekhar.android:android-networking:1.0.2'

  // other app dependencies
  }
```

:::important

Android SDK compatible with armeabi-v7a, arm64-v8a, x86_64 architectures. If you want to run the application in an emulator, choose ABI x86_64 when creating a device.

:::

### Add permissions into your project

- In `/app/Manifests/AndroidManifest.xml`, add the following permissions after `</application>`.

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

:::note

If your project has set `android.useAndroidX=true`, then set `android.enableJetifier=true` in the `gradle.properties` file to migrate your project to AndroidX and avoid duplicate class conflict.

:::

### Structure of the project

Your project structure should look like this.

```jsx title="Project Structure"
   app
   ├── java
   │    ├── packagename
   │         ├── JoinActivity
   │         ├── MeetingActivity
   │         ├── SpeakerAdapter
   │         ├── SpeakerFragment
   |         ├── ViewerFragment
   ├── res
   │    ├── layout
   │    │    ├── activity_join.xml
   │    │    ├── activity_meeting.xml
   |    |    ├── fragment_speaker.xml
   |    |    ├── fragment_viewer.xml
   │    │    ├── item_remote_peer.xml
```

:::note

You have to set JoinActivity as Launcher activity.

:::

### App Architecture

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/android_ils_quickstart_app_structure.png' />

</center>


### Step 1: Creating Joining Screen


Create a new Activity named `JoinActivity`.

The Joining screen will include :

1. **Create Button** - This button will create a new meeting for you.
2. **TextField for Meeting Id** - This text field will contain the meeting Id you want to join.
3. **Join as Host Button** - This button will join the meeting as **host** with `meetingId` you provided.
4. **Join as Viewer Button** - This button will join the meeting as **viewer** with `meetingId` you provided.

In `/app/res/layout/activity_join.xml` file, replace the content with the following.

```xml title="activity_join.xml"
<?xml version="1.0" encoding="utf-8"?>



    

    

    

    

</LinearLayout>
```

**Integration of Create Meeting API**

1. Create field `sampleToken` in `JoinActivity` which will hold the generated token from the [VideoSDK dashboard](https://app.videosdk.live/api-keys). This token will use in VideoSDK config as well as in generating meetingId.

**Kotlin:**

```js title="JoinActivity.kt"
class JoinActivity : AppCompatActivity() {

  //highlight-next-line
  //Replace with the token you generated from the VideoSDK Dashboard
  private var sampleToken = ""

  override fun onCreate(savedInstanceState: Bundle?) {
//...
  }
}
```

---

**Java:**

```java title="JoinActivity.java"
public class JoinActivity extends AppCompatActivity {

  //highlight-next-line
  //Replace with the token you generated from the VideoSDK Dashboard
  private String sampleToken ="";

  @Override
  protected void onCreate(Bundle savedInstanceState) {
//...
  }
}
```

2. On **Join Button as Host** `onClick` events, we will naviagte to `MeetingActivity` with token, meetingId and mode as `SEND_AND_RECV`.

3. On **Join Button as Viewer** `onClick` events, we will naviagte to `MeetingActivity` with token, meetingId and mode as `Viewer`.

**Kotlin:**

```js title="JoinActivity.kt"
class JoinActivity : AppCompatActivity() {

   //Replace with the token you generated from the VideoSDK Dashboard
   private var sampleToken = "";

   override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  setContentView(R.layout.activity_join)

  val btnCreate = findViewById

</center>


### Step 2: Creating Meeting Screen


Create a new Activity named `MeetingActivity`.

In `/app/res/layout/activity_meeting.xml` file, replace the content with the following.

```xml title="activty_meeting.xml"
<?xml version="1.0" encoding="utf-8"?>


</RelativeLayout>
```

**The next step is to initialize a meeting, After getting token and meetigId from JoinActivity:**

1. Initialize **VideoSDK**.
2. Configure **VideoSDK** with token.
3. Initialize the meeting with required params such as `meetingId`, `participantName`, `micEnabled`, `webcamEnabled` , `mode` and more.
4. Join the room with `meeting.join()` method.
5. Add `MeetingEventListener` for listening **Meeting Join** event.
6. Check mode of `localParticipant`, If mode is **SEND_AND_RECV** than we will replace mainLayout with `SpeakerFragment` otherwise replace with `ViewerFragment`.

**Kotlin:**

```js title="MeetingActivity.kt"
class MeetingActivity : AppCompatActivity() {
  var meeting: Meeting? = null
  private set

  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_meeting)

val meetingId = intent.getStringExtra("meetingId")
val token = intent.getStringExtra("token")
val mode = intent.getStringExtra("mode")
val localParticipantName = "John Doe"
val streamEnable = mode == "SEND_AND_RECV"

//highlight-next-line
// initialize VideoSDK
VideoSDK.initialize(applicationContext)

//highlight-next-line
// Configuration VideoSDK with Token
VideoSDK.config(token)

//highlight-next-line
// Initialize VideoSDK Meeting
meeting = VideoSDK.initMeeting(
    this@MeetingActivity, meetingId, localParticipantName,
    streamEnable, streamEnable, null, mode, false, null, null
)

//highlight-next-line
// join Meeting
meeting!!.join()

//highlight-next-line
// if mode is SEND_AND_RECV than replace mainLayout with SpeakerFragment otherwise with ViewerFragment
meeting!!.addEventListener(object : MeetingEventListener() {
  override fun onMeetingJoined() {
      if (meeting != null) {
        if (mode == "SEND_AND_RECV") {
          //highlight-next-line
          //pin the local participant
          meeting!!.localParticipant.pin("SHARE_AND_CAM")
          supportFragmentManager
              .beginTransaction()
              .replace(R.id.mainLayout, SpeakerFragment(), "MainFragment")
              .commit()
          } else if (mode == "SIGNALLING_ONLY") {
            supportFragmentManager
                .beginTransaction()
                .replace(R.id.mainLayout, ViewerFragment(), "viewerFragment")
                .commit()
          }
      }
  }
})
  }
}
```

---

**Java:**

```java title="MeetingActivity.java"
public class MeetingActivity extends AppCompatActivity {
  private Meeting meeting;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_meeting);

final String meetingId = getIntent().getStringExtra("meetingId");
String token = getIntent().getStringExtra("token");
String mode = getIntent().getStringExtra("mode");
String localParticipantName = "John Doe";
boolean streamEnable = mode.equals("SEND_AND_RECV");

//highlight-next-line
// initialize VideoSDK
VideoSDK.initialize(getApplicationContext());

//highlight-next-line
// Configuration VideoSDK with Token
VideoSDK.config(token);

//highlight-next-line
// Initialize VideoSDK Meeting
meeting = VideoSDK.initMeeting(
        MeetingActivity.this, meetingId, localParticipantName,
        streamEnable, streamEnable, null, mode, false, null, null);

//highlight-next-line
// join Meeting
meeting.join();

//highlight-next-line
// if mode is SEND_AND_RECV than replace mainLayout with SpeakerFragment otherwise with ViewerFragment
meeting.addEventListener(new MeetingEventListener() {
    @Override
    public void onMeetingJoined() {
      if (meeting != null) {
        if (mode.equals("SEND_AND_RECV")) {
          //highlight-next-line
          //pin the local participant
          meeting.getLocalParticipant().pin("SHARE_AND_CAM");
          getSupportFragmentManager()
              .beginTransaction()
              .replace(R.id.mainLayout, new SpeakerFragment(), "MainFragment")
              .commit();
        } else if (mode.equals("SIGNALLING_ONLY")) {
          getSupportFragmentManager()
              .beginTransaction()
              .replace(R.id.mainLayout, new ViewerFragment(), "viewerFragment")
              .commit();
        }
      }
    }
  });
  }
  public Meeting getMeeting() {
  return meeting;
  }
}
```

#### Output

<center>

<img style={{height: '450px'}} src="https://cdn.videosdk.live/website-resources/docs-resources/android_ils_quickstart_meeting_screen.jpg" />

</center>




### Step 3: Implement SpeakerView


After successfully enter into the meeting, it's time to render speaker's view and manage controls such as toggle webcam/mic,start/stop HLS and leave the meeting.

1. Create a new fragment named `SpeakerFragment`.

2. In `/app/res/layout/fragment_speaker.xml` file, replace the content with the following.

```xml title="fragment_speaker.xml"
<?xml version="1.0" encoding="utf-8"?>


        

    </LinearLayout>

    

    <androidx.recyclerview.widget.RecyclerView
        android:id="@+id/rvParticipants"
        android:layout_width="match_parent"
        android:layout_height="0dp"
        android:layout_marginVertical="10sp"
        android:layout_weight="1" />

    

        

        

    </LinearLayout>

</LinearLayout>
```

3. Now, let's set listener for buttons which will allow the participant to toggle media.

**Kotlin:**

```js title="SpeakerFragment.kt"
class SpeakerFragment : Fragment() {
  private var micEnabled = true
  private var webcamEnabled = true
  private var hlsEnabled = false
  private var btnMic: Button? = null
  private var btnWebcam: Button? = null
  private var btnHls: Button? = null
  private var btnLeave: Button? = null
  private var tvMeetingId: TextView? = null
  private var tvHlsState: TextView? = null
  override fun onAttach(context: Context) {
super.onAttach(context)
mContext = context
if (context is Activity) {
  mActivity = context
  //highlight-next-line
  // getting meeting object from Meeting Activity
  meeting = (mActivity as MeetingActivity?)!!.meeting
}
  }

  override fun onCreateView(
  inflater: LayoutInflater, container: ViewGroup?,
  savedInstanceState: Bundle?
  ): View? {
// Inflate the layout for this fragment
val view = inflater.inflate(R.layout.fragment_speaker, container, false)
btnMic = view.findViewById(R.id.btnMic)
btnWebcam = view.findViewById(R.id.btnWebcam)
btnHls = view.findViewById(R.id.btnHLS)
btnLeave = view.findViewById(R.id.btnLeave)
tvMeetingId = view.findViewById(R.id.tvMeetingId)
tvHlsState = view.findViewById(R.id.tvHlsState)
if (meeting != null) {
  tvMeetingId!!.text = "Meeting Id : " + meeting!!.meetingId
  //highlight-next-line
  setActionListeners()
}
return view
  }

  private fun setActionListeners() {
btnMic!!.setOnClickListener {
  if (micEnabled) {
    //highlight-next-line
    meeting!!.muteMic()
    Toast.makeText(mContext, "Mic Muted", Toast.LENGTH_SHORT).show()
  } else {
    //highlight-next-line
    meeting!!.unmuteMic()
    Toast.makeText(
        mContext,
        "Mic Enabled",
        Toast.LENGTH_SHORT
    ).show()
  }
  micEnabled = !micEnabled
}
btnWebcam!!.setOnClickListener {
  if (webcamEnabled) {
    //highlight-next-line
    meeting!!.disableWebcam()
    Toast.makeText(
        mContext,
        "Webcam Disabled",
        Toast.LENGTH_SHORT
    ).show()
  } else {
    //highlight-next-line
    meeting!!.enableWebcam()
    Toast.makeText(
        mContext,
        "Webcam Enabled",
        Toast.LENGTH_SHORT
    ).show()
  }
  webcamEnabled = !webcamEnabled
}
//highlight-next-line
btnLeave!!.setOnClickListener { meeting!!.leave() }
btnHls!!.setOnClickListener {
  if (!hlsEnabled) {
    //highlight-start
    val config = JSONObject()
    val layout = JSONObject()
    JsonUtils.jsonPut(layout, "type", "SPOTLIGHT")
    JsonUtils.jsonPut(layout, "priority", "PIN")
    JsonUtils.jsonPut(layout, "gridSize", 4)
    JsonUtils.jsonPut(config, "layout", layout)
    JsonUtils.jsonPut(config, "orientation", "portrait")
    JsonUtils.jsonPut(config, "theme", "DARK")
    JsonUtils.jsonPut(config, "quality", "high")
    meeting!!.startHls(config)
    //highlight-end
  } else {
    //highlight-next-line
    meeting!!.stopHls()
  }
}
  }

  companion object {
private var mActivity: Activity? = null
private var mContext: Context? = null
private var meeting: Meeting? = null
  }
}
```

---

**Java:**

```java title="SpeakerFragment.java"
public class SpeakerFragment extends Fragment {

  private static Activity mActivity;
  private static Context mContext;
  private static Meeting meeting;
  private boolean micEnabled = true;
  private boolean webcamEnabled = true;
  private boolean hlsEnabled = false;
  private Button btnMic, btnWebcam, btnHls, btnLeave;
  private TextView tvMeetingId, tvHlsState;

  public SpeakerFragment() {
// Required empty public constructor
  }

  @Override
  public void onAttach(@NonNull Context context) {
super.onAttach(context);
mContext = context;
if (context instanceof Activity) {
  mActivity = (Activity) context;
  //highlight-next-line
  // getting meeting object from Meeting Activity
  meeting = ((MeetingActivity) mActivity).getMeeting();
}
  }

  @Override
  public View onCreateView(LayoutInflater inflater, ViewGroup container,
                        Bundle savedInstanceState) {
// Inflate the layout for this fragment
View view = inflater.inflate(R.layout.fragment_speaker, container, false);
btnMic = view.findViewById(R.id.btnMic);
btnWebcam = view.findViewById(R.id.btnWebcam);
btnHls = view.findViewById(R.id.btnHLS);
btnLeave = view.findViewById(R.id.btnLeave);

tvMeetingId = view.findViewById(R.id.tvMeetingId);
tvHlsState = view.findViewById(R.id.tvHlsState);

if (meeting != null) {
    tvMeetingId.setText("Meeting Id : " + meeting.getMeetingId());
    //highlight-next-line
    setActionListeners();
}
return view;
  }

  private void setActionListeners() {
btnMic.setOnClickListener(v -> {
    if (micEnabled) {
      //highlight-next-line
      meeting.muteMic();
      Toast.makeText(mContext,"Mic Muted",Toast.LENGTH_SHORT).show();
    } else {
      //highlight-next-line
      meeting.unmuteMic();
      Toast.makeText(mContext,"Mic Enabled",Toast.LENGTH_SHORT).show();
    }
    micEnabled=!micEnabled;
});

btnWebcam.setOnClickListener(v -> {
    if (webcamEnabled) {
      //highlight-next-line
      meeting.disableWebcam();
      Toast.makeText(mContext,"Webcam Disabled",Toast.LENGTH_SHORT).show();
    } else {
      //highlight-next-line
      meeting.enableWebcam();
      Toast.makeText(mContext,"Webcam Enabled",Toast.LENGTH_SHORT).show();
    }
    webcamEnabled=!webcamEnabled;
});

//highlight-next-line
btnLeave.setOnClickListener(v -> meeting.leave());

btnHls.setOnClickListener(v -> {
  if (!hlsEnabled) {
    //highlight-start
    JSONObject config = new JSONObject();
    JSONObject layout = new JSONObject();
    JsonUtils.jsonPut(layout, "type", "SPOTLIGHT");
    JsonUtils.jsonPut(layout, "priority", "PIN");
    JsonUtils.jsonPut(layout, "gridSize", 4);
    JsonUtils.jsonPut(config, "layout", layout);
    JsonUtils.jsonPut(config, "orientation", "portrait");
    JsonUtils.jsonPut(config, "theme", "DARK");
    JsonUtils.jsonPut(config, "quality", "high");
    meeting.startHls(config);
    //highlight-end
  } else {
    //highlight-next-line
    meeting.stopHls();
  }
});
  }
}
```

4. After adding listners for buttons, let's add `MeetingEventListener` to the meeting and remove all listners in `onDestroy()` method.

**Kotlin:**

```js title="SpeakerFragment.kt"
class SpeakerFragment : Fragment() {

  override fun onCreateView(
  inflater: LayoutInflater, container: ViewGroup?,
  savedInstanceState: Bundle?
  ): View? {
//...
if (meeting != null) {
  //...
  //highlight-next-line
  // add Listener to the meeting
  meeting!!.addEventListener(meetingEventListener)
}
return view
  }

  private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onMeetingLeft() {
    //highlight-next-line
    // unpin the local participant
    meeting!!.localParticipant.unpin("SHARE_AND_CAM")
    if (isAdded) {
      val intents = Intent(mContext, JoinActivity::class.java)
      intents.addFlags(
          Intent.FLAG_ACTIVITY_NEW_TASK
                  or Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_CLEAR_TASK
      )
      startActivity(intents)
      mActivity!!.finish()
    }
  }

  @RequiresApi(api = Build.VERSION_CODES.P)
  override fun onHlsStateChanged(HlsState: JSONObject) {
    if (HlsState.has("status")) {
      try {
          tvHlsState!!.text = "Current HLS State : " + HlsState.getString("status")
          //highlight-next-line
          if (HlsState.getString("status") == "HLS_STARTED") {
            hlsEnabled = true
            btnHls!!.text = "Stop HLS"
          }
          //highlight-next-line
          if (HlsState.getString("status") == "HLS_STOPPED") {
            hlsEnabled = false
            btnHls!!.text = "Start HLS"
          }
        } catch (e: JSONException) {
            e.printStackTrace()
        }
    }
  }
  }

  override fun onDestroy() {
  mContext = null
  mActivity = null
  if (meeting != null) {
      meeting!!.removeAllListeners()
      meeting = null
  }
  super.onDestroy()
  }
}
```

---

**Java:**

```java title="SpeakerFragment.java"
public class SpeakerFragment extends Fragment {

  @Override
  public View onCreateView(LayoutInflater inflater, ViewGroup container,
                        Bundle savedInstanceState) {
//...
if (meeting != null) {
    //...
    //highlight-next-line
    // add Listener to the meeting
    meeting.addEventListener(meetingEventListener);
}
return view;
  }

  private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
@Override
public void onMeetingLeft() {
  //highlight-next-line
  //unpin local participant
  meeting.getLocalParticipant().unpin("SHARE_AND_CAM");
  if (isAdded()) {
    Intent intents = new Intent(mContext, JoinActivity.class);
    intents.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK
            | Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_CLEAR_TASK);
    startActivity(intents);
    mActivity.finish();
  }
}

@RequiresApi(api = Build.VERSION_CODES.P)
@Override
public void onHlsStateChanged(JSONObject HlsState) {
    if (HlsState.has("status")) {
      try {
        tvHlsState.setText("Current HLS State : " + HlsState.getString("status"));
        //highlight-next-line
        if (HlsState.getString("status").equals("HLS_STARTED")) {
            hlsEnabled=true;
            btnHls.setText("Stop HLS");
        }
        //highlight-next-line
        if (HlsState.getString("status").equals("HLS_STOPPED")) {
            hlsEnabled = false;
            btnHls.setText("Start HLS");
        }
      } catch (JSONException e) {
          e.printStackTrace();
      }
    }
}
  };

  @Override
  public void onDestroy() {
mContext = null;
mActivity = null;
if (meeting != null) {
    meeting.removeAllListeners();
    meeting = null;
}
super.onDestroy();
  }

}
```

5. Next step is to render speaker's view. With `RecyclerView`, we will be display list of participant who joined the meeting as a `host`.

:::info

- Here the participant's video is displayed using `VideoView`, but you may also use `SurfaceViewRender` for the same.
- For `VideoView`, SDK version should be `0.1.13` or higher.
- To know more about `VideoView`, please visit [here](/android/guide/video-and-audio-calling-api-sdk/render-media/display-video/understand-videoView-component)

:::

- Create a new layout for the participant view named `item_remote_peer.xml` in the `res/layout` folder.

```xml title="item_remote_peer.xml"
<?xml version="1.0" encoding="utf-8"?>


    

    </LinearLayout>

</FrameLayout>
```

- Create a recycler view adapter named `SpeakerAdapter` which will show the participant list. Create `PeerViewHolder` in the adapter which will extend `RecyclerView.ViewHolder`.

**Kotlin:**

```js title="SpeakerAdapter.kt"
class SpeakerAdapter(private val meeting: Meeting) :
RecyclerView.Adapter

</center>






### Step 4: Implement ViewerView


When host start the live streaming, viewer will be able to see the live streaming.

To implement player view, we are going to use `ExoPlayer`. It will be helpful to play hls stream.

Let's first add dependency into the project.

```js title="app/build.gradle"
dependencies {
  implementation 'com.google.android.exoplayer:exoplayer:2.18.5'
  // other app dependencies
  }
```

Create a new Fragment named `ViewerFragment`

The Viewer Fragment will include :

1. **TextView for Meeting Id** - The meeting Id that you joined will be displayed in this text view.
2. **Leave Button** - This button will leave the meeting.
3. **waitingLayout** - This is textView that will be shown when there is no active HLS.
4. **StyledPlayerView** - This is mediaplayer which will display livestreaming.

In `/app/res/layout/fragment_viewer.xml` file, replace the content with the following.

```xml title="fragment_viewer.xml"
<?xml version="1.0" encoding="utf-8"?>


        

    </LinearLayout>

    

    <com.google.android.exoplayer2.ui.StyledPlayerView
        android:id="@+id/player_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:visibility="gone"
        app:resize_mode="fixed_width"
        app:show_buffering="when_playing"
        app:show_subtitle_button="false"
        app:use_artwork="false"
        app:show_next_button="false"
        app:show_previous_button="false"
        app:use_controller="true"
        android:layout_below="@id/meetingLayout"/>

</RelativeLayout>
```

**Initialize player and Playing HLS stream**

1. Initialize player and play the HLS when the meeting HLS state is `HLS_PLAYABLE`, and release it when the HLS state is `HLS_STOPPED`. Whenever the meeting HLS state changes, the event `onHlsStateChanged` will be triggered.

- when you receive `HLS_PLAYABLE` status you will receive 2 urls
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

**Kotlin:**

```js title="ViewerFragment.kt"
class ViewerFragment : Fragment() {
  private var meeting: Meeting? = null
  private var playerView: StyledPlayerView? = null
  private var waitingLayout: TextView? = null
  private var player: ExoPlayer? = null
  private var dataSourceFactory: DefaultHttpDataSource.Factory? = null
  private val startAutoPlay = true
  private var playbackHlsUrl: String? = ""


  override fun onCreateView(
inflater: LayoutInflater, container: ViewGroup?,
savedInstanceState: Bundle?
  ): View? {
// Inflate the layout for this fragment
val view = inflater.inflate(R.layout.fragment_viewer, container, false)
playerView = view.findViewById(R.id.player_view)
waitingLayout = view.findViewById(R.id.waitingLayout)
if (meeting != null) {
    //highlight-next-line
    // set MeetingId to TextView
    (view.findViewById

<img style={{height: '450px'}} src="https://cdn.videosdk.live/website-resources/docs-resources/android_ils_quickstart_viewer_screen.jpg" />

</center>

<br/>



## Final Output

We are done with implementation of customised video calling app in Android using Video SDK. To explore more features go through Basic and Advanced features.


<div style={{textAlign: 'center'}}>



</div>

<br/>

:::tip
You can checkout the complete [quick start example here](https://github.com/videosdk-live/quickstart/tree/main/android-hls).
:::


---

# Quick Start for Interactive Live Streaming in Android

**VideoSDK** empowers you to seamlessly integrate **interactive live streaming** features into your Android application in minutes. While built for meetings, the SDK is easily adaptable for live streaming with support for up to **100 hosts/co-hosts** and **2,000 viewers** in **real-time**. Perfect for social use cases, this guide will walk you through integrating live streaming into your app.

:::info

For standard live streaming with 6-7 second latency and playback support, follow this [documentation](./quick-start-ILS.md).
:::

## Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

- Android Studio Arctic Fox (2020.3.1) or later.
- Android SDK API Level 21 or higher.
- A mobile device that runs Android 5.0 or later.

## Getting Started with the Code!

Follow the steps to create the environment necessary to add video calls into your app. Also you can find the code sample for [quickstart here](https://github.com/videosdk-live/quickstart/tree/main/interactive-live-streaming/android-ils).



### Create new Android Project

For a new project in **Android Studio**, create a **Phone and Tablet** Android project with an **Empty Activity**.

![VideoSDK Android Quick Start New Project](https://cdn.videosdk.live/docs/images/android/quickstart/android_compose_newProject.jpg)

:::caution
After creating the project, Android Studio automatically starts gradle sync. Ensure that the sync succeeds before you continue.
:::

### Integrate Video SDK



**Maven Central:**

```js title="settings.gradle"
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven {url= uri("https://maven.aliyun.com/repository/jcenter")}
  }
}
```

---

**Jitpack:**

```js title="settings.gradle"
dependencyResolutionManagement{
  repositories {
google()
maven { url = uri("https://www.jitpack.io") }
mavenCentral()
maven {url= uri("https://maven.aliyun.com/repository/jcenter")}
  }
}
```

- Add the following dependency in your app's `app/build.gradle`.

```js title="app/build.gradle"
dependencies {
  implementation ("live.videosdk:rtc-android-sdk:0.3.0")

  // library to perform Network call to generate a stream id
  implementation ("com.amitshekhar.android:android-networking:1.0.2")

  // other app dependencies
  }
```

:::important

Android SDK compatible with armeabi-v7a, arm64-v8a, x86_64 architectures. If you want to run the application in an emulator, choose ABI x86_64 when creating a device.

:::

### Add permissions into your project

- In `/app/Manifests/AndroidManifest.xml`, add the following permissions.

```xml title="AndroidManifest.xml"
<uses-feature android:name="android.hardware.camera" android:required="false" />
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.permission.RECORD_AUDIO"/>
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>
```

:::note

If your project has set `android.useAndroidX=true`, then set `android.enableJetifier=true` in the `gradle.properties` file to migrate your project to AndroidX and avoid duplicate class conflict.

:::

### Structure of the project

Your project structure should look like this.

```jsx title="Project Structure"
app/
├── src/main/
│   ├── java/com/example/app/
│   │   ├── components/
│   │   ├── screens/
│   │   ├── ui/
│   │   │   └── theme/
│   │   ├── model/
│   │   ├── MainApplication.kt
│   │   ├── MainActivity.kt
│   │   └── NetworkClass.kt
|   |   └── StreamingMode.kt
│   ├── res/
│   └── AndroidManifest.xml
├── build.gradle
└── settings.gradle
```

### App Architecture

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ils_qs_android_app_ architecture.png' />

</center>

### Step 1: Initialize VideoSDK


1. Create `MainApplication` class which will extend the `android.app.Application`.

- Create field `sampleToken` in `MainApplication` which will hold the generated token from the [VideoSDK dashboard](https://app.videosdk.live/api-keys). This token will use in VideoSDK config as well as generating meetingId.

```js title="MainApplication.kt"
import android.app.Application
import live.videosdk.rtc.android.VideoSDK

class MainApplication: Application() {

    val sampleToken = "YOUR_TOKEN" //paste your token here

    override fun onCreate() {
        super.onCreate()
        VideoSDK.initialize(applicationContext)
    }
}
```

2. Add `MainApplication` to `AndroidManifest.xml`

```xml title="AndroidManifest.xml"
<application
    android:name=".MainApplication"
   
</application>
```


### Step 2: Managing Permissions and Setting Up Navigation


The `MainActivity` handles permission requests for the camera and microphone and sets up navigation using Jetpack Compose.

Upon creation, it checks for required permissions (RECORD_AUDIO and CAMERA). If not granted, it requests them. Once permissions are granted, the MyApp composable is initialized, which contains the navigation logic through the NavigationGraph.

The NavigationGraph defines two screens:

- JoinScreen: For joining or create stream.
- StreamingScreen: For participating in a stream, passing meetingId and mode as arguments.

```js title="MainActivity.kt"
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        checkSelfPermission(REQUESTED_PERMISSIONS[0], PERMISSION_REQ_ID)
        checkSelfPermission(REQUESTED_PERMISSIONS[1], PERMISSION_REQ_ID)

        setContent {
            Videosdk_android_modes_quickstartTheme {
                MyApp(this) } }
    }

    private fun checkSelfPermission(permission: String, requestCode: Int): Boolean {
        if (ContextCompat.checkSelfPermission(this, permission) != PackageManager.PERMISSION_GRANTED) {
            ActivityCompat.requestPermissions(this, REQUESTED_PERMISSIONS, requestCode)
            return false
        }
        return true
    }

    companion object {
        private const val PERMISSION_REQ_ID = 22
        private val REQUESTED_PERMISSIONS = arrayOf(Manifest.permission.RECORD_AUDIO, Manifest.permission.CAMERA)
    }
}

@Composable
fun MyApp(context: Context) {
    NavigationGraph(context = context)
}

@Composable
fun NavigationGraph(navController: NavHostController = rememberNavController(), context: Context) {
    NavHost(navController = navController, startDestination = "join_screen") {
        composable("join_screen") { JoinScreen(navController, context) }
        composable("stream_screen?streamId={streamId}&mode={mode}") { backStackEntry ->
            val streamId = backStackEntry.arguments?.getString("streamId")
            val modeStr = backStackEntry.arguments?.getString("mode")
            val mode = StreamingMode.valueOf(modeStr ?: StreamingMode.SendAndReceive.name)

            streamId?.let {
                StreamingScreen(viewModel = StreamViewModel(), navController, streamId, mode, context)
            }
        }
    }
}
```


### Step 3: Creating Reusable Components


- Before building the individual screens, it's essential to develop reusable composable components that will be used throughout the project.

1. Create a `ReusableComponents.kt` file to organize all reusable components for the project, such as buttons, spacers, and customizable text.

```js title="ReusableComponents.kt"
@Composable
fun MyAppButton(task: () -> Unit, buttonName: String) {
    Button(onClick = task) {
        Text(text = buttonName) }
}

@Composable
fun MySpacer() {
    Spacer(modifier = Modifier.fillMaxWidth()
            .height(1.dp)
            .background(color = Color.Gray)) }

@Composable
fun MyText(text: String, fontSize: TextUnit = 23.sp) {
    Text(text = text,
        fontSize = fontSize,
        fontWeight = FontWeight.Normal,
        modifier = Modifier.padding(4.dp),
        style = MaterialTheme.typography.bodyMedium.copy(fontSize = 16.sp),
        color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.7f))
}
```

2. Create a `ParticipantVideoView.kt` file that includes two composable functions: `ParticipantVideoView` for rendering individual participant video streams, and `ParticipantsGrid` for displaying a grid of participant videos.

:::info

- Here the participant's video is displayed using `VideoView`. To know more about `VideoView`, please visit [here](/android/guide/video-and-audio-calling-api-sdk/render-media/display-video/understand-videoView-component)
- `VideoView` is a custom View. Since Jetpack Compose does not natively support traditional `View` objects, we need to integrate the `VideoView` into the Compose layout using the `AndroidView` wrapper.
- `AndroidView()` is a composable that can be used to add Android views inside a @Composable function.

:::

```js title="ParticipantVideoView.kt"
@Composable
fun ParticipantVideoView(
    participant: Participant
) {
        var isVideoEnabled by remember { mutableStateOf(false) }
        // Remember the event listener to prevent recreation on each recomposition
        val eventListener = remember(participant) {
            object : ParticipantEventListener() {
                override fun onStreamEnabled(stream: Stream) {
                    if (stream.kind.equals("video", ignoreCase = true)) {
                        val videoTrack = stream.track as VideoTrack
                        isVideoEnabled = true
                    }
                }
                override fun onStreamDisabled(stream: Stream) {
                    if (stream.kind.equals("video", ignoreCase = true)) {
                        isVideoEnabled = false
                    }
                }
            }
        }

        // Add and remove the event listener using side effects
        DisposableEffect(participant, eventListener) {
            participant.addEventListener(eventListener)
            onDispose { participant.removeEventListener(eventListener) }
        }

        // Initial video state check
        LaunchedEffect(participant) {
            val hasVideoStream = participant.streams.any { (_, stream) ->
                stream.kind.equals("video", ignoreCase = true) && stream.track != null
            }
            isVideoEnabled = hasVideoStream
        }

        Box(
            modifier = Modifier.fillMaxWidth()
                .height(200.dp)
                .background(if (isVideoEnabled) Color.DarkGray else Color.Gray)
        ) {
            AndroidView(
                factory = { context ->
                    VideoView(context).apply {
                        for ((_, stream) in participant.streams) {
                            if (stream.kind.equals("video", ignoreCase = true)) {
                                val videoTrack = stream.track as VideoTrack
                                addTrack(videoTrack)
                                isVideoEnabled = true
                            }
                        }
                    }
                },
                update = { videoView ->
                    // Handle video track updates only
                    // The event listener is now managed separately
                    for ((_, stream) in participant.streams) {
                        if (stream.kind.equals(
                                "video",
                                ignoreCase = true
                            ) && stream.track != null
                        ) {
                            val videoTrack = stream.track as VideoTrack
                            videoView.addTrack(videoTrack)
                        }
                    }
                },
                modifier = Modifier.fillMaxSize()
            )

            if (!isVideoEnabled) {
                Box(
                    modifier = Modifier.fillMaxSize()
                        .background(Color.DarkGray),
                    contentAlignment = Alignment.Center
                ) {
                    Text(text = "Camera Off", color = Color.White)
                }
            }

            Box(
                modifier = Modifier.align(Alignment.BottomCenter)
                    .fillMaxWidth()
                    .background(Color(0x99000000))
                    .padding(4.dp)
            ) {
                Text(
                    text = participant.displayName,
                    color = Color.White,
                    modifier = Modifier.align(Alignment.Center)
                )
            }
        }
}

@Composable
fun ParticipantsGrid(
    participants: List
</div>

1. SEND_AND_RECV:

- Designed primarily for the Host or Co-host.
- Allows sending and receiving media.
- Hosts can broadcast their audio/video and interact directly with the audience.

2. RECV_ONLY:

- Tailored for the Audience.
- Enables receiving media shared by the Host.
- Audience members can view and listen but cannot share their own media.

```js title="StreamingMode"
enum class StreamingMode {
    SendAndReceive,
    ReceiveOnly
}
```


### Step 4: Creating Joining Screen


Join screen will serve as a medium to either Create a new Live Stream or join an existing one as a host or a audience.

We will create a simple UI for the Join screen that includes three action buttons for joining or creating a Live Stream:

1. **`Create Stream`**: Lets the user initiate a new Live Stream in SEND_AND_RECV mode, granting full host controls.
2. **`Join as Host`**: Allows the user to join an existing Live Stream using the provided meetingId with the SEND_AND_RECV mode, enabling full host privileges.
3. **`Join as Audience`**: Enables the user to join an existing Live Stream using the provided meetingId with the RECV_ONLY mode, allowing view-only access.

```js title="JoinScreen.kt"
@Composable
fun JoinScreen(
    navController: NavController, context: Context
) {
    val app = context.applicationContext as MainApplication
    val token = app.sampleToken
    Box(
        modifier = Modifier.fillMaxSize()
            .padding(8.dp),
        contentAlignment = Alignment.Center
    ) {
        Column(
            modifier = Modifier.padding(4.dp),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.SpaceEvenly
        ) {
            var input by rememberSaveable { mutableStateOf("") }
            CreateStreamBtn(navController, token)
            Text(text = "OR")
            InputMeetingId(input) { updateInput -> input = updateInput }
            JoinHostBtn(navController, input)
            JoinAudienceBtn(navController, input)
        }
    }
}


@Composable
fun JoinHostBtn(navController: NavController, streamId: String) {
    MyAppButton({
        if (streamId.isNotEmpty()) {
            navController.navigate("stream_screen?streamId=$streamId&mode=${StreamingMode.SendAndReceive.name}")
        }
    }, "Join as Host")
}

@Composable
fun JoinAudienceBtn(navController: NavController, streamId: String) {
    MyAppButton({
        if (streamId.isNotEmpty()) {
            navController.navigate("stream_screen?streamId=$streamId&mode=${StreamingMode.ReceiveOnly.name}")
        }
    }, "Join as Audience")
}

@Composable
fun CreateStreamBtn(navController: NavController, token: String) {
    MyAppButton({
        NetworkManager.createStreamId(token) { streamId ->
            navController.navigate("stream_screen?streamId=$streamId&mode=${StreamingMode.SendAndReceive.name}")
        }
    }, "Create Stream")
}

@Composable
fun InputMeetingId(input: String, onInputChange: (String) -> Unit) {
    OutlinedTextField(value = input,
        onValueChange = onInputChange,
        label = { Text(text = "Enter Stream Id") })
}
```

#### Output

<div style={{ textAlign: 'center' }}>
    <img 
        src='https://cdn.videosdk.live/website-resources/docs-resources/ils_qs_android_join_screen.png' 
        alt="VideoSDK Android Quick Start joining Screen" 
         style={{height: '450px'}}
    />
</div>


### Step 5: Creating StreamId


The `NetworkManager` singleton handles stream creation by making a POST request to the [VideoSDK API](https://docs.videosdk.live/api-reference/realtime-communication/create-room):

- stream Creation: Sends a request to the API with an authorization token to create a stream.
- Response Handling: Extracts the roomId from the response and triggers the `onMeetingCreated` callback.

```js title="NetworkManager"
object NetworkManager {
    fun createStreamId(token: String, onStreamIdCreated: (String) -> Unit) {
        AndroidNetworking.post("https://dev-api.videosdk.live/v2/rooms")
            .addHeaders("Authorization", token)
            .build()
            .getAsJSONObject(object : JSONObjectRequestListener {
                override fun onResponse(response: JSONObject) {
                    try {
                        val streamId = response.getString("roomId")
                        onStreamIdCreated(streamId)
                    } catch (e: JSONException) {
                        e.printStackTrace()
                    }
                }
                override fun onError(anError: ANError) {
                    anError.printStackTrace()
                    Log.d("TAG", "onError: $anError")
                }
            })
    }
}
```

:::note

Don't confuse with Room and stream keyword, both are same thing 😃

:::


### Step 6: Creating Streaming Screen


We will create a simple Streaming screen UI with two main sections:

1. `Header`: Displays the stream ID and current streaming mode at the top of the screen for reference.
2. `ParticipantsGrid`: Shows the list of participants in a grid layout, adjusting dynamically.

:::note

In Step 3, we created the ParticipantsGrid component.

:::

```js title="StreamingScreen.kt"
@Composable
fun StreamingScreen(viewModel: StreamViewModel, navController: NavController,
    streamId: String,
    mode: StreamingMode,
    context: Context
) {
    val app = context.applicationContext as MainApplication
    val isStreamLeft = viewModel.isStreamLeft
    val currentMode = viewModel.currentMode
    val isJoined = viewModel.isJoined

    LaunchedEffect(isStreamLeft) {
        if (isStreamLeft) {
            navController.navigate("join_screen") }
    }

    Column(modifier = Modifier.fillMaxSize()) {
        Header(streamId, currentMode)
        MySpacer()
        ParticipantsGrid(
            participants = viewModel.currentParticipants,
            modifier = Modifier.weight(1f)
        )
        MySpacer()
        MediaControlButtons(
            onJoinClick = { viewModel.initStream(context, app.sampleToken, streamId, mode)},
            onMicClick = { viewModel.toggleMic() },
            onCamClick = { viewModel.toggleWebcam()},
            onModeToggleClick = { viewModel.toggleMode() },
            showMediaControls = currentMode == StreamingMode.SendAndReceive,
            currentMode = currentMode,
            onLeaveClick = { viewModel.leaveStream() },
            isJoined = isJoined )
    }
}
@Composable
fun Header(streamId: String, mode: StreamingMode) {
    val context = LocalContext.current
    val clipboardManager = context.getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager

    Box(modifier = Modifier.fillMaxWidth()
                        .padding(8.dp),
        contentAlignment = Alignment.TopStart
    ) {
        Row( modifier = Modifier.fillMaxWidth(),
            horizontalArrangement = Arrangement.SpaceBetween,
            verticalAlignment = Alignment.CenterVertically
        ) {
            Column {
                Row(verticalAlignment = Alignment.CenterVertically) {
                    MyText("StreamID: ", 28.sp)
                    MyText(streamId, 25.sp)
                    IconButton( onClick = {
                            val clip = ClipData.newPlainText("Stream ID", streamId)
                            clipboardManager.setPrimaryClip(clip)
                        })
                    {
                        //get baseline_content_copy_24 icon from Vector Asset
                        Icon( painter = painterResource(R.drawable.baseline_content_copy_24),
                            contentDescription = "Copy Stream ID",
                            modifier = Modifier.size(40.dp).padding(start = 8.dp)
                        )
                    }
                }
                Row {
                    MyText("Mode: ", 20.sp)
                    MyText(mode.name, 18.sp)
                }
            }
        }
    }
}
//...
```


### Step 7: Implementing Mode Switch and Media Toggles


Implement interactive controls to leave the stream, toggle microphone and webcam, and switch between Host (SEND_AND_RECV) and Audience (RECV_ONLY) modes for a seamless experience.

```js title="StreamingScreen.kt"
@Composable
fun MediaControlButtons(
    onJoinClick: () -> Unit,
    onMicClick: () -> Unit,
    onCamClick: () -> Unit,
    onModeToggleClick: () -> Unit,
    onLeaveClick: () -> Unit,
    showMediaControls: Boolean = true,
    currentMode: StreamingMode,
    isJoined: Boolean
) {
    Column( modifier = Modifier.fillMaxWidth()
                        .padding(6.dp),
        horizontalAlignment = Alignment.CenterHorizontally,
        verticalArrangement = Arrangement.spacedBy(8.dp)
    ) {
        Row( modifier = Modifier.fillMaxWidth(),
            horizontalArrangement = Arrangement.SpaceEvenly,
            verticalAlignment = Alignment.CenterVertically
        ) {
            if (!isJoined) {
                MyAppButton(onJoinClick, "Join")
            }
            if (showMediaControls && isJoined) {  // Only show media controls if joined
                MyAppButton(onMicClick, "ToggleMic")
                MyAppButton(onCamClick, "ToggleCam")
            }
        }

        Row( modifier = Modifier.fillMaxWidth(),
            horizontalArrangement = Arrangement.SpaceEvenly,
            verticalAlignment = Alignment.CenterVertically
        ) {
            if (isJoined) {
                MyAppButton(onLeaveClick, "Leave")
                MyAppButton(
                    task = onModeToggleClick,
                    buttonName = if (currentMode == StreamingMode.SendAndReceive)
                        "Switch to Audience"
                    else
                        "Switch to Host"
                )
            }
        }
    }
}
```


### Step 8: Setting Up StreamViewModel


The `StreamViewModel` manages the core functionality of Interactive Live Streaming (ILS), serving as the central state manager:

1. **Stream State Management**

   - Handles stream initialization with appropriate mode (Conference/Audience)
   - Tracks stream lifecycle (joined, left, current mode)

2. **Media Control Integration**

   - Provides microphone toggle (mute/unmute)
   - Controls webcam state (enable/disable)

3. **Mode Switching**
   - Enables seamless transitions between Conference and Audience modes

```js title="StreamViewModel"
class StreamViewModel : ViewModel() {
    private var stream: Meeting? = null
    private var micEnabled by mutableStateOf(true)
    private var webcamEnabled by mutableStateOf(true)
    var isConferenceMode by mutableStateOf(true)
    val currentParticipants = mutableStateListOf
</div>


## Final Output

We are done with implementation of customised video calling app in Android using Video SDK. To explore more features go through Basic and Advanced features.



<div style={{textAlign: 'center'}}>



</div>

:::tip
You can checkout the complete [quick start example here](https://github.com/videosdk-live/quickstart/tree/main/interactive-live-streaming/android-ils).
:::


---

# Quick Start for Conference in Android

VideoSDK enables you to embed the video calling feature into your Android application in minutes.

In this quickstart, we are going to explore group calling feature of Video SDK. We will go through step by step guide of integrating video calling with Android Video SDK.

This guide will get you running with the VideoSDK video & audio calling in minutes.

## Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

- Android Studio Arctic Fox (2020.3.1) or later.
- Android SDK API Level 21 or higher.
- A mobile device that runs Android 5.0 or later.

:::important

One should have a VideoSDK account to generate token.
Visit VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate token

:::

## Getting Started with the Code!

Follow the steps to create the environment necessary to add video calls into your app. Also you can find the code sample for [quickstart here](https://github.com/videosdk-live/quickstart/tree/main/android-rtc/Videosdk_android_compose_quickstart/).

### Create new Android Project

For a new project in **Android Studio**, create a **Phone and Tablet** Android project with an **Empty Activity**.

![VideoSDK Android Quick Start New Project](https://cdn.videosdk.live/docs/images/android/quickstart/android_compose_newProject.jpg )

:::caution
After creating the project, Android Studio automatically starts gradle sync. Ensure that the sync succeeds before you continue.
:::

### Integrate Video SDK



**Maven Central:**

```js title="settings.gradle"
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven {url= uri("https://maven.aliyun.com/repository/jcenter")}
  }
}
```

---

**Jitpack:**

```js title="settings.gradle"
dependencyResolutionManagement{
  repositories {
google()
maven { url = uri("https://www.jitpack.io") }
mavenCentral()
maven {url= uri("https://maven.aliyun.com/repository/jcenter")}
  }
}
```

- Add the following dependency in your app's `app/build.gradle`.

```js title="app/build.gradle"
dependencies {
  implementation ("live.videosdk:rtc-android-sdk:0.3.0")

  // library to perform Network call to generate a meeting id
  implementation ("com.amitshekhar.android:android-networking:1.0.2")

  // other app dependencies
  }
```

:::important

Android SDK compatible with armeabi-v7a, arm64-v8a, x86_64 architectures. If you want to run the application in an emulator, choose ABI x86_64 when creating a device.

:::

### Add permissions into your project

- In `/app/Manifests/AndroidManifest.xml`, add the following permissions.

```xml title="AndroidManifest.xml"
<uses-feature android:name="android.hardware.camera" android:required="false" />
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.permission.RECORD_AUDIO"/>
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>
```

:::note

If your project has set `android.useAndroidX=true`, then set `android.enableJetifier=true` in the `gradle.properties` file to migrate your project to AndroidX and avoid duplicate class conflict.

:::

### Structure of the project

Your project structure should look like this.

```jsx title="Project Structure"
app/
├── src/main/
│   ├── java/com/example/app/
│   │   ├── components/          
│   │   ├── screens/            
│   │   ├── navigation/          
│   │   ├── ui/                  
│   │   │   └── theme/           
│   │   ├── model/               
│   │   ├── MainApplication.kt   
│   │   ├── MainActivity.kt      
│   │   └── NetworkClass.kt      
│   ├── res/                     
│   └── AndroidManifest.xml      
├── build.gradle
└── settings.gradle
```


### App Architecture

<center>

<img src='https://cdn.videosdk.live/docs/images/android/quickstart/android_compose_quickstart_app_structure.jpg ' />

</center>

### Step 1: Initialize VideoSDK


1. Create `MainApplication` class which will extend the `android.app.Application`.

- Create field `sampleToken` in `MainApplication` which will hold the generated token from the [VideoSDK dashboard](https://app.videosdk.live/api-keys). This token will use in VideoSDK config as well as in generating meetingId.


```js title="MainApplication.kt"
import android.app.Application
import live.videosdk.rtc.android.VideoSDK

class MainApplication: Application() {

    val sampleToken = "YOUR_TOKEN" //paste your token here

    override fun onCreate() {
        super.onCreate()
        VideoSDK.initialize(applicationContext)
    }
}
```

2. Add `MainApplication` to `AndroidManifest.xml`

```xml title="AndroidManifest.xml"
<application
    android:name=".MainApplication" >
   
</application>
```


### Step 2: Managing Permissions


The `MainActivity` is the entry point of the application. It handles permission requests for accessing the camera and microphone.

On creation, it checks if the required permissions (RECORD_AUDIO and CAMERA) are granted.

If not, it requests them. Once permissions are granted, it sets the content view using Jetpack Compose and initializes the MyApp composable, which contains the app's navigation and UI logic.

```js title="MainActivity.kt"
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        checkSelfPermission(REQUESTED_PERMISSIONS[0], PERMISSION_REQ_ID)
        checkSelfPermission(REQUESTED_PERMISSIONS[1], PERMISSION_REQ_ID)

        setContent {
            Videosdk_android_compose_quickstartTheme {
                MyApp(this)
            }
        }
    }

    private fun checkSelfPermission(permission: String, requestCode: Int): Boolean {
        if (ContextCompat.checkSelfPermission(this, permission) !=
            PackageManager.PERMISSION_GRANTED
        ) {
            ActivityCompat.requestPermissions(this,
                REQUESTED_PERMISSIONS, requestCode)
            return false
        }
        return true
    }

    companion object {
        private const val PERMISSION_REQ_ID = 22
        private val REQUESTED_PERMISSIONS = arrayOf(
            Manifest.permission.RECORD_AUDIO,
            Manifest.permission.CAMERA
        )
    }
}

@Composable
fun MyApp(context: Context) {
    NavigationGraph(context = context)
}
```


### Step 3: Setting Up Navigation


The `NavigationGraph` composable manages navigation between the `JoinScreen` and `MeetingScreen` using `NavController`.

```js title="NavigationGraph.kt"
@Composable
fun NavigationGraph(navController: NavHostController = rememberNavController(),context: Context) {
    NavHost(navController = navController, startDestination = "join_screen") {
        composable("join_screen") {
            JoinScreen(navController,context)
        }
        composable("meeting_screen?meetingId={meetingId}") { backStackEntry ->
            val meetingId = backStackEntry.arguments?.getString("meetingId")
            meetingId?.let {
                MeetingScreen(viewModel = MeetingViewModel(),navController, meetingId, context)
            }
        }
    }
}
```


### Step 4: Creating Components


- Before building the individual screens, it's essential to develop reusable composable components that will be used throughout the project.

1. Create a `ReusableComponents.kt` file to organize all reusable components for the project, such as buttons, spacers, and customizable text.

```js title="ReusableComponents.kt"
@Composable
fun MyAppButton(task: () -> Unit, buttonName: String) {
    Button(onClick = task) {
        Text(text = buttonName)
    }
}
@Composable
fun MySpacer() {
    Spacer(
        modifier = Modifier
            .fillMaxWidth()
            .height(1.dp)
            .background(color = Color.Gray))}
@Composable
fun MyText(text: String, fontSize: TextUnit = 23.sp) {
    Text(
        text = text,
        fontSize = fontSize,
        fontWeight = FontWeight.Normal,
        modifier = Modifier.padding(4.dp),
        style = MaterialTheme.typography.bodyMedium.copy(fontSize = 16.sp),
        color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.7f)
    )}
```
2. Create a `ParticipantVideoView.kt` file that includes two composable functions: `ParticipantVideoView` for rendering individual participant video streams, and `ParticipantsGrid` for displaying a grid of participant videos.

:::info

- Here the participant's video is displayed using `VideoView`. To know more about `VideoView`, please visit [here](/android/guide/video-and-audio-calling-api-sdk/render-media/display-video/understand-videoView-component)
- `VideoView` is a custom View. Since Jetpack Compose does not natively support traditional `View` objects, we need to integrate the `VideoView` into the Compose layout using the `AndroidView` wrapper.
- `AndroidView()` is a composable that can be used to add Android views inside a @Composable function.

:::

```js title="ParticipantVideoView.kt"
@Composable
fun ParticipantVideoView(
    participant: Participant
) {
    var isVideoEnabled by remember { mutableStateOf(false) }

    LaunchedEffect(participant) {
        isVideoEnabled = participant.streams.any { (_, stream) ->
            stream.kind.equals("video", ignoreCase = true) && stream.track != null
        }
    }
    Box(
        modifier = Modifier
            .fillMaxWidth()
            .height(200.dp)
            .background(if (isVideoEnabled) Color.DarkGray else Color.Gray)
    ) {
        AndroidView(
            factory = { context ->
                VideoView(context).apply {
                    for ((_, stream) in participant.streams) {
                        if (stream.kind.equals("video", ignoreCase = true)) {
                            val videoTrack = stream.track as VideoTrack
                            addTrack(videoTrack)
                            isVideoEnabled = true
                        }
                    }
                }
            },
            update = { videoView ->
                participant.addEventListener(object : ParticipantEventListener() {
                    override fun onStreamEnabled(stream: Stream) {
                        if (stream.kind.equals("video", ignoreCase = true)) {
                            val videoTrack = stream.track as VideoTrack
                            videoView.addTrack(videoTrack)
                            isVideoEnabled = true
                        }
                    }

                    override fun onStreamDisabled(stream: Stream) {
                        if (stream.kind.equals("video", ignoreCase = true)) {
                            videoView.removeTrack()
                            isVideoEnabled = false
                        }
                    }
                })
            },
            onRelease = { videoView ->
                videoView.releaseSurfaceViewRenderer()
            },
            modifier = Modifier.fillMaxSize()
        )

        if (!isVideoEnabled) {
            Box(
                modifier = Modifier
                    .fillMaxSize()
                    .background(Color.DarkGray),
                contentAlignment = Alignment.Center
            ) {
                Text(
                    text = "Camera Off",
                    color = Color.White
                )
            }
        }

        Box(
            modifier = Modifier
                .align(Alignment.BottomCenter)
                .fillMaxWidth()
                .background(Color(0x99000000))
                .padding(4.dp)
        ) {
            Text(
                text = participant.displayName,
                color = Color.White,
                modifier = Modifier.align(Alignment.Center)
            )
        }
    }
}
@Composable
fun ParticipantsGrid(
    participants: List
</div>


### Step 6: Creating MeetingId


The `NetworkManager` singleton handles meeting creation by making a POST request to the [VideoSDK API](https://docs.videosdk.live/api-reference/realtime-communication/create-room):

- Meeting Creation: Sends a request to the API with an authorization token to create a meeting.
- Response Handling: Extracts the roomId from the response and triggers the `onMeetingCreated` callback.


```js title="NetworkManager.kt"
object NetworkManager {
    fun createMeetingId(token: String, onMeetingIdCreated: (String) -> Unit) {
        AndroidNetworking.post("https://api.videosdk.live/v2/rooms")
            .addHeaders("Authorization", token)
            .build()
            .getAsJSONObject(object : JSONObjectRequestListener {
                override fun onResponse(response: JSONObject) {
                    try {
                        val meetingId = response.getString("roomId")
                        onMeetingIdCreated(meetingId)
                    } catch (e: JSONException) {
                        e.printStackTrace()
                    }
                }

                override fun onError(anError: ANError) {
                    anError.printStackTrace()
                    Log.d("TAG", "onError: $anError")
                }
            })
    }
}
```

:::note

Don't confuse with Room and Meeting keyword, both are same thing 😃

:::


### Step 7: Creating Meeting Screen


We will create a simple Meeting screen UI with two main sections:

- Participants' Video Streams: Displays video feeds of meeting participants.
- Media Control Buttons: Includes buttons to control the mic, camera, and leave the meeting.

The `MeetingScreen` composable is the main UI for a video call meeting, handling meeting details and user actions. The `MeetingScreen` composable is organized into three sections, each serving a specific purpose:

1. `Header`: Displays the meeting ID at the top of the screen for reference.
2. `ParticipantsGrid`: Shows the list of participants in a grid layout, adjusting dynamically.
3. `MediaControlButtons`: A set of buttons to control the microphone, camera, and leave the meeting.


```js title="MeetingScreen.kt"
@Composable
fun MeetingScreen(viewModel: MeetingViewModel, navController: NavController, meetingId: String, context: Context) {

    val app = context.applicationContext as MainApplication
    val isMeetingLeft = viewModel.isMeetingLeft

    LaunchedEffect(isMeetingLeft) {
        if (isMeetingLeft) {
            navController.navigate("join_screen")
        }
    }
    Column(modifier = Modifier.fillMaxSize()) {
        Header(meetingId)
        MySpacer()
        ParticipantsGrid(viewModel.participants, Modifier.weight(1f))
        MySpacer()
        MediaControlButtons(
            onJoinClick = {
                viewModel.initMeeting(context, app.sampleToken, meetingId)
            },
            onMicClick = { viewModel.toggleMic() },
            onCamClick = { viewModel.toggleWebcam() },
            onLeaveClick = {
                viewModel.leaveMeeting()
            }
        )
    }
}
@Composable
fun Header(meetingId: String) {
    Box(
        modifier = Modifier
            .fillMaxWidth()
            .padding(8.dp),
        contentAlignment = Alignment.TopStart
    ) {
        Row {
            MyText("MeetingID: ", 28.sp)
            MyText(meetingId, 25.sp)
        }
    }
}
@Composable
fun MediaControlButtons(onJoinClick:()->Unit,onMicClick: () -> Unit, onCamClick: () -> Unit, onLeaveClick: () -> Unit) {
    Row(
        modifier = Modifier
            .fillMaxWidth()
            .padding(6.dp),
        verticalAlignment = Alignment.CenterVertically,
        horizontalArrangement = Arrangement.SpaceAround
    ) {
        MyAppButton(onJoinClick,"Join")
        MyAppButton(onMicClick,"ToggleMic")
        MyAppButton(onCamClick,"ToggleCam")
        MyAppButton(onLeaveClick,"Leave")
    }
}
```


### Step 8: Setting Up MeetingViewModel


The `MeetingViewModel` manages the meeting state, handles participants, and controls microphone and camera settings to ensure a smooth video call experience.

Managing Meeting State and Media Control:

1. Meeting Initialization: Initializes the meeting with the VideoSDK and adds an event listener.
2. Participant Management: Tracks participants, adding/removing them as they join/leave.
3. Media Control: Toggles microphone and webcam states.
4. Leave Meeting: Allows users to leave the meeting.

```js title="MeetingViewModel.kt"
class MeetingViewModel : ViewModel() {

    private var meeting: Meeting? = null
    private var micEnabled by mutableStateOf(true)
    private var webcamEnabled by mutableStateOf(true)
    val participants = mutableStateListOf
</div>


## Final Output

We are done with implementation of customised video calling app in Android using Video SDK. To explore more features go through Basic and Advanced features.


<div style={{textAlign: 'center'}}>



</div>

:::tip
You can checkout the complete [quick start example here](https://github.com/videosdk-live/quickstart/tree/main/android-rtc/Videosdk_android_compose_quickstart/).
:::


---

# Quick Start for Conference in Android



VideoSDK enables you to embed the video calling feature into your Android application in minutes.

In this quickstart, we are going to explore group calling feature of Video SDK. We will go through step by step guide of integrating video calling with Android Video SDK.

This guide will get you running with the VideoSDK video & audio calling in minutes.

## Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

- Java Development Kit.
- Android Studio 3.0 or later.
- Android SDK API Level 21 or higher.
- A mobile device that runs Android 5.0 or later.

:::important

One should have a VideoSDK account to generate token.
Visit VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate token

:::

## Getting Started with the Code!

Follow the steps to create the environment necessary to add video calls into your app. Also you can find the code sample for [quickstart here](https://github.com/videosdk-live/quickstart/tree/main/android-rtc).

### Create new Android Project

For a new project in **Android Studio**, create a **Phone and Tablet** Android project with an **Empty Activity**.

![VideoSDK Android Quick Start New Project](/img/quick-start/android_newProject.png)

:::caution
After creating the project, Android Studio automatically starts gradle sync. Ensure that the sync succeeds before you continue.
:::

### Integrate Video SDK



**Maven Central:**

```js title="settings.gradle"
dependencyResolutionManagement{
  repositories {
// ...
google()
mavenCentral()
maven { url "https://maven.aliyun.com/repository/jcenter" }
  }
}
```

---

**Jitpack:**

```js title="settings.gradle"
dependencyResolutionManagement{
  repositories {
// ...
google()
maven { url 'https://jitpack.io' }
mavenCentral()
maven { url "https://maven.aliyun.com/repository/jcenter" }
  }
}
```

- Add the following dependency in your app's `app/build.gradle`.

```js title="app/build.gradle"
dependencies {
  implementation 'live.videosdk:rtc-android-sdk:0.3.0'

  // library to perform Network call to generate a meeting id
  implementation 'com.amitshekhar.android:android-networking:1.0.2'

  // other app dependencies
  }
```

:::important

Android SDK compatible with armeabi-v7a, arm64-v8a, x86_64 architectures. If you want to run the application in an emulator, choose ABI x86_64 when creating a device.

:::

### Add permissions into your project

- In `/app/Manifests/AndroidManifest.xml`, add the following permissions after `</application>`.

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

:::note

If your project has set `android.useAndroidX=true`, then set `android.enableJetifier=true` in the `gradle.properties` file to migrate your project to AndroidX and avoid duplicate class conflict.

:::

### Structure of the project

Your project structure should look like this.

```jsx title="Project Structure"
   app
   ├── java
   │    ├── packagename
   │         ├── JoinActivity
   │         ├── MainApplication
   │         ├── MeetingActivity
   │         ├── ParticipantAdapter
   ├── res
   │    ├── layout
   │    │    ├── activity_join.xml
   │    │    ├── activity_meeting.xml
   │    │    ├── item_remote_peer.xml
```

:::note

You have to set JoinActivity as Launcher activity.

:::

### App Architecture

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/android_quickstart_app_structure.png' />

</center>

### Step 1: Initialize VideoSDK

1. Create `MainApplication` class which will extend the `android.app.Application`.

**Kotlin:**

```js title="MainApplication.kt"
import live.videosdk.rtc.android.VideoSDK

class MainApplication : Application() {
  override fun onCreate() {
  super.onCreate()
  //highlight-next-line
  VideoSDK.initialize(applicationContext)
  }
}
```

---

**Java:**

```java title="MainApplication.java"
import android.app.Application;
import live.videosdk.rtc.android.VideoSDK;

public class MainApplication extends Application {
  @Override
  public void onCreate() {
super.onCreate();
//highlight-next-line
VideoSDK.initialize(getApplicationContext());
  }
}
```

2. Add `MainApplication` to `AndroidManifest.xml`

```xml title="AndroidManifest.xml"
<application
    android:name=".MainApplication" >
   
</application>
```


### Step 2: Creating Joining Screen


Create a new Activity named `JoinActivity`. The Joining screen will include :

1. **Create Button** - This button will create a new meeting for you.
2. **TextField for Meeting Id** - This text field will contain the meeting Id you want to join.
3. **Join Button** - This button will join the meeting with `meetingId` you provided.

In `/app/res/layout/activity_join.xml` file, replace the content with the following.

```xml title="activity_join.xml"
<?xml version="1.0" encoding="utf-8"?>


    

    <com.google.android.material.textfield.TextInputLayout
        style="@style/Widget.MaterialComponents.TextInputLayout.OutlinedBox"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_marginVertical="16dp"
        android:hint="Enter Meeting ID">

        
    </com.google.android.material.textfield.TextInputLayout>

    
</LinearLayout>
```
**Here is the implementation for the Join Activity:**


1. Create field `sampleToken` in `JoinActivity` which will hold the generated token from the [VideoSDK dashboard](https://app.videosdk.live/api-keys). This token will use in VideoSDK config as well as in generating meetingId.

**Kotlin:**

```js title="JoinActivity.kt"
class JoinActivity : AppCompatActivity() {

  //highlight-next-line
  //Replace with the token you generated from the VideoSDK Dashboard
  private var sampleToken = ""

  override fun onCreate(savedInstanceState: Bundle?) {
//...
  }
}
```

---

**Java:**

```java title="JoinActivity.java"
public class JoinActivity extends AppCompatActivity {

  //highlight-next-line
  //Replace with the token you generated from the VideoSDK Dashboard
  private String sampleToken ="";

  @Override
  protected void onCreate(Bundle savedInstanceState) {
//...
  }
}
```

2. On **Join Button** `onClick` events, we will naviagte to `MeetingActivity` with token and meetingId.

**Kotlin:**

```js title="JoinActivity.kt"
class JoinActivity : AppCompatActivity() {

   //Replace with the token you generated from the VideoSDK Dashboard
   private var sampleToken = ""

   override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_join)

    val btnCreate = findViewById

    <androidx.recyclerview.widget.RecyclerView
        android:id="@+id/rvParticipants"
        android:layout_width="match_parent"
        android:layout_height="0dp"
        android:layout_weight="1" />

    

        

        

    </LinearLayout>

</LinearLayout>
```

**The next step is to initialize a meeting, After getting token and meetigId from JoinActivity:**

1. Configure **VideoSDK** with token.
2. Initialize the meeting with required params such as `meetingId`, `participantName`, `micEnabled`, `webcamEnabled` and more.
3. Add `MeetingEventListener` for listening events such as **Meeting Join/Left** and **Participant Join/Left**.
4. Join the room with `meeting.join()` method.

**Kotlin:**

```js title="MeetingActivity.kt"
class MeetingActivity : AppCompatActivity() {
  // declare the variables we will be using to handle the meeting
  private var meeting: Meeting? = null
  private var micEnabled = true
  private var webcamEnabled = true

  override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_meeting)

val token = intent.getStringExtra("token")
val meetingId = intent.getStringExtra("meetingId")
val participantName = "John Doe"

//highlight-next-line
// 1. Configuration VideoSDK with Token
VideoSDK.config(token)

//highlight-next-line
// 2. Initialize VideoSDK Meeting
meeting = VideoSDK.initMeeting(
  this@MeetingActivity, meetingId, participantName,
  micEnabled, webcamEnabled, null, null, false, null, null)

//highlight-next-line
// 3. Add event listener for listening upcoming events
meeting!!.addEventListener(meetingEventListener)

//highlight-next-line
//4. Join VideoSDK Meeting
meeting!!.join()

(findViewById

</div>


### Step 5: Handling the Participants View

We will be showing the list of participant in a `RecyclerView`.

:::info

- Here the participant's video is displayed using `VideoView`, but you may also use `SurfaceViewRender` for the same.
- For `VideoView`, SDK version should be `0.1.13` or higher.
- To know more about `VideoView`, please visit [here](/android/guide/video-and-audio-calling-api-sdk/render-media/display-video/understand-videoView-component)

:::

1. Create a new layout for the participant view named `item_remote_peer.xml` in the `res/layout` folder.

```xml title="item_remote_peer.xml"
<?xml version="1.0" encoding="utf-8"?>


    

    </LinearLayout>

</FrameLayout>
```

2. Create a recycler view adapter named `ParticipantAdapter` which will show the participant list. Create `PeerViewHolder` in the adapter which will extend `RecyclerView.ViewHolder`.

**Kotlin:**

```js title="ParticipantAdapter.kt"
class ParticipantAdapter(meeting: Meeting) : RecyclerView.Adapter

</div>

:::tip
You can checkout the complete [quick start example here](https://github.com/videosdk-live/quickstart/tree/main/android-rtc).
:::


---

## Understanding Usage Quota Limits - Android

In this documentation, you will find detailed information about the quotas associated with each plan, including usage limits for various features and functionalities. Understanding these quotas will help you optimize your usage, selecting the best pricing plan and make the most of your VideoSDK experience.

## How VideoSDK limits concurrent usage quota

VideoSDK's approach to limiting usage focuses on concurrent usage rather than overall usage. Concurrent usage refers to the number of participants or requests that can be hosted or processed simultaneously. 

For example, if there's a limit of 50 concurrent participants per organization, users can run multiple calls (sessions) simultaneously, with a maximum of 50 participants across all sessions combined.

## How to view my current plan’s quota limits?

To view the current quota limits on your organization, simply navigate to the [VideoSDK Dashboard](https://app.videosdk.live/), go to your Profile section, and click on the Billing tab.

## Free Plan

Since, we’ve designed Free Plan for developers who are just exploring, we’ve kept the limits that would get you started without a hitch.

Organisations on Free Plan have the following limits on concurrent usage:

| Feature | Concurrent Limit |
| --- | --- |
| Participants in Video Calls | 50 concurrent participants |
| Viewers in Live Streams | 100 concurrent viewers |
| Recording Request | 1 concurrent request at a time |
| HLS Encoding Request | 1 concurrent request at a time |
| RTMP-Out Request | 1 concurrent request at a time |

 
### How to increase my limits?

To increase your limits, simply upgrade your plan by providing billing details and credit card information.

## Pay-as-you-Go Plan

We've increased participant limits for this paid plan. This way, it won't significantly impact users heavily involved in production or integration.

Organisations on Pay-as-you-Go have the following limits on concurrent usage:

| Feature | Concurrent Limit |
| --- | --- |
| Participants in Video Calls | 100 concurrent participants |
| Viewers in Live Streams | 500 concurrent viewers |
| Recording Request | 5 concurrent request at a time |
| HLS Encoding Request | 5 concurrent request at a time |
| RTMP-Out Request | 5 concurrent request at a time |

### How to increase my limits?

To increase your limits further more, simply get in touch with us. [Contact us](https://www.videosdk.live/contact) directly or reach out via email at [support@videosdk.live](mailto:support@videosdk.live), and we'll handle the rest gladly.

## Enterprise Plan

For Enterprise users, all limits are tailored to the specific needs. Customised limits ensure optimal performance for your unique requirements.

To get started as an Enterprise user, simply get in touch with us, explain your requirements and use case, and we’ll customise the quota and limits according to your needs.

## Examples to understand concurrent limits

**Example #1**

Let's say you're using video callings (RTC) in your organization on the Free Plan. In this scenario, you can concurrently host up to 50 participants. However, the number of calls (sessions) you initiate is unrestricted.

To simplify, you can run multiple sessions simultaneously, but concurrently, you can only accommodate a maximum of 50 participants across all sessions. If a 51st participant attempts to join, they won't be able to access the session until you upgrade your plan to increase your participant limits.

**Example #2**

Let’s say you're using live streaming in your organization on the Free Plan. In this setup, you can concurrently host up to 100 viewers joining the sessions. While you have the flexibility to host multiple live streaming sessions, the number of viewers joining session concurrently is restricted.

**Example #3**

Lets say you’re using video callings (RTC) in your organization on the Pay-as-you-Go Plan and you're hosting 5 concurrent calls (sessions), all of which are being recorded. Now, when you initiate the 6th call (session) and request recording, VideoSDK will not process your recording request. Instead, it will throw an error because you've reached your recording request limit.

If you have any questions regarding quota limits and pricing plan, post in our [Discord community](https://discord.com/invite/Qfm8j4YAUJ), [contact us](https://www.videosdk.live/contact) directly, or reach out to us on [support@videosdk.live](mailto:support@videosdk.live).

---

Recording meetings is an essential feature that ensures all important discussions, decisions, and interactions are documented for future reference. VideoSDK offers three types of recordings: Meeting Recording, Participant Recording, and Participant Track Recording. Each type serves a specific purpose to cater to different recording needs during a meeting.

## Meeting Recording

Meeting Recording captures the entire meeting, including all participants, audio, video, and shared content. This comprehensive recording is ideal for reviewing the entire meeting, ensuring that nothing is missed. It provides a holistic view of the meeting, capturing every interaction and piece of information shared during the session.

![Meeting Recording](https://cdn.videosdk.live/website-resources/docs-resources/MeetingRecording.png)

## Participant Recording

Participant Recording focuses on individual participants, capturing both their audio and video into a single file. This type of recording is particularly useful for tracking the contributions of specific participants or for scenarios where detailed analysis of an individual’s participation is needed. When a participant mutes their audio or turns off their video, the recording continues but with silenced audio or a black screen, respectively. This ensures a continuous recording without interruptions, reflecting the participant's involvement throughout the meeting.

![Participant Recording](https://cdn.videosdk.live/website-resources/docs-resources/ParticipantRecording.png)

## Participant Track Recording

Participant Track Recording allows you to record specific tracks of a participant, either audio or video, based on user input. This targeted approach is perfect for capturing particular aspects of a participant’s contribution, such as only their audio or only their video. Multiple files are generated whenever there is a change in the track's status (e.g., starting after being muted ), ensuring focused documentation of each continuous segment. This method is especially useful in scenarios where detailed analysis of specific media (audio or video) is required.

![Participant Track Recording](https://cdn.videosdk.live/website-resources/docs-resources/TrackRecording.png)



---

https://sdk.videosdk.live/js-sdk/0.2.6/videosdk.jsVideoSDK offers a range of video streaming tools and solutions for content creators, publishers, and developers.

- A custom template is a specialized layout for a live stream that allows users to integrate real-time graphics into their broadcasts.

- With custom templates, users can enhance their video content by overlaying graphics, text, images, and animations onto their live streams. These elements can be customized to align with specific branding requirements.

- By leveraging custom templates, users can craft dynamic and engaging video experiences. Whether incorporating live scoreboards, social media feeds, or other personalized elements, users have the flexibility to create visually appealing streams that stand out and capture audience attention.

:::note

Custom templates can also be used with recordings and RTMP service provided by VideoSDK.

:::

### What you can do with Custom Template

By utilizing a custom template, you have the flexibility to create various modes for your live stream. Here are some popular modes that you can design:

- **`PK Host:`** The host can organize a player vs. player battle, as illustrated in the example of a gaming battle shown below.

![pk host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_pk_battle.png)

- **`Watermark:`** The host has the ability to add and update watermarks anywhere in the template; for instance, the image below features a VideoSDK watermark on the top right side of the screen.

![watermark host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_water_mark.png)

- **`News Mode:`** Additionally, the host can incorporate dynamic text in the lower third banner, as demonstrated by the sample text in the bottom left of the screen.

![news mode](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_news_live.png)

### Custom template with VideoSDK

In this section, we will discuss how Custom Templates work with VideoSDK.

- **`Host`**: The host initiates live streaming by providing the `templateURL`. The `templateURL` is the URL of the hosted template webpage. The host is also responsible for managing the template, including tasks such as altering text, logos, and switching template layouts.

- **`VideoSDK Template Engine`** : The VideoSDK Template Engine accepts and opens the templateURL in the browser, actively listening to all events initiated by the Host. It facilitates the customization of the template in accordance with the host's preferences.

- **`Viewer`**: Viewers can stream the content, experiencing the live stream with added real-time graphics. This feature contributes to a distinctive and engaging viewing experience.

![custom template](https://cdn.videosdk.live/website-resources/docs-resources/custom_template.png)

### Understanding Template URL

The template URL is a webpage that VideoSDK Template Engine will open while composing the live stream.

It will appear as shown below.

![template url](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_url.png)

The Template URL comprises of two essential parts:

- Your actual page URL, resembling something like `https://example.com/videosdk-template`.
- Query parameters, designed to enable the VideoSDK Template Engine to seamlessly join the meeting upon opening the URL. There are three key query parameters in total:
  - `token`: Your token, serving as the authentication key to join the meeting.
  - `meetingId`: The meeting Id of the meeting that the VideoSDK Template Engine will join.
  - `participantId`: The participant ID of the VideoSDK Template Engine. This should be included when joining the template engine in your template, ensuring that the template engine participant remains invisible to other participants. **This parameter is automatically added by the VideoSDK**.

:::info

Above mentioned query parameters are mandatory. Apart from these parameters, you can pass any other extra parameters which are required according to your use-case.

:::

### **Creating Template**

**`Step 1:`** Import VideoSDK using `<script>` tag or install it using the below-mentioned npm command.
Make sure you are in your app directory before you run this command.



**Tab:**

" label="<script>" default>

```html
<html>
  <head></head>
  <body>
// highlight-next-line
<script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
  </body>
</html>
```

---

**npm:**

```bash
npm install @videosdk.live/js-sdk
```

---

**yarn:**

```bash
yarn add @videosdk.live/js-sdk
```

:::note

You can use VideoSDK's React or JavaScript SDK to create custom template. Following is the example of building custom template with JavaScript SDK.

:::

###### Structure of the Project

```jsx title="Project Structure"
  root
   ├── index.html
   ├── index.js
```

**`Step 2:`** Craft a user interface (UI) tailored for your live stream presentation.

```html title="index.html"
<!DOCTYPE html>
<html>
  <head> </head>

  <body>
    <div id="textDiv">Starting live stream...</div>

    
    <div class="row" id="videoContainer"></div>

    <script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
    <script src="index.js"></script>
  </body>
</html>
```

**`Step 3:`** Next, fetch the query parameters, from the URL which will be later used to initialize the meeting and get the elements from DOM.

```js title=index.js
const url = window.location;
const urlParams = new URLSearchParams(url.search);

const meetingId = urlParams.get("meetingId");
const token = urlParams.get("token");
const participantId = urlParams.get("participantId");

const videoContainer = document.getElementById("videoContainer");
const textDiv = document.getElementById("textDiv");
```

**`Step 4:`** Subsequently, initialize the meeting with the parameters that were extracted from the URL. Ensure direct initialization so that the template engine seamlessly joins the meeting upon page load.

```js title=index.js
window.VideoSDK.config(token);

const meeting = window.VideoSDK.initMeeting({
  meetingId: meetingId, // required
  name: "recorder", // required
  micEnabled: false,
  webcamEnabled: false,
  participantId: participantId,
});

meeting.join();

meeting.on("meeting-joined", () => {
  textDiv.style.display = "none";
});
```

**`Step 5:`** Next step is to create the container that will render the meeting view on the `participant-joined` event.

```js title=index.js
//  participant joined
meeting.on("participant-joined", (participant) => {
  let videoElement = createVideoElement(
    participant.id,
    participant.displayName
  );
  let audioElement = createAudioElement(participant.id);

  participant.on("stream-enabled", (stream) => {
    setTrack(stream, audioElement, participant, false);
  });
  videoContainer.appendChild(videoElement);
  videoContainer.appendChild(audioElement);
});

// participants left
meeting.on("participant-left", (participant) => {
  let vElement = document.getElementById(`f-${participant.id}`);
  vElement.remove(vElement);

  let aElement = document.getElementById(`a-${participant.id}`);
  aElement.remove(aElement);
});

// creating video element
function createVideoElement(pId, name) {
  let videoFrame = document.createElement("div");
  videoFrame.setAttribute("id", `f-${pId}`);

  //create video
  let videoElement = document.createElement("video");
  videoElement.classList.add("video-frame");
  videoElement.setAttribute("id", `v-${pId}`);
  videoElement.setAttribute("playsinline", true);
  videoElement.setAttribute("width", "300");
  videoElement.muted = true;
  videoFrame.appendChild(videoElement);

  let displayName = document.createElement("div");
  displayName.innerHTML = `Name : ${name}`;
  videoFrame.appendChild(displayName);

  return videoFrame;
}

// creating audio element
function createAudioElement(pId) {
  let audioElement = document.createElement("audio");
  audioElement.setAttribute("autoPlay", "false");
  audioElement.setAttribute("playsInline", "true");
  audioElement.setAttribute("controls", "false");
  audioElement.setAttribute("id", `a-${pId}`);
  audioElement.style.display = "none";
  return audioElement;
}

// setting media track
function setTrack(stream, audioElement, participant, isLocal) {
  if (stream.kind == "video") {
    isWebCamOn = true;
    const mediaStream = new MediaStream();
    mediaStream.addTrack(stream.track);
    let videoElm = document.getElementById(`v-${participant.id}`);
    videoElm.srcObject = mediaStream;
    videoElm
      .play()
      .catch((error) =>
        console.error("videoElem.current.play() failed", error)
      );
  }
  if (stream.kind == "audio") {
    if (isLocal) {
      isMicOn = true;
    } else {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(stream.track);
      audioElement.srcObject = mediaStream;
      audioElement
        .play()
        .catch((error) => console.error("audioElem.play() failed", error));
    }
  }
}
```

**`Step 6:`** Now, listen to PubSub messages from the `CHANGE_BACKGROUND` topic, triggering a change in the meeting's background color accordingly.

:::note

The PubSub mechanism is utilized to communicate with the template. You can learn more about [PubSub from here](/javascript/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

:::

```js title=index.js
meeting.on("meeting-joined", () => {
  //  ...

  meeting.pubSub.subscribe("CHANGE_BACKGROUND", (data) => {
    let { message } = data;
    document.body.style.backgroundColor = message;
  });
});
```

**`Step 7:`** Once tested, you can deploy it using your backend or host it on services like [firebase](https://www.geeksforgeeks.org/how-to-deploy-react-project-on-firebase/) or vercel.

:::tip

You can checkout the github repository for sample custom template [created here](https://github.com/videosdk-live/videosdk-custom-recording-template-js-example).

:::

### Setup Livestream Using Custom Template

- To utilize Custom Templates with Livestream, you need to establish both the Host and Viewer setups. The Host initiates the livestream, while Viewers can watch the broadcast.

![template manager](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_manager.png)

- To understand custom templates, clone this example and run it on your system.

```bash
git clone https://github.com/videosdk-live/videosdk-custom-recording-template-js-example.git
```

- You can utilize this custom template in [Start Recording API](/api-reference/realtime-communication/start-recording), [Start HLS API](/api-reference/realtime-communication/start-hlsStream) and [Start Livestream API](/api-reference/realtime-communication/start-livestream). Here is the example of HLS.
- To utilize the custom template that has been deployed, invoke the [Start HLS API](https://docs.videosdk.live/api-reference/realtime-communication/start-hlsStream) instead of the `startHls` method from the `Meeting` class. The necessary code has already been incorporated in the cloned example above.

:::important

You can create your own custom template manager in JavaScript. In this example, we are using one for better understanding.

:::

```js
<button
  onClick={async () => {
    const url = `https://api.videosdk.live/v2/hls/start`;
    //Update your Custom Template URL here if you have deployed your own, if not deployed you can use this template from our URL.
    //highlight-next-line
    const templateUrl = `https://lab.videosdk.live/js-template-demo/?meetingId=${meetingId}&token=${authToken}`;
    const options = {
      method: "POST",
      headers: {
        Authorization: authToken,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        roomId: meetingId,
        templateUrl: templateUrl,
      }),
    };

    const result = await fetch(url, options)
      .then((response) => response.json()) // result will have playbackHlsUrl and livestreamUrl
      .catch((error) => console.error("error", error));
  }}
>
  Start HLS
</button>
```

- In this example, the host has two options on their side, enabling them to change the background and send messages to the viewers.

- Given below is a test run of the example.


<div style={{textAlign: 'center'}}>



</div>

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)
- [Start HLS API](/api-reference/realtime-communication/start-hlsStream)
- [Start Livestream API](/api-reference/realtime-communication/start-livestream)
- [recordingState](/react/api/sdk-reference/use-meeting/properties#recordingstate)
- [hlsState](/react/api/sdk-reference/use-meeting/properties#hlsstate)
- [livestreamState](/react/api/sdk-reference/use-meeting/properties#livestreamstate)
- [hlsUrls](/react/api/sdk-reference/use-meeting/properties#hlsurls)
- [onRecordingStateChanged](/react/api/sdk-reference/use-meeting/events#onrecordingstatechanged)
- [onHlsStateChanged](/react/api/sdk-reference/use-meeting/events#onhlsstatechanged)
- [onLivestreamStateChanged](/react/api/sdk-reference/use-meeting/events#onlivestreamstatechanged)



---

# Geo Tag Meeting Recordings - Android

To ensure compliance for BFSIs doing vKYC, it very important to include the co-ordinates(location) of the customer in the recordings. VideoSDK provides a very customizable solution to implement this feature. You will be using custom templates for this purpose.

We have created a ready to use template for this use case which can be found [here](https://github.com/videosdk-live/videosdk-rtc-react-prebuilt-ui/tree/template/geo-tag-watermark). To integrate this template with your recordings follow the below mentiond instructions.

### Host the template

1. Clone the template repository and switch to the branch `template/geo-tag-watermark`.

```bash
git clone https://github.com/videosdk-live/videosdk-rtc-react-prebuilt-ui.git
cd videosdk-rtc-react-prebuilt-ui
git checkout template/geo-tag-watermark
```

2. Install the dependencies and create a build of the project using below mentioned commands.

```bash
npm install
npm run build
```

3. Host the contents of the build folder on your server and check if the template is up and running.

:::note

If you want to create the complete template from scratch you can [follow this guide.](./custom-template.md)

:::

### Using the template for recording

1. To use the template that we deployed earlier, we will be using the `templateUrl` feature in the `startRecording` API.
   To generate the template URL, you will have to append the `meetingId`, and `token` has to be added in the query parameters. Also if you are using the template provided above you need to added a few extra paramters mentioned below. Here is the code snippet to generate the URL.

```js
async function main() {
  let meetingId = "Your MeetingID";
  let token = "Your Token";
  const templateUrl = `https://${YOUR Template URL}/?meetingId=${meetingId}&token=${token}&name=recorder&isRecorder=true&joinWithoutUserInteraction=true`;

  console.log(templateUrl);
}

main();
```

2. Now that we have the template URL, we will use this URL to start the recording using the below provided API call.

```js
async function main() {
  let meetingId = "Your MeetingID";
  let token = "Your Token";
  const templateUrl = `https://${YOUR Template URL}/?meetingId=${meetingId}&token=${token}&name=recorder&isRecorder=true&joinWithoutUserInteraction=true`;

  console.log(templateUrl);

  //Using the previouly created template URL and starting the recording using the API.
  const options = {
    method: "POST",
    headers: {
      Authorization: "$YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      roomId: "Your MeetingId",
      templateUrl: templateUrl,
    }),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();
```

### Updating the Geo Tagging Coordinates

We will be using the PubSub feature of VideoSDK to update the data of latitude and longitude. For the predefined template provided by us we are using `GEO_TAG` as topic name. We will be publishing the `participantName`, `latitude` and `longitude` of the participant for whom we want to show in the recording.

:::note

You will have to fetch the longitude and latitude of the participant before sending it using the pubsub.

:::

Here is the code how you will have to publish the message:



**Kotlin:**

```js
private fun sendMessage() {
  // publish message
  val options = PubSubPublishOptions()
  options.isPersist = true
  val geoTagData = JSONObject()
  JsonUtils.jsonPut(geoTagData, "latitude", "PARTICIPANT LATITUDE")
  JsonUtils.jsonPut(geoTagData, "longitude", "PARTICIPANT LONGITUDE")
  JsonUtils.jsonPut(geoTagData, "participantName", "PARTICIPANT NAME")

  //highlight-next-line
  meeting!!.pubSub.publish("GEO_TAG", "GEO_TAG_DATA", options, geoTagData)
}
```

---

**Java:**

```js
protected void sendMessage() {
  // publish message
  PubSubPublishOptions options = new PubSubPublishOptions();
  options.setPersist(true);
  JSONObject geoTagData = JSONObject()
  JsonUtils.jsonPut(geoTagData, "latitude", "YOUR LATITUDE")
  JsonUtils.jsonPut(geoTagData, "longitude", "YOUR LONGITUDE")
  JsonUtils.jsonPut(geoTagData, "participantName", "PARTICIPANT NAME")
  //highlight-next-line
  meeting.pubSub.publish("GEO_TAG", "GEO TAG DATA", options, geoTagData);
}
```

After implementing this, you should get the recording in the following format:

![Geo Tagging Recoridng](https://cdn.videosdk.live/website-resources/docs-resources/geo-tag-recording-template.png)

If you wish to change how UI looks on recording, you can change it by updating the layout in the template itself.

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)
- [Learn more about Custom Templates](./custom-template.md)


---

You have the option to create presigned URL, allowing you to upload your recordings to AWS, Azure, or GCP securely.
presigned URL provide a secure and temporary way to upload objects to your cloud storage. Instead of sharing your entire credentials, you can create a special URL that allows uploading a specific file for a limited time.

:::important

While presigned URL offer a convenient way to upload files securely, each cloud provider (AWS, Azure, and GCP) might have different restrictions on how they work. It's advisable to refer the respective documentation for **[<u>AWS</u>](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)**, **[<u>Azure</u>](https://learn.microsoft.com/en-us/rest/api/storageservices/delegate-access-with-shared-access-signature)**, and **[<u>GCP</u>](https://cloud.google.com/cdn/docs/using-signed-urls)** to gain a clearer understanding of presigned URL.

:::

### Code Sample

This guide will walk you through the process of generating a presigned URL for uploading recordings to your cloud storage of choice. You can use this generated presigned URL in [Start Recording API](/api-reference/realtime-communication/start-recording#preSignedUrl).



**AWS:**

```js
const { S3Client, PutObjectCommand } = require("@aws-sdk/client-s3");
const { getSignedUrl } = require("@aws-sdk/s3-request-presigner");

const region = <YOUR S3 REGION>;
const bucket = <YOUR S3 BUCKET NAME>;
const key = <YOUR FILE NAME>; // test/abc.mp4
const accessKeyId = <YOUR S3 ACCESS KEY ID>;
const secretAccessKey = <YOUR S3 SECRET ACCESS KEY>;
const expiresIn = <URL EXPIRY IN SECONDS>; // this number should be higher than duraion of recording

const s3Client = new S3Client({
credentials: {
    accessKeyId: accessKeyId,
    secretAccessKey: secretAccessKey,
},
region: region,
});

const createPresignedUrlWithClient = async () => {
const command = new PutObjectCommand({ Bucket: bucket, Key: key });
const preSignedUrl = await getSignedUrl(s3Client, command, { expiresIn: expiresIn });
return preSignedUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await createPresignedUrlWithClient();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

---

**AZURE:**

```js
const { BlobServiceClient, BlobSASPermissions } = require("@azure/storage-blob");

const connectionString = <YOUR AZURE STORAGE CONNECTION STRING>;
const containerName = <YOUR AZURE CONTAINER NAME>;
const blobName = <YOUR AZURE BLOB NAME>;
const startsOn = <YOUR SASURL START TIME>; // (optional, defaults to now)
const expiresOn = <YOUR SASURL EXPIRY TIME>; // expiry time should be higher than duration of recording

const generateSASUrl = async () => {
let blobServiceClient = BlobServiceClient.fromConnectionString(connectionString);
let containerClient = blobServiceClient.getContainerClient(containerName);

await containerClient.createIfNotExists({
    access: "container",
});

const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const sasUrl = await blockBlobClient.generateSasUrl({
    startsOn: startsOn, // sasUrl start time
    expiresOn: expiresOn, // sasUrl expiration time
    permissions: BlobSASPermissions.parse("write"),
});
return sasUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await generateSASUrl();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

---

**GCP:**

```js
const { Storage } = require("@google-cloud/storage");

const projectId = <YOUR GCP PROJECT ID>;
const clientEmail = <YOUR GCP CLIENT EMAIL>;
const privateKey = <YOUR GCP PRIVATE KEY>;
const expires =<URL EXPIRY IN SECONDS>; // this number should be higher than duraion of recording
const bucketName = <YOUR GCP BUCKET NAME>;
const fileName = <YOUR FILE NAME>; // test/abc.mp4

const storage = new Storage({
projectId: projectId,
credentials: {
    client_email: clientEmail,
    private_key: privateKey,
},
});

const generateSignedUrl = async () => {
const options = {
    version: "v4",
    action: "write",
    expires: expires,
    contentType: "video/mp4",
};

const [signedUrl] = storage.bucket(bucketName).file(fileName).getSignedUrl(options);
return signedUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await generateSignedUrl();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)



---

# Start and Stop - Android

This guide will provide an overview of how to implement start and stop Meeting Recording.

### `startRecording()`

`startRecording()` can be used to start a recording of the meeting which can be accessed from the `Meeting` class. This method accepts four parameters:

- `1. webhookUrl`: This would the webhook URL where you would like to listen to event happening for the recording like starting and stopping of recording. It will be triggered when the recording is completed and stored into server. Read more about webhooks [here](https://en.wikipedia.org/wiki/Webhook)

- `2. awsDirPath`: This parameter accepts the path for the your S3 bucket where you want to store recordings to. To allow us to store recording in your S3 bucket, you will need to fill this form by providing the required values. ([VideoSDK Cloud (AWS S3, Azure Blob or GCP ) Integration](/android/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config))

- `3. config`: This parameter will define how the meeting should be recorded.

- `4. transcription`: This parameter lets you start post transcription for the recording.

:::note

If you don't have a value for `webhookUrl`,`awsDirPath` or `config`, you should pass `null` in place of the missing value. If you pass `null` in `awsDirPath` parameter then by default recordings will be store on the VideoSDK's storage.
:::



**Kotlin:**

```js
val config = JSONObject()

//highlight-next-line
// Layout Configuration
val layout = JSONObject()
JsonUtils.jsonPut(layout, "type", "GRID") // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
JsonUtils.jsonPut(layout, "priority", "SPEAKER") // "PIN", Default : "SPEAKER"
JsonUtils.jsonPut(layout, "gridSize", 4) // MAX : 4
JsonUtils.jsonPut(config, "layout", layout)

//highlight-next-line
// Theme of recording
JsonUtils.jsonPut(config, "theme", "DARK") //  "LIGHT" | "DEFAULT"

//highlight-next-line
// `mode` is used to either record video & audio both or only audio.
JsonUtils.jsonPut(config, "mode", "video-and-audio") // "audio", Default : "video-and-audio"

//highlight-next-line
// Quality of recording and is only applicable to `video-and-audio` type mode.
JsonUtils.jsonPut(config, "quality", "high") /* Default : "med"
   "low" (SD Recording) | "med" (HD Recording) | "high" (FHD Recording) */

//highlight-start
// This mode refers to orientation of recording.
// landscape : Record the meeting in horizontally
// portrait : Record the meeting in vertically (Best for mobile view)
//highlight-end
JsonUtils.jsonPut(config, "orientation", "portrait") // "landscape",  Default : "landscape"

//highlight-next-line
// Post Transcription Configuration
val prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
val summaryConfig = SummaryConfig(true, prompt)
val modelId = "raman_v1"
val transcription = PostTranscriptionConfig(true, summaryConfig, modelId)

meeting.startRecording(null, null, config, transcription)
```

---

**Java:**

```js
JSONObject config = new JSONObject();

//highlight-next-line
// Layout Configuration
JSONObject layout = new JSONObject();
JsonUtils.jsonPut(layout, "type", "GRID"); // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
JsonUtils.jsonPut(layout, "priority", "SPEAKER");  // "PIN", Default : "SPEAKER"
JsonUtils.jsonPut(layout, "gridSize", 4); // MAX : 4
JsonUtils.jsonPut(config, "layout", layout);

//highlight-next-line
// Theme of recording
JsonUtils.jsonPut(config, "theme", "DARK"); //  "LIGHT" | "DEFAULT"

//highlight-next-line
// `mode` is used to either record video & audio both or only audio.
JsonUtils.jsonPut(config, "mode", "video-and-audio"); // "audio", Default : "video-and-audio"

//highlight-next-line
// Quality of recording and is only applicable to `video-and-audio` type mode.
JsonUtils.jsonPut(config, "quality", "high"); /* Default : "med"
   "low" (SD Recording) | "med" (HD Recording) | "high" (FHD Recording) */

//highlight-start
// This mode refers to orientation of recording.
// landscape : Record the meeting in horizontally
// portrait : Record the meeting in vertically (Best for mobile view)
//highlight-end
JsonUtils.jsonPut(config, "orientation", "portrait"); // "landscape",  Default : "landscape"

//highlight-next-line
// Post Transcription Configuration
String prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary";
SummaryConfig summaryConfig = new SummaryConfig(true, prompt);
String modelId = "raman_v1";
PostTranscriptionConfig transcription = new PostTranscriptionConfig(true, summaryConfig, modelId);

meeting.startRecording(null, null, config, transcription);
```

### `stopRecording()`

- `stopRecording()` is used to stop the meeting recording which can be accessed from the `Meeting` class.

#### Example

**Kotlin:**

```js
// keep track of recording
val recording = false

findViewById<View>(R.id.btnRecording).setOnClickListener { view: View? ->
if (!recording) {
  //highlight-start
  val config = JSONObject()
  val layout = JSONObject()
  JsonUtils.jsonPut(layout, "type", "GRID")
  JsonUtils.jsonPut(layout, "priority", "SPEAKER")
  JsonUtils.jsonPut(layout, "gridSize", 4)
  JsonUtils.jsonPut(config, "layout", layout)
  JsonUtils.jsonPut(config, "theme", "DARK")
  JsonUtils.jsonPut(config, "mode", "video-and-audio")
  JsonUtils.jsonPut(config, "quality", "high")
  JsonUtils.jsonPut(config, "orientation", "portrait")
  //highlight-end

  //highlight-next-line
  // Post Transcription Configuration
  val prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
  val summaryConfig = SummaryConfig(true, prompt)
  val modelId = "raman_v1"
  val transcription = PostTranscriptionConfig(true, summaryConfig, modelId)

  // Start Recording
  // If you don't have a `webhookUrl` or `awsDirPath`, you should pass null.
  // If you don't want to enable transcription, you can pass null as parameter.
  //highlight-next-line
  meeting!!.startRecording("YOUR WEB HOOK URL", "AWS Directory Path", config, transcription)
} else {
  // Stop Recording
  //highlight-next-line
  meeting!!.stopRecording()
}
}
```

---

**Java:**

```js
// keep track of recording
boolean recording = false;

findViewById(R.id.btnRecording).setOnClickListener(view -> {
if (!recording) {
  //highlight-start
  JSONObject config = new JSONObject();
  JSONObject layout = new JSONObject();
  JsonUtils.jsonPut(layout, "type", "GRID");
  JsonUtils.jsonPut(layout, "priority", "SPEAKER");
  JsonUtils.jsonPut(layout, "gridSize", 4);
  JsonUtils.jsonPut(config, "layout", layout);
  JsonUtils.jsonPut(config, "theme", "DARK");
  JsonUtils.jsonPut(config, "mode", "video-and-audio");
  JsonUtils.jsonPut(config, "quality", "high");
  JsonUtils.jsonPut(config, "orientation", "portrait");
  //highlight-end

  //highlight-next-line
  // Post Transcription Configuration
  String prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary";
  SummaryConfig summaryConfig = new SummaryConfig(true, prompt);
  String modelId = "raman_v1";
  PostTranscriptionConfig transcription = new PostTranscriptionConfig(true, summaryConfig, modelId);

  // Start Recording
  // If you don't have a `webhookUrl` or `awsDirPath`, you should pass null.
  // If you don't want to enable transcription, you can pass null as parameter.
  //highlight-next-line
  meeting.startRecording("YOUR WEB HOOK URL", "AWS Directory Path", config, transcription);
} else {
  // Stop Recording
  //highlight-next-line
  meeting.stopRecording();
}
});
```

:::important

To initiate automatic recording at the beginning of a `session`, simply provide the `autoStartConfig` feature `recording` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.

:::

### API Reference

The API references for all the methods utilised in this guide are provided below.

- [startRecording()](/android/api/sdk-reference/meeting-class/methods#startrecording)
- [stopRecording()](/android/api/sdk-reference/meeting-class/methods#stoprecording)
- [onRecordingStateChanged](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onrecordingstatechanged)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

VideoSDK offers individual participant recording, generating a single, continuous file for a participant.

This recording captures the participant's audio and video streams throughout the meeting, regardless of whether they are muted or have their camera turned off. During periods of audio muting or video disengagement, the respective tracks will be silent or display a black screen, respectively.

You can access the recorded files in the developer dashboard or opt to store them in your own cloud storage.

This guide provides an overview of the start and stop functionality for individual participant recording through APIs.


## Start Individual Participant Recording

To start a participant recording, you will have to call `/v2/recordings/participant/start` API with following body parameters.

- `roomId`: RoomId for which the participant recording is to be started
- `participantId`: participantId of the participant to be recorder.
- `fileFormat`: Currently only `webm` is supported as file format. We will add the support for other formats in future.
- `webhookUrl`: The webhook URL where you would like to get the status updates of the recording. To learn more about webhooks refer [here](#participant-track-recording-starting).
- `bucketDirPath`: If you are using your own storage, you can provide the directory path where you want to store the recording. To configure the storage please [refere this quide](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config).

The usual recording path would look like `${sessionId}/${participantId}/${filename}`.



**Kotlin:**

```kotlin
import org.json.JSONObject
import java.io.OutputStream
import java.net.HttpURLConnection
import java.net.URL
import java.io.IOException

fun StartParticipantRecording() {
val roomId = "<YOUR ROOM ID>"
val participantId = "<PARTICIPANT ID>"
val fileFormat = "<YOUR FILE FORMAT>" // (Optional) default: webm
val bucketDirPath = "<YOUR CLOUD STORAGE BUCKET PATH>" // (Optional) test/abc
val webhookUrl = "<YOUR WEBHOOK URL>" // (Optional)

try {
    val url = URL("https://api.videosdk.live/v2/recordings/participant/start")
    val conn = url.openConnection() as HttpURLConnection
    conn.requestMethod = "POST"
    conn.setRequestProperty("Authorization", "$YOUR_TOKEN")
    conn.setRequestProperty("Content-Type", "application/json")
    conn.doOutput = true

    val json = JSONObject()
    json.put("roomId", roomId)
    json.put("participantId", participantId)
    json.put("fileFormat", fileFormat)
    json.put("bucketDirPath", bucketDirPath)
    json.put("webhookUrl", webhookUrl)

    conn.outputStream.use { os: OutputStream ->
        val input = json.toString().toByteArray(Charsets.UTF_8)
        os.write(input, 0, input.size)
    }

    val responseCode = conn.responseCode
    if (responseCode == HttpURLConnection.HTTP_OK) {
        println("Participant Recording started successfully.")
    } else {
        println("Failed to start participant recording.")
    }
} catch (e: Exception) {
    e.printStackTrace()
}
}

```

---

**Java:**

```java
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import org.json.JSONObject;

private void StartParticipantRecording() {
String roomId = "<YOUR ROOM ID>";
String participantId = "<PARTICIPANT ID>";
String fileFormat = "<YOUR FILE FORMAT>"; // (Optional) default: webm
String bucketDirPath = "<YOUR CLOUD STORAGE BUCKET PATH>"; // (Optional) test/abc
String webhookUrl = "<YOUR WEBHOOK URL>"; // (Optional)

try {
    URL url = new URL("https://api.videosdk.live/v2/recordings/participant/start");
    HttpURLConnection conn = (HttpURLConnection) url.openConnection();
    conn.setRequestMethod("POST");
    conn.setRequestProperty("Authorization", "$YOUR_TOKEN");
    conn.setRequestProperty("Content-Type", "application/json");
    conn.setDoOutput(true);

    JSONObject json = new JSONObject();
    json.put("roomId", roomId);
    json.put("participantId", participantId);
    json.put("fileFormat", fileFormat);
    json.put("bucketDirPath", bucketDirPath);
    json.put("webhookUrl", webhookUrl);

    try (OutputStream os = conn.getOutputStream()) {
        byte[] input = json.toString().getBytes("utf-8");
        os.write(input, 0, input.length);
    }

    int responseCode = conn.getResponseCode();
    if (responseCode == HttpURLConnection.HTTP_OK) {
        System.out.println("Participant Recording started successfully.");
    } else {
        System.out.println("Failed to start participant recording.");
    }
} catch (Exception e) {
    e.printStackTrace();
}
}

```

## Stop Individual Participant Recording

To stop a participant recording, you will have to call `/v2/recordings/participant/stop` API with following body parameters.

- `roomId`: RoomId for which the participant recording is to be stopped
- `participantId`: participantId for which the recording is to be stopped.

**Kotlin:**

```kotlin
import org.json.JSONObject
import java.io.OutputStream
import java.net.HttpURLConnection
import java.net.URL

fun StopParticipantRecording() {
val roomId = "<YOUR ROOM ID>"
val participantId = "<PARTICIPANT ID>"

try {
    val url = URL("https://api.videosdk.live/v2/recordings/participant/stop")
    val conn = url.openConnection() as HttpURLConnection
    conn.requestMethod = "POST"
    conn.setRequestProperty("Authorization", "$YOUR_TOKEN")
    conn.setRequestProperty("Content-Type", "application/json")
    conn.doOutput = true

    val json = JSONObject()
    json.put("roomId", roomId)
    json.put("participantId", participantId)

    conn.outputStream.use { os: OutputStream ->
        val input = json.toString().toByteArray(Charsets.UTF_8)
        os.write(input, 0, input.size)
    }

    val responseCode = conn.responseCode
    if (responseCode == HttpURLConnection.HTTP_OK) {
        println("Participant Recording stopped successfully.")
    } else {
        println("Failed to stop participant recording.")
    }
} catch (e: Exception) {
    e.printStackTrace()
}

}

```

---

**Java:**

```java
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import org.json.JSONObject;

private void StopParticipantRecording() {
String roomId = "<YOUR ROOM ID>";
String participantId = "<PARTICIPANT ID>";

try {
    URL url = new URL("https://api.videosdk.live/v2/recordings/participant/stop");
    HttpURLConnection conn = (HttpURLConnection) url.openConnection();
    conn.setRequestMethod("POST");
    conn.setRequestProperty("Authorization", "$YOUR_TOKEN");
    conn.setRequestProperty("Content-Type", "application/json");
    conn.setDoOutput(true);

    JSONObject json = new JSONObject();
    json.put("roomId", roomId);
    json.put("participantId", participantId);

    try (OutputStream os = conn.getOutputStream()) {
        byte[] input = json.toString().getBytes("utf-8");
        os.write(input, 0, input.length);
    }

    int responseCode = conn.getResponseCode();
    if (responseCode == HttpURLConnection.HTTP_OK) {
        System.out.println("Participant Recording stopped successfully.");
    } else {
        System.out.println("Failed to stop participant recording.");
    }
} catch (Exception e) {
    e.printStackTrace();
}
}


```

## Webhook associated with Participant Recording

### participant-recording-starting

- A "Participant Recording Starting" webhook is triggered when the participant recording process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-started

- Participant Recording started webhook will be received when successfully participant recording is started in meeting

###### Example

```javascript
{
    "webhookType": "participant-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopping

- A "Participant Recording Stopping" webhook is triggered when the participant recording end process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopped

- Participant Recording stopped webhook will be received when participant recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "participant-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-recording-failed

- A "Participant Recording Failed" webhook is generated when the participant recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "participant-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
    },
}
```

---

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Participant Recording API](/api-reference/realtime-communication/start-participant-recording)
- [Stop Participant Recording API](/api-reference/realtime-communication/stop-participant-recording)



---

VideoSDK provides participant track recording, creating separate audio or video files for participant.

New files are generated when a participant starts their audio or video again after turning it off (e.g., unmuting the microphone or restarting the camera). This ensures that each file represents a continuous segment of audio or video content.

Once track recording is complete, all audio files for a participant are consolidated into a single directory, as are the video files.


## Start Participant Track Recording

To start a participant track recording, you will have to call `/v2/recordings/participant/track/start` API with following body parameters.

- `roomId`: RoomId for which the participant track recording is to be started
- `participantId`: participantId of the participant to be recorder.
- `kind`: The kind of tracks you want to record.
  - You can pass following values: _`audio`_ | _`video`_ | _`screen_audio`_ | _`screen_video`_
- `fileFormat`: Currently only `webm` is supported as file format. We will add the support for other formats in future.
- `webhookUrl`: The webhook URL where you would like to get the status updates of the recording. To learn more about webhooks refer [here](#participant-track-recording-starting).
- `bucketDirPath`: If you are using your own storage, you can provide the directory path where you want to store the recording. To configure the storage please [refere this quide](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config).

The usual recording path would look like `${sessionId}/${participantId}/${kind}/${filename}`.



**Kotlin:**

```kotlin
import org.json.JSONObject
import java.io.OutputStream
import java.net.HttpURLConnection
import java.net.URL
import java.io.IOException

fun StartTrackRecording() {
val roomId = "<YOUR ROOM ID>"
val participantId = "<PARTICIPANT ID>"
val kind = "<YOUR STREAM KIND>"
val fileFormat = "<YOUR FILE FORMAT>"
val bucketDirPath = "<YOUR CLOUD STORAGE BUCKET PATH>"
val webhookUrl = "<YOUR WEBHOOK URL>"

try {
    val url = URL("https://api.videosdk.live/v2/recordings/participant/track/start")
    val conn = url.openConnection() as HttpURLConnection
    conn.requestMethod = "POST"
    conn.setRequestProperty("Authorization", "$YOUR_TOKEN")
    conn.setRequestProperty("Content-Type", "application/json")
    conn.doOutput = true

    val jsonBody = JSONObject()
    jsonBody.put("roomId", roomId)
    jsonBody.put("participantId", participantId)
    jsonBody.put("kind", kind)
    jsonBody.put("fileFormat", fileFormat)
    jsonBody.put("bucketDirPath", bucketDirPath)
    jsonBody.put("webhookUrl", webhookUrl)

    conn.outputStream.use { os: OutputStream ->
        val input = json.toString().toByteArray(Charsets.UTF_8)
        os.write(input, 0, input.size)
    }

    val responseCode = conn.responseCode
    if (responseCode == HttpURLConnection.HTTP_OK) {
        println("Track Recording started successfully.")
    } else {
        println("Failed to start track recording.")
    }
} catch (e: Exception) {
    e.printStackTrace()
}
}



```

---

**Java:**

```java
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import org.json.JSONObject;

public void StartTrackRecording() {
String roomId = "<YOUR ROOM ID>";
String participantId = "<PARTICIPANT ID>";
String kind = "<YOUR STREAM KIND>";
String fileFormat = "<YOUR FILE FORMAT>";
String bucketDirPath = "<YOUR CLOUD STORAGE BUCKET PATH>";
String webhookUrl = "<YOUR WEBHOOK URL>";

try {
    URL url = new URL("https://api.videosdk.live/v2/recordings/participant/track/start");
    HttpURLConnection conn = (HttpURLConnection) url.openConnection();
    conn.setRequestMethod("POST");
    conn.setRequestProperty("Authorization", "$YOUR_TOKEN");
    conn.setRequestProperty("Content-Type", "application/json");
    conn.setDoOutput(true);

    JSONObject jsonBody = new JSONObject();
    jsonBody.put("roomId", roomId);
    jsonBody.put("participantId", participantId);
    jsonBody.put("kind", kind);
    jsonBody.put("fileFormat", fileFormat);
    jsonBody.put("bucketDirPath", bucketDirPath);
    jsonBody.put("webhookUrl", webhookUrl);

    try (OutputStream os = conn.getOutputStream()) {
    byte[] input = json.toString().getBytes("utf-8");
    os.write(input, 0, input.length);
    }

    int responseCode = conn.getResponseCode();
    if (responseCode == HttpURLConnection.HTTP_OK) {
        System.out.println("Track Recording started successfully.");
    } else {
        System.out.println("Failed to start track recording.");
    }
} catch (Exception e) {
    e.printStackTrace();
}
}

```

## Stop Participant Track Recording

To stop a participant track recording, you will have to call `/v2/recordings/participant/track/stop` API with following body parameters.

- `roomId`: RoomId for which the participant track recording is to be stopped
- `participantId`: participantId for which the recording is to be stopped.
- `kind`: The kind of track recording you want to stop for the given participant.
  - You can pass following values: _`audio`_ | _`video`_ | _`screen_audio`_ | _`screen_video`_

**Kotlin:**

```kotlin
import org.json.JSONObject
import java.io.OutputStream
import java.net.HttpURLConnection
import java.net.URL

fun StopTrackRecording() {
val roomId = "<YOUR ROOM ID>"
val participantId = "<PARTICIPANT ID>"
val kind = "<YOUR STREAM KIND>"

try {
    val url = URL("https://api.videosdk.live/v2/recordings/participant/track/stop")
    val conn = url.openConnection() as HttpURLConnection
    conn.requestMethod = "POST"
    conn.setRequestProperty("Authorization", "$YOUR_TOKEN")
    conn.setRequestProperty("Content-Type", "application/json")
    conn.doOutput = true

    val jsonBody = JSONObject()
    jsonBody.put("roomId", roomId)
    jsonBody.put("participantId", participantId)
    jsonBody.put("kind", kind)

    conn.outputStream.use { os: OutputStream ->
        val input = json.toString().toByteArray(Charsets.UTF_8)
        os.write(input, 0, input.size)
    }

    val responseCode = conn.responseCode
    if (responseCode == HttpURLConnection.HTTP_OK) {
        println("Track Recording stopped successfully.")
    } else {
        println("Failed to stop track recording.")
    }
} catch (e: Exception) {
    e.printStackTrace()
}
}

```

---

**Java:**

```java
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import org.json.JSONObject;

public void StopTrackRecording() {
String roomId = "<YOUR ROOM ID>";
String participantId = "<PARTICIPANT ID>";
String kind = "<YOUR STREAM KIND>";


try {
    URL url = new URL("https://api.videosdk.live/v2/recordings/participant/track/stop");
    HttpURLConnection conn = (HttpURLConnection) url.openConnection();
    conn.setRequestMethod("POST");
    conn.setRequestProperty("Authorization", "$YOUR_TOKEN");
    conn.setRequestProperty("Content-Type", "application/json");
    conn.setDoOutput(true);

    JSONObject jsonBody = new JSONObject();
    jsonBody.put("roomId", roomId);
    jsonBody.put("participantId", participantId);
    jsonBody.put("kind", kind);

    try (OutputStream os = conn.getOutputStream()) {
    byte[] input = json.toString().getBytes("utf-8");
    os.write(input, 0, input.length);
    }

    int responseCode = conn.getResponseCode();
    if (responseCode == HttpURLConnection.HTTP_OK) {
        System.out.println("Track Recording stopped successfully.");
    } else {
        System.out.println("Failed to stop track recording.");
    }
} catch (Exception e) {
    e.printStackTrace();
}
}

```

## Webhook associated with Participant Track Recording

### participant-track-recording-starting

- A "Participant Track Recording Starting" webhook is triggered when the track recording process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-started

- Participant Track Recording started webhook will be received when successfully track recording is started in meeting

###### Example

```javascript
{
    "webhookType": "participant-track-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopping

- A "Participant Track Recording Stopping" webhook is triggered when the track recording end process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopped

- Participant Track Recording stopped webhook will be received when track recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-track-recording-failed

- A "Participant Track Recording Failed" webhook is generated when the track recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Track Recording API](/api-reference/realtime-communication/start-track-recording)
- [Stop Track Recording API](/api-reference/realtime-communication/stop-track-recording)



---

### Storage Configuration

While recording your meetings, you have the flexibility to store them either on VideoSDK's storage or configure your own storage solution such as **`AWS S3 Storage, Azure Blob or GCP Cloud Storage`**. To set up your own storage, you can navigate to the [API section](https://app.videosdk.live/api-keys) in the VideoSDK Dashboard.

- This feature allows you to configure storage provider for your meeting recordings.

- You can configure multiple storage provider with multiple API Keys.

- Currently, we support `AWS S3`, `Azure Blob` and `GCP Cloud Storage`. We will add support for other storage provider soon !!

## Prerequisites

- An active [VideoSDK Developer Account](https://app.videosdk.live)
- `Aws S3`, `Azure Blob Storage` or `GCP Cloud Storage` Credentials

## How to setup ?

### Step 1 : Select Api Key

![Dashboard](/img/tutorial/dashboard/api-key-dashboard.png)

- Go to [VideoSDK Dashboard](https://app.videosdk.live/api-keys).
- Select API Key for which, you want to set storage configuration.
- Then click on `Storage Config` Icon in Actions.

### Step 2 : Choose Cloud Storage Provider

![Dashboard](/img/tutorial/dashboard/storage-config.png)

- As you can see in the image, there are 3 Cloud Storage Provider (`Aws`, `Azure`, `GCP`).
- You can select a Cloud Storage Provider as per your requirements.

### Step 3 : Configure Bucket or Container

<h4> For Aws S3 Storage </h4>

![Aws S3](/img/tutorial/dashboard/s3.png)

- You will need AWS S3 Bucket. [Learn to create S3 Bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html).

- As you can see in the image, you will need enter `accessKeyId`, `secretAccessKey`, `region`, `bucket`, and `ACL` to setup for Aws S3 Storage.

- Click on `Save` button.

<hr />

<h4> For Azure Blob Storage: </h4>

![Azure Blob](/img/tutorial/dashboard/blob.png)

- You will need Azure Blob Container. [Learn to create Blob Container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal#create-a-container).

- As you can see in the image, you will need to enter `connectionString` and `containerName` to setup for Azure Blob.

- Click on `Save` button.

<hr />

<h4> For Google Cloud Storage: </h4>

<img src="/img/tutorial/dashboard/gcp.png" alt="GCP Cloud Storage" width="436" height="632"/>

1. You will need Google Cloud Storage Bucket. [Learn to create Google Cloud Storage Bucket](https://cloud.google.com/storage/docs/creating-buckets).

2. After creation, click on the <b> &#xFE19; </b>button in the upper right corner and select **`Project settings`**.

3. Under **`IAM and Admin`**, select **`Service Accounts`**. In the service account list, click on the <b> &#xFE19; </b> button for the account just added or created before, and select **`Manage keys`**.

4. Click **`ADD KEY > Create new key`**. Select **`JSON`** in the pop-up box and click **`CREATE`**. A json file is downloaded with the name format `projectId-xxxxxxxx.json`.

5. Open the downloaded json file, which looks like the following example:

```
{
  "type": "service_account",
  "project_id": "videosdk-12345",
  "private_key_id": "yourprivateidkeyyourprivateidkeyyourprivateidkey",
  "private_key": "-----BEGIN PRIVATE KEY-----\nThisisYourPrivateKeyThisisYourPrivateKeyThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\n-----END PRIVATE KEY-----\n",
  "client_email": "xxxx-xxxx@videosdk-12345.iam.gserviceaccount.com",
  "client_id": "123456789012345678901",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/videosdk%40videosdk-404307.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}
```

- As you can see in the image, you will need to enter `Project Id`, `Client Email`, `Bucket`, `Private Key` to setup for Google Cloud Storage Bucket. You can retrieve these details from the json file.

- Click on `Save` button.

### Step 4 : Test

- It's time to test !!
- [Create Room](https://docs.videosdk.live/api-reference/realtime-communication/create-room) with token generated with the API Key, you have configured for.
- Start meeting with the roomId created and Start Recording !!
- Then, you can see that recording will be available in your Bucket or Container.

:::note

- Only a single Recording Storage Config can be possible for a particular Api Key at a time.
- In order to add new Recording Configuration, first you need to delete current configuration.

:::


---

# Webhooks and Events - Android

### Event associated with Recording

- **onRecordingStateChanged** - Whenever meeting recording state changes, then `onRecordingStateChanged` event will trigger.



**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onRecordingStateChanged(recordingState: String) {
when (recordingState) {
    "RECORDING_STARTING" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is starting")
    }
    "RECORDING_STARTED" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is started")
    }
    "RECORDING_STOPPING" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is stopping")
    }
    "RECORDING_STOPPED" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is stopped")
    }
}
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onRecordingStateChanged(String recordingState) {
  switch (recordingState) {
      case "RECORDING_STARTING":
          Log.d("onRecordingStateChanged", "Meeting recording is starting");
          break;
      case "RECORDING_STARTED":
          Log.d("onRecordingStateChanged", "Meeting recording is started");
          break;
      case "RECORDING_STOPPING":
          Log.d("onRecordingStateChanged", "Meeting recording is stopping");
          break;
      case "RECORDING_STOPPED":
          Log.d("onRecordingStateChanged", "Meeting recording is stopped");
          break;
  }
  }
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting.addEventListener(meetingEventListener);
}
```

## Webhook associated with Recording

### recording-starting

- A "Recording Starting" webhook is triggered when the recording process for a meeting is initiated.

###### Example

```javascript
{
    "webhookType": "recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-started

- Recording started webhook will be received when successfully recording is started in meeting

###### Example

```javascript
{
    "webhookType": "recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopping

- A "Recording Stopping" webhook is triggered when the recording end process for a meeting is initiated.

###### Example

```javascript
{
    "webhookType": "recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopped

- Recording stopped webhook will be received when recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
        "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",

    },
}
```

---

### recording-failed

- A "Recording Failed" webhook is generated when the recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```


---

# Interactive Livestream (HLS) - Android

Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

In an interactive live stream (HLS), viewers can take part in a variety of activities like live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/mobile_hls.png' />

</center>

VideoSDK also allows you to configure the interactive livestream layouts in numerous ways like by simply setting different prebuilt layouts in the configuration or by providing your own custom template to do the livestream according to your layout choice.

This guide will provide an overview of how to implement start and stop Interactive live streaming (HLS).

:::important

To initiate automatic Interactive live streaming (HLS) at the beginning of a `session`, simply provide the `autoStartConfig` feature `hls` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.

:::

### `startHls()`

`startHls()` can be used to start a interactive livestream of the meeting which can be accessed from the `Meeting` class. This method accepts two parameter:

- `config`: This parameter will define how the interactive livestream layout should look like.

- `transcription`: This parameter lets you start post transcription for the Livestreaming.




**Kotlin:**

```js
val config = JSONObject()

//highlight-next-line
// Layout Configuration
val layout = JSONObject()
JsonUtils.jsonPut(layout, "type", "GRID") // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
JsonUtils.jsonPut(layout, "priority", "SPEAKER") // "PIN", Default : "SPEAKER"
JsonUtils.jsonPut(layout, "gridSize", 4) // MAX : 25
JsonUtils.jsonPut(config, "layout", layout)

//highlight-next-line
// Theme of interactive livestream layout
JsonUtils.jsonPut(config, "theme", "DARK") //  "LIGHT" | "DEFAULT"

//highlight-next-line
// `mode` is used to either interactive livestream video & audio both or only audio.
JsonUtils.jsonPut(config, "mode", "video-and-audio") // "audio", Default : "video-and-audio"

//highlight-next-line
// Quality of interactive livestream and is only applicable to `video-and-audio` type mode.
JsonUtils.jsonPut(config, "quality", "high") /* Default : "med"
   "low" (SD HLS) | "med" (HD HLS) | "high" (FHD HLS) */

//highlight-start
// This mode refers to orientation of interactive livestream.
// landscape : Start interactive livestream of the meeting in horizontally
// portrait : Start interactive livestream of the meeting in vertically (Best for mobile view)
//highlight-end
JsonUtils.jsonPut(config, "orientation", "portrait") // "landscape",  Default : "landscape"

//highlight-next-line
// Post Transcription Configuration
val prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
val summaryConfig = SummaryConfig(true, prompt)
val modelId = "raman_v1"
val transcription = PostTranscriptionConfig(true, summaryConfig, modelId)

meeting.startHls(config, transcription)
```

---

**Java:**

```js
JSONObject config = new JSONObject();

//highlight-next-line
// Layout Configuration
JSONObject layout = new JSONObject();
JsonUtils.jsonPut(layout, "type", "GRID"); // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
JsonUtils.jsonPut(layout, "priority", "SPEAKER");  // "PIN", Default : "SPEAKER"
JsonUtils.jsonPut(layout, "gridSize", 4); // MAX : 25
JsonUtils.jsonPut(config, "layout", layout);

//highlight-next-line
// Theme of interactive livestream layout
JsonUtils.jsonPut(config, "theme", "DARK"); //  "LIGHT" | "DEFAULT"

//highlight-next-line
// `mode` is used to either interactive livestream video & audio both or only audio.
JsonUtils.jsonPut(config, "mode", "video-and-audio"); // "audio", Default : "video-and-audio"

//highlight-next-line
// Quality of interactive livestream and is only applicable to `video-and-audio` type mode.
JsonUtils.jsonPut(config, "quality", "high"); /* Default : "med"
   "low" (SD HLS) | "med" (HD HLS) | "high" (FHD HLS) */

//highlight-start
// This mode refers to orientation of interactive livestream.
// landscape : Start interactive livestream of the meeting in horizontally
// portrait : Start interactive livestream of the meeting in vertically (Best for mobile view)
//highlight-end
JsonUtils.jsonPut(config, "orientation", "portrait"); // "landscape",  Default : "landscape"

//highlight-next-line
// Post Transcription Configuration
String prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary";
SummaryConfig summaryConfig = new SummaryConfig(true, prompt);
String modelId = "raman_v1";
PostTranscriptionConfig transcription = new PostTranscriptionConfig(true, summaryConfig, modelId);

meeting.startHls(config, transcription);
```

### `stopHls()`

- `stopHls()` is used to stop interactive livestream of the meeting which can be accessed from the `Meeting` class.

#### Example

**Kotlin:**

```js
// keep track of hls
val hls = false

findViewById<View>(R.id.btnHls).setOnClickListener { view: View? ->
  if (!hls) {
//highlight-start
val config = JSONObject()
val layout = JSONObject()
JsonUtils.jsonPut(layout, "type", "GRID")
JsonUtils.jsonPut(layout, "priority", "SPEAKER")
JsonUtils.jsonPut(layout, "gridSize", 4)
JsonUtils.jsonPut(config, "layout", layout)
JsonUtils.jsonPut(config, "theme", "DARK")
JsonUtils.jsonPut(config, "mode", "video-and-audio")
JsonUtils.jsonPut(config, "quality", "high")
JsonUtils.jsonPut(config, "orientation", "portrait")
//highlight-end

//highlight-next-line
// Post Transcription Configuration
val prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
val summaryConfig = SummaryConfig(true, prompt)
val modelId = "raman_v1"
val transcription = PostTranscriptionConfig(true, summaryConfig, modelId)

// Start Hls
//highlight-next-line
meeting!!.startHls(config)
  } else {
// Stop Hls
//highlight-next-line
meeting!!.stopHls()
  }
}
```

---

**Java:**

```js
// keep track of hls
boolean hls = false;

findViewById(R.id.btnHls).setOnClickListener(view -> {
  if (!hls) {
//highlight-start
JSONObject config = new JSONObject();
JSONObject layout = new JSONObject();
JsonUtils.jsonPut(layout, "type", "GRID");
JsonUtils.jsonPut(layout, "priority", "SPEAKER");
JsonUtils.jsonPut(layout, "gridSize", 4);
JsonUtils.jsonPut(config, "layout", layout);
JsonUtils.jsonPut(config, "theme", "DARK");
JsonUtils.jsonPut(config, "mode", "video-and-audio");
JsonUtils.jsonPut(config, "quality", "high");
JsonUtils.jsonPut(config, "orientation", "portrait");
//highlight-end

//highlight-next-line
// Post Transcription Configuration
String prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary";
SummaryConfig summaryConfig = new SummaryConfig(true, prompt);
String modelId = "raman_v1";
PostTranscriptionConfig transcription = new PostTranscriptionConfig(true, summaryConfig, modelId);

// Start Hls
//highlight-next-line
meeting.startHls(config);
  } else {
// Stop Hls
//highlight-next-line
meeting.stopHls();
  }
});
```

:::tip
If you want to learn more about the Interactive Livestream and how you can implement it in your own platform, you can checkout this [guide](/android/guide/interactive-live-streaming/integrate-hls/overview).
:::

### Event associated with HLS

- **onHlsStateChanged** - Whenever meeting HLS state changes, then `onHlsStateChanged` event will trigger.

- You can get the `playbackHlsUrl` and `livestreamUrl` of the HLS to play it on the Viewer side when the state changes to `HLS_PLAYABLE`.
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onHlsStateChanged(HlsState: JSONObject) {
when (HlsState.getString("status")) {
    "HLS_STARTING" -> Log.d("onHlsStateChanged", "Meeting hls is starting")
    "HLS_STARTED" -> Log.d("onHlsStateChanged", "Meeting hls is started")
    "HLS_PLAYABLE" -> {
        Log.d("onHlsStateChanged", "Meeting hls is playable now")
        //highlight-start
         // on hls playable you will receive playbackHlsUrl and livestreamUrl
        val playbackHlsUrl = HlsState.getString("playbackHlsUrl")
        val livestreamUrl = HlsState.getString("livestreamUrl")
        //highlight-end
    }
    "HLS_STOPPING" -> Log.d("onHlsStateChanged", "Meeting hls is stopping")
    "HLS_STOPPED" -> Log.d("onHlsStateChanged", "Meeting hls is stopped")
}
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onHlsStateChanged(JSONObject HlsState) {
  switch (HlsState.getString("status")) {
      case "HLS_STARTING":
          Log.d("onHlsStateChanged", "Meeting hls is starting");
          break;
      case "HLS_STARTED":
          Log.d("onHlsStateChanged", "Meeting hls is started");
          break;
      case "HLS_PLAYABLE":
          Log.d("onHlsStateChanged", "Meeting hls is playable now");
          //highlight-start
          // on hls started you will receive playbackHlsUrl and livestreamUrl
          String playbackHlsUrl = HlsState.getString("playbackHlsUrl");
          String livestreamUrl = HlsState.getString("livestreamUrl");
          //highlight-end
          break;
      case "HLS_STOPPING":
          Log.d("onHlsStateChanged", "Meeting hls is stopping");
          break;
      case "HLS_STOPPED":
          Log.d("onHlsStateChanged", "Meeting hls is stopped");
          break;
  }
  }
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting.addEventListener(meetingEventListener);
}
```

### Custom Template

With VideoSDK, you can also use your own custom designed layout template to livestream the meetings. In order to use the custom template, you need to create a template for which you can [follow this guide](/react/guide/interactive-live-streaming/custom-template). Once you have setup the template, you can use the [REST API to start](/api-reference/realtime-communication/start-livestream) the livestream with the `templateURL` parameter.

### API Reference

The API references for all the methods utilised in this guide are provided below.

- [startHls()](/android/api/sdk-reference/meeting-class/methods#starthls)
- [stopHls()](/android/api/sdk-reference/meeting-class/methods#stophls)
- [onHlsStateChanged](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onhlsstatechanged)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

# Record Meeting - Android

VideoSDK allows you to record video & audio during the meeting. The recording files are available in developer dashboard or you can also choose to store them in your own cloud storage.

VideoSDK also allows you to configure the recording layouts in numerous ways like by simply setting different prebuilt layouts in the configuration or by providing your own custom template to do the recording according to your layout choice.

This guide will provide an overview of how to implement start and stop Meeting Recording.

:::important

To initiate automatic recording at the beginning of a `session`, simply provide the `autoStartConfig` feature `recording` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.

:::

### `startRecording()`

`startRecording()` can be used to start a recording of the meeting which can be accessed from the `Meeting` class. This method accepts four parameters:

- `1. webhookUrl`: This would the webhook URL where you would like to listen to event happening for the recording like starting and stopping of recording. It will be triggered when the recording is completed and stored into server. Read more about webhooks [here](https://en.wikipedia.org/wiki/Webhook)

- `2. awsDirPath`: This parameter accepts the path for the your S3 bucket where you want to store recordings to. To allow us to store recording in your S3 bucket, you will need to fill this form by providing the required values. ([VideoSDK Cloud (AWS S3, Azure Blob or GCP ) Integration](/android/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config))

- `3. config`: This parameter will define how the meeting should be recorded.

- `4. transcription`: This parameter lets you start post transcription for the recording.

:::note

If you don't have a value for `webhookUrl`,`awsDirPath` or `config`, you should pass `null` in place of the missing value. If you pass `null` in `awsDirPath` parameter then by default recordings will be store on the VideoSDK's storage.
:::



**Kotlin:**

```js
val config = JSONObject()

//highlight-next-line
// Layout Configuration
val layout = JSONObject()
JsonUtils.jsonPut(layout, "type", "GRID") // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
JsonUtils.jsonPut(layout, "priority", "SPEAKER") // "PIN", Default : "SPEAKER"
JsonUtils.jsonPut(layout, "gridSize", 4) // MAX : 4
JsonUtils.jsonPut(config, "layout", layout)

//highlight-next-line
// Theme of recording
JsonUtils.jsonPut(config, "theme", "DARK") //  "LIGHT" | "DEFAULT"

//highlight-next-line
// `mode` is used to either record video & audio both or only audio.
JsonUtils.jsonPut(config, "mode", "video-and-audio") // "audio", Default : "video-and-audio"

//highlight-next-line
// Quality of recording and is only applicable to `video-and-audio` type mode.
JsonUtils.jsonPut(config, "quality", "high") /* Default : "med"
   "low" (SD Recording) | "med" (HD Recording) | "high" (FHD Recording) */

//highlight-start
// This mode refers to orientation of recording.
// landscape : Record the meeting in horizontally
// portrait : Record the meeting in vertically (Best for mobile view)
//highlight-end
JsonUtils.jsonPut(config, "orientation", "portrait") // "landscape",  Default : "landscape"

//highlight-next-line
// Post Transcription Configuration
val prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
val summaryConfig = SummaryConfig(true, prompt)
val modelId = "raman_v1"
val transcription = PostTranscriptionConfig(true, summaryConfig, modelId)

meeting.startRecording(null, null, config, transcription)
```

---

**Java:**

```js
JSONObject config = new JSONObject();

//highlight-next-line
// Layout Configuration
JSONObject layout = new JSONObject();
JsonUtils.jsonPut(layout, "type", "GRID"); // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
JsonUtils.jsonPut(layout, "priority", "SPEAKER");  // "PIN", Default : "SPEAKER"
JsonUtils.jsonPut(layout, "gridSize", 4); // MAX : 4
JsonUtils.jsonPut(config, "layout", layout);

//highlight-next-line
// Theme of recording
JsonUtils.jsonPut(config, "theme", "DARK"); //  "LIGHT" | "DEFAULT"

//highlight-next-line
// `mode` is used to either record video & audio both or only audio.
JsonUtils.jsonPut(config, "mode", "video-and-audio"); // "audio", Default : "video-and-audio"

//highlight-next-line
// Quality of recording and is only applicable to `video-and-audio` type mode.
JsonUtils.jsonPut(config, "quality", "high"); /* Default : "med"
   "low" (SD Recording) | "med" (HD Recording) | "high" (FHD Recording) */

//highlight-start
// This mode refers to orientation of recording.
// landscape : Record the meeting in horizontally
// portrait : Record the meeting in vertically (Best for mobile view)
//highlight-end
JsonUtils.jsonPut(config, "orientation", "portrait"); // "landscape",  Default : "landscape"

//highlight-next-line
// Post Transcription Configuration
String prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary";
SummaryConfig summaryConfig = new SummaryConfig(true, prompt);
String modelId = "raman_v1";
PostTranscriptionConfig transcription = new PostTranscriptionConfig(true, summaryConfig, modelId);

meeting.startRecording(null, null, config, transcription);
```

### `stopRecording()`

- `stopRecording()` is used to stop the meeting recording which can be accessed from the `Meeting` class.

#### Example

**Kotlin:**

```js
// keep track of recording
val recording = false

findViewById<View>(R.id.btnRecording).setOnClickListener { view: View? ->
if (!recording) {
  //highlight-start
  val config = JSONObject()
  val layout = JSONObject()
  JsonUtils.jsonPut(layout, "type", "GRID")
  JsonUtils.jsonPut(layout, "priority", "SPEAKER")
  JsonUtils.jsonPut(layout, "gridSize", 4)
  JsonUtils.jsonPut(config, "layout", layout)
  JsonUtils.jsonPut(config, "theme", "DARK")
  JsonUtils.jsonPut(config, "mode", "video-and-audio")
  JsonUtils.jsonPut(config, "quality", "high")
  JsonUtils.jsonPut(config, "orientation", "portrait")
  //highlight-end

  //highlight-next-line
  // Post Transcription Configuration
  val prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
  val summaryConfig = SummaryConfig(true, prompt)
  val modelId = "raman_v1"
  val transcription = PostTranscriptionConfig(true, summaryConfig, modelId)

  // Start Recording
  // If you don't have a `webhookUrl` or `awsDirPath`, you should pass null.
  // If you don't want to enable transcription, you can pass null as parameter.
  //highlight-next-line
  meeting!!.startRecording("YOUR WEB HOOK URL", "AWS Directory Path", config, transcription)
} else {
  // Stop Recording
  //highlight-next-line
  meeting!!.stopRecording()
}
}
```

---

**Java:**

```js
// keep track of recording
boolean recording = false;

findViewById(R.id.btnRecording).setOnClickListener(view -> {
if (!recording) {
  //highlight-start
  JSONObject config = new JSONObject();
  JSONObject layout = new JSONObject();
  JsonUtils.jsonPut(layout, "type", "GRID");
  JsonUtils.jsonPut(layout, "priority", "SPEAKER");
  JsonUtils.jsonPut(layout, "gridSize", 4);
  JsonUtils.jsonPut(config, "layout", layout);
  JsonUtils.jsonPut(config, "theme", "DARK");
  JsonUtils.jsonPut(config, "mode", "video-and-audio");
  JsonUtils.jsonPut(config, "quality", "high");
  JsonUtils.jsonPut(config, "orientation", "portrait");
  //highlight-end

  //highlight-next-line
  // Post Transcription Configuration
  String prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary";
  SummaryConfig summaryConfig = new SummaryConfig(true, prompt);
  String modelId = "raman_v1";
  PostTranscriptionConfig transcription = new PostTranscriptionConfig(true, summaryConfig, modelId);

  // Start Recording
  // If you don't have a `webhookUrl` or `awsDirPath`, you should pass null.
  // If you don't want to enable transcription, you can pass null as parameter.
  //highlight-next-line
  meeting.startRecording("YOUR WEB HOOK URL", "AWS Directory Path", config, transcription);
} else {
  // Stop Recording
  //highlight-next-line
  meeting.stopRecording();
}
});
```

### Event associated with Recording

- **onRecordingStateChanged** - Whenever meeting recording state changes, then `onRecordingStateChanged` event will trigger.

**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onRecordingStateChanged(recordingState: String) {
when (recordingState) {
    "RECORDING_STARTING" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is starting")
    }
    "RECORDING_STARTED" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is started")
    }
    "RECORDING_STOPPING" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is stopping")
    }
    "RECORDING_STOPPED" -> {
        Log.d("onRecordingStateChanged", "Meeting recording is stopped")
    }
}
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onRecordingStateChanged(String recordingState) {
  switch (recordingState) {
      case "RECORDING_STARTING":
          Log.d("onRecordingStateChanged", "Meeting recording is starting");
          break;
      case "RECORDING_STARTED":
          Log.d("onRecordingStateChanged", "Meeting recording is started");
          break;
      case "RECORDING_STOPPING":
          Log.d("onRecordingStateChanged", "Meeting recording is stopping");
          break;
      case "RECORDING_STOPPED":
          Log.d("onRecordingStateChanged", "Meeting recording is stopped");
          break;
  }
  }
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting.addEventListener(meetingEventListener);
}
```

### Storage Configuration

While recording your meetings, you can choose to store them on the VideoSDK's storage or you can also configure your own **`AWS S3 Storage, Azure Blob or GCP Cloud Storage`** to store the meeting recordings directly on your storage.

You can configure your own **`AWS S3 Storage, Azure Blob or GCP Cloud Storage`** from the [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).

You can also go through this [guide to setup](/docs/tutorials/user-dashboard/recording-storage-config) the storage or watch this [video to configure](https://www.loom.com/share/23a2617f824a4a5da004d14d1a541a9d) your storage.

### Custom Template

With VideoSDK, you can also use your own custom designed layout template to record the meetings. In order to use the custom template, you need to create a template for which you can [follow this guide](/react/guide/interactive-live-streaming/custom-template). Once you have setup the template, you can use the [REST API to start](/api-reference/realtime-communication/start-recording) the recording with the `templateURL` parameter.

### API Reference

The API references for all the methods utilised in this guide are provided below.

- [startRecording()](/android/api/sdk-reference/meeting-class/methods#startrecording)
- [stopRecording()](/android/api/sdk-reference/meeting-class/methods#stoprecording)
- [onRecordingStateChanged](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onrecordingstatechanged)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

# RTMP Livestream - Android

RTMP is a popular protocol for live streaming video content from a VideoSDK to platforms such as YouTube, Twitch, Facebook, and others.

By providing the platform-specific stream key and stream URL, the VideoSDK can connect to the platform's RTMP server and transmit the live video stream.

VideoSDK allows you to livestream your meeting to platform which support RTMP ingestion just by providing the platform-specific stream key and stream URL, we can connect to the platform's RTMP server and transmit the live video stream.

VideoSDK also allows you to configure the livestream layouts in numerous ways like by simply setting different prebuilt layouts in the configuration or by providing your own custom template to do the livestream according to your layout choice.

This guide will provide an overview of how to implement start and stop RTMP Livestreaming.

### `startLivestream()`

`startLivestream()` can be used to start a RTMP livestream of the meeting which can be accessed from the `Meeting` class. This method accepts two parameters:

- `1. outputs`: This parameter accepts a list of `LivestreamOutput` objects which contains the RTMP `url` and `streamKey` of the platforms you want to start the livestream.

- `2. config`: This parameter will define how the livestream layout should look like. You can pass `null` for default layout.



**Kotlin:**

```js
val config = JSONObject()

//highlight-next-line
// Layout Configuration
val layout = JSONObject()
JsonUtils.jsonPut(layout, "type", "GRID") // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
JsonUtils.jsonPut(layout, "priority", "SPEAKER") // "PIN", Default : "SPEAKER"
JsonUtils.jsonPut(layout, "gridSize", 4) // MAX : 4
JsonUtils.jsonPut(config, "layout", layout)

//highlight-next-line
// Theme of livestream layout
JsonUtils.jsonPut(config, "theme", "DARK") //  "LIGHT" | "DEFAULT"

val outputs: MutableList<LivestreamOutput> = ArrayList()
outputs.add(LivestreamOutput(RTMP_URL, RTMP_STREAM_KEY))

meeting!!.startLivestream(outputs,config)
```

---

**Java:**

```js
JSONObject config = new JSONObject();

//highlight-next-line
// Layout Configuration
JSONObject layout = new JSONObject();
JsonUtils.jsonPut(layout, "type", "GRID"); // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
JsonUtils.jsonPut(layout, "priority", "SPEAKER");  // "PIN", Default : "SPEAKER"
JsonUtils.jsonPut(layout, "gridSize", 4); // MAX : 4
JsonUtils.jsonPut(config, "layout", layout);

//highlight-next-line
// Theme of livestream layout
JsonUtils.jsonPut(config, "theme", "DARK"); //  "LIGHT" | "DEFAULT"

List<LivestreamOutput> outputs = new ArrayList<>();
outputs.add(new LivestreamOutput(RTMP_URL, RTMP_STREAM_KEY));

meeting.startLivestream(outputs,config);
```

### `stopLivestream()`

- `stopLivestream()` is used to stop the meeting livestream which can be accessed from the `Meeting` class.

#### Example

**Kotlin:**

```js
// keep track of livestream status
val liveStream = false

findViewById<View>(R.id.btnLiveStream).setOnClickListener { view: View? ->
  if (!liveStream) {
//highlight-start
val config = JSONObject()
val layout = JSONObject()
JsonUtils.jsonPut(layout, "type", "GRID")
JsonUtils.jsonPut(layout, "priority", "SPEAKER")
JsonUtils.jsonPut(layout, "gridSize", 4)
JsonUtils.jsonPut(config, "layout", layout)
JsonUtils.jsonPut(config, "theme", "DARK")
//highlight-end

val outputs: MutableList<LivestreamOutput> = ArrayList()
//highlight-next-line
outputs.add(LivestreamOutput(RTMP_URL, RTMP_STREAM_KEY))

// Start LiveStream
//highlight-next-line
meeting!!.startLivestream(outputs,config)
  } else {
// Stop LiveStream
//highlight-next-line
meeting!!.stopLivestream()
  }
}
```

---

**Java:**

```js
// keep track of livestream status
boolean liveStream = false;

findViewById(R.id.btnLiveStream).setOnClickListener(view -> {
  if (!liveStream) {
//highlight-start
JSONObject config = new JSONObject();
JSONObject layout = new JSONObject();
JsonUtils.jsonPut(layout, "type", "GRID");
JsonUtils.jsonPut(layout, "priority", "SPEAKER");
JsonUtils.jsonPut(layout, "gridSize", 4);
JsonUtils.jsonPut(config, "layout", layout);
JsonUtils.jsonPut(config, "theme", "DARK");
//highlight-end

List<LivestreamOutput> outputs = new ArrayList<>();
//highlight-next-line
outputs.add(new LivestreamOutput(RTMP_URL, RTMP_STREAM_KEY));

// Start LiveStream
//highlight-next-line
meeting.startLivestream(outputs,config);
  } else {
// Stop LiveStream
//highlight-next-line
meeting.stopLivestream();
  }
});
```

## Event associated with Livestream

- **onLivestreamStateChanged** - Whenever meeting livestream state changes, then `onLivestreamStateChanged` event will trigger.

**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onLivestreamStateChanged(livestreamState: String?) {
when (livestreamState) {
  "LIVESTREAM_STARTING" -> Log.d( "LivestreamStateChanged",
      "Meeting livestream is starting"
  )
  "LIVESTREAM_STARTED" -> Log.d( "LivestreamStateChanged",
      "Meeting livestream is started"
  )
  "LIVESTREAM_STOPPING" -> Log.d("LivestreamStateChanged",
      "Meeting livestream is stopping"
  )
  "LIVESTREAM_STOPPED" -> Log.d("LivestreamStateChanged",
      "Meeting livestream is stopped"
  )
}
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
  public void onLivestreamStateChanged(String livestreamState) {
switch (livestreamState) {
  case "LIVESTREAM_STARTING":
      Log.d("LivestreamStateChanged", "Meeting livestream is starting");
      break;
  case "LIVESTREAM_STARTED":
      Log.d("LivestreamStateChanged", "Meeting livestream is started");
      break;
  case "LIVESTREAM_STOPPING":
      Log.d("LivestreamStateChanged", "Meeting livestream is stopping");
      break;
  case "LIVESTREAM_STOPPED":
      Log.d("LivestreamStateChanged", "Meeting livestream is stopped");
      break;
}
  }
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting.addEventListener(meetingEventListener);
}
```

### Custom Template

With VideoSDK, you can also use your own custom designed layout template to livestream the meetings. In order to use the custom template, you need to create a template for which you can [follow this guide](/react/guide/interactive-live-streaming/custom-template). Once you have setup the template, you can use the [REST API to start](/api-reference/realtime-communication/start-livestream) the livestream with the `templateURL` parameter.

### API Reference

The API references for all the methods utilised in this guide are provided below.

- [startLivestream()](/android/api/sdk-reference/meeting-class/methods#startlivestream)
- [stopLivestream()](/android/api/sdk-reference/meeting-class/methods#stoplivestream)
- [onLivestreamStateChanged](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onlivestreamstatechanged)


---

# Release Notes - Android




---

# Render Participant - Android

In this guide, we will take a look at how to render the participant's video on the screen.

:::info

- Here the participant's video is displayed using `VideoView`, but you may also use `SurfaceViewRender` for the same.
- For `VideoView`, SDK version should be `0.1.13` or higher.
- To know more about `VideoView`, please visit [here](./understand-videoView-component)

:::

## Steps to render panticipant

**`Step 1:`** Create a new layout for the participant view named `item_participant.xml` in the `res/layout` folder.

```xml title="item_participant.xml"
<?xml version="1.0" encoding="utf-8"?>


    <live.videosdk.rtc.android.VideoView
        android:id="@+id/participantView"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:visibility="gone" />

    

    </LinearLayout>
</FrameLayout>
```

**`Step 2:`** Now, Create a recycler view adapter named `ParticipantAdapter` which will show the participant list. Create `PeerViewHolder` in the adapter which will extend `RecyclerView.ViewHolder`



**Kotlin:**

```js title="ParticipantAdapter.kt"
class ParticipantAdapter(meeting: Meeting) : RecyclerView.Adapter

</center>

## Mirror Local Video View

If you wish to show the mirror view of the local participant, you can set `setMirror` property to `true` of `VideoView` class.

**Kotlin:**

```js title="PartipantAdapter.kt"
class ParticipantAdapter(meeting: Meeting) :
RecyclerView.Adapter<ParticipantAdapter.PeerViewHolder>() {

  override fun onBindViewHolder(holder: PeerViewHolder, position: Int) {
//...
holder.tvName.text = participant.displayName
//highlight-next-line
holder.participantView.setMirror(true)
//...
  }
}
```

---

**Java:**

```java title="PartipantAdapter.java"
public class ParticipantAdapter extends RecyclerView.Adapter<ParticipantAdapter.PeerViewHolder> {

  @Override
  public void onBindViewHolder(@NonNull PeerViewHolder holder, int position) {
//...
holder.tvName.setText(participant.getDisplayName());
//highlight-next-line
holder.participantView.setMirror(true);
//...
  };
}
```

##### Sample of mirror view video

![mirror view](/img/mirror-view.jpg)

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [Participant](/android/api/sdk-reference/participant-class/introduction)
- [VideoView](./understand-videoView-component)


---

# What is SurfaceViewRender ?

`SurfaceViewRender` is a very powerful component of `WebRTC` since it is used to display the video stream on a SurfaceView. You can use `SurfaceViewRender` to show video of participant in your screen.

Here's the lifecycle of a SurfaceViewRenderer:

<div style={{textAlign: 'center'}}>

<img style={{height: '200px'}} src="/img/android/VideoView/life-cycle.png" />

</div>

Which means:

1. The SurfaceViewRenderer must be first initialised after being created and before it can be use at all. It starts a render thread.

2. `addSink()` needs to be called when you are having VideoTrack to render. addSink is method of `VideoTrack` that you want to add to it. You have to pass `surfaceViewRender` as parameter.

3. `removeSink()` should only be called when you're done showing the video. Another method of `VideoTrack`, and it takes the `surfaceViewRenderer` as a parameter.

4. Release at last to allow the render thread to terminate. This function should be called before the activity is destroyed and/or before init it again.

#### Mistakes you might make and stuck :

###### 1. Not initialised surfaceViewRender

The video never appears since a render thread was never start and you will see black view.

###### 2. Init it again before releasing it.

If you are not releasing surfaceViewRender before calling `init()` again, you will get this error.

```js
java.lang.IllegalStateException: svrParticipant Already initialized
        at org.webrtc.EglRenderer.init(EglRenderer.java:212)
```

###### 3. Two videos render on same SurfaceViewRender

If you called `addSink()` on the same `SurfaceViewRenderer` for two different tracks and did not call `removeSink` before that, then you will see two different videos on same SurfaceViewRenderer with flickers which would look like this :


<div style={{textAlign: 'center'}}>



</div>

<br/>

Too complicated right? However, VideoSDK makes it simple for you. You can use `VideoView` instead of `SurfaceViewRenderer`.

:::info

- If you want to use `VideoView`, please update SDK version to `0.1.13` or higher.

:::

### VideoView

`VideoView` provides a better abstraction to render live video and handles edge cases like managing init state, render more than one videos on same surfaceViewRender.

### Methods

1. **addTrack(VideoTrack videoTrack)** - `addTrack` will initialised SurfaceViewRender for you and render videoTrack that you provided.

2. **removeTrack()** - `removeTrack` should only be called when you're done showing the video.

3. **releaseSurfaceViewRenderer()** - `releaseSurfaceViewRenderer` should be called before the activity is destroyed.

## How to use VideoView ?

##### Layout

```js
// <org.webrtc.SurfaceViewRenderer
//        android:id="@+id/svrParticipant"
//        android:layout_width="match_parent"
//        android:layout_height="match_parent" />

<live.videosdk.rtc.android.VideoView
  android:id="@+id/participantView"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
/>
```

##### Initalising and adding video track



**Kotlin:**

```js
// svrParticipant.init(PeerConnectionUtils.getEglContext(), null)
// var track = stream.getTrack() as VideoTrack
// track!!.addSink(svrParticipant)

val track = stream.track as VideoTrack
participantView!!.addTrack(track);
```

---

**Java:**

```js
// svrParticipant.init(PeerConnectionUtils.getEglContext(), null);
// VideoTrack track = (VideoTrack) stream.getTrack();
// track.addSink(svrParticipant);

VideoTrack track = (VideoTrack) stream.getTrack();
participantView.addTrack(track);
```

##### removeTrack

**Kotlin:**

```js
// var track = stream.track as VideoTrack
// track!!.removeSink(svrParticipant);

participantView.removeTrack();
```

---

**Java:**

```js
// VideoTrack track = (VideoTrack) stream.getTrack();
// if (track != null) track.removeSink(svrParticipant);

participantView.removeTrack();
```

#### release

**Kotlin:**

```js
override fun onDestroy() {
    participantView.releaseSurfaceViewRenderer()
    super.onDestroy()
}
```

---

**Java:**

```js
@Override
protected void onDestroy() {
participantView.releaseSurfaceViewRenderer();
super.onDestroy();
}
```


---

# Layout and Grid Management - Android

In this guide, we will take a look at how to efficiently manage the participants in different types of layout.

## Grid Layout

The most usual way to showing participants within a grid. There are multiple things you should keep in mind when showing participants in the grid.

This includes the number of participants being shown on the screens, number of participants in the background(in the meeting but not on the grid), quality which is being consumed for each and every participant in the grid.

### Quality of Participant's Video

When there are large number of participants present on the screen, it is best to consume them in lower resolutions. For this we recommend you to call the `setQuality` method on the participants present in the grid with dynamic values based on the number of participants on the screen.

Here is the recommended video quality:

1. Participants less than 3: `setQuality("high")`
2. Participants between 3 to 4: `setQuality("med")`
3. Participants greater than 4: `setQuality("low")`

<center>
<img src='https://cdn.videosdk.live/website-resources/docs-resources/grid_quality_mobile.png' />
</center>

### Grid with Screen Share

When you are rendering a small grid along with the screen share of the presenter or you are showing a simple sidebar video of the participants while the screenshare is on, it is recommended to do `setQuality("low")` for the participants who are present in the sidebar.

## Grid with Pagination

If you are having large video calls where there are multiple speakers with video turned on, it is best to implement a pagination type setup where only a few (4-6) participants are shown on the grid and rest can be seen by changing the page.

To best utilize the resourses, you should pause the streams of the participants who are not present in the grid and resume them when the come in to the grid. You can [follow this guide](#pauseresume-stream) to pause/resume the stream.

<center>
<img src='https://cdn.videosdk.live/website-resources/docs-resources/grid_pagination.png' />
</center>

:::note
You can get the sample code for grid with pagination [here](https://github.com/videosdk-live/videosdk-rtc-android-kotlin-sdk-example/tree/main/app/src/main/java/live/videosdk/rtc/android/kotlin/GroupCall).
:::

## Pause/Resume Stream

Whenver you wish to stop/resume download stream(webcam, screenShare and mic) of participant, you can simply do it by using `pause`, `resume` methods.

### Pause stream

- `pause()` method is used for pause stream(webcam, screenShare and mic) of a particular participant.



**Kotlin:**

```js
for ((_, stream) in participant.streams) {
  //highlight-next-line
  stream.pause()
}
```

---

**Java:**

```js
for (Map.Entry<String, Stream> entry : participant.getStreams().entrySet()) {
  Stream stream = entry.getValue();
  //highlight-next-line
  stream.pause();
}
```

### Resume stream

- `resume()` method is used to resume stream(webcam, screenShare and mic) of a particular participant.

**Kotlin:**

```js
for ((_, stream) in participant.streams) {
  //highlight-next-line
  stream.resume()
}
```

---

**Java:**

```js
for (Map.Entry<String, Stream> entry : participant.getStreams().entrySet()) {
  Stream stream = entry.getValue();
  //highlight-next-line
  stream.resume();
}
```

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [setQuality](/android/api/sdk-reference/participant-class/methods#setquality)


---

# Optimize Audio Track - Android

While optimizing for the best listening experience, it is necessary to fine-tune the audio track that is being used during the calls.

For the best fine-tuning experience, we have introduced the ability to pass a custom audio track for the participant's media before and during the meeting.

## Custom Audio Track

This feature can be used to create a custom Audio track for the Audio of the participants with different encoder configuration and send it to other participants.

### `How to Create Custom Audio Track ?`

- You can create a Audio Track using `createAudioTrack()` method of `VideoSDK`.

- This method can be used to create audio track using different encoding parameters.

#### Example



**Kotlin:**

```js
val audioCustomTrack: CustomStreamTrack = VideoSDK.createAudioTrack("speech_standard",this)
// `high_quality` | `music_standard`,  Default : `speech_standard`
```

---

**Java:**

```js
CustomStreamTrack audioCustomTrack=VideoSDK.createAudioTrack("speech_standard", this);
// `high_quality` | `music_standard`,  Default : `speech_standard`
```

- `speech_standard` : This config is optimised for normal voice communication.

- `high_quality` : This config is used for getting RAW audio, where you can apply your `noiseConfig`.

- `music_standard` : This config is optimised for communication, where sharing of musical notes such as songs or instrumental sounds, is important.

### `How to Setup Custom Audio Track ?`

The custom track can be set up both before and after the initialization of the meeting.

1. [Setting up a Custom Track during the initialization of a meeting](/android/guide/video-and-audio-calling-api-sdk/render-media/optimize-audio-track#1-setting-up-a-custom-track-during-the-initialization-of-a-meeting)
2. [Setting up a Custom Track with methods](/android/guide/video-and-audio-calling-api-sdk/render-media/optimize-audio-track#2-setting-up-a-custom-track-with-methods)

##### 1. Setting up a Custom Track during the initialization of a meeting

If you are passing `micEnabled: true` in the `initMeeting` of `VideoSDK` and want to use custom tracks from start of the meeting, you can pass custom track in the `initMeeting` as shown below.

:::caution
Custom Track will not apply on `micEnabled: false` configuration.
:::

##### Example

**Kotlin:**

```js
override fun onCreate(savedInstanceState: Bundle?) {
  //..

  val customTracks: MutableMap<String, CustomStreamTrack> = HashMap()

  //highlight-start
  val audioCustomTrack: CustomStreamTrack = VideoSDK.createAudioTrack("high_quality", this)
  customTracks["mic"] = audioCustomTrack  //Key must be "mic"
  //highlight-end

  // create a new meeting instance
  val meeting = VideoSDK.initMeeting(
this@MainActivity,meetingId,participantName,
//MicEnabled , If true, it will use the passed custom track to turn mic on
true,
//WebcamEnabled
true,
//ParticipantId
null,
//Mode
null,
//MultiStream
false,
//Pass the custom tracks here
//highlight-next-line
customTracks,
//MetaData
null
  )
}
```

---

**Java:**

```js
@Override
protected void onCreate(Bundle savedInstanceState) {
  //..

  Map<String, CustomStreamTrack> customTracks = new HashMap<>();

  //highlight-start
  CustomStreamTrack audioCustomTrack = VideoSDK.createAudioTrack("high_quality", this);
  customTracks.put("mic", audioCustomTrack);  //Key must be "mic"
  //highlight-end

  // create a new meeting instance
  Meeting meeting = VideoSDK.initMeeting(
  MainActivity.this, meetingId, participantName,
  //MicEnabled , If true, it will use the passed custom track to turn mic on
  true,
  //WebcamEnabled
  true,
  //ParticipantId
  null,
  //Mode
  null,
  //MultiStream
  false,
  //Pass the custom tracks here
  //highlight-next-line
  customTracks,
  //MetaData
  null
  );
}
```

#### 2. Setting up a Custom Track with methods

In order to switch tracks during the meeting, you have to pass the `CustomStreamTrack` in the `unmuteMic()` method of `Meeting`.

You can also pass custom track in `changeMic()` method of `Meeting`.

:::tip
Make sure to call `muteMic()` before you create a new track as it may lead to unexpected behavior.
:::

##### Example

**Kotlin:**

```js
try {
  val audioCustomTrack: CustomStreamTrack = VideoSDK.createAudioTrack("high_quality", this)
  meeting!!.unmuteMic(audioCustomTrack)

  //or
  meeting!!.changeMic(AppRTCAudioManager.AudioDevice.BLUETOOTH, audioCustomTrack)
} catch (e: JSONException) {
  e.printStackTrace()
}
```

---

**Java:**

```js
try {
  CustomStreamTrack audioCustomTrack = VideoSDK.createAudioTrack("high_quality", this);
  meeting.unmuteMic(audioCustomTrack);

  //or
  meeting.changeMic(AppRTCAudioManager.AudioDevice.BLUETOOTH,audioCustomTrack);
}catch (JSONException e) {
  e.printStackTrace();
}
```

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [Custom Audio Track](/android/api/sdk-reference/custom-tracks#custom-audio-track---android)


---

# Optimize Video Tracks - Android

While optimizing for the best viewing experience, it is necessary to fine-tune the video tracks that are being used during the calls.

For the best fine-tuning experience, we have introduced the ability to pass a custom video track for the participant's media before and during the meeting.

1. [Custom Video Track](#custom-video-track)
2. [Custom Screen Share Track](#custom-screen-share-track)

## Custom Video Track

This feature gives you powerful tools to deliver the best possible video stream for varying network conditions. You can specify a modern video quality profile (`bitrateMode`) and control simulcast behavior (`maxLayer`). 

The SDK also supports legacy optimization modes (such as focusing on **motion**, **text**, or **detail**) and allows for the integration of background removal and video filters from external SDKs (e.g., [Banuba](https://www.banuba.com/)) to further enhance the video.

### `How to Create a Custom Video Track ?`

- You can create a Video Track using `createCameraVideoTrack()` method of `VideoSDK`.
- This method can be used to create video track by specifying parameters like video resolution, camera facing mode, and the quality controls (`bitrateMode` and `maxLayer`).
- You can choose video resolution from the below mentioned list of values for the encoder config:

| Config            | Resolution | Frame Rate | Optimized (kbps) | Balanced (kbps) | High Quality (kbps) |
| :---------------- | :--------: | :--------: | :--------------: | :-------------: | :-----------------: |
| h144p_w176p |  176x144   |   15 fps   |        60        |       100       |         150         |
| h240p_w320p |  320x240   |   15 fps   |        80        |       150       |         300         |
| h360p_w640p |  360x640   |  25 fps   |       200        |       400       |         800         |
| h480p_w640p |  640x480   |   25 fps   |       300        |       600       |        1000         |
| h480p_w720p |  720x480   |   30 fps   |       400        |       700       |        1100         |
| h720p_w960p |  960x720   |   30 fps   |       800        |      1300       |        1800         |
| h720p_w1280p |  1280x720  |   30 fps   |       1000       |      1600       |        2400         |
| h1080p_w1440p | 1440x1080  |   30 fps   |       2000       |      2500       |        3500         |

#### Example



**Kotlin:**

```javascript
val videoCustomTrack: CustomStreamTrack = VideoSDK.createCameraVideoTrack(

  // highlight-next-line
  // This will accept the resolution (height x width) of video you want to capture.
  "h720p_w960p", // "h480p_w6400p" | "h720p_w1280p" ... // Default : "h480p_w720p"

  // highlight-next-line
  // It will specify whether to use front or back camera for the video track.
  "front", "back",  Default : "front"

  // highlight-next-line
  // We will discuss this parameter in next step.
  CustomStreamTrack.VideoMode.MOTION, // CustomStreamTrack.VideoMode.TEXT, CustomStreamTrack.VideoMode.DETAIL ,  Default : CustomStreamTrack.VideoMode.MOTION

  // highlight-next-line
  // multiStream - we will discuss this parameter in next step.
  false, // true

  // highlight-next-line
  // Pass Context
  this,

  // highlight-next-line
  // Optional: Specify a specific camera device.
  videoDeviceInfo, // Default: null

  // highlight-next-line
  // Optional: This specifies the maximum number of simulcast layers (maxLayer) to publish.
  2, // 3 |  Default: 3

  // highlight-next-line
  // Optional: This controls the video quality and bandwidth usage.
  BitrateMode.HIGH_QUALITY // .BANDWIDTH_OPTIMIZED | .BALANCED Default: .BALANCED 
  )
```

---

**Java:**

```javascript
CustomStreamTrack customStreamTrack = VideoSDK.createCameraVideoTrack(

  // highlight-next-line
  // This will accept the resolution (height x width) of video you want to capture.
  "h720p_w960p", // "h480p_w640p" | "h720p_w1280p" ... // Default : "h480p_w720p"

  // highlight-next-line
  // It will specify whether to use front or back camera for the video track.
  "front", // "back,  Default : "front""

  // highlight-next-line
  // We will discuss this parameter in next step.
  CustomStreamTrack.VideoMode.MOTION, // CustomStreamTrack.VideoMode.TEXT, CustomStreamTrack.VideoMode.DETAIL ,  Default : CustomStreamTrack.VideoMode.MOTION

  // highlight-next-line
  // multiStream - we will discuss this parameter in next step.
  false, // true

  // highlight-next-line
  // Pass Context
  this,

  // highlight-next-line
  // Optional: Specify a specific camera device.
  videoDeviceInfo, // Default: null

  // Optional: This specifies the maximum number of simulcast layers (maxLayer) to publish.
  2, // 3 |  Default: 3

  // Optional: This controls the video quality and bandwidth usage.
  BitrateMode.HIGH_QUALITY // .BANDWIDTH_OPTIMIZED | .BALANCED Default: .BALANCED 
  );
```

:::caution
The capabilities of the device have a significant impact on how custom track configurations behave. Assuming a case where you set encoder configuration to 1080p but the camera only supports 720p, then encoder configuration will automatically switch to the highest resolution that the device can handle, which is 720p.
:::


##### What is `multiStream`?

- It will specify if the stream should send multiple resolution layers or single resolution layer.

**`multiStream : true`** By default, VideoSDK sends multiple resolution video streams to the server (whether you are using custom video track or not), For instance, user device capability is 720p, so VideoSDK sends 720p along with 360p and 144p streams. This allows VideoSDK to deliver the appropriate stream to each participant based on their network bandwidth.

<center>

![Multi Stream False](/img/multistream_true_android.png)

</center>

**`multiStream : false`** If you want to restrict the VideoSDK to send only one stream to maintain quality, you can set `multiStream` to `false`.

<center>

![Multi Stream False](/img/multistream_false.png)

</center>

:::danger
`setQuality` would not have any effect if multiStream is set to `false`.
:::

##### What is `BitrateMode`?
`BitrateMode` is the key setting for video quality. It lets you decide whether to prioritize sharp details, save internet data, or find a good balance between the two.

You can choose from three distinct modes:
- `BitrateMode.BANDWIDTH_OPTIMIZED`: Prioritizes lower bandwidth usage over video quality. Ideal for users with poor or unstable network conditions.
- `BitrateMode.BALANCED`: The default setting. It provides a smart compromise between clear video and efficient bandwidth consumption, suitable for most use cases.
- `BitrateMode.HIGH_QUALITY`: Prioritizes video quality over bandwidth usage. Use this when high-fidelity video is essential and viewers are expected to have strong network connections.

##### What is `MaxLayer`?
`MaxLayer` is an advanced parameter that gives you direct control over simulcast, which is the process of sending multiple versions (or "layers") of the same video stream at different resolutions and qualities simultaneously.

- `maxLayer = 3` **(Default)**: Publishes all available layers (e.g., high, medium, and low quality). This provides the maximum adaptability for viewers on diverse and unpredictable networks.
- `maxLayer = 2`: Intelligently publishes only the highest and lowest quality layers, skipping any in the middle. This is useful for providing a high-quality option and a low-bandwidth fallback without the overhead of a third stream.
  - If a device is capable of producing a `h720p_w960p` stream, setting `maxLayer = 2` will result in two streams being sent: the highest quality (`h720p_w960p`) and the lowest quality (e.g. `h144p_w176p`), ensuring a fallback for poor connections.

:::info
To use the `maxLayer` parameter, `multiStream` must be set to `true`. The `multiStream` flag enables simulcasting (sending multiple quality streams), while `maxLayer` specifies how many streams to send.
:::

:::note
- If the video width or height is 960 or higher, it will create 3 layers.
- If it’s 360 or higher and less than 960, it will create 2 layers.
- If it’s below 360, it will create only 1 layer.
  - For example, if you set MaxLayer to 3 but your video is 320×240, it will only create 1 layer.
:::

##### What is `optimizationMode`?

- It will specify the optimization mode for the video track being generated.

- `motion` : This type of track should more focus on motion video. For example, webcam video, movies or video games.

  - This type of track will degrade `resolution` in order to maintain `frame rate`.

- `text` : This type of track should more focus on significant sharp edges and areas of consistent color that can change frequently. For example, presentations or web pages with text content.

  - This type of track will degrade `frame rate` in order to maintain `resolution`.

- `detail` : This type of track should more focus on details of the video. For example, presentations, painting or line art.

  - This type of track will degrade `frame rate` in order to maintain `resolution`.

##### What is `observer`?

- If you want to use video filter from external SDK(e.g., [Banuba](https://www.banuba.com/)) then pass instance of `CapturerObserver` in this parameter.

:::note

For Banuba integraion with VideoSDK, please visit [Banuba Intergation with VideoSDK](../video-processor/banuba-integration.md)

:::

### `How to Setup a Custom Video Track ?`

The custom track can be set up both before and after the initialization of the meeting.

1. [Setting up a Custom Track during the initialization of a meeting](/android/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track#1-setting-up-a-custom-track-during-the-initialization-of-a-meeting)
2. [Setting up a Custom Track with methods](/android/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track#2-setting-up-a-custom-track-with-methods)

##### 1. Setting up a Custom Track during the initialization of a meeting

If you are passing `webcamEnabled: true` in the `initMeeting` of `VideoSDK` and want to use custom tracks from start of the meeting, you can pass custom track in the `initMeeting` as shown below.

:::caution
Custom Track will not apply on `webcamEnabled: false` configuration.
:::

##### Example

**Kotlin:**

```js
override fun onCreate(savedInstanceState: Bundle?) {
  //..

  //highlight-start
  val customTracks: MutableMap
</center>

## Custom Screen Share Track

This feature can be used to customise screenshare streams with enhanced optimization mode and predefined encoderConfig(Resolution + FPS) for specific use-case and send it to other participants.

### `How to Create Custom Screen Share Track ?`

- You can create a Screen Share track using `createScreenShareVideoTrack()` method of `VideoSDK`.
- This method can be used to create video track using different encoding parameters and optimization mode.

#### Example

**Kotlin:**

```javascript
// data is received from onActivityResult method.
VideoSDK.createScreenShareVideoTrack(

  //highlight-next-line
  // This will accept the  height & FPS of video you want to capture.
  "h720p_15fps", //  `h360p_30fps` | `h1080p_30fps` // Default : `h720p_15fps`

  //highlight-next-line
  // It is Intent received from onActivityResult when user provide permission for ScreenShare.
  data,

  //highlight-next-line
  // Pass Conext
  this)

  //highlight-next-line
  //Callback to this listener will be made when track is ready with CustomTrack as parameter
  {
track ->
meeting!!.enableScreenShare(track)
  }
```

---

**Java:**

```javascript
// data is received from onActivityResult method.
VideoSDK.createScreenShareVideoTrack(
  //highlight-next-line
  // This will accept the  height & FPS of video you want to capture.
  "h720p_15fps", //  `h360p_30fps` | `h1080p_30fps` // Default : `h720p_15fps`

  /highlight-next-line
  // It is Intent received from onActivityResult when user provide permission for ScreenShare
  data,

  //highlight-next-line
  // Pass Conext
  this,

  //highlight-next-line
  //Callback to this listener will be made when track is ready with CustomTrack as parameter
  (track)->{meeting.enableScreenShare(track);}
);
```

### `How to Setup Custom Screen Share Track ?`

In order to switch tracks during the meeting, you have to pass the `CustomStreamTrack` in the `enableScreenShare()` method of `Meeting`.

:::note

Make sure to call `disableScreenShare()` before you create a new track as it may lead to unexpected behavior.

:::

##### Example

**Kotlin:**

```javascript
@TargetApi(21)
private fun askPermissionForScreenShare() {
  val mediaProjectionManager = application.getSystemService<Any>(
  Context.MEDIA_PROJECTION_SERVICE
  ) as MediaProjectionManager
  startActivityForResult(
  mediaProjectionManager.createScreenCaptureIntent(), CAPTURE_PERMISSION_REQUEST_CODE
  )
}

@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
  super.onActivityResult(requestCode, resultCode, data)
  if (requestCode != CAPTURE_PERMISSION_REQUEST_CODE) return
  if (resultCode == RESULT_OK) {
//highlight-start
VideoSDK.createScreenShareVideoTrack("h720p_15fps", data, this) { track ->
    meeting!!.enableScreenShare(track)
}
//highlight-end
  }
}

```

---

**Java:**

```javascript
@TargetApi(21)
private void askPermissionForScreenShare() {
  MediaProjectionManager mediaProjectionManager =
  (MediaProjectionManager) getApplication().getSystemService(
      Context.MEDIA_PROJECTION_SERVICE);
  startActivityForResult(
  mediaProjectionManager.createScreenCaptureIntent(), CAPTURE_PERMISSION_REQUEST_CODE);
}

@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  if (requestCode != CAPTURE_PERMISSION_REQUEST_CODE)
  return;
  if (resultCode == Activity.RESULT_OK) {
//highlight-start
VideoSDK.createScreenShareVideoTrack("h720p_15fps", data, this, (track)->{
    meeting.enableScreenShare(track);
});
//highlight-end
  }
}

```

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [Custom Video Track](/android/api/sdk-reference/custom-tracks#custom-video-track---react)
- [Custom Screen Share Track](/android/api/sdk-reference/custom-tracks#custom-screen-share-track---react)


---

---
title: Picture-in-Picture Mode | Video SDK
hide_title: true
hide_table_of_contents: false
description: Picture-in-picture (PiP) is a feature that is commonly used in video conferencing software. It allows you to continue your video conference while also performing other tasks on your device.
sidebar_label: Picture-in-Picture Mode
pagination_label: Picture-in-Picture Mode
keywords:
  - audio calling
  - video calling
  - real-time communication
  - collaboration
  - Picture In Picture Mode 
  - Android Application 
  - Kotlin 
  - WebRTC PiP Mode
  - Android Picture In Picture Mode 
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: picture-in-picture
--- 

# Picture-in-Picture Mode - Android

## Overview

Picture-in-Picture (PiP) mode enables users to continue video calls while interacting with other apps. This native Android feature is particularly valuable for video conferencing applications, allowing seamless multitasking. Our implementation uses Android's built-in PiP API without third-party dependencies.

This guide will help you integrate PiP mode into your app, ensuring it activates both when the user presses the PiP button and when the app is sent to the background.

<center>
<img src='https://cdn.videosdk.live/docs/images/android/pip-mode/join_screen.png' style={{height: '500px'}}/>
</center>

:::note 
You can check out the complete implementation in the [Github repository](https://github.com/videosdk-live/videosdk-android-pip-mode-example).
:::

## Prerequisites

- Clone our [Quick Start Repository](https://github.com/videosdk-live/quickstart/tree/main/android-rtc/Videosdk_android_compose_quickstart)
- Run the base application
- Ensure Android API level 26+ (Oreo) for PiP support

## Android Manifest Setup

Add these essential attributes to your `AndroidManifest.xml`:

```xml title="AndroidManifest. xml"
<activity 
    android:name=".MainActivity"
    android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout"
    android:resizeableActivity="true"
    android:supportsPictureInPicture="true">
</activity>
```

## Getting Started with the Code!

### ViewModel

The `MeetingViewModel` manages two key variables: `pipMode` and `meetingJoined`.

- `pipMode` tracks whether the app is currently in Picture-in-Picture (PiP) mode. This variable is primarily used in the UI to show or hide relevant controls based on the PiP state.

- `meetingJoined` indicates whether the user is currently in a meeting. This is useful in various scenarios, such as determining whether to allow PiP mode when `onPictureInPictureRequested` is called.


```kotlin title="MeetingViewModel.kt"
class MeetingViewModel : ViewModel() {
    // Track PiP activation state
    var pipMode = mutableStateOf(false)
    // Monitor meeting connection status
    var meetingJoined = mutableStateOf(false)
    private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
        override fun onMeetingJoined() {
            meetingJoined.value = true
        }
        override fun onMeetingLeft() {
            meetingJoined.value = false
        }
    }
}
```

### MainActivity


1. **Handling PiP Mode Changes (`onPictureInPictureModeChanged`)**

- This method is triggered whenever the activity enters or exits PiP mode (e.g., when the user minimizes the app or returns to full-screen mode).
- The system passes a `Boolean` flag (`isInPictureInPictureMode`), which indicates whether the activity is currently in PiP mode.
- Here, we update the `pipMode` state in `MeetingViewModel` to notify the UI.

2. **Handling PiP Mode Requests (`onPictureInPictureRequested`)**

- This method is called when the system suggests entering PiP mode, typically when the user presses the home button or switches to another app.
- It checks whether the user is in a meeting (`meetingJoined == true`) before allowing PiP mode.

```kotlin title="MainActivity.kt"
class MainActivity : ComponentActivity() {
    // ViewModel instance for managing meeting state
    private lateinit var viewModel: MeetingViewModel
    @RequiresApi(Build.VERSION_CODES.O)
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // Initialize the ViewModel using ViewModelProvider
        viewModel = ViewModelProvider(this)[MeetingViewModel::class.java]
    }
    override fun onPictureInPictureModeChanged(
        isInPictureInPictureMode: Boolean,
        newConfig: Configuration
    ) {
        // Update the ViewModel state when PiP mode changes
        viewModel.pipMode.value = isInPictureInPictureMode
        super.onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig)
    }
    override fun onPictureInPictureRequested(): Boolean {
        // Allow PiP mode only if the meeting is active
        viewModel.pipMode.value = viewModel.meetingJoined.value
        return super.onPictureInPictureRequested()
    }
}
```

### MeetingScreen

The `MeetingScreen` UI includes a Picture-in-Picture (PiP) mode button, allowing users to switch to PiP mode when a meeting is joined. The screen displays meeting participants in a grid layout. If the user is alone, a message is shown. If there are more than two participants, only the first two are displayed.

- When not in PiP mode, the full meeting UI is shown, including the header, participant grid, and media control buttons (Join, Mic, Cam, Leave, PiP).

- When in PiP mode, the UI adapts by hiding the header and buttons. If the user is alone, a message is displayed. Otherwise, up to two participants are shown.


```kotlin title="MeetingScreen.kt"
@RequiresApi(Build.VERSION_CODES.O)
@Composable
fun MeetingScreen(
    viewModel: MeetingViewModel, 
    navController: NavController, 
    meetingId: String, 
    context: Context
) {
    // Observing the Picture-in-Picture (PiP) mode state from the ViewModel
    val pipMode = viewModel.pipMode
    // If PiP mode is not enabled, show the full meeting UI
    if (!pipMode.value) {
        Column(modifier = Modifier.fillMaxSize()) {
            Header(meetingId)
            MySpacer()
            ParticipantsGrid(
                gridCells = GridCells.Fixed(2),
                participants = viewModel.participants,
                modifier = Modifier.weight(1f)
            )
            MySpacer()
            // Media control buttons (Join, Mic, Cam, Leave, PiP)
            MediaControlButtons(
                onJoinClick = { viewModel.initMeeting(
                    context, app.sampleToken, meetingId
                ) },
                onMicClick = { viewModel.toggleMic() },
                onCamClick = { viewModel.toggleWebcam() },
                onLeaveClick = { viewModel.leaveMeeting() },
                // Enable PiP if meeting is joined
                onPiPClick = { pipMode.value = viewModel.meetingJoined.value } 
            )
        }
    }
    // If PiP mode is enabled, adjust UI accordingly
    if (pipMode.value) {
        activity?.enterPictureInPictureMode(
            PictureInPictureParams.Builder()
            // Custom aspect ratio for PiP window
            .setAspectRatio(Rational(16, 9)) .build()
        )
        if (viewModel.participants.size == 1) {
            Row(modifier = Modifier.fillMaxSize()) {
                // Display the single participant
                Box(modifier = Modifier.weight(1f)) {
                    ParticipantsGrid(
                        gridCells = GridCells.Fixed(1),
                        participants = viewModel.participants.take(1),
                    )
                }
                // Display a message when the user is alone in the meeting
                Box(
                    modifier = Modifier
                        .weight(1f)
                        .fillMaxHeight()
                        .wrapContentSize(Alignment.Center),
                    contentAlignment = Alignment.Center
                ) {
                    Text(
                        text = "You are alone \n in the \n meeting",
                        color = Color.Black,
                        textAlign = TextAlign.Center,
                        fontSize = 12.sp,
                        maxLines = 3,
                        overflow = TextOverflow.Ellipsis,
                        modifier = Modifier.fillMaxWidth()
                    )
                }
            }
        } else {
            // Display up to two participants in PiP mode
            ParticipantsGrid(
                gridCells = GridCells.Fixed(2),
                participants = viewModel.participants.take(2),
                modifier = Modifier.fillMaxSize()
            )
        }
    }
}
@Composable
fun MediaControlButtons(
    // .....
    onPiPClick: () -> Unit
) {
    Row {
        // Other buttons (Join, Mic, Cam, Leave) can be placed here
        // Button to toggle Picture-in-Picture mode
        MyAppButton(onPiPClick, "PiP Mode")
    }
}
```

## Final Output

The final output of Picture-in-Picture (PiP) Mode in the Android application using VideoSDK, without relying on any third-party packages. You can further customize the view and optimize it as per your requirements.


<div style={{ textAlign: 'center', marginBottom: '50px' }}> 
  
</div>

<div>
  :::tip  
  Stuck anywhere? Check out this [example code](https://github.com/videosdk-live/videosdk-android-pip-mode-example) on GitHub  
  :::  
</div>

---

# Understanding Analytics Dashboard - Android

Welcome to the world of actionable insights and empowered decision-making. VideoSDK's session analytics dashboard is your gateway to understanding, optimizing, and elevating every aspect of your sessions.

## Accessing Analytics Made Easy

Navigating through session data is a breeze with VideoSDK. Simply head to your session page at https://app.videosdk.live/meetings/sessions, where a treasure trove of session information awaits.

### How to Access Analytics?

Open Session Analytics effortlessly by following these steps:

1. **Click on Meeting-ID:**
    - Directly access analytics by clicking on the meeting-ID within the session table.
2. **Hover and Click View Analytics:**
    - Hover over a specific meeting row to reveal the **View Analytics** button in the Actions Column.
    - Click on **View Analytics** to open the Session Overview sidebar, unlocking a wealth of insights.

![Access Analytics](https://cdn.videosdk.live/website-resources/docs-resources/access_analytics.png)

---

There are three tabs available within the session analytics view:

## **1. Session Overview**

This tab provides an overview of the session, including its duration and participant details. You can explore individual participant statistics to understand their session performance better.

## **2. Errors**

In this tab, you can find information about any errors encountered during the session. It helps you identify and address issues like network problems or technical glitches promptly.

:::note

Session errors are visible with JS SDK v0.0.82 or higher, React SDK v0.1.85 or higher, and React Native v0.1.6 or newer versions.

:::

## **3. Session Stats**

Explore data and metrics sent and received by participants to measure performance of the session in this tab. It offers insights into data exchange among participants, including metrics on jitter, RTT, and packet loss, resolutions, and fps aiding in assessing communication efficiency.

Let's dive deeper into each of these tabs to gain a better understanding of session analytics.

# Session Overview

The session overview page is your compass in the sea of data. Here's what you'll uncover:

- **Meeting ID:** Unique identifier for the meeting in the format of `abcd-efgh-ijkl`.
- **Session ID:** Unique identifier for each session, uniquely identified by its `sessionId`.
- **Session Status:** Indicates if the session is ongoing or ended.
- **Session Initiating Time:** Time taken by the first participant to establish the connection.
- **Start and End Time:** Marks the start and end of the session.
- **Total Unique Participants Joined:** Total number of unique participants in the session.
- **Total Session Duration:** Overall duration of the session from start to end.
- **Total Participant Minutes:** A sum of all participant duration.
- **Recording, HLS, RTMP:** Additional services used in the session.

### Participant Table List

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for each participant.
- **Join Time:** Time taken by the participant to establish connection.
- **Duration:** Total time spent by this participant in the session.

### Efficient Session Management with Actions

Enhance your session management with streamlined actions:

- **Kick Out Participants:** Effortlessly remove/kickout participants from ongoing sessions.
- **Detailed Participant Analytics:**
- Hover over a specific participant row to reveal the `View Stats` button at the end of the row.
- Click on `View Stats` to open the Participant Overview sidebar.


![View Stats](https://cdn.videosdk.live/website-resources/docs-resources/view_stats.png)


## Explore Participant Insights

Discover valuable participant data that provides a clear view of engagement and experience:

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for better interaction.
- **Joined At:** Indicates the precise moment when participant connects to the session.
- **Left At:** Indicates the precise moment when participant left the session.
- **Total Duration:** Total duration of participant within that session.
- **Joining Time:** Time taken by the this participant to establish the connection.
- **Location:** Approx. geographic location from where the participant joined.
- **Platform:** Specifies whether participants are using a desktop or mobile device.
- **Device Info:** Offers details regarding the participant's device.
- **OS:** Provides information about the participant's OS.
- **Browser:** Provides specifics about the participant's browser
- **SDK Version:** Indicates the version of the SDK used by participants.

### Understanding Participant Call Health

We've developed call health to offer a rapid assessment of participant performance during calls. This feature highlights the performance of audio, video, and screen sharing audio-video separately. We've utilized color theory, with green indicating good performance, orange for moderate, and red for poor performance, to enhance clarity. For detailed insights, simply hover over the bars

![Participant Call Health](https://cdn.videosdk.live/website-resources/docs-resources/participant_call_health.png)

## Participant Session Stats

Dive into Participant Session Stats for valuable insights into your session experience! With just a click on `View Session Stats` at the bottom of the page, unlock a treasure trove of data crucial for understanding audio and video experiences.

Within this section, you can observe quality metrics for the selected participant, comparing them to others. Additionally, the `Sessions Stats` covers quality stats comparison for every participant. Keep reading to explore more about Session Stats.

**Visualizing Session Performance from Both Sides**

This section provides a two-sided view of your session's metrics.

- **Left Side: Sender Participant Graph** This section displays graphs representing the metrics sent by the sender participant.. Here, you can see how the various factors impacted the data you transmitted.
- **Right Side: Receiver Participant Graph** On the right side, you'll find a dropdown menu where you can select a specific participant. Choosing a receiver will display graphs showcasing the metrics **received by that participant**. This allows you to compare the sending experience (left side) with the receiving experience (right side) for different participants.

![VideoSDK Jitter Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_jitter_graph.png)

**See How Your Session Performed**

These metrics give you a clear picture of your session's quality. Understanding them helps you spot any issues and keep things running smoothly. Let's dive into what each metric means!

**Jitter:** Imagine your internet connection like a bumpy road. Jitter is how much those bumps cause your signal to bounce around. Less jitter means a smoother ride for your data (audio and video, threshold ≤ 30ms).

**RTT (Latency):** This is how long it takes for data to travel between you and the server you're connected to. Think of it like the time it takes for a message to get delivered – a lower RTT means a faster delivery (affects both audio and video, threshold ≤ 300ms).

**Bitrate:** This measures the amount of data flowing through your connection per second. Imagine it like the width of a water pipe – a higher bitrate allows for more data to flow, which can be good for high-quality audio/video or fast downloads.

**Packet Loss:** Think of data traveling in tiny packets. Packet loss is when some of those packets get dropped along the way. More packet loss means information might be missing, affecting things like audio/video quality or lag in games (threshold ≤ 5%).

**Resolution:** This refers to the sharpness and detail of an image or video. Think of it like the number of pixels on your screen – a higher resolution means a crisper picture (**Video Only**).

**FPS (Frames Per Second):** This measures how many images (frames) are displayed on your screen every second. Imagine it like a flipbook – a higher FPS creates a smoother and more fluid animation or video experience (**Video Only**).

![VideoSDK FPS Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_fps_graph.png)

![VideoSDK Resolution Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_resolution_graph.png)

---

# **Analyse Session Stats**

Similar to `Participant Session Stats`, this tab covers quality statistics sent by individual participants. You can select any participant to compare effectively with others.

Choose a sender participant from the dropdown menu on the left and select a recipient on the right to compare data over different time frames. This allows you to identify and explore issues within specific durations.

This tab covers the same metrics as covered in the `participant session stats`: Jitter, RTT (Latency), Bitrate, Packet-loss, Resolution (Video only), and FPS (Video only).

![VideoSDK Session Stats](https://cdn.videosdk.live/website-resources/docs-resources/session_stats.png)

---

# Understanding Call Quality - Android

When developing a video call app, customer satisfaction heavily depends on your app's video and audio quality and its fluctuation.

## Call Quality

If we look at the video quality from the user's perspective, a good video quality can be defined as smooth and clear video, along with a crystal clear audio. If the same is viewed from the developer's perspective, a good video quality can be determined as a high resolution, high frame rate video with minimal latency along with a high bitrate audio with minimal audio loss.

## Factors affecting Quality

When it comes to measuring the video and audio quality of a call, there are multiple variables to consider, and the most common factors which affect the video and audio quality are:

### `1. Network Bandwidth`

- Network bandwidth is a measurement of a user's network capability to how large data can be received and send.
- If the bandwidth is low at participant side, he/she is likely to get pixelated or frozen video along with robotic voice or minor breaking in the audio.
- Frequent change in the network providers can also result in high fluctuation of the internet bandwidth, which can also result in poor quality video.

### `2. Latency`

- Latency basically means the time it takes for data to transfer from one machine to another.
- If the meeting is hosted in `Ohio` region, and users are joining from `Singapore` region, so this will create long delay for data to transfer from one machine to another, thus you should pick a server according to your user base.
- In VideoSDK you can set the server during creation of Meeting/Room.

### `3. CPU Usage`

- CPU Usage is an also quite determining factor as all the audio and video streams which are going out and coming in will have to encoded or decoded which will require a significant amount of computation.
- The high the resolution and frame rate of the videos, the larger would be the computation required, which can be a reason for the bottleneck of delivering a good quality video.
- If the CPU is being consumed heavily, it can also result in a choppy or robotic audio.

### `4. Camera and Mic Quality`

- The camera and microphone should capture good quality of streams so that remote user doesn't get low quality stream even if he/she has good network bandwidth

## Identifying the Quality Issues

In order to identify quality issues, VideoSDK collects multiple audio and video related metrics which can help in pinpointing the quality issues. Let's have a look at those metrics and understand what the indicates.

### `1. Resolutions and Framerates`

- Resolution and frame rate are key metrics for video quality in a video call app. Resolution refers to the number of pixels in a video image, while frame rate refers to the number of frames displayed per second.

- Higher resolutions and frame rates can provide better video quality, but they also require more bandwidth and processing power. It's important to optimize this metrics for the devices and network conditions of your users.

- For example, if most of your users are on mobile devices, a lower resolution and frame rate may be more appropriate to ensure smooth playback and minimize bandwidth usage.

- If most of your users are on mobile and desktop devices, having higher resolution for desktop and mid-resolutions for mobile devices can help in improving the performance and quality as we will be saving the bandwidth on the mobile end.

### `2. Bitrate`

- Bitrate is the number of bits per second send or received during the transmission of audio or video streams. Bitrate can be a key parameter to determine the quality of the audio or video streams, as it should be fine-tuned for each resolution to achieve the best match of performance and bandwidth utilization.

- If the users are having excellent network conditions, higher bitrate can result in much better video quality but on the other hand, having very high bitrates on the mobile devices can result in heating issues due to high computation required to encode and decode the videos.

##### Example

We joined using the same phone **(iPhone 14)**, but the resolution and bitrate were different, first participant having resolution **`1280x720`** with bitrate **`1442 kbps`** and second participant having resolution **`960x540`** with bitrate **`642 kbps`**, so as we can see both participants' video appeared to be of equal quality even though resolution and bitrate are different.

![resolution-and-bitrate](/img/resolution-and-bitrate.png)

### `3. Packet Loss`

- Packet loss is a metric that indicates how many data packets are lost during transmission from the sender to the receiver. Packet loss can occur due to network congestion, hardware or software issues, or network latency. Higher packet loss can result in poor video and audio quality, as the missing packets can cause gaps or distortions in the media stream.


<div style={{textAlign: 'center'}}>



</div>

### `4. Jitter`

- The audio and video packets are sent out at random intervals over a specified time frame as they are being sent between the server and client. Nevertheless, jitter is produced when there is a variation in transmitting or receiving this data packets as a result of a faulty network connection.

- When data packets delay while being transmitted to the participant, usually because the network is busy. They'll display as pixelated video on a video call or sound choppy, distorted, or robotic on a voice call as they arrive. They'll arrive at random intervals, creating jitter.

### `5. Round Trip Time (Latency)`

- Round trip time is the amount of time required to transmit the data packets to send or receive from the server. If the servers are located very far from the user's location, they can observe a high latency (delay).

- With VideoSDK, this factor is taken care of as we automatically choose the nearest available server for participants. But if you are geofencing to a certain region, you should make sure that you choose the server which will be nearest to your users.

<center>

![resolution-and-bitrate](/img/rtt.png)

</center>

## Checking Realtime Statistics

VideoSDK provides methods to check the realtime statistics of the audio and video of all the participants.

### `getVideoStats()`

- `getVideoStats()` returns an array of object containing the different quality parameters for video stream which can be accessed through the `Participant` class.

- This objects will have values for the specific participant's video stream resolution, frame rate, bitrate, jitter, round trip time, and packet loss.

<div style={{textAlign: 'center'}}>



</div>

### `getAudioStats()`

- `getAudioStats()` returns an object containing the different quality parameters for audio stream which can be accessed through the `Participant` class.

- This objects will have values for the specific participant's audio stream bitrate, jitter, round trip time and packet loss.

### `getShareStats()`

- `getShareStats()` returns an object containing the different quality parameters for screen share stream which can be accessed through the `Participant` class.

- This objects will have values for the specific participant's screen share stream resolution, frame rate, bitrate, jitter, round trip time, and packet loss.

:::note
To show the popup dialog for the participant's realtime stats, you can [refer to this component](https://github.com/videosdk-live/videosdk-rtc-react-sdk-example/blob/main/src/utils/common.js#L142).
:::

## Quality analysis Graphs

For all the sessions taken using the VideoSDK, you can find the quality analysis graphs from the [VideoSDK Dashboard](https://app.videosdk.live/meetings/sessions) which can help you visualize the data you are seeing in realtime and identify the spikes of a few parameters happing during call which can help figure out the reason for the quality issue.

![quality analysis](/img/quality-analysis.png)

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [getVideoStats()](/android/api/sdk-reference/participant-class/methods#getvideostats)
- [getAudioStats()](/android/api/sdk-reference/participant-class/methods#getaudiostats)
- [getShareStats()](/android/api/sdk-reference/participant-class/methods#getsharestats)


---

# Virtual Background - Android

Virtual backgrounds allow you to replace your actual background during video calls or meetings with an image, a solid color, or even a blur effect. This can be useful for:

- Privacy: Hide your messy room or anything you don't want others to see.

- Focus: Minimize distractions and keep the focus on the conversation.

- Fun: Liven up the call with a cool background theme.




## Virtual Background using `MediaEffects` library

The `MediaEffects` library enables the integration of sophisticated virtual background effects within your video applications. By leveraging this library, users can replace their physical backgrounds with custom images or static backdrops, creating a more immersive and engaging experience. 

:::info

The Virtual Background feature in VideoSDK can be utilized regardless of the meeting environment, including the pre-call screen.

:::

### Install the library 
You can install our Android library by using Maven Central package repositories.

- Add the dependency in your `app/build.gradle` file.

```js title="app/build.gradle"
dependencies {
	implementation 'live.videosdk:videosdk-media-effects:0.0.2'
	// other app dependencies
}
```
### Apply Virtual Background

- The `applyVideoProcessor()` method of the `VideoSDK` class enables dynamic changes to the video background during a live session.
- This method accepts an instance of the `VideoFrameProcessor` class as its parameter.
- The following classes implement the `VideoFrameProcessor` interface. Depending on your requirements, you can create an instance of the appropriate class and pass it to the `applyVideoProcessor()` method:

    1. `BackgroundImageProcessor` : The `BackgroundImageProcessor` class takes a `Uri` as a parameter and uses it as the video stream background.
    2. `BackgroundBlurProcessor`: The `BackgroundBlurProcessor` class takes a `float` value for the blur radius and a `Context` to apply a blur effect to the video stream background. It supports range between 0 to 25.
    3. `BackgroundColorProcessor`: The `BackgroundColorProcessor` class takes an `int` value for the color and sets it as the background for the video stream.

### Change Virtual Background

- To change the virtual background, users can utilize a set of setters that allow easy switching between a new image, a blur effect, or a solid color. This functionality supports dynamic customization, enhancing the user's video experience by enabling seamless background updates in real-time.

- You can use following setters to change Virtual Background:

    1. `setBackgroundSource(Uri uri)`: This method of the `BackgroundImageProcessor` class takes a `Uri` as a parameter to update the current background image for the video stream.
    2. `setBlurRadius(float opacity)`: This method of the `BackgroundBlurProcessor` class takes a `float` value for the blur radius to adjust the blur effect of the current background.
    3. `setBackgroundColor(int color)`: This method of the `BackgroundColorProcessor` class takes an `int` value as a parameter to update the current background color for the video stream.
### Remove Virtual Background

- The `removeVideoProcessor()` method from the `VideoSDK` class provides users with a convenient way to revert their video background to its original state, removing any previously applied virtual background. This functionality ensures flexibility for users to switch between virtual and real backgrounds as needed.

#### Example



**Kotlin:**

```js
Class MeetingActivity : AppCompatActivity() {
private var backgroundImageProcessor: BackgroundImageProcessor? = null
private var backgroundBlurProcessor: BackgroundBlurProcessor? = null
private var backgroundColorProcessor: BackgroundColorProcessor? = null

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    //...

    //To Apply Virtual Background
    findViewById<View>(R.id.applyBackground).setOnClickListener { view: View? ->
        val uri =
            Uri.parse("https://st.depositphotos.com/2605379/52364/i/450/depositphotos_523648932-stock-photo-concrete-rooftop-night-city-view.jpg")
        backgroundImageProcessor = BackgroundImageProcessor(uri)
  //    backgroundBlurProcessor = BackgroundBlurProcessor(25f, this)
  //    backgroundColorProcessor = BackgroundColorProcessor(Color.BLUE)
        VideoSDK.applyVideoProcessor(backgroundColorProcessor)
    }

    //To Change Virtual Background
    findViewById<View>(R.id.changeBackground).setOnClickListener { view: View? ->
        val newUri =
            Uri.parse("https://images.pexels.com/photos/531880/pexels-photo-531880.jpeg?cs=srgb&dl=pexels-pixabay-531880.jpg&fm=jpg")
        backgroundImageProcessor!!.setBackgroundSource(newUri)
  //    backgroundColorProcessor!!.setBackgroundColor(Color.CYAN)
  //    backgroundBlurProcessor!!.setBlurRadius(17f)
    }
    
    //To Remove Virtual Background
    findViewById<View>(R.id.changeBackground).setOnClickListener { view: View? ->
        VideoSDK.removeVideoProcessor()
    }
}
}
```

---

**Java:**

```java
public class MeetingActivity extends AppCompatActivity {

private BackgroundImageProcessor backgroundImageProcessor;
private BackgroundBlurProcessor backgroundBlurProcessor;
private BackgroundColorProcessor backgroundColorProcessor;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    //...

    //To Apply Virtual Background
    findViewById(R.id.applyBackground).setOnClickListener(view -> {
        Uri uri = Uri.parse("https://st.depositphotos.com/2605379/52364/i/450/depositphotos_523648932-stock-photo-concrete-rooftop-night-city-view.jpg");
        backgroundImageProcessor = new BackgroundImageProcessor(uri);
    //   backgroundBlurProcessor = new BackgroundBlurProcessor(25,this);
    //   backgroundColorProcessor = new BackgroundColorProcessor(Color.BLUE);
        VideoSDK.applyVideoProcessor(backgroundColorProcessor);
    });

    //To Change Virtual Background
    findViewById(R.id.changeBackground).setOnClickListener(view -> {
        Uri newUri = Uri.parse("https://images.pexels.com/photos/531880/pexels-photo-531880.jpeg?cs=srgb&dl=pexels-pixabay-531880.jpg&fm=jpg");
        backgroundImageProcessor.setBackgroundSource(newUri);
    //    backgroundColorProcessor.setBackgroundColor(Color.CYAN);
    //    backgroundBlurProcessor.setBlurRadius(17);    
    });
    
    //To Remove Virtual Background
    findViewById(R.id.removeBackground).setOnClickListener(view -> {
        VideoSDK.removeVideoProcessor();
    });
}
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [applyVideoProcessor()](/android/api/sdk-reference/videosdk-class/methods#applyvideoprocessor)
- [removeVideoProcessor()](/android/api/sdk-reference/videosdk-class/methods#removevideoprocessor)



---

# Run a Sample HLS Project - Android

Video SDK provides open-source sample project [videosdk-hls-android-kotlin-example](https://github.com/videosdk-live/videosdk-hls-android-kotlin-example) on Github. This document introduces how to run this project.

## Prerequisites

- Development environment requirements:
  - [Java Development Kit](https://www.oracle.com/java/technologies/downloads/)
  - Android Studio 3.0 or later
- A physical or virtual mobile device running Android 5.0 or later
- Valid Video SDK [Account](https://app.videosdk.live/)


### Generate Token

To manage secured communication, every participant that connects to a meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key`, which you can obtain from the [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

**For development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for obtaining a token involves generating it from your backend server which will help in **keeping your credentials safe**.
:::


## Run the Sample Project

### Step 1: Clone the sample project

Clone the repository to your local environment.



**Kotlin:**

```js
git clone https://github.com/videosdk-live/videosdk-hls-android-kotlin-example.git
```

---

**Java:**

```js
git clone https://github.com/videosdk-live/videosdk-hls-android-java-example.git
```


### Step 2: Modify local.properties

Open your favorite code editor, add `auth_token` in `local.properties` file and paste the earlier generated temporary token as value.

```js title="local.properties"
auth_token = "TEMPORARY-TOKEN";
```


### Step 3: Run the Sample App

Run the android app with **Shift+F10** or the ** ▶ Run ** from toolbar.



---

# Run Interactive Live Streaming Project - Android

Video SDK provides open-source sample project [videosdk-ils-android-kotlin-example](https://github.com/videosdk-live/videosdk-ils-android-sdk-example) on Github. This document introduces how to run this project.

## Prerequisites

- Development environment requirements:
  - [Java Development Kit](https://www.oracle.com/java/technologies/downloads/)
  - Android Studio 3.0 or later
- A physical or virtual mobile device running Android 5.0 or later
- Valid Video SDK [Account](https://app.videosdk.live/)


### Generate Token

To manage secured communication, every participant that connects to a meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key`, which you can obtain from the [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

**For development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for obtaining a token involves generating it from your backend server which will help in **keeping your credentials safe**.
:::


## Run the Sample Project

### Step 1: Clone the sample project

Clone the repository to your local environment.



**Kotlin:**

```js
git clone https://github.com/videosdk-live/videosdk-ils-android-sdk-example
```

---

**Java:**

```js
git clone https://github.com/videosdk-live/videosdk-ils-android-sdk-example
```


### Step 2: Modify local.properties

Open your favorite code editor, add `auth_token` in `local.properties` file and paste the earlier generated temporary token as value.

```js title="local.properties"
auth_token = "TEMPORARY-TOKEN";
```


### Step 3: Run the Sample App

Run the android app with **Shift+F10** or the ** ▶ Run ** from toolbar.



---

# Run Audio & Video Call Project - Android

Video SDK provides open-source sample project [videosdk-rtc-android-kotlin-sdk-example](https://github.com/videosdk-live/videosdk-rtc-android-kotlin-sdk-example) on Github. This document introduces how to run this project.

## Prerequisites

- Development environment requirements:
  - [Java Development Kit](https://www.oracle.com/java/technologies/downloads/)
  - Android Studio 3.0 or later
- A physical or virtual mobile device running Android 5.0 or later
- Valid Video SDK [Account](https://app.videosdk.live/)


### Generate Token

To manage secured communication, every participant that connects to a meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key`, which you can obtain from the [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

**For development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for obtaining a token involves generating it from your backend server which will help in **keeping your credentials safe**.
:::


## Run the Sample Project

### Step 1: Clone the sample project

Clone the repository to your local environment.



**Kotlin:**

```js
git clone https://github.com/videosdk-live/videosdk-rtc-android-kotlin-sdk-example.git
```

---

**Java:**

```js
git clone https://github.com/videosdk-live/videosdk-rtc-android-java-sdk-example.git
```


### Step 2: Modify local.properties

Open your favorite code editor, add `auth_token` in `local.properties` file and paste the earlier generated temporary token as value.

```js title="local.properties"
auth_token = "TEMPORARY-TOKEN";
```


### Step 3: Run the Sample App

Run the android app with **Shift+F10** or the ** ▶ Run ** from toolbar.



---

# Scalability Guide for Large Participant Meetings

## Overview

This guide explains how to optimize performance when hosting video meetings with 10+ participants by using a key feature:

**Adaptive Subscriptions**: Intelligently prioritizes audio/video streams based on who's speaking

These features help solve common challenges in large meetings, such as excessive bandwidth consumption and poor quality for users with network constraints.

## Common Challenges in Large Meetings

### 1. Ineffective Stream Prioritization

**Problem**: All streams receive equal treatment regardless of importance.

**Impact**:

- Users with limited bandwidth experience poor quality
- Audio quality suffers when competing with video for resources
- Important speakers may not be clearly heard or seen

## Solution Features

### Adaptive Subscriptions

This feature optimizes bandwidth by prioritizing active speakers and managing stream quality.

**Key Benefits**:

- Identifies and prioritizes dominant speakers
- Intelligently manages bandwidth constraints
- Ensures clear audio even under network limitations
- Gives highest priority to pinned participants

**How It Works**:  
The system analyzes speaking patterns to detect active participants and adjusts stream priorities accordingly. For bandwidth-constrained users, it strategically pauses or lowers the quality of non-essential video streams. Pinned participants always receive the highest priority in stream allocation.

_Visual Illustration:_

<div style={{textAlign: 'center'}}>

<img src="https://cdn.videosdk.live/website-resources/docs-resources/adaptive_subscriptions_priority.png" alt="Viewport illustration" height="500px"/>
</div>

If a user experiences bandwidth constraints, Adaptive Subscriptions will pause the video streams in the following priority order:

1. Muted Participants
2. Least Dominant Speakers
3. Dominant Speakers

> If you want to achieve pin/unpin functionality, you can refer to [this documentation](https://docs.videosdk.live/android/api/sdk-reference/participant-class/methods#pin)

## Implementation Guide

### Prerequisites

- SDK Version: 0.6.0 or later

### Enabling Adaptive Subscriptionss(BETA)

You can toggle this feature using these methods:

```java
// Enable adaptive subscriptions
meeting.enableAdaptiveSubscriptions();

// Disable adaptive subscriptions
meeting.disableAdaptiveSubscriptions();
```

**Recommended Implementation**:



**Kotlin:**

```kotlin
private val meetingEventListener = object : MeetingEventListener {
override fun onMeetingJoined() {
    meeting.enableAdaptiveSubscriptions()
}
}

```

---

**Java:**

```java
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
@Override
public void onMeetingJoined() {
    meeting.enableAdaptiveSubscriptions();
}
}
```

### Stream Pause/Resume Events

When a video stream is paused or resumed, the system triggers events with specific reasons:

**Kotlin:**

```kotlin
private val participantEventListener = object : ParticipantEventListener {
override fun onStreamPaused(kind: String, reason: String) {
    Log.d("onStreamPaused", "reason : $reason")
}

override fun onStreamResumed(kind: String, reason: String) {
    Log.d("onStreamResumed", "reason : $reason")
}
}

```

---

**Java:**

```java
private final ParticipantEventListener participantEventListener = new ParticipantEventListener() {
@Override
public void onStreamPaused(String kind, String reason) {
    Log.d("onStreamPaused", "reason : " + reason);
}

@Override
public void onStreamResumed(String kind, String reason) {
    Log.d("onStreamResumed", "reason : " + reason);
}
}
```

**Pause Reasons**:

- `muted`: Participant has turned off their audio
- `leastDominance`: Participant hasn't spoken much in the meeting

**Resume Reasons**:

- `adaptiveSubscriptionsDisabled`: Feature was disabled
- `networkStable`: Network conditions have improved

> **Developer Tip**: When a stream is paused (e.g., due to network issues), always keep users in the loop by displaying a helpful UI indicator. For instance, render a message such as:
> "Paused: Waiting for stable connection..."

## Best Practices

- Enable adaptive subscriptions at the start of every meeting
- Design your UI to display indicators when a stream is paused
- Pin important participants to ensure they receive the highest streaming priority




---

# End-to-End Encryption (E2EE) - Android

### Overview

End-to-end encryption (E2EE) ensures that your media content remains private and secure by encrypting it on the sender's device and decrypting it only on the receiver's device. This prevents intermediaries, including VideoSDK servers, from accessing or modifying the content.

E2EE is particularly important for applications in security-critical domains such as telehealth, finance, and legal services.

### E2EE Modes

VideoSDK offers two modes of End-to-End Encryption (E2EE) for securing media streams during sessions:

  1. **Shared Key** (Meeting-Level): A single encryption key is used across the entire session, encrypting and decrypting media tracks for all participants.
  2. **Per-Participant Keys**: Individual participants have unique encryption keys, providing enhanced security by ensuring each participant's media streams are encrypted separately.

### How E2EE Works

- E2EE is applied at the session level, where in Shared Key mode, a single key encrypts and decrypts all media tracks for every participant, while in Per-Participant Keys mode, each participant is assigned a unique key to encrypt their individual media streams separately.
- Participants without the key cannot access the media.
- The entire encryption process is handled client-side. VideoSDK does not access or store any encryption keys.


### Key Management & Distribution

You are **fully responsible** for generating, managing, and securely distributing encryption keys to all participants. VideoSDK **never stores, accesses, or transfers** your encryption keys.

- Common Key Distribution Approaches:
  - Generate the key **on your server** when creating a meeting.
  - Send the key securely along with the **meeting access token**.
  - Use **HTTPS-secured API calls** to fetch the key on the client.

:::important

⚠️ Ensure that all participants have access to the correct encryption key before joining the room.

:::
  

### SDK Version Compatibility

The table below lists the minimum SDK versions that support E2EE.

| Android | iOS | React Native | React   | Flutter | JavaScript |
|---------|--------|---------------|-------|----------|-------------|
|  0.5.0  | 2.2.2 | 0.2.1 | 0.3.5 | 2.1.0  | 0.2.6 |
---

### Enabling End-to-End Encryption (E2EE) in VideoSDK Android

VideoSDK provides two ways to enable End-to-End Encryption (E2EE):
  1. **Shared Key**: A single encryption key shared by all participants.
  2. **Per-Participant Key**: Unique encryption keys assigned to individual participants.

#### 1. Enabling E2EE using a Shared Key
  When using a shared key, all participants utilize the same encryption key, set via the `setSharedKey()` method.



**Kotlin:**

```kotlin
class MainActivity : AppCompatActivity() {

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // Initialize the encryption key using Shared Key approach
    keySetup("SHARED_KEY") // Replace with your actual shared key

    // Initialize the meeting instance
    VideoSDK.initMeeting(...)
}

private fun keySetup(sharedKey: String) {
    val baseKeyProvider = BaseKeyProvider()

    // Set a single shared encryption key for all participants
    baseKeyProvider.setSharedKey(sharedKey)

    // Set the key provider for E2EE
    VideoSDK.setKeyProvider(baseKeyProvider)
}
}
```

---

**Java:**

```java
public class MainActivity extends AppCompatActivity {

	@Override  
	protected void onCreate(Bundle savedInstanceState) {
		
  // Initialize the encryption key using Shared Key approach
  keySetup("SHARED_KEY"); // Replace with your actual shared key

  // Initialize the meeting instance  
  VideoSDK.initMeeting(...);
	}

  private void keySetup(String sharedKey){  
  BaseKeyProvider baseKeyProvider = new BaseKeyProvider();  

  // Set a single shared encryption key for all participants
  baseKeyProvider.setSharedKey(sharedKey);  

  // Set the key provider for E2EE
  VideoSDK.setKeyProvider(baseKeyProvider);  
}
}
```

:::warning

Make sure to set the encryption key using `setSharedKey()` before assigning the key provider with `setKeyProvider()`, otherwise it will throw an Exception.

:::

#### 2. Enabling E2EE using Per-Participant Keys
Per-Participant Keys enhance security by assigning a distinct encryption key to each participant, ensuring that access is uniquely controlled on a per-user basis.
  
##### Step 1. Initialize the BaseKeyProvider and Set Up Encryption Keys
  - Create a global reference to BaseKeyProvider.
  - To enable encryption, you must set the `localParticipantId` along with its corresponding key using the `setKey() `method of the `BaseKeyProvider` class.
  - Save each participant’s ID and encryption key securely to your server for later use in decryption.

  :::important
    You must use a single, shared BaseKeyProvider instance for both encryption (local participant) and decryption (remote participants).
  :::
    **Kotlin:**

```kotlin
class MainActivity : AppCompatActivity() {

// BaseKeyProvider reference
private lateinit var baseKeyProvider: BaseKeyProvider

  override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)

      val localParticipantId = "YOUR_LOCAL_PARTICIPANT_ID"

      // Set up the BaseKeyProvider
      keyProviderSetup(localParticipantId, "SECRET_KEY")

      // Initialize the meeting instance
      meeting = VideoSDK.initMeeting(
            context, "MEETING_ID", "PARTICIPANT_NAME",
            true, true, localParticipantId, null, false, null , null)

  }

  // Setup Method
  private fun keyProviderSetup(localParticipantId: String, secretKey: String) {
      baseKeyProvider = BaseKeyProvider()
      // Per-Participant E2EE: Set key for local participant
      baseKeyProvider.setKey(localParticipantId, secretKey) // Your Encryption Key
      VideoSDK.setKeyProvider(baseKeyProvider)
  }
}
```

---

**Java:**

```java
public class MainActivity extends AppCompatActivity {
	
	private BaseKeyProvider baseKeyProvider;

	@Override  
	protected void onCreate(Bundle savedInstanceState) {

    String localParticipantId = "YOUR_LOCAL_PARTICIPANT_ID";

    // Set up the encryption key  
		keyProviderSetup(localParticipantId, "SECRET_KEY");
	
		// Initialize the meeting instance  
		Meeting meeting =  VideoSDK.initMeeting(
            context, "MEETING_ID", "PARTICIPANT_NAME",
            true, true, localParticipantId, null, false, null , null
    );
	}

private void keyProviderSetup(String: localParticipantId, String: secretKey){  
    baseKeyProvider = new BaseKeyProvider();  
    // Per-Participant E2EE: Set key for local participant
    baseKeyProvider.setKey(localParticipantId , secretKey); // Your Encryption Key 
    VideoSDK.setKeyProvider(baseKeyProvider);  
} 
```

  :::warning
    Make sure to set the encryption key using `setKey()` before assigning the key provider with `setKeyProvider()`, otherwise it will throw an Exception.
  :::

  ##### Step 2. Decrypting Participant Streams using Per-Participant Keys
  - When a participant joins, retrieve the corresponding encryption key (previously stored on your server) using the participant’s ID to decrypt their media streams.

**Kotlin:**

```kotlin
private val meetingEventListener = object : MeetingEventListener() {

override fun onParticipantJoined(participant: Participant) {
   
    // Retrieve the encryption key for the participant from your server
    val secretKey = "SECRET_KEY"

    // Set the key to decrypt incoming participant streams
    baseKeyProvider.setKey(participant.id, secretKey)
}
}
```

---

**Java:**

```java
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {

@Override  
public void onParticipantJoined(Participant participant) {  

    // Retrieve the corresponding encryption key for the joined participant using participant.getId()
    String secretKey = "SECRET_KEY";
    
    // Set the retrieved key to decrypt incoming participant streams
    baseKeyProvider.setKey(participant.getId(), secretKey);
}
};

```

:::important

- Ensure all encryption keys are securely stored and retrieved from your server.
- Proper key management is essential for effective encryption and decryption, especially when using Per-Participant Keys.

:::

#### Event for E2EE State Changes
To monitor encryption/decryption state changes for each participant's media stream:

**Kotlin:**

```kotlin
meeting.localParticipant.addEventListener(object : ParticipantEventListener() {
override fun onE2eeStateChanged(state: E2EEState, stream: Stream) {
    super.onE2eeStateChanged(state)
    Log.d("e2ee", "Local-Participant onE2eeStateChanged -> $state")
    Log.d("e2ee", "Local-Participant Stream Kind -> ${stream.kind}")
}
})
```

---

**Java:**

```java
meeting.getLocalParticipant().addEventListener(new ParticipantEventListener() {
	@Override
public void onE2eeStateChanged(E2EEState state, Stream stream) {
Log.d("e2ee", "Local-Participant E2eeStateChanged -> " + state);
Log.d("e2ee", "Local-Participant Stream Kind -> " + stream.getKind());
  }
};
```


The possible values for `state` are:

| State |  Description |
|-------|--------------|
| EncryptionSuccess | Media encryption is successfully applied.|
| DecryptionSuccess | Incoming media is successfully decrypted.|
| EncryptionFailed | Encryption encountered an error. |
| DecryptionFailed | Decryption encountered an error. |
| InternalError | Internal processing error occurred. |

### To check whether E2EE is enabled

You can check whether E2EE is enabled by using `isE2eeEnabled()` getter function of `Meeting` class.

```java
meeting.isE2eeEnabled();
```

### Limitations

E2EE only applies to media. It does not apply to:

- Chat messages or metadata
- API calls and signaling data

These communications are still protected by TLS but are not encrypted end-to-end.

:::info

Recording and Transcription features are not supported when End-to-End Encryption (E2EE) is enabled.

:::


---

<h1> {props.title} </h1>{" "}

### Why we are using JWT based Token ?

Token based authentication allows users to verify their identity by providing generated API key and secret.

We use JWT token for the authentication purpose because Token-based authentication is **widely used** in modern web applications and APIs because it offers several benefits over traditional authentication. For example, it can **reduce the risk of the credentials being misused**, and it allows for **more fine-grained control** over access to resources. Additionally, tokens can be easily revoked or expired, making it easier to manage access rights.

### How to generate Token ?

To manage secured communication, every participant that connects to the meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key` which you can get from [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

#### 1. Generating token from Dashboard

If you are looking to do **testing or for development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for getting token includes generating it from your backend server which will help in **keeping your credentials safe**.
:::

#### 2. Generating token in your backend

- Your server will generate access token using your API key and secret.
  - While generating a token, you can provide **expiration time, permissions and roles** which are discussed later in this section.
- Your client obtains token from your backend server.
- For token validation, client will pass this token to VideoSDK server.
- VideoSDK server will only allow entry in the meeting if the token is valid.

![img2.png](../../static/img/authentication-and-token.png)




Follow our official example repositories to setup token API [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)

### Payload while generating token

```js
{
 apikey: API_KEY, //MANDATORY
 permissions: [`allow_join`], //`ask_join` || `allow_mod` //MANDATORY
 version: 2, //OPTIONAL
 roomId: ROOM_ID, //OPTIONAL,
 participantId: PARTICIPANT_ID, //OPTIONAL
 roles: ['crawler', 'rtc'], //OPTIONAL
}
```

- **`apikey`(Mandatory)**: This must be the API Key generated from the VideoSDK Dashboard. You can get it from [here](https://app.videosdk.live/api-keys).

- **`permissions`(Mandatory)**: By providing the permissions, you can control what a participant can do in the meeting and whether he can join the meeting directly.

  Available permissions are:

  - **`allow_join`**: The participant is **allowed to join** the meeting directly.
  - **`ask_join`**: The participant is required to **ask for permission to join** the meeting. The participant having the permission `allow_join` can accept or reject a participant whenever someone wants to join.
  - **`allow_mod`**: The participant is **allowed to toggle** webcam & mic of other participants.

- **`version`(optional)**: For accessing the [v2 API](/api-reference/realtime-communication/intro), you need to provide `2` as the version value.

  - For passing `roomId`, `participantId` or `roles` parameters in payload, it is essential to set the version value to `2`.

- **`roomId`(optional)**: To provide customised access control, you can make the token applicable to a particular room by including the `roomId` in the payload.

- **`participantId`(optional)**: You can include the `participantId` in the payload to limit the token's access to a particular participant.

- **`roles`(optional)**:

  - **`crawler`**: This role is only for accessing [v2 API](/api-reference/realtime-communication/intro), you can not use this token for running the `Meeting`/`Room`.
  - **`rtc`**: This role is only allowed for running the `Meeting` / `Room`, with this role you can not use [server-side APIs](/api-reference/realtime-communication/intro).

Then, you have to sign this payload with your **`SECRET KEY`** and `jwt` options using the **`HS256 algorithm`**.

### Expiration time

You can set any expiration time to the token. But in the **production environment**, it is recommended to generate a token with **short expiration time** because by any chance if someone gets hold of the token, it won't be valid for a longer period of time.

### What happens if token is expired?

If your token is expired, the user won't be able to join the meeting and all the API calls will give error with message `Token is invalid or expired`.

:::note
Token is validated only once while joining the meeting, so if a person joins the meeting and the token gets expired after that, there won't be any issue in the current meeting.
:::

## How to check validity of token?

1. After generating the token, visit [jwt.io](https://jwt.io) and paste your token in the given area.
2. You will be able to see the payload you passed while generating the token and also be able to see the expiration time and token creation time.

![img1.png](../../static/img/validate-token.png)

## API Settings & Controls

The VideoSDK Dashboard provides a powerful [API Settings](https://app.videosdk.live/api-keys) section where you can configure various services and controls for your meetings. These settings allow you to customize the behavior of different features directly from the dashboard without requiring code changes.

## Audio/Video Configurations

:::note
Runtime configuration from the dashboard has higher precedence than static SDK configurations.
If a value is modified in the dashboard, it will override any previously defined SDK settings for that session.

Example:
Code: Video = HD → Dashboard: Video = Full HD → Applied: Full HD
:::

### Maximum Send Bitrate Per Participant

Control the maximum total upload bandwidth for all media streams from a single participant.

![Maximum Send Bitrate](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.00.11%E2%80%AFPM.png)

**Available Options:**
- **Auto**: Removes the upload bitrate limit (recommended for best quality)
- **SD (800kbps)**: Standard definition bitrate
- **HD (1500kbps)**: High definition bitrate
- **Full HD (3000kbps)**: Full high definition bitrate

:::tip
Setting this to **Auto** provides the best video quality as it removes upload bitrate constraints, allowing adaptive streaming based on network conditions.
:::

## Recording & Streaming Configuration

:::note
Recording and HLS follow a precedence-based configuration model:

API/SDK configuration → Highest priority
Dashboard configuration → Used only when no API values are defined

Any parameters explicitly set via the API will not be overridden by dashboard changes.
:::

### Recording Configuration

Configure recording settings for your meetings including layout, quality, and auto-start options.

![Recording Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.01.00%E2%80%AFPM.png)

**Recording Controls:**
- **Enabled**: Toggle to enable/disable recording functionality
- **Enabled Modes**: Choose between Video & Audio or Audio Only recording
- **Start Recording Automatically**: Auto-start recording when meeting begins
- **Layout Style**: Select Grid layout for recording composition
- **Maximum Tiles In Grid**: Set the number of participants visible in grid (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme for recordings
- **Video Orientation**: Choose between Landscape or Portrait mode
- **Recording Quality**: Select quality level (e.g., HD Medium)
- **Recording Mode**: Choose between Video & Audio or Audio Only

### HLS Streaming Configuration

Configure HTTP Live Streaming (HLS) settings for broadcasting your meetings.

![HLS Streaming Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.02.18%E2%80%AFPM.png)

**HLS Streaming Controls:**
- **Enabled**: Toggle to enable/disable HLS streaming
- **Enabled Modes**: Choose between Video & Audio or Audio Only streaming
- **Auto Start HLS**: Automatically start HLS when meeting begins
- **Record HLS Stream**: Enable recording of the HLS stream
- **Layout Style**: Select Grid layout for stream composition
- **Maximum Tiles In Grid**: Set the number of participants visible (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme
- **HLS Orientation**: Choose between Landscape or Portrait mode
- **HLS Quality**: Select streaming quality (e.g., HD Medium)
- **HLS Streaming Mode**: Choose between Video & Audio or Audio Only

### Additional Service Controls

Enable or disable additional services for your API key.

![Service Controls](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.08%E2%80%AFPM.png)

**Available Services:**
- **RTMP Output**: Enable RTMP streaming to external platforms
- **SIP Integration**: Enable SIP (Session Initiation Protocol) integration for telephony
- **Realtime Translation**: Enable real-time language translation in meetings

### Transcription & Summary

Configure transcription and domain whitelisting for your API key.

![Transcription Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.50%E2%80%AFPM.png)

**Transcription Controls:**
- **Enabled**: Toggle to enable/disable transcription and summary features
- **Whitelist Domain**: Add domain restrictions for API key usage
  - Enter domain names in the format `https://domain.name`
  - Click "Add Domain" to whitelist specific domains
  - Only whitelisted domains can use this API key
  - When no domains are whitelisted, the API key can be used from any domain


---

# Initialize Meeting - Android

To configure a VideoSDK meeting you require two things, first the `token` which will be used for **Authentication** purpose and a `meetingId` which will be used to specify where a participant will join. Let's see each of the steps closely.

### Generating Token

You can generate a `token` in two ways:

1. **`Temporary Token`** : You can visit [Dashboard's API Key section](https://app.videosdk.live/api-keys) and generate the temporary token from there.

2. **`Server`** : You can setup **JWT** in backend and make an API call to get the token from your server.

To learn more about **Authentication** and token in detail you can follow [this guide](../authentication-and-token).



**Kotlin:**

```js
// With Temporary Token
fun getToken(): String? {
  // Update the token here from the VideoSDK dashboard
  // highlight-next-line
  return "YOUR_TOKEN"
}

// Server
fun getToken(): String? {
  val token = arrayOfNulls

- **`multiStream`**:

  - It will specify if the stream should send multiple resolution layers or single resolution layer.

  - It has to be of `boolean` type.

- **`customTracks`**:

  - If you want to set the initial custom tracks, then you can pass map of custom tracks in this paramater.

  - It has to be of `Map<String, CustomStreamTrack>` type.

- **`metaData`**:

  - If you want to provide additional details about a user joining a meeting, such as their profile image, you can pass that information in this parameter.

  - It has to be of `JsonObject` type.

- **`signalingBaseUrl`**:

  - If you want to use a proxy server with the VideoSDK, you can specify your base URL here.

  - It has to be of `String` type.

  - It is Optional parameter.

:::note

If you intend to use a proxy server with the VideoSDK, priorly inform us at support@videosdk.live

:::

- **`preferredProtocol`**:

  - If you want to provide a preferred network protocol for communication, you can specify that in `PreferredProtocol`, with options including `UDP_ONLY`, `UDP_OVER_TCP`, and `TCP_ONLY`.

  - It has to be of `PreferredProtocol` type.

  - It is Optional parameter.

With all the configuration options explained, here is how you can initialize the meeting.

**Kotlin:**

```js
class MainActivity : AppCompatActivity() {

  fun getToken(): String? {
//highlight-next-line
...
  }

  fun getMeetingId(token: String?): String? {
//highlight-next-line
...
  }

 override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)

// initialize AndroidNetworking to perform Network call
AndroidNetworking.initialize(applicationContext)

//We will fetch token and meetingId and store it in local variables
val token: String = getToken()
val meetingId = getMeetingId(token)

// highlight-start
// initialize the VideoSDK
VideoSDK.initialize(this@MainActivity)

// set token property of VideoSDK
VideoSDK.config(token)

// create a new meeting instance
val meeting: Meeting = VideoSDK.initMeeting(
    this@MainActivity, meetingId, "NAME HERE",
    true, true, null, null, false, null, null
)
// highlight-end

Log.d("VideoSDK", "onCreate: $meetingId")
  }
}
```

---

**Java:**

```java
public class MainActivity extends AppCompatActivity {

  public String getToken()
  {
//highlight-next-line
...
  }

  public String getMeetingId(String token) {
//highlight-next-line
...
  }

  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

// initialize AndroidNetworking to perform Network call
AndroidNetworking.initialize(getApplicationContext());

//We will fetch token and meetingId and store it in local variables
String token = getToken();
String meetingId = getMeetingId(token);

// highlight-start
// initialize the VideoSDK
VideoSDK.initialize(MainActivity.this);

// set token property of VideoSDK
VideoSDK.config(token);

// create a new meeting instance
Meeting meeting = VideoSDK.initMeeting(
        MainActivity.this, meetingId, "NAME HERE",
        true, true, null, null, false, null, null
// highlight-end

Log.d("VideoSDK", "onCreate: " + meetingId);
  }
}
```

### API Reference

The API references for all the methods utilised in this guide are provided below.

- [initMeeting](/android/api/sdk-reference/initMeeting)


---

# Join Meeting - Android

### Overview

After meeting initialization by `initMeeting()` it returns a new instance of `Meeting`. If you have not initialized a meeting yet, you can [follow the guide here.](./initialize-meeting) However, by default, it will not automatically join the meeting. Hence, to join the meeting you have to call `join()` .

### `join()`

- To join the meeting you can call the `join()` method of `Meeting` class.
- This method can be called after the meeting is initialized using `VideoSDK` class.



**Kotlin:**

```js
class MainActivity : AppCompatActivity() {
 override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
// initialize the meeting
...

// join meeting
// highlight-next-line
meeting!!.join()
  }
}
```

---

**Java:**

```java
public class MainActivity extends AppCompatActivity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// initialize the meeting
...

// join meeting
// highlight-next-line
meeting.join();
  }
}
```

### Events associated with Join

Following callbacks are received when a participant is successfully joined.

- [Local Participant](../concept-and-architecture#2-participant) will receive a [`onMeetingJoined`](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmeetingjoined) event, when successfully joined.
- [Remote Participant](../concept-and-architecture#2-participant) will receive a [`onParticipantJoined`](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onparticipantjoined) event with the newly joined `Participant` object from the event callback.

**Kotlin:**

```js
class MainActivity : AppCompatActivity() {
 override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
// initialize the meeting
...

// join meeting
meeting!!.join()

// Add event listener for listening upcoming events of meeting
// highlight-next-line
meeting!!.addEventListener(meetingEventListener)
  }

  private val meetingEventListener: MeetingEventListener = object : MeetingEventListener(){
// Event to know meeting is joined
//highlight-start
fun onMeetingJoined() {
    Log.d("VideoSDK", "onMeetingJoined")
}
//highlight-end
// Event to know some other participant joined
//highlight-start
fun onParticipantJoined(participant: Participant) {
    Log.d("#VideoSDK", participant.displayName + " joined");
}
//highlight-end
  }
}
```

---

**Java:**

```java
public class MainActivity extends AppCompatActivity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// initialize the meeting
...

// join meeting
meeting.join();

// Add event listener for listening upcoming events of meeting
//highlight-next-line
meeting.addEventListener(meetingEventListener);
  }

  private final MeetingEventListener meetingEventListener=new MeetingEventListener() {
// Event to know meeting is joined
//highlight-start
@Override
public void onMeetingJoined() {
    Log.d("VideoSDK", "onMeetingJoined");
}
//highlight-end

// Event to know some other participant joined
//highlight-start
@Override
public void onParticipantJoined(Participant participant) {
    Log.d("#VideoSDK", participant.getDisplayName() + " joined");
}
//highlight-end
  };
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [initMeeting](/android/api/sdk-reference/initMeeting)
- [join()](/android/api/sdk-reference/meeting-class/methods#join)
- [onMeetingJoined()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmeetingjoined)
- [onParticipantJoined()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onparticipantjoined)


---

# Leave or End Meeting - Android

Participant can choose to leave the meeting without removing all the other participants. This is typically done by `Leave Meeting`.

Alternatively, if the participant is the host and the last person remaining in the session, they can choose `End Meeting` by removing all other participants, which will end the session for everyone.

### `leave()`

To leave the meeting without removing all the participant you need to call `leave()` method of `Meeting` class.

### `end()`

To leave the meeting by removing all the participant you need to call `end()` method of `Meeting` class.

:::note
This methods can be called after the meeting is joined successfully.
:::

#### Example



**Kotlin:**

```js
  btnLeave!!.setOnClickListener { _: View? ->
//highlight-next-line
meeting!!.leave() // Leaving Meeting
  }

  btnEnd!!.setOnClickListener { _: View? ->
//highlight-next-line
meeting!!.end() // Ending Meeting
  }
```

---

**Java:**

```js
  btnLeave.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
    //highlight-next-line
    meeting.leave(); // Leaving Meeting
  }
  });

  btnEnd.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
    //highlight-next-line
    meeting.end(); // Ending Meeting
  }
  });
```

### Events associated with Leave

Following callbacks are received when a participant leaves the meeting.

- **Local Participant**: Will receive [`onMeetingLeft`](#onmeetingleft) with an optional `LeaveReasons` object.
- **Remote Participants**: Will receive [`onParticipantLeft`](#onparticipantleft) with the `Participant` object and an optional `LeaveReasons` object.

### Events associated with End

Following callbacks are received when a participant ends the meeting.

- All participants (local and remote) will receive a callback on [`onMeetingLeft`](#onmeetingleft) with an optional `LeaveReasons` object.

**Kotlin:**

```javascript
private val meetingEventListener = object : MeetingEventListener() {
// Leave reason is optional
// Event to know meeting is left
//highlight-start
override fun onMeetingLeft(reason: LeaveReason) {
    Log.d("#VideoSDK", "onMeetingLeft() :: reason: ${reason?.message}")
}
//highlight-end

// Event to know some other participant left
//highlight-start
override fun onParticipantLeft(participant: Participant, reason: LeaveReason) {
    Log.d("#VideoSDK", "${participant.displayName} left :: reason: ${reason?.message}")
}
//highlight-end
}
```

---

**Java:**

```javascript
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
// Leave reason is optional
// Event to know meeting is left
//highlight-start
@Override
public void onMeetingLeft(LeaveReason reason) {
    Log.d("#VideoSDK", "onMeetingLeft() :: reason: " + reason.getMessage()));
}
//highlight-end

// Event to know some other participant left
//highlight-start
@Override
public void onParticipantLeft(Participant participant, LeaveReason reason) {
    Log.d("#VideoSDK", participant.getDisplayName() + " left :: reason: " + reason.getMessage()));
}
//highlight-end
};
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [Leave Reason Enum Table](/android/api/sdk-reference/meeting-class/properties#leavereasons-enum)
- [leave()](/android/api/sdk-reference/meeting-class/methods#leave)
- [end()](/android/api/sdk-reference/meeting-class/methods#end)
- [onMeetingLeft()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmeetingleft)
- [onParticipantLeft()](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onparticipantleft)


---

# Precall Setup - Android 

Picture this: before diving into the depths of a video call, imagine giving your setup a quick check-up, like a tech-savvy doctor ensuring all systems are a go. That's essentially what a precall experience does- it’s like your extensive debug session before the main code execution—a crucial step in ensuring your app's performance is top-notch.

## Why is it necessary?

Why invest time and effort into crafting a precall experience, you wonder? Well, picture this scenario: your users eagerly join a video call, only to encounter a myriad of technical difficulties—muted microphones, pixelated cameras, and laggy connections. Not exactly the smooth user experience you had in mind, right?

By integrating a robust precall process into your app, developers become the unsung heroes, preemptively addressing potential pitfalls and ensuring that users step into their video calls with confidence.

## Step-by-Step Guide: Integrating Precall Feature

### Step 1: Check and Request Permissions

- Begin by ensuring that your application has the necessary permissions to access user devices, such as the camera, microphone and Bluetooth.
- Utilize the `checkPermissions()` method of the `VideoSDK` class to verify if permissions are granted.
- If the permissions are not granted, the method will request the required permissions.
- `PermissionHandler` is used to manage and handle permission-related events (such as granting, denying, or blocking permissions).
  - `onGranted()`: This method is called when all requested permissions are granted.
  - `onBlocked()`: This method is called when one or more permissions are permanently blocked (i.e., the user has checked "Don't ask   again").
  - `onDenied()`: This method is called when one or more permissions are denied.
  - `onJustBlocked()`: This method is called when one or more permissions are just blocked (i.e., the user has just checked "Don't ask again" for the first time).



**Kotlin:**

```js
private fun checkPermissions() {
val permissionList: MutableList

</center>


### Step 2: Render Device Lists

- You can fetch and render lists of available video and audio devices using the `getVideoDevices()` and `getAudioDevices()` methods of the VideoSDK class, respectively.
  
**Kotlin:**

```js
private fun getAudioaDevices() {
  
  val audioDevices: Set
</center>


### Step 3: Handle Audio Device Changes

- Implement the `onAudioDeviceChanged()` callback of the `VideoSDK` class to dynamically re-render audio device lists whenever new devices are attached or removed from the system.
- Ensure that users can seamlessly interact with newly connected devices without disruptions.


**Kotlin:**

```js
VideoSDK.setAudioDeviceChangeListener(object : VideoSDK.AudioDeviceChangeEvent {
override fun onAudioDeviceChanged(
    selectedAudioDevice: AudioDeviceInfo?,
    audioDevices: MutableSet

### Step 4: Ensuring the selected devices are used in the Meeting

- Ensure that the status of all relevant devices, such as the microphone and camera (on/off), as well as the selected devices, are correctly configured and passed into the meeting from the precall screen.
- To select a video device, you can either create a custom track with the chosen `VideoDeviceInfo` and pass it to the `initMeeting` method of the `VideoSDK` class, or you can use the `setSelectedVideoDevice()` method of the `VideoSDK` class.
- To select an audio device, use the `setSelectedAudioDevice()` method of the `VideoSDK` class.  
- By ensuring this integration, users can seamlessly transition from the precall setup to the actual meeting while preserving their preferred settings.

**Kotlin:**

```js
class MainActivity : AppCompatActivity() {

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val customTracks: MutableMap<String, CustomStreamTrack> = HashMap()

    // Specify the video device to use in the meeting
    val videoDeviceInfo: VideoDeviceInfo = selectedVideoDeviceInfo

    val videoCustomTrack = VideoSDK.createCameraVideoTrack(
        "h720p_w960p", "front", CustomStreamTrack.VideoMode.TEXT, true,
        this, VideoSDK.getSelectedVideoDevice()
    )
    customTracks["video"] = videoCustomTrack

    VideoSDK.setSelectedVideoDevice(videoDeviceInfo)

    // Specify the audio device to use in the meeting
    val audioDeviceInfo: AudioDeviceInfo = selectedAudioDeviceInfo

    VideoSDK.setSelectedAudioDevice(audioDeviceInfo)

    val meeting: Meeting = VideoSDK.initMeeting(
        this@MainActivity, "meetingId", "John Due", true,
        true, null, null, false, customTracks, null
    );
}
}
```

---

**Java:**

```java
public class MainActivity extends AppCompatActivity {

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    Map<String, CustomStreamTrack> customTracks = new HashMap<>();

    // Specify the video device to use in the meeting
    VideoDeviceInfo videoDeviceInfo = selectedVideoDeviceInfo; 

    CustomStreamTrack videoCustomTrack = VideoSDK.createCameraVideoTrack(
        "h720p_w960p", "front", CustomStreamTrack.VideoMode.TEXT, true,
        this, VideoSDK.getSelectedVideoDevice()
    );        
    customTracks.put("video", videoCustomTrack);

    VideoSDK.setSelectedVideoDevice(videoDeviceInfo);

    // Specify the audio device to use in the meeting
    AudioDeviceInfo audioDeviceInfo = selectedAudioDeviceInfo; 
 
    VideoSDK.setSelectedAudioDevice(audioDeviceInfo);

    Meeting meeting = VideoSDK.initMeeting(
        MainActivity.this, "meetingId", "John Due",true,
        true, null, null, false, customTracks,null
    );
}
}
```

### Step 5: Get Selected Devices

- VideoSDK library provides two methods, `getSelectedVideoDevice()` and `getSelectedAudioDevice()`, which allow us to determine which video and audio devices are currently selected on our Android device.

**Kotlin:**

```js
private fun getSelectedVideoDevice(){
Log.d("TAG", "onCreate: " + VideoSDK.getSelectedVideoDevice().label)
}

private fun getSelectedAudioDevice(){
Log.d("TAG", "onCreate: " + VideoSDK.getSelectedAudioDevice().label)
}
```

---

**Java:**

```java
private void getSelectedVideoDevice() {
  VideoDeviceInfo selectedVideoDevice = VideoSDK.getSelectedVideoDevice();
  Log.d("TAG", "Selected Video Device Label: " + selectedVideoDevice.getLabel());
}

private void getSelectedAudioDevice() {
  AudioDeviceInfo selectedAudioDevice = VideoSDK.getSelectedAudioDevice();
  Log.d("TAG", "Selected Audio Device Label: " + selectedAudioDevice.getLabel());
}
```


By following these step-by-step instructions, you can seamlessly integrate a precall feature into your application, empowering users to optimize their audio and video setup for a superior communication experience.

:::note

You can explore the complete implementation of the Precall feature in the official Android SDK example [available here.](https://github.com/videosdk-live/videosdk-rtc-android-kotlin-sdk-example)

:::

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [checkPermissions](/android/api/sdk-reference/videosdk-class/methods#checkpermissions)
- [getAudioDevices](/android/api/sdk-reference/videosdk-class/methods#getaudiodevices)
- [getVideoDevices](/android/api/sdk-reference/videosdk-class/methods#getvideodevices)
- [setAudioDeviceChangeListener](/android/api/sdk-reference/videosdk-class/events)
- [getSelectedVideoDevice](/android/api/sdk-reference/videosdk-class/properties#getselectedvideodevice)
- [getSelectedAudioDevice](/android/api/sdk-reference/videosdk-class/properties#getselectedaudiodevice)






---

### Generate Token

To manage secured communication, every participant that connects to a meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key`, which you can obtain from the [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

**For development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for obtaining a token involves generating it from your backend server which will help in **keeping your credentials safe**.
:::



---

SIP Connect allows you to connect any SIP-compatible device or softphone to a VideoSDK room. This guide explains how to configure SIP for your VideoSDK account and connect a SIP user to an existing meeting.

## Architecture

The following diagram illustrates how SIP Connect works. A SIP user connects to the VideoSDK SIP Gateway, which then bridges the call to the VideoSDK Room.

![VideoSDK Telephony Workflow](https://strapi.videosdk.live/uploads/SIP_CONNECT_c81702f580.png)

## Steps

In this guide, we are using Twilio as the SIP provider, but you can choose from other providers like Plivo, Exotel, Telnyx, Ozontel, etc. The configuration process is similar across most providers.

### 1. Create VideoSDK Meeting


:::note
Ensure you have a VideoSDK meeting setup. If you don't have one, follow the <a href={props.quickStartLink}>Quick Start Guide</a> to create a basic video calling app.
:::

You can connect a SIP user to any active VideoSDK meeting. If you already have a meeting ID, you can proceed to the next step.



### 2. Create Inbound Gateway


An **Inbound Gateway** is required to receive calls from a SIP provider (like Twilio, Vonage, Telnyx) and route them to VideoSDK.

**twilio:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/inbound-gateways).
2. Navigate to **Telephony > Inbound Gateways**.
3. Click **Add Inbound Gateway**.
4. Enter a name and the phone number you purchased from your SIP provider.
5. Select the Geo Region option and choose where inbound SIP traffic should be routed (currently supported: India, US).
6. Click **Create**.
7. Copy the **Inbound Gateway SIP URI**
- Default: `sip:orgId.sip.videosdk.live`
- Regional (to restrict calls to a specific region): `sip:orgId.<region>.sip.videosdk.live`
8. Configure this URI as the **Origination SIP URI** in your SIP provider's dashboard (e.g., Twilio, Vonage, Telnyx).

<div style={{textAlign: 'center'}}>
  
</div>

---

**vonage:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/inbound-gateways).
2. Navigate to **Telephony > Inbound Gateways**.
3. Click **Add Inbound Gateway**.
4. Enter a name and the phone number you purchased from Vonage.
5. Select the Geo Region option and choose where inbound SIP traffic should be routed (currently supported: India, US).
6. Click **Create**.
7. Copy the **Inbound Gateway SIP URI**
- Default: `sip:orgId.sip.videosdk.live`
- Regional (to restrict calls to a specific region): `sip:orgId.<region>.sip.videosdk.live`
8. In your **Vonage Console**, go to your SIP Trunk settings.
9. Under **Inbound Calls**, select your region.
10. In the **URI** section, paste the Inbound Gateway SIP URI you copied.
11. Link the phone number you purchased to this trunk.

<div style={{textAlign: 'center'}}>
  
</div>

---

**telnyx:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/inbound-gateways).
2. Navigate to **Telephony > Inbound Gateways**.
3. Click **Add Inbound Gateway**.
4. Enter a name and the phone number you purchased from Telnyx.
5. Select the Geo Region option and choose where inbound SIP traffic should be routed (currently supported: India, US).
6. Click **Create**.
7. Copy the **Inbound Gateway SIP URI**
- Default: `sip:orgId.sip.videosdk.live`
- Regional (to restrict calls to a specific region): `sip:orgId.<region>.sip.videosdk.live`
8. In your **Telnyx Console**, go to **Connections** and create a new SIP Connection.
9. Set the type as **FQDN**.
10. Under **FQDN**, add the VideoSDK Inbound Gateway SIP URI you copied.
11. Assign the phone number you purchased to this connection.

<div style={{textAlign: 'center'}}>
  
</div>

---

**api:**

You can create an inbound gateway programmatically using the API.

```bash title="cURL"
curl --request POST \
  --url https://api.videosdk.live/v2/sip/inbound-gateways \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
"name": "My Inbound Gateway",
"numbers": ["+1234567890"]
  }'
```

> **API Reference**: [Create Inbound Gateway](/api-reference/realtime-communication/sip/inbound-gateway/create-inbound-gateway)



### 3. Create Outbound Gateway


An **Outbound Gateway** is used if you want to dial out to a SIP user from a VideoSDK meeting.

**twilio:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/outbound-gateways).
2. Navigate to **Telephony > Outbound Gateways**.
3. Click **Add Outbound Gateway**.
4. Enter a name.
5. Enter the **Termination SIP URI** provided by your SIP provider.
6. Enter the **Username** and **Password** for your SIP provider.
7. Set the Geo Region to route outbound calls through a specific region (currently supported: India, US).
8. Click **Create**.

<div style={{textAlign: 'center'}}>
  
</div>

---

**vonage:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/outbound-gateways).
2. Navigate to **Telephony > Outbound Gateways**.
3. Click **Add Outbound Gateway**.
4. Enter a name.
5. Enter the **Domain** you set up in your Vonage SIP Trunk settings.
6. Enter the **Username** and **Password** you configured in Vonage under **Outbound Calls**.
7. Set the Geo Region to route outbound calls through a specific region (currently supported: India, US).
8. Click **Create**.
9. **Note:** For outbound gateway numbers, do not use the `+` sign—just use the country code and number.

<div style={{textAlign: 'center'}}>
  
</div>

---

**telnyx:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/outbound-gateways).
2. Navigate to **Telephony > Outbound Gateways**.
3. Click **Add Outbound Gateway**.
4. Enter a name.
5. Enter the **SIP Domain** you configured in your Telnyx SIP Connection.
6. Enter the **Username** and **Password** you set up in Telnyx under **Outbound Authentication**.
7. Set the Geo Region to route outbound calls through a specific region (currently supported: India, US).
8. Click **Create**.

<div style={{textAlign: 'center'}}>
  
</div>

---

**api:**

To route outbound calls through a specific region, set the `geoRegion` property in the API request. By default, the SIP server region is automatically selected based on the location nearest to the dialed number (currently supported: India, US).

```bash title="cURL"
curl --request POST \
  --url https://api.videosdk.live/v2/sip/outbound-gateways \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
"name": "My Outbound Gateway",
"numbers": ["+1234567890"],
"address": "sip.provider.com",
"geoRegion" : "us002",
"auth": {
  "username": "sip_username",
  "password": "sip_password"
}
  }'
```

> **API Reference**: [Create Outbound Gateway](/api-reference/realtime-communication/sip/outbound-gateway/create-outbound-gateway)



### 4. Create Routing Rules


Routing rules determine how calls are handled.

#### Inbound Routing
For inbound calls, you need to route the call to a specific meeting room.

1. Go to **Telephony > Routing Rules**.
2. Click **Add Routing Rule**.
3. Select your **Inbound Gateway**.
4. Select the **Phone Number**.
5. Under **Dispatch**, select **Room**.
6. Choose **Dynamic** (creates a new room) or **Static** (connects to a specific room ID).
7. Click **Create**.

#### Outbound Routing
For outbound calls, the routing rule selects which Outbound Gateway to use based on the dialed number.

1. Go to **Telephony > Routing Rules**.
2. Click **Add Routing Rule**.
3. Select your **Outbound Gateway**.
4. Enter the **Phone Number** pattern (e.g., `+1*`).
5. Click **Create**.

<div style={{textAlign: 'center'}}>
  
</div>



## Connect SIP User

### Inbound Call
Now that everything is configured, a SIP user can join the meeting by simply dialing the phone number configured in the Inbound Gateway.
1. The call reaches your SIP provider.
2. The provider forwards it to VideoSDK.
3. VideoSDK checks the Routing Rule.
4. The user is connected to the VideoSDK Room.

### Outbound Call
To dial a SIP user from the meeting, you can use the `dispatch` API or the SDK method if available.

```bash title="cURL"
curl --request POST \
  --url https://api.videosdk.live/v2/sip/call \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "gatewayId": "outbound-gateway-id",
    "sipCallTo": "+1234567890",
    "destinationRoomId": "room-id"
  }'
```

> **API Reference**: [Make Outbound Call](/api-reference/realtime-communication/sip/calls/call-trigger)

## Webhooks

You can configure webhooks to receive real-time updates about SIP calls.

### Available Webhook Events
Below is the list of all supported webhook events:

| Event Name | Description |
| :--- | :--- |
| `call-started` | Triggered when a new outbound or inbound call is initiated. |
| `call-answered` | Triggered when the call is answered by the recipient. |
| `call-hangup` | Triggered when the call is completed or hung up by either party. |
| `call-transferred` | Call transferred to another destination. |
| `call-missed` | Triggered when the call is not answered or missed by the recipient. |
| `call-update` | Triggered when there is an update in the call status. |
| `call-ringing` | Triggered when the call is ringing at the destination endpoint. |
| `call-transfer-initiated` | Call transfer has been initiated. |
| `call-transfer-accepted` | Call transfer has been accepted by the target. |
| `call-transferring` | Call is being transferred to another destination. |
| `call-transfer-ringing` | Call is ringing at the transfer target. |
| `call-transfer-failed` | Call transfer failed. |

You can configure these in the **Telephony > Webhooks** section of the dashboard.

## Configuring Webhooks

You can set up webhooks using:

- **Dashboard:** Navigate to the SIP section and add a webhook by specifying your target URL and selecting the events you want to subscribe to.
- **API:** Use the `POST /v2/sip/webhooks` endpoint to register a webhook.



## API Reference

- [Create Webhook API](/api-reference/realtime-communication/sip/webhook/create-webhook)
- [Fetch all Webhook API](/api-reference/realtime-communication/sip/webhook/fetch-all-webhooks)
- [Fetch a Webhook API](/api-reference/realtime-communication/sip/webhook/fetch-webhook)
- [Update Webhook API](/api-reference/realtime-communication/sip/webhook/update-webhook)
- [Delete Webhook API](/api-reference/realtime-communication/sip/webhook/delete-webhook)



---

# Supported Device OS and Architecture

:::note
The following device OS version represent the minimum required version to ensure full support for the listed features.
:::




<br/>

# Supported ABIs





---

# Post Transcription & Summary - Android

This guide will walk you through the necessary steps to enable post-transcription functionality in your application, allowing users to access transcriptions of recorded meetings.

Moreover, VideoSDK offers flexibility in configuring post-time transcription, allowing you to set up webhooks for this purpose.

## Integrating Post Transcription Feature

![alt text](/img/transcription/post-transcription.png)

In the image above, the recording begins with transcription and summary features turned on. This triggers a webhook call for the start of recording. When the recording stops, another webhook is activated. After the recording, our transcriber starts transcribing, which in turn activates a webhook. Once the transcription is finished, it's sent to the summarizer for summary generation, and then another webhook is triggered.

### **Step 1: Configure Post Transcription & Summary**

- In this step, we set up the configuration for post transcription and summary generation. We define the webhook URL where the webhooks will be received.



**Kotlin:**

```js
// Webhook URL where, webhooks are received
val webhookUrl = "https://www.example.com"

//highlight-next-line
// Post Transcription Configuration
val prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
val summaryConfig = SummaryConfig(true, prompt)
val modelId = "raman_v1"
val transcription = PostTranscriptionConfig(true, summaryConfig, modelId)
```

---

**Java:**

```js
// Webhook URL where, webhooks are received
final String webhookUrl = "https://www.example.com";

//highlight-next-line
// Post Transcription Configuration
String prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary";
SummaryConfig summaryConfig = new SummaryConfig(true, prompt);
String modelId = "raman_v1";
PostTranscriptionConfig transcription = new PostTranscriptionConfig(true, summaryConfig, modelId);
```

### **Step 2: Start Recording with Transcription Configuration**

- Once the configuration is set, we initiate the recording process for the meeting, incorporating the transcription configuration we defined earlier.

**Kotlin:**

```js
// Start Recording
meeting!!.startRecording(webhookUrl, "AWS Directory Path", null, transcription)
```

---

**Java:**

```js
// Start Recording
meeting.startRecording(webhookUrl, "AWS Directory Path", null, transcription);
```

### **Step 3: Stop Recording**

- When the meeting concludes or recording is no longer needed, we stop the recording process.

**Kotlin:**

```js
// Stop Recording
meeting!!.stopRecording()
```

---

**Java:**

```js
// Stop Recording
meeting.stopRecording();
```

### **Step 4: Fetch Post Transcriptions**

- After the meeting recording is stopped, post transcription and summary data can be obtained using the [Post Transcription API](/api-reference/realtime-communication/fetch-post-transcriptions-summary).

- The API provides information such as the status of transcription, file paths for transcription data in various formats (JSON, SRT, TXT, TSV, VTT), and a summarized text file.

- The transcription document is structured as follows:

```json
{
  "id": "40b0a4ed-9842-40c9-a288-e4b1bf98a90a",
  "status": "completed",
  "roomId": "abc-xyzw-lmno",
  "sessionId": "621497578bea0d0404c35c4c",
  "recordingId": "65d303d6d2c373dfd71b38a2",
  "filePath": "https://cdn.videosdk.live/encoded/videos/dummy.mp4",
  "transcriptionFilePaths": {
    "json": "https://cdn.videosdk.live/transcriptions/dummy/dummy.json",
    "srt": "https://cdn.videosdk.live/transcriptions/dummy/dummy.srt",
    "txt": "https://cdn.videosdk.live/transcriptions/dummy/dummy.txt",
    "tsv": "https://cdn.videosdk.live/transcriptions/dummy/dummy.tsv",
    "vtt": "https://cdn.videosdk.live/transcriptions/dummy/dummy.vtt"
  },
  "summarizedFilePaths": {
    "txt": "https://cdn.videosdk.live/transcriptions/dummy/dummy-summary.txt"
  },
  "userStorage": null,
  "start": "2024-02-27T16:00:36.828Z",
  "end": "2024-02-27T16:01:46.939Z"
}
```

### Example

- The following code snippet allows you to start and stop recording meetings with just a click. When you click the "Start Recording" button, it begins recording the meeting and enables post-transcription, which generates a summary of the meeting's content. Clicking the "Stop Recording" button ends the recording.

**Kotlin:**

```js
import android.os.Bundle
import android.widget.Button
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity

class MeetingActivity : AppCompatActivity() {
private lateinit var meeting: Meeting

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_meeting)

    //initialize a meeting
    //...

    val startButton = findViewById<Button>(R.id.startRecording)
    val stopButton = findViewById<Button>(R.id.stopRecording)

    startButton.setOnClickListener {
        //highlight-start
        // Configuration for post transcription
        val prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
        val summaryConfig = SummaryConfig(true, prompt)
        val modelId = "raman_v1"
        val transcription = PostTranscriptionConfig(true, summaryConfig, modelId)

        // If you don't have a `webhookUrl` or `awsDirPath`, you have to pass null.
        // Start recording with post transcription
        meeting.startRecording("YOUR WEB HOOK URL", "AWS Directory Path", null, transcription)
        //highlight-end
    }

    stopButton.setOnClickListener {
        //highlight-start
        // Stop recording
        meeting.stopRecording()
        //highlight-end
    }
}
}
```

---

**Java:**

```js
import android.os.Bundle;
import android.widget.Button;
import android.widget.Toast;
import androidx.appcompat.app.AppCompatActivity;

public class MeetingActivity extends AppCompatActivity {
private Meeting meeting;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_meeting);

    //initialize a meeting
    //...

    Button startButton = findViewById(R.id.startRecording);
    Button stopButton = findViewById(R.id.stopRecording);

    startButton.setOnClickListener(v -> {
        //highlight-start
        // Configuration for post transcription
        String prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary";
        SummaryConfig summaryConfig = new SummaryConfig(true, prompt);
        String modelId = "raman_v1";
        PostTranscriptionConfig transcription = new PostTranscriptionConfig(true, summaryConfig, modelId);

        // If you don't have a `webhookUrl` or `awsDirPath`, you have to pass null.
        // Start recording with post transcription
        meeting.startRecording("YOUR WEB HOOK URL", "AWS Directory Path", null, transcription);
        //highlight-end
    });

    stopButton.setOnClickListener(v -> {
        //highlight-start
        // Stop recording
        meeting.stopRecording();
        //highlight-end
    });
}
}
```

:::important

Please be aware that there may be a delay in processing the transcription data after the recording has been stopped. This delay could vary depending on factors such as server load and the duration of the meeting.

:::

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [startRecording()](/android/api/sdk-reference/meeting-class/methods#startrecording)
- [stopRecording()](/android/api/sdk-reference/meeting-class/methods#stoprecording)
- [fetchPostTranscriptions](/api-reference/realtime-communication/fetch-post-transcriptions-summary)


---

# Realtime Transcription - Android

Realtime transcription allows you to transcribe audio content into text in real-time during a session. This guide will walk you through using the `startTranscription()` and `stopTranscription()` functions to manage realtime transcription in your application.

Moreover, VideoSDK offers flexibility in configuring real-time transcription, allowing you to set up webhooks for this purpose.

## Integrating Realtime Transcription Feature

![alt text](/img/transcription/realtime-transcription.png)

The above image represents,

1. **Start Transcription:** The SDK Client initiates real-time transcription using the `startTranscription` method.

2. **Resource Acquisition:** VideoSDK server requests necessary resources from transcription service.

   - If the request is denied, the server sends a `transcription-failed` event to the SDK Client.
   - If the request is successful, the server sends a `onTranscriptionStateChanged` event with status `TRANSCRIPTION_STARTED` to the client, indicating that transcription has begun.

3. **Transcription Data:** As transcription progresses, the client receives `onTranscriptionText` event with data such as the text itself, participant ID, and timestamp.

4. **Stop Transcription:** When the client decides to stop transcription, it informs the VideoSDK server to release resources.
   - The server then sends a `onTranscriptionStateChanged` event with status `TRANSCRIPTION_STOPPED` to confirm that transcription has ended and resources are released.

### **Step 1: Configure Realtime Transcription**

- In this step, we set up the configuration for realtime transcription. We define the webhook URL where the webhooks will be received.



**Kotlin:**

```js
// Webhook URL where, webhooks are received
val webhookUrl = "YOUR_WEBHOOK_URL"

//highlight-next-line
// Realtime Transcription Configuration
val summaryConfig = SummaryConfig(
true,
"Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
)
val transcription = TranscriptionConfig(
webhookUrl,
summaryConfig
)
```

---

**Java:**

```js
// Webhook URL where, webhooks are received
final String webhookUrl = "YOUR_WEBHOOK_URL";

//highlight-next-line
// Realtime Transcription Configuration
SummaryConfig summaryConfig = new SummaryConfig(
true,
"Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
);
TranscriptionConfig transcription = new TranscriptionConfig(
webhookUrl,
summaryConfig
);
```

### **Step 2: Listen for the transcription events**

- Here, we configure the callback methods for transcription events.

**Kotlin:**

```js
private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onTranscriptionStateChanged(data: JSONObject) {
try {
    val status = data.getString("status")
    val id = data.getString("id")
    when (status) {
        TranscriptionState.TRANSCRIPTION_STARTING.name -> Log.d("onTranscriptionStateChanged", "Realtime Transcription is starting, ID: $id")
        TranscriptionState.TRANSCRIPTION_STARTED.name -> Log.d("onTranscriptionStateChanged", "Realtime Transcription is started, ID: $id")
        TranscriptionState.TRANSCRIPTION_STOPPING.name -> Log.d("onTranscriptionStateChanged", "Realtime Transcription is stopping, ID: $id")
        TranscriptionState.TRANSCRIPTION_STOPPED.name -> Log.d("onTranscriptionStateChanged", "Realtime Transcription is stopped, ID: $id")
        else -> Log.d("onTranscriptionStateChanged", "Unknown transcription state: $status, ID: $id")
    }
} catch (e: JSONException) {
    Log.e("onTranscriptionStateChanged", "Error parsing transcription state", e)
}
  }

  override fun onTranscriptionText(data: TranscriptionText) {
val participantId: String = data.participantId
val participantName: String = data.participantName
val text: String = data.text
val timestamp: Int = data.timestamp
val type: String = data.type

Log.d("onTranscriptionText", "$participantName: $text $timestamp")
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting!!.addEventListener(meetingEventListener)
}
```

---

**Java:**

```js
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
  @Override
public void onTranscriptionStateChanged(JSONObject data) {
    try {
        String status = data.getString("status");
        String id = data.getString("id");

        if (TranscriptionState.TRANSCRIPTION_STARTING.name().equals(status)) {
            Log.d("onTranscriptionStateChanged", "Realtime Transcription is starting, ID: " + id);
        }
        else if (TranscriptionState.TRANSCRIPTION_STARTED.name().equals(status)) {
            Log.d("onTranscriptionStateChanged", "Realtime Transcription is started, ID: " + id);
        }
        else if (TranscriptionState.TRANSCRIPTION_STOPPING.name().equals(status)) {
            Log.d("onTranscriptionStateChanged", "Realtime Transcription is stopping, ID: " + id);
        }
        else if (TranscriptionState.TRANSCRIPTION_STOPPED.name().equals(status)) {
            Log.d("onTranscriptionStateChanged", "Realtime Transcription is stopped, ID: " + id);
        }
        else {
            Log.d("onTranscriptionStateChanged", "Unknown transcription state: " + status + ", ID: " + id);
        }
    } catch (JSONException e) {
        Log.e("onTranscriptionStateChanged", "Error parsing transcription state", e.getMessage());
    }
}

@Override
public void onTranscriptionText(TranscriptionText data) {
    String participantId = data.getParticipantId();
    String participantName = data.getParticipantName();
    String text = data.getText();
    int timestamp = data.getTimestamp();
    String type = data.getType();

    Log.d("onTranscriptionText", participantName + ": " + text + " " + timestamp);
}
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  //...

  // add listener to meeting
  //highlight-next-line
  meeting.addEventListener(meetingEventListener);
}
```

### **Step 3: Start realtime transcription**

- Initiate the realtime transcription using the `startTranscription()` method.

**Kotlin:**

```js
fun startRealtimeTranscription() {
// Webhook URL where, webhooks are received
val webhookUrl = "YOUR_WEBHOOK_URL"

//highlight-next-line
// Realtime Transcription Configuration
val summaryConfig = SummaryConfig(
    true,
    "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
)
val transcription = TranscriptionConfig(
    webhookUrl,
    summaryConfig
)

//highlight-next-line
meeting!!.startTranscription(transcription)
}
```

---

**Java:**

```js
private void startRealtimeTranscription() {
// Webhook URL where, webhooks are received
final String webhookUrl = "YOUR_WEBHOOK_URL";

//highlight-next-line
// Realtime Transcription Configuration
SummaryConfig summaryConfig = new SummaryConfig(
    true,
    "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
);
TranscriptionConfig transcription = new TranscriptionConfig(
    webhookUrl,
    summaryConfig
);

//highlight-next-line
meeting.startTranscription(transcription);
}
```

### **Step 4: Stop realtime transcription**

- Terminate the realtime transcription using the `stopTranscription() `method.

**Kotlin:**

```js
fun stopRealtimeTranscription() {
meeting!!.stopTranscription()
}
```

---

**Java:**

```js
private void stopRealtimeTranscription() {
meeting.stopTranscription();
}
```

:::important

You can access a summary of your realtime transcription using the **[<u>Fetch Realtime Transcription API</u>](/api-reference/realtime-communication/fetch-a-realtime-transcription)**.

:::

### Example

- The following code snippet allows you to start and stop realtime transcription with just a click. When you click the "Start Realtime Transcription" button, it begins realtime transcription. Clicking the "Stop Realtime Transcription" button ends the realtime transcription.

**Kotlin:**

```js
import android.os.Bundle
import android.util.Log
import android.widget.Button
import androidx.appcompat.app.AppCompatActivity
import org.json.JSONObject

class MeetingActivity : AppCompatActivity() {
private lateinit var meeting: Meeting

// add meetingEventListener to handle transcription events
private val meetingEventListener = object : MeetingEventListener {
    override fun onTranscriptionStateChanged(data: JSONObject) {
        val status = data.getString("status")
        Log.d("MeetingActivity", "Transcription status: $status")
    }

    override fun onTranscriptionText(data: TranscriptionText) {
        val participantId = data.participantId
        val participantName = data.participantName
        val text = data.text
        val timestamp = data.timestamp
        val type = data.type

        Log.d("MeetingActivity", "$participantName: $text $timestamp")
    }
}

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_meeting)

    //initialize a meeting
    //...

    val startButton: Button = findViewById(R.id.startTranscriptionButton)
    val stopButton: Button = findViewById(R.id.stopTranscriptionButton)

    startButton.setOnClickListener { startRealtimeTranscription() }
    stopButton.setOnClickListener { stopRealtimeTranscription() }

    // add listener to meeting
    meeting!!.setEventListener(meetingEventListener)
}

private fun startRealtimeTranscription() {
    // Configuration for realtime transcription
    val summaryConfig = SummaryConfig(
        true,
        "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
    )
    val transcriptionConfig = TranscriptionConfig(
        null,
        summaryConfig
    )

    // Call to start transcription with the specified configuration
    meeting!!.startTranscription(transcriptionConfig)
}

private fun stopRealtimeTranscription() {
    // Call to stop transcription
    meeting!!.stopTranscription()
}
}
```

---

**Java:**

```js
import android.os.Bundle;
import android.util.Log;
import android.widget.Button;
import android.widget.Toast;
import androidx.appcompat.app.AppCompatActivity;

public class MeetingActivity extends AppCompatActivity {
private Meeting meeting;

// add meetingEventListener to handle transcription events
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
    @Override
    public void onTranscriptionStateChanged(JSONObject data) {
        String status = data.getString("status");
        Log.d("MeetingActivity", "Transcription status: " + status);
    }

    @Override
    public void onTranscriptionText(TranscriptionText data) {
        String participantId = data.getParticipantId();
        String participantName = data.getParticipantName();
        String text = data.getText();
        int timestamp = data.getTimestamp();
        String type = data.getType();

        Log.d("MeetingActivity", participantName + ": " + text + " " + timestamp);
    }
};

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_meeting);

    //initialize a meeting
    //...

    Button startButton = findViewById(R.id.startTranscriptionButton);
    Button stopButton = findViewById(R.id.stopTranscriptionButton);

    startButton.setOnClickListener(v -> startRealtimeTranscription());
    stopButton.setOnClickListener(v -> stopRealtimeTranscription());

    // add listener to meeting
    meeting.setEventListener(meetingEventListener);
}

private void startRealtimeTranscription() {
    // Configuration for realtime transcription
    SummaryConfig summaryConfig = new SummaryConfig(
        true,
        "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
    );
    TranscriptionConfig transcriptionConfig = new TranscriptionConfig(
        null,
        summaryConfig
    );

    // Call to start transcription with the specified configuration
    meeting.startTranscription(transcriptionConfig);
}

private void stopRealtimeTranscription() {
    // Call to stop transcription
    meeting.stopTranscription();
}
}
```

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [startTranscription()](/android/api/sdk-reference/meeting-class/methods#starttranscription)
- [stopTranscription()](/android/api/sdk-reference/meeting-class/methods#stoptranscription)
- [onTranscriptionStateChanged](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#ontranscriptionstatechanged)
- [onTranscriptionText](/android/api/sdk-reference/meeting-class/meeting-event-listener-class#ontranscriptiontext)


---

# How to integrate Banuba SDK with Android Video SDK?

The Banuba SDK is a software development kit that enables developers to integrate advanced augmented reality (AR) features, such as real-time face filters and effects, into their apps. It is widely used for creating engaging video experiences in applications like video conferencing, live streaming, and social media platforms.

<center>
<img src='https://assets.videosdk.live/images/android-banuba.png' style={{height: '400px'}}/>
</center>

To integrate the Banuba SDK with Android Video SDK, follow these steps:

### Step 1: Get Banuba Token

- To begin working with the Banuba SDK in your project, you'll need Banuba's client token.
- You can obtain this token by following the instructions in Banuba's documentation at [banuba.com](https://www.banuba.com/)

### Step 2: Add Banuba SDK dependencies

- Add custom maven repo to your `settings.gradle`:

```js title="settings.gradle"
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            name = "GitHubPackages"
            url = uri("https://maven.pkg.github.com/sdk-banuba/banuba-sdk-android")
            credentials {
                username = "sdk-banuba"
                password = "\u0067\u0068\u0070\u005f\u004a\u0067\u0044\u0052\u0079\u0049\u0032\u006d\u0032\u004e\u0055\u0059\u006f\u0033\u0033\u006b\u0072\u0034\u0049\u0069\u0039\u0049\u006f\u006d\u0077\u0034\u0052\u0057\u0043\u0064\u0030\u0052\u0078\u006d\u0045\u0069"
            }
        }
        maven { url 'https://jitpack.io' }
        maven { url "https://maven.aliyun.com/repository/jcenter" }
}}
```

- Add Banuba SDK and VideoSDK dependencies in `app/build.gradle` file.

```js title="app/build.gradle"
dependencies {
  // Banuba SDK dependencies
    implementation "com.banuba.sdk:banuba_sdk:1+"
  // Video SDK dependencies
    implementation 'live.videosdk:rtc-android-sdk:0.3.0'
  // other app dependencies
  }
```
### Step 3: Initialization of Banuba SDK

1. Create a `MainApplication` class that extends `android.app.Application`.

2. Within the `MainApplication` class, create a KEY field to store the token you generated from Banuba. This token will be used to initialize the `BanubaSdkManager`.



**Kotlin:**

```js title="MainApplication.kt"
class MainApplication : Application() {
override fun onCreate() {
    super.onCreate()

    //...
    val key = "Banuba Client Token"
    BanubaSdkManager.initialize(requireNonNull(applicationContext), key)
}

override fun onTerminate() {
    BanubaSdkManager.deinitialize()
    super.onTerminate()
}
}
```

---

**Java:**

```js title="MainApplication.java"
public class MainApplication extends Application {
@Override
public void onCreate() {
    super.onCreate();

    //...
    String KEY ="Banuba Client Token";
    BanubaSdkManager.initialize(requireNonNull(getApplicationContext()), KEY);
}
@Override
public void onTerminate() {
    BanubaSdkManager.deinitialize();
    super.onTerminate();
}
}
```

### Step 4: Add effects into your project

- Create an effects folder under the assets directory in your project and add the filters you want to use. You can download test filters from here [Effects](https://docs.banuba.com/face-ar-sdk-v1/overview/demo_face_filters)

<div style={{textAlign: 'center'}}>

![Banuba SDK effects folder](/img/android/banuba/banuba_effects.png)

</div>

### Step 5: Integration of BanubaProcessor

- The `BanubaProcessor` class will implement the `VideoFrameProcessor` interface from VideoSDK.
- The `VideoFrameProcessor` interface provides `onFrameCaptured()` method, which is invoked when a new video frame is captured.
- The `onFrameCaptured()` method is used to manipulate the `VideoFrame` in order to achieve the desired effects.

**Kotlin:**

```js title="BanubaProcessor.kt"
class BanubaProcessor : VideoFrameProcessor {
private var mPlayer: Player = Player()
private var mFrameOutput: FrameOutput? = null
private val eglContext: EglBase.Context = EglBase.create().eglBaseContext
private var mSurfaceTextureHelper: SurfaceTextureHelper? = null
private var videoFrame: VideoFrame? = null
private val streamInput: StreamInput = StreamInput()

init {
    mSurfaceTextureHelper = SurfaceTextureHelper.create("CaptureThread", eglContext, false)
}

// set a visual effect in the Banuba Player
fun setEffect(effect: String) {
    mPlayer.loadAsync("effects/$effect")
    mPlayer.play()
}

// remove any applied effects
fun removeEffect() {
    mPlayer.loadAsync("")
}

fun removePlayer() {
    // close the player when it's no longer needed
    mPlayer.close()
}

// method to initialize the frame output for video processing
private fun initOutput(): VideoFrame? {
    val handler = mSurfaceTextureHelper!!.handler
    mFrameOutput = FrameOutput { iOutput, framePixelBuffer ->
        handler.post {
            val i420Buffer = JavaI420Buffer.wrap(
                framePixelBuffer.width,
                framePixelBuffer.height,
                framePixelBuffer.getPlane(0),
                framePixelBuffer.getBytesPerRowOfPlane(0),
                framePixelBuffer.getPlane(1),
                framePixelBuffer.getBytesPerRowOfPlane(1),
                framePixelBuffer.getPlane(2),
                framePixelBuffer.getBytesPerRowOfPlane(2),
                null
            )
            videoFrame = VideoFrame(i420Buffer, 0, System.nanoTime())
        }
    }
    mFrameOutput!!.format = FramePixelBufferFormat.I420_BT601_FULL

    handler.postDelayed({
        mFrameOutput?.close()
    }, 2000)

    // attach the FrameOutput to the player for rendering
    mPlayer.use(mFrameOutput)

    // Return the processed video frame
    return videoFrame
}

 // called whenever a new video frame is captured
override fun onFrameCaptured(videoFrame: VideoFrame?): VideoFrame? {
    if (videoFrame != null) {
        // Determine the camera orientation based on the rotation of the video frame
        val cameraOrientation = CameraOrientation.values()[(videoFrame.rotation / 90) % 4]
        val orientation = FullImageData.Orientation(cameraOrientation, true, 0)
        val i420Buffer = videoFrame.buffer.toI420()

        // create FullImageData using the frame data and orientation
        val fullImageData = FullImageData(
            Size(i420Buffer.width, i420Buffer.height),
            i420Buffer.dataY,
            i420Buffer.dataU,
            i420Buffer.dataV,
            i420Buffer.strideY,
            i420Buffer.strideU,
            i420Buffer.strideV,
            1, 1, 1,
            orientation
        )

        val frameData = FrameData.create() ?: return null
        frameData.addFullImg(fullImageData)
        i420Buffer.release()
        streamInput.push(frameData, videoFrame.timestampNs)

        // attach the StreamInput to the player for further processing
        mPlayer.use(streamInput)

        // return the processed video frame
        return initOutput()
    }
    return null
}
}
```

---

**Java:**

```js title="BanubaProcessor.java"
public class BanubaProcessor implements VideoFrameProcessor {
private Player mPlayer;
private FrameOutput mFrameOutput;
private final EglBase.Context eglContext = EglBase.create().getEglBaseContext();
private SurfaceTextureHelper mSurfaceTextureHelper;
VideoFrame videoFrame;
final StreamInput streamInput = new StreamInput();

public BanubaProcessor (){
    mSurfaceTextureHelper = SurfaceTextureHelper.create("CaptureThread", eglContext, false);
    mPlayer = new Player();
}
// set a visual effect in the Banuba Player
public void setEffect(String effect)
{
    mPlayer.loadAsync("effects/" + effect);
    mPlayer.play();
}
// remove any applied effects
public void removeEffect()
{
    mPlayer.loadAsync("");
}
public void removePlayer()
{
    // close the player when it's no longer needed
    mPlayer.close();
}
// method to initialize the frame output for video processing
private VideoFrame initOutput() {
    final Handler handler = mSurfaceTextureHelper.getHandler();
    mFrameOutput = new FrameOutput((iOutput, framePixelBuffer) -> {
        handler.post(() -> {

            final JavaI420Buffer i420buffer = JavaI420Buffer.wrap(
                    framePixelBuffer.getWidth(),
                    framePixelBuffer.getHeight(),
                    framePixelBuffer.getPlane(0),
                    framePixelBuffer.getBytesPerRowOfPlane(0),
                    framePixelBuffer.getPlane(1),
                    framePixelBuffer.getBytesPerRowOfPlane(1),
                    framePixelBuffer.getPlane(2),
                    framePixelBuffer.getBytesPerRowOfPlane(2),
                    null);
            videoFrame = new VideoFrame(i420buffer, 0, System.nanoTime());
        });
    });
    mFrameOutput.setFormat(FramePixelBufferFormat.I420_BT601_FULL);
    
    handler.postDelayed(() -> {
        mFrameOutput.close();
    },2000);

    // attach the FrameOutput to the player for rendering
    mPlayer.use(mFrameOutput);

    // return the processed video frame
    return videoFrame;
}
// called whenever a new video frame is captured
@Override
public VideoFrame onFrameCaptured(VideoFrame videoFrame) {
    if(videoFrame != null) {
        // determine the camera orientation based on the rotation of the video frame
        final CameraOrientation cameraOrientation = CameraOrientation.values()[(videoFrame.getRotation() / 90) % 4];
        final FullImageData.Orientation orientation = new FullImageData.Orientation(cameraOrientation, true, 0);
        final VideoFrame.I420Buffer i420Buffer = videoFrame.getBuffer().toI420();
        // create FullImageData using the frame data and orientation
        final FullImageData fullImageData = new FullImageData(
                new Size(i420Buffer.getWidth(), i420Buffer.getHeight()),
                i420Buffer.getDataY(),
                i420Buffer.getDataU(),
                i420Buffer.getDataV(),
                i420Buffer.getStrideY(),
                i420Buffer.getStrideU(),
                i420Buffer.getStrideV(),
                1, 1, 1,
                orientation);
        final FrameData frameData = Objects.requireNonNull(FrameData.create());
        frameData.addFullImg(fullImageData);
        i420Buffer.release();
        streamInput.push(frameData, videoFrame.getTimestampNs());
        // attach the StreamInput to the player for further processing
        mPlayer.use(streamInput);
        // return the processed video frame
        return initOutput();
    }
    return null;
}
}
```

### Step 5: Use filters in the Meeting

- First, create an instance of `BanubaProcessor` class and pass it to the `applyVideoProcessor()` method of `VideoSDK` class.
- Next, use the `setEffect` method on the instance of `BanubaProcessor` class apply the desired effect.
- To apply video filters from the beginning of the meeting, you can call `setEffect` method in `onMeetingJoined` event.

**Kotlin:**

```js title="MainActivity.kt"
private val meetingEventListener = object : MeetingEventListener {
override fun onMeetingJoined() {
    val banubaProcessor = BanubaProcessor()
    VideoSDK.applyVideoProcessor(banubaProcessor)
    //here you can pass any effect that you want to apply
    banubaProcessor.setEffect("PineappleGlasses")
}
}
```

---

**Java:**

```js title="MainActivity.java"
private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
@Override
public void onMeetingJoined() {
    BanubaProcessor banubaProcessor = new BanubaProcessor();
    VideoSDK.applyVideoProcessor(banubaProcessor);
    //here you can pass any effect that you want to apply
    banubaProcessor.setEffect("PineappleGlasses");
}
};
```

:::tip

Stuck anywhere? Check out this [Code Sample of Banuba Intergation with Android-SDK](https://github.com/videosdk-live/videosdk-rtc-android-sdk-banuba-example.git) on GitHub

:::


---

# Video Processor - Android

VideoSDK allows you to add custom effects to your video stream before it's transmitted during video calls. This lets you enhance your video in creative ways or achieve specific functionalities.

### Understanding Video Processing

Video processing involves manipulating raw video data (frames) captured by your camera. You can create native processors to enhance video streams during meetings.


### The `VideoFrameProcessor` Interface

The `VideoFrameProcessor` interface defines a way for your code to interact with the video stream. It essentially lets you intercept each frame before it's sent and apply your processing logic.

#### Key Function: `onFrameCaptured`

This is the heart of video processing with VideoSDK. Whenever a new video frame is captured by your camera, the `onFrameCaptured` function is called. This function provides you with the raw frame data, allowing you to modify it as needed.

### How it Works:

1. **Implement the Interface:** Create a class that implements the `VideoFrameProcessor` interface. Within this class, define the `onFrameCaptured` function.

2. **Process the Frame:** In the `onFrameCaptured` function, access the raw video frame data. Apply your desired effects or manipulations to this data.

3. **Return the Processed Frame:** After processing the frame, return the modified version to VideoSDK. This processed frame will then be transmitted during the video call.

4. **Apply the Processor:** To apply a processor, pass an object of your class as a parameter to the `applyVideoProcessor()` method of the `VideoSDK` class.

5. **Remove the Processor:** To stop applying the selected video processor, use the `removeVideoProcessor()` method of the `VideoSDK` class.

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [applyVideoProcessor()](/android/api/sdk-reference/videosdk-class/methods#applyvideoprocessor)
- [removeVideoProcessor()](/android/api/sdk-reference/videosdk-class/methods#removevideoprocessor)


---

# Create Deployment - API






---

# End Session - API






---

# Fetch a Deployment - API






---

# Fetch Deployments - API






---

# Fetch a Session - API






---

# Fetch Sessions - API






---

# Start Session - API






---

# Acquire Resource - Beta API








---

## Architecture




## Terminology

### Meeting

A Meeting represents real-time audio, video, and/or screen-share session, and is the basic building block for media sharing among participants.

### Participants

Participants are the client applications that are connected to a Meeting and shares video & audio media with one another.

### Local Participant

Participant producing audio or video stream from the local client's media sources

### Streams

Streams are indiviual video & audio streams produced by the participants in the meeting

### Active Speaker

Active speaker represents the participant who is currently producing highest decibels audio stream (in other words speaking)

### Active presenter

Active presenter is the participant who is currently sharing his/her screen as a video stream

### Main participant

Main participant represents the client who shall be displayed on the main screen indicating that he/she is either presenting or speaking

---


---

# Authentication - API

## Using an API to authenticate

The process of authentication is designed in such a way that it can be useful in both server and client side.

First of all, you have to install either of the SDK to generate token. Next step is to generate a `jsonwebtoken` in programming environment you are working with.

## Generate access token (NodeJS)

```js {20} title="server.js"
const express = require("express");
const jwt = require("jsonwebtoken");
const cors = require("cors");
const request = require("request");

const app = express();
const port = 9000;
app.use(cors());
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

app.get("/get-token", (req, res) => {
  const API_KEY = process.env.VIDEOSDK_API_KEY;
  const SECRET_KEY = process.env.VIDEOSDK_SECRET_KEY;
  const options = { expiresIn: "10m", algorithm: "HS256" };
  const payload = {
    apikey: API_KEY,
    permissions: ["allow_join", "allow_mod", "ask_join"], // Trigger permission.
  };
  const token = jwt.sign(payload, SECRET_KEY, options);
  res.json({ token });
});

app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`);
});
```

Now, using this `token`. You can call API's at either client or server side. Refer [jwt.io](https://jwt.io/) for other programming languages.


---

- The VideoSDK API uses authentication token to authenticate api requests.

- In REST APIs, token will be passed in header field called "Authorization".

- For Example:





---

# How to generate authentication token ?

- In order to generate authentication token, you will need `API_KEY` and `SECRET`, which you can get them from [here](https://app.videosdk.live/api-keys).

- In payload, you will add your `apikey` and `permissions`.

  - `apikey`: You can get it from [here](https://app.videosdk.live/api-keys).
  - `permissions`: List of permissions that you want to allow.
    - `allow_join`
    - `allow_mod`
    - `ask_join`

- Then, you will sign this payload with your `SECRET` and jwt options.

- You can learn more, [here](https://jwt.io/introduction)


---

# Start All Streams - API








---

# Stop All streams - API








---

# Fetch a Composite Recording - API






---

# Fetch all Composite Recording - API






---

# Start Composite Recording - API






---

# Stop Composite Recording - API






---

# Create/Join Meeting using API

### Create meeting

Use the following Rest API to create new meeting.



**curl:**

```js
cURL -H "Content-Type: application/json" \
 -H "Authorization: $YOUR_JWT_TOKEN" \
 -d '{ "userMeetingId": "unicorn" }' \
 -XPOST \
 https://api.videosdk.live/v1/meetings
```

---

**node:**

```js
var request = require("node-fetch");

var options = {
  method: "POST",
  url: "https://api.videosdk.live/v1/meetings",
  headers: {
authorization: `${YOUR_JWT_TOKEN}`,
"Content-Type": "application/json",
  },
  body: JSON.stringify({ userMeetingId: "unicorn" }),
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
```

---

**python:**

```python
import requests

url = "https://api.videosdk.live/v1/meetings"

headers = {'authorization': f'Bearer {YOUR_JWT_TOKEN}'}

response = requests.request("GET", url, headers=headers,json={"userMeetingId": "unicorn"})

print(response.text)
```

---

**ruby:**

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.videosdk.live/v1/meetings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url, 'Content-Type' => 'application/json')
request.authorization = "Bearer #{YOUR_JWT_TOKEN}"
request.body = {userMeetingId: 'unicorn'}.to_json
response = http.request(request)
puts response.read_body
```

---

**result:**

```js
{
  "meetingId": "87i6-bvw8-dtn1",
  "userMeetingId": "unicorn",
  "userId": "5fa671e77b80d58c11cbca95",
  "createdAt": "2022-01-05T06:41:16.018Z",
  "updatedAt": "2022-01-05T06:41:16.018Z",
  "id": "61d53d8c964704379e7d927a"
}
```

### Validate existing meeting id

To validate existing meeting id, before joining use following API.
**curl:**

```js
cURL -H "Content-Type: application/json" \
 -H "Authorization: $YOUR_JWT_TOKEN" \
 -XPOST \
 https://api.videosdk.live/v1/meetings/${meetingId}
```

---

**node:**

```js
var request = require("request");

var options = {
  method: "POST",
  url: "https://api.videosdk.live/v1/meetings/${meetingId}",
  headers: { authorization: `${YOUR_JWT_TOKEN}` },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
```

---

**python:**

```python
import requests

url = "https://api.videosdk.live/v1/meetings/${meetingId}"

headers = {'authorization': f'Bearer {YOUR_JWT_TOKEN}'}

response = requests.request("GET", url, headers=headers)

print(response.text)
```

---

**ruby:**

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.videosdk.live/v1/meetings/${meetingId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["authorization"] = "Bearer #{YOUR_JWT_TOKEN}"

response = http.request(request)
puts response.read_body
```

---

**result:**

```js
{
  "meetingId": "87i6-bvw8-dtn1",
  "userMeetingId": "unicorn",
  "userId": "5fa671e77b80d58c11cbca95",
  "createdAt": "2022-01-05T06:41:16.018Z",
  "updatedAt": "2022-01-05T06:41:16.018Z",
  "id": "61d53d8c964704379e7d927a"
}
```


---

# Create a Room - API








---

# Deactivate a Room - API








---

#








---

# Delete A Participant Recording - API








---

# Delete A Recording - API








---

# Delete A Track Recording - API








---

# End Session - API








---

# Fetch A Merge Recording - API






---

# Fetch a Participant Recording - API






---

# Fetch a Post Transcription & Summary - API






---

# Fetch a Realtime Transcription - API






---

# Fetch a Resource - Beta API






---

# Fetch a Track Recording - API






---

# Fetch Active HLS - API








---

# Fetch Active Participants - API








---

# Fetch all HLS - API








---

# Fetch All Merge Recordings - API






---

# Fetch All Participant Recordings - API






---

# Fetch All Resources - Beta API








---

# Fetch Rooms - API








---

# Fetch all RTMP - API








---

# Fetch All Track Recordings - API






---

#








---

# Fetch an HLS - API








---

# Fetch an RTMP - API






---

# Fetch Participants - API






---

# Fetch Post Transcriptions & Summary - API






---

# Fetch Realtime Transcriptions - API






---

# Fetch a Recording - API






---

# Fetch Recordings - API






---

# Fetch a Room - API






---

# Fetch Participant Quality Stats - API








---

# Fetch Session Quality Stats - API








---

# Fetch a Session - API






---

# Fetch Sessions - API






---

# Firebase Cloud Function - API

<div class="sdk-api-ref-only-h4">

Cloud Functions for Firebase is a serverless framework that lets you automatically run backend code in response to events triggered by Firebase features and HTTPS requests. There's no need to manage and scale your own servers.

Perform the following steps to create token and create room HTTP Triggers.

### Install Firebase CLI

Before initiating a cloud functions project we need to make use of the Firebase Command Line Client and to install the latest version use the following command.

```javascript
npm install -g firebase-tools
```

### Firebase Login

Login to your firebase account using following command.

```javascript
firebase login
```

### Firebase Initiate

Now go to project folder and initiate Firebase.

```javascript
firebase init functions
```

You’re being asked to select the Firebase project you would like to use for the Firebase Cloud Functions project. You can also select the entry [create a new project] if you would like to add a new Firebase project to your account.

The next question you’re being asked is “Do you want to install dependencies with npm now?”. As we would like to add all necessary dependencies you need to say “Y” here or simply hit return as “Y” is the default setting.

### Install Dependancies

You have to install express, jsonwebtoken, node-fetch and body-parser dependencies for the project.

```javascript
npm install express jsonwebtoken node-fetch body-parser
```

### Node Project File

Create index.js file

```javascript
const functions = require("firebase-functions");
const express = require("express");
const jwt = require("jsonwebtoken");
const bodyParser = require("body-parser");
const PORT = 3000;
const app = express();

app.use(bodyParser.json());

function generateToken() {
  const API_KEY = "$YOUR_API_KEY";
  const SECRET = "$YOUR_SECRET";

  const options = {
    expiresIn: "120m",
    algorithm: "HS256",
  };

  const payload = {
    apikey: API_KEY,
    permissions: [`allow_join`], // `ask_join` || `allow_mod`
  };

  const token = jwt.sign(payload, SECRET, options);

  return token;
}

app.get("/token", (req, res, next) => {
  // .... your verification
  const token = generateToken();
  res.json({ token: token });
});

app.post("/room", async (req, res, next) => {
  const { meetingId } = req.body;
  // .... your verification

  const token = generateToken();
  const options = {
    method: "POST",
    headers: {
      Authorization: token,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      region: "in001",
      customRoomId: meetingId,
      webhook: "see example",
    }),
  };

  const url = `https://api.videosdk.live/v2/rooms`;
  const response = await fetch(url, options);
  const data = await response.json();

  res.json(data);
});

app.listen(PORT, () => {
  console.info("Server is running on PORT:", PORT);
});

exports.app = functions.https.onRequest(app);
```

### Firebase Deploy

To try out the function we now need to deploy our project to Firebase. Therefore we’re making use of the Firebase CLI again:

```javascript
firebase deploy --only functions
```

If the deployment has been completed successfully and you get back the function URL which now can be used to trigger the execution of the Cloud Function. now you can use this url to create room or token.

</div>


---

# Get Meeting Details - API

Use the following Rest API to get meeting details.



**curl:**

```js

curl -L -X GET 'https://api.videosdk.live/v1/meetings/:id' \
-H 'Authorization: $YOUR_JWT_TOKEN'

```

---

**node:**

```js
var request = require("request");
var options = {
  method: "GET",
  url: "https://api.videosdk.live/v1/meetings/:id",
  headers: {
Authorization: "$YOUR_JWT_TOKEN",
  },
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
```

---

**python:**

```python
import requests

url = "https://api.videosdk.live/v1/meetings/:id"

headers = {
  'Authorization': '$YOUR_JWT_TOKEN'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

```

---

**ruby:**

```ruby
require "uri"
require "net/http"

url = URI("https://api.videosdk.live/v1/meetings/:id")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = "$YOUR_JWT_TOKEN"

response = https.request(request)
puts response.read_body

```

---

**result:**

```js
{
"meetingId": "yw3w-nfzh-9jl0",
"userId": "5fa671e77b80d58c11cbca95",
"createdAt": "2021-06-18T08:10:46.683Z",
"updatedAt": "2021-06-18T08:10:46.683Z",
"id": "60cc550656592b6a03d7a2d0"
}
```




### Request


      
    </MethodListGroup>
</MethodListGroup>

### Response


      
      
      
          
        </MethodListGroup>
      </MethodListItemLabel>
      
      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>


---

# Get Recording Details - API

Use the following Rest API to get recording details.



**curl:**

```js

curl -L -X GET 'https://api.videosdk.live/v1/meeting-recordings/:id' \
-H 'Authorization: $YOUR_JWT_TOKEN'

```

---

**node:**

```js
var request = require("request");
var options = {
  method: "GET",
  url: "https://api.videosdk.live/v1/meeting-recordings/:id",
  headers: {
Authorization: "$YOUR_JWT_TOKEN",
  },
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
```

---

**python:**

```python
import requests

url = "https://api.videosdk.live/v1/meeting-recordings/:id"

headers = {
  'Authorization': '$YOUR_JWT_TOKEN'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

```

---

**ruby:**

```ruby
require "uri"
require "net/http"

url = URI("https://api.videosdk.live/v1/meeting-recordings/:id")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = "$YOUR_JWT_TOKEN"

response = https.request(request)
puts response.read_body

```

---

**result:**

```js
{
  "userId": "5f7edbb14c938bcd42944517",
  "meetingId": "hv6a-uwrj-8jbd",
  "origFileId": "60df15dc1b5d6a3205573786",
  "jobId": "60df15df7433b02e7d06853a",
  "createdAt": "2021-07-02T13:34:23.768Z",
  "updatedAt": "2021-07-02T13:34:30.616Z",
  "fileId": "60df15e61b5d6a3205533289",
  "file": {
  "meta": {
      "resolution": {
          "width": 1280,
          "height": 720
      },
      "format": "mov,mp4,m4a,3gp,3g2,mj2",
      "duration": 3.561
  },
  "jobId": "60df15df7433b02e1d06653a",
  "filePath": "encoded/videos/60df15dc1b5d6a8205573286/720.mp4",
  "size": 613596,
  "type": "video",
  "createdAt": "2021-07-02T13:34:30.566Z",
  "updatedAt": "2021-07-02T13:34:30.566Z",
  "fileUrl": "https://cdn.videosdk.live/encoded/videos/60df15dc1b5d6a8205573286/720.mp4",
  "id": "60df15e61b5d6a3805573289"
  },
  "id": "60df15df7433b02e3d06653c"
}
```




### Request


      
    </MethodListGroup>
</MethodListGroup>

### Response


          
          
          
          
          
          
          
                                
                            </MethodListGroup>
                          </MethodListItemLabel>
                      
                      
                  </MethodListGroup>
                </MethodListItemLabel>
              
              
              
              
              
              
              
              
            </MethodListGroup>
          </MethodListItemLabel>
          
          
          
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>


---

# Get Session Details - API

Use the following Rest API to list session details.



**curl:**

```js

curl -L -X GET 'https://api.videosdk.live/v1/meeting-sessions/:id' \
-H 'Authorization: $YOUR_JWT_TOKEN'

```

---

**node:**

```js
var request = require("request");
var options = {
  method: "GET",
  url: "https://api.videosdk.live/v1/meeting-sessions/:id",
  headers: {
Authorization: "$YOUR_JWT_TOKEN",
  },
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
```

---

**python:**

```python
import requests

url = "https://api.videosdk.live/v1/meeting-sessions/:id"

headers = {
  'Authorization': '$YOUR_JWT_TOKEN'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

```

---

**ruby:**

```ruby
require "uri"
require "net/http"

url = URI("https://api.videosdk.live/v1/meeting-sessions/:id")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = "$YOUR_JWT_TOKEN"

response = https.request(request)
puts response.read_body

```

---

**result:**

```js
{
"id": "616e79f7ba68c7768bfd18bf",
"meetingId": "ywnm-eicr-d55x",
"chatLink" : "https://cdn.videosdk.live/chats/hq3g-ny2g-kv8x-12348924f6213b0f00a9f7a6-6169bd856790717248e86cff.csv",
"start": "2021-10-19T07:55:35.807Z",
"end": "2021-10-19T07:55:39.941Z",
"activeDuration": 0,
"participants": [
    {
        "participantId": "wcrkkrf4",
        "name": "John Doe",
        "timelog": [
            {
                "start": "2021-10-19T07:55:36.316Z",
                "end": "2021-10-19T07:55:39.937Z"
            }
        ]
    }
]
}
```




### Request


      
    </MethodListGroup>
</MethodListGroup>

### Response


          
          
          
          
          
          
            
              
               
               
                    
                </MethodListGroup>
            </MethodListGroup>
          </MethodListItemLabel>
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>


---

# Customise Interface

Cooming soon


---

# Embeded meeting

Coming Soon.

![Build a embeded meeting.](/img/Zujonow-whitelabel-desktop-min.jpg)


---

# Explore console

Coming Soon.


---

# What we offer

## Explore amazing features

Let's discover **Realtime SDK features in less than 5 minutes**.

### ✅ : Shipped

### 🚧 : Working on it

### ❌ : Not implemented

## Features

|                                                      | Embeded | SDK |
| ---------------------------------------------------- | ------- | --- |
| video & audio chat functionality                     | ✅      | ✅  |
| Customised interface for video & audio               | 🚧      | ✅  |
| Adaptive video & audio calling                       | ✅      | ✅  |
| Cross browser and device support                     | 🚧      | ✅  |
| Screen sharing                                       | ✅      | ✅  |
| Interactive Whiteboard                               | ✅      | ✅  |
| Auto switching on active speakers                    | ✅      | ✅  |
| Grid Layouts                                         | ✅      | ✅  |
| Participant List                                     | ✅      | ✅  |
| Raise Hand                                           | ✅      | ✅  |
| Text chat and file sharing                           | ✅      | ✅  |
| Cloud and local recording                            | ✅      | ✅  |
| Console analytics and operations                     | ✅      | ✅  |
| Compatible with JS, React, Electron, Vue and Angular | ✅      | ✅  |
| Compatible with React Native, Flutter                | 🚧      | ✅  |
| Compatible with native Android, IOS                  | 🚧      | 🚧  |


---

# Integrate SDK with mobile, tab and tv

## @videosdk.live/react-native-sdk

`@videosdk.live/react-native-sdk` is hybrid sdk for the react native. It inherits `js` and `react` sdk to provide better support and fast development in mobile devices.

![Build a React Native video chat app with @videosdk.live/react-native-sdk.](/img/Zujonow-whitelabel-mobile-landscape.jpg)


---

# What next?


---

<div id="tailwind">
<div class="row">
<div class="col col--6">
<br />
<h1> API Reference </h1>
<div >
VideoSDK provides REST APIs for RealTime Communication, which includes APIs for Rooms, Sessions, Recordings, RTMP and HLS.
</div>
</div>
<div class="col col--6">
<br /> <br /> <br />
<div>
 <div className="bg-[#333A47] rounded-t-lg pt-4 pb-4 pl-3 flex lg:flex-row flex-col align-middle">
  <div className="flex-1 text-sm font-bold text-white-1">BASE URL</div>
  </div>
  <div className="method_code_block">
   <div className="pt-4 pl-4 pr-4 pb-2 bg-[#252a34] rounded-b-lg flex flex-col align-middle">
    <p className="mb-2">
              <span className="text-[#7D8EAD] text-sm font-bold max-w-min hover:text-white-100">
                {"https://api.videosdk.live"}
              </span>
    </p>
    </div>
</div>
</div>

</div>
</div>

<hr />
<br />
<div class="row">
<div class="col col--6">
<h2> Authentication </h2>
<div >
The VideoSDK API uses access token to authenticate api requests.
In REST APIs, token will be passed in a header field called `Authorization`.

In order to generate authentication token, you will need `API_KEY` and `SECRET`, which you can get them from [here](https://app.videosdk.live/api-keys).

In payload, you have to add your `apikey`, `permissions`, `version` and `role`.

If you are concerned with security and want to generate token only for v2 API access, then you need to provide `version` and `role`.

- `apikey`(**Mandatory**): You can get it from [here](https://app.videosdk.live/api-keys).

- `permissions`(**Mandatory**): Based on provided permission, participant will join the meeting accordingly.

  Available permissions are:

  - **`allow_join`**: The participant is **allowed to join** the meeting directly.
  - **`ask_join`**: The participant requires to **ask for permission to join** the meeting.
  - **`allow_mod`**: The participant is **allowed to toggle** webcam & mic of other participants.

- **`version`(optional)**: For accessing the [v2 API](/api-reference/realtime-communication/intro), you need to provide `2` as the version value.

  - For passing `roomId`, `participantId` or `roles` parameters in payload, it is essential to set the version value to `2`.

- **`roomId`(optional)**: To provide customised access control, you can make the token applicable to a particular room by including the `roomId` in the payload.

- **`participantId`(optional)**: You can include the `participantId` in the payload to limit the token's access to a particular participant.

- **`roles`(optional)**:

  - **`crawler`**: This role is only for accessing [v2 API](/api-reference/realtime-communication/intro), you can not use this token for running the `Meeting`/`Room`.
  - **`rtc`**: This role is only allow for running the `Meeting` / `Room`, you can not use [server-side APIs](/api-reference/realtime-communication/intro).

Then, you will sign this payload with your `SECRET`and jwt options.

</div>
</div>
<div class="col col--6">


<br /><br />


</div>
</div>
</div>

---






---

# List Meetings - API

Use the following Rest API to list meetings.



**curl:**

```js

curl -L -X GET 'https://api.videosdk.live/v1/meetings' \
-H 'Authorization: $YOUR_JWT_TOKEN'

```

---

**node:**

```js
var request = require("request");
var options = {
  method: "GET",
  url: "https://api.videosdk.live/v1/meetings",
  headers: {
Authorization: "$YOUR_JWT_TOKEN",
  },
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
```

---

**python:**

```python
import requests

url = "https://api.videosdk.live/v1/meetings"

headers = {
  'Authorization': '$YOUR_JWT_TOKEN'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

```

---

**ruby:**

```ruby
require "uri"
require "net/http"

url = URI("https://api.videosdk.live/v1/meetings")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = "$YOUR_JWT_TOKEN"

response = https.request(request)
puts response.read_body

```

---

**result:**

```js
{
"pageInfo": {
    "currentPage": 1,
    "perPage": 20,
    "lastPage": 4,
    "total": 65
},
"data": [
    {
        "meetingId": "yw3w-nfzh-9jl0",
        "userId": "5fa671e77b80d58c11cbca95",
        "createdAt": "2021-06-18T08:10:46.683Z",
        "updatedAt": "2021-06-18T08:10:46.683Z",
        "id": "60cc550656592b6a03d7a2d0"
    },
    ...
]
}
```




### Request


      
      
    </MethodListGroup>
</MethodListGroup>

### Response


      
          
          
        </MethodListGroup>
      </MethodListItemLabel>
      
          
          
              
            </MethodListGroup>
          </MethodListItemLabel>
          
          
          
        </MethodListGroup>
      </MethodListItemLabel>
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>


---

# List Meeting Sessions - API

Use the following Rest API to list meeting sessions.



**curl:**

```js

curl -L -X GET 'https://api.videosdk.live/v1/meeting-sessions' \
-H 'Authorization: $YOUR_JWT_TOKEN'

```

---

**node:**

```js
var request = require("request");
var options = {
  method: "GET",
  url: "https://api.videosdk.live/v1/meeting-sessions",
  headers: {
Authorization: "$YOUR_JWT_TOKEN",
  },
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
```

---

**python:**

```python
import requests

url = "https://api.videosdk.live/v1/meeting-sessions"

headers = {
  'Authorization': '$YOUR_JWT_TOKEN'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

```

---

**ruby:**

```ruby
require "uri"
require "net/http"

url = URI("https://api.videosdk.live/v1/meeting-sessions")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = "$YOUR_JWT_TOKEN"

response = https.request(request)
puts response.read_body

```

---

**result:**

```js
{
   "pageInfo": {
    "currentPage": 1,
    "perPage": 20,
    "lastPage": 1,
    "total": 8
},
"data": [
    {
        "id": "616e79f7ba68c7768bfd18bf",
        "meetingId": "ywnm-eicr-d55x",
        "start": "2021-10-19T07:55:35.807Z",
        "end": "2021-10-19T07:55:39.941Z",
        "chatLink" : "https://cdn.videosdk.live/chats/hq3g-ny2g-kv8x-12348924f6213b0f00a9f7a6-6169bd856790717248e86cff.csv",
        "activeDuration": 0,
        "participants": [
            {
                "participantId": "wcrkkrf4",
                "name": "John Doe",
                "timelog": [
                    {
                        "start": "2021-10-19T07:55:36.316Z",
                        "end": "2021-10-19T07:55:39.937Z"
                    }
                ]
            }
        ]
}
```




### Request


      
      
      
    </MethodListGroup>
</MethodListGroup>

### Response


      
          
          
        </MethodListGroup>
      </MethodListItemLabel>
      
          
          
          
          
          
            
              
               
               
                    
                </MethodListGroup>
            </MethodListGroup>
          </MethodListItemLabel>
        </MethodListGroup>
      </MethodListItemLabel>
    </MethodListGroup>

  </MethodListItemLabel>
</MethodListGroup>


---

# List Meeting Recordings - API

Use the following Rest API to list recordings.



**curl:**

```js

curl -L -X GET 'https://api.videosdk.live/v1/meeting-recordings' \
-H 'Authorization: $YOUR_JWT_TOKEN'

```

---

**node:**

```js
var request = require("request");
var options = {
  method: "GET",
  url: "https://api.videosdk.live/v1/meeting-recordings",
  headers: {
Authorization: "$YOUR_JWT_TOKEN",
  },
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
```

---

**python:**

```python
import requests

url = "https://api.videosdk.live/v1/meeting-recordings"

headers = {
  'Authorization': '$YOUR_JWT_TOKEN'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

```

---

**ruby:**

```ruby
require "uri"
require "net/http"

url = URI("https://api.videosdk.live/v1/meeting-recordings")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = "$YOUR_JWT_TOKEN"

response = https.request(request)
puts response.read_body

```

---

**result:**

```js
{
"pageInfo": {
    "currentPage": 1,
    "perPage": 20,
    "lastPage": 1,
    "total": 20
},
"data": [
  {
        "userId": "5f7edbb14c938bcd42944517",
        "meetingId": "hv6a-uwrj-8jbd",
        "origFileId": "60df15dc1b5d6a3205573786",
        "jobId": "60df15df7433b02e7d06853a",
        "createdAt": "2021-07-02T13:34:23.768Z",
        "updatedAt": "2021-07-02T13:34:30.616Z",
        "fileId": "60df15e61b5d6a3205533289",
        "file": {
            "meta": {
                "resolution": {
                    "width": 1280,
                    "height": 720
                },
                "format": "mov,mp4,m4a,3gp,3g2,mj2",
                "duration": 3.561
            },
            "jobId": "60df15df7433b02e1d06653a",
            "filePath": "encoded/videos/60df15dc1b5d6a8205573286/720.mp4",
            "size": 613596,
            "type": "video",
            "createdAt": "2021-07-02T13:34:30.566Z",
            "updatedAt": "2021-07-02T13:34:30.566Z",
            "fileUrl": "https://cdn.videosdk.live/encoded/videos/60df15dc1b5d6a8205573286/720.mp4",
            "id": "60df15e61b5d6a3805573289"
        },
        "id": "60df15df7433b02e3d06653c"
    },
    {...}
]
}
```




### Request


      
      
      
      
    </MethodListGroup>
</MethodListGroup>

### Response


      
          
          
          
        </MethodListGroup>
      </MethodListItemLabel>
      
          
          
          
          
          
          
                                
                            </MethodListGroup>
                          </MethodListItemLabel>
                      
                      
                  </MethodListGroup>
                </MethodListItemLabel>
              
              
              
              
              
              
              
              
            </MethodListGroup>
          </MethodListItemLabel>
          
          
          
        </MethodListGroup>
      </MethodListItemLabel>
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>


---

# Merge Participant Recordings - API






---

# Release Resource - Beta API






---

# Remove Participant - API






---

# Delete Recordings - API

Use the following Rest API to delete recordings.



**curl:**

```js

curl -L -X DELETE 'https://api.videosdk.live/v1/meeting-recordings/:id' \
-H 'Authorization: $YOUR_JWT_TOKEN'

```

---

**node:**

```js
var request = require("request");
var options = {
  method: "DELETE",
  url: "https://api.videosdk.live/v1/meeting-recordings/:id",
  headers: {
Authorization: "$YOUR_JWT_TOKEN",
  },
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
```

---

**python:**

```python
import requests

url = "https://api.videosdk.live/v1/meeting-recordings/:id"

headers = {
  'Authorization': '$YOUR_JWT_TOKEN'
}

response = requests.request("DELETE", url, headers=headers)

print(response.text)

```

---

**ruby:**

```ruby
require "uri"
require "net/http"

url = URI("https://api.videosdk.live/v1/meeting-recordings/:id")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["Authorization"] = "$YOUR_JWT_TOKEN"

response = https.request(request)
puts response.read_body

```

---

**result:**

```
"Room Recording deleted successfully"
```




### Request


      
    </MethodListGroup>
</MethodListGroup>

### Response


</MethodListGroup>


---

# Architecture


---

# Demos


---

# Device and Browser Support

## Browser Support

We support the following web browsers:

- Chrome 74 and above
- Safari 12.1 and above
- Firefox 78 ESR and above
- Microsoft Edge 74 and above.
- Electron 6 and above
- IOS Safari (in IOS 12.1 and later)
- 3rd-party browsers (such as Chrome) and in-app browsers (such as the Gmail app's built-in browser) using WKWebView, as of IOS 14
- Android Chrome, Firefox, Samsung Internet, and Chromium-based 3rd-party browsers

## Screen sharing

- To start a screen share, a user must be on desktop. A user can start a screen share from Chrome, Safari, or Firefox on desktop.
- To clarify, all browsers can view screen shares. A mobile user can see a screen share (but only a call participant on desktop can share their screen).

## Mobile support

- IOS 12.1 and later versions
- Android 5.0 and above with current security and platform updates


---

# Hippa Compliance for Healthcare







---

# Tutorials


---

# VideoSDK RTC .NET API Server Example

A complete .NET Core server example demonstrating VideoSDK RTC API integration.

## Pre-requisites

- **.NET Core** 3.1 or higher
- **VideoSDK Account** - Get your API credentials from [VideoSDK Developer Console](https://app.videosdk.live/)
- **VideoSDK RTC API Server Examples Repo** - Clone it from [Github](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)


## Installation & Setup

### 1. Clone the Repository

```bash
git clone https://github.com/videosdk-live/videosdk-rtc-api-server-examples.git
cd dotnet/jwt-example
```

### 2. Install Dependencies

```bash
dotnet restore
```

### 3. Configure Credentials

Open the `HelloController.cs` file and update it with your VideoSDK API Key and Secret:

```csharp
VIDEOSDK_API_KEY = "your_api_key_here"
VIDEOSDK_SECRET_KEY = "your_secret_key_here"
VIDEOSDK_API_ENDPOINT = "https://api.videosdk.live"
```

### 4. Run the Server

```bash
dotnet run
```

---

# VideoSDK RTC Go API Server Example

A complete Go server example demonstrating VideoSDK RTC API integration.

## Pre-requisites

- **Go** (Golang)
- **VideoSDK Account** - Get your API credentials from [VideoSDK Developer Console](https://app.videosdk.live/)
- **VideoSDK RTC API Server Examples Repo** - Clone it from [Github](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)


## Installation & Setup

### 1. Clone the Repository

```bash
git clone https://github.com/videosdk-live/videosdk-rtc-api-server-examples.git
cd go
```

### 2. Install Dependencies

```bash
go install
```

### 3. Configure Credentials

Open the `main.go` file and update it with your VideoSDK API Key and Secret:

```go
VIDEOSDK_API_KEY = "your_api_key_here"
VIDEOSDK_SECRET_KEY = "your_secret_key_here"
VIDEOSDK_API_ENDPOINT = "https://api.videosdk.live/v2"
```

### 4. Run the Server

```bash
go run main.go
```

---

# VideoSDK RTC Java API Server Example

A complete Java server example demonstrating VideoSDK RTC API integration using the Spring Boot framework.

## Pre-requisites

- **Java JDK** 11 or higher
- **VideoSDK Account** - Get your API credentials from [VideoSDK Developer Console](https://app.videosdk.live/)
- **VideoSDK RTC API Server Examples Repo** - Clone it from [Github](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)


## Installation & Setup

### 1. Clone the Repository

```bash
git clone https://github.com/videosdk-live/videosdk-rtc-api-server-examples.git
cd java
```

### 2. Configure Credentials

Open the `DemoApplication.java` file and update it with your VideoSDK API Key and Secret:

```java
VIDEOSDK_API_KEY = "your_api_key_here"
VIDEOSDK_SECRET_KEY = "your_secret_key_here"
VIDEOSDK_API_ENDPOINT = "https://api.videosdk.live/v2"
```

### 3. Run the Server

The Maven wrapper will automatically install any required dependencies before starting the server.

```bash
./mvnw spring-boot:run
```

---

# VideoSDK RTC Node.js API Server Example

A complete Node.js server example demonstrating VideoSDK RTC API integration using Express.js framework.


## Pre-requisites

- **Node.js** 12 or higher
- **npm** (comes with Node.js)
- **VideoSDK Account** - Get your API credentials from [VideoSDK Developer Console](https://app.videosdk.live/)
- **VideoSDK RTC API Server Examples Repo** - Clone it from [Github](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)

## Installation & Setup

### 1. Clone the Repository

```bash
git clone https://github.com/videosdk-live/videosdk-rtc-api-server-examples.git
cd nodejs
```

### 2. Install Dependencies

```bash
npm install
```

### 3. Configure Environment Variables

Copy the example environment file and update it with your credentials:

```bash
cp .env.example .env
```

Edit the `.env` file with your VideoSDK credentials:

```env
VIDEOSDK_API_KEY=your_api_key_here
VIDEOSDK_SECRET_KEY=your_secret_key_here
VIDEOSDK_API_ENDPOINT=https://api.videosdk.live/v2
```

### 4. Run the Server

```bash
npm run start
```

---

# VideoSDK RTC API Server Examples

A comprehensive collection of server-side examples demonstrating how to integrate VideoSDK RTC APIs across multiple programming languages and frameworks.

## What is VideoSDK RTC?
 
VideoSDK RTC is a powerful real-time communication platform that enables developers to build video calling, live streaming, and interactive broadcasting applications with minimal effort.

## Quick Start

1. **Choose your language** from the table above
2. **Get your API credentials** from [VideoSDK Developer Console](https://app.videosdk.live/)
3. **Clone the repo** from [Github](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)
3. **Follow the setup instructions** in your chosen language's docs
4. **Start building** your real-time communication app!

## Pre-requisites

- VideoSDK account and API credentials
- Basic knowledge of your chosen programming language
- HTTP client (Postman, cURL, etc.) for testing

## Available Examples

Choose your preferred programming language or framework:

| Language/Framework | Description |
|-------------------|-------------|
| [**Node.js**](server-side-examples-nodejs) | Express.js server with JWT token generation |
| [**Python**](server-side-examples-python) | Flask-based API server |
| [**PHP**](server-side-examples-php) | PHP server with Composer dependencies |
| [**Go**](server-side-examples-go) | Go HTTP server with standard library |
| [**Java**](server-side-examples-java) | Spring Boot application |
| [**.NET Core**](server-side-examples-dotnet) | ASP.NET Core Web API |
| [**Ruby**](server-side-examples-ruby) | Ruby on Rails application |
| [**Rust**](server-side-examples-rust) | Rust HTTP server with Actix-web |



---

# VideoSDK RTC PHP API Server Example

A complete PHP server example demonstrating VideoSDK RTC API integration.

## Pre-requisites

- **PHP**
- **PHP Composer**
- **php-curl** extension
- **VideoSDK Account** - Get your API credentials from [VideoSDK Developer Console](https://app.videosdk.live/)
- **VideoSDK RTC API Server Examples Repo** - Clone it from [Github](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)


## Installation & Setup

### 1. Clone the Repository

```bash
git clone https://github.com/videosdk-live/videosdk-rtc-api-server-examples.git
cd php
```

### 2. Install Dependencies

```bash
composer install
```

### 3. Configure Credentials

Open the `index.php` file and update it with your VideoSDK API Key and Secret:

```php
VIDEOSDK_API_KEY = "your_api_key_here";
VIDEOSDK_SECRET_KEY = "your_secret_key_here";
VIDEOSDK_API_ENDPOINT = "https://api.videosdk.live/v2";
```

### 4. Run the Server

```bash
php -S localhost:3000
```

---

# VideoSDK RTC Python API Server Example

A complete Python server example demonstrating VideoSDK RTC API integration using the Flask framework.

## Pre-requisites

- **Python** 3 or higher
- **pip** (comes with Python)
- **VideoSDK Account** - Get your API credentials from [VideoSDK Developer Console](https://app.videosdk.live/)
- **VideoSDK RTC API Server Examples Repo** - Clone it from [Github](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)


## Installation & Setup

### 1. Clone the Repository

```bash
git clone https://github.com/videosdk-live/videosdk-rtc-api-server-examples.git
cd python
```

### 2. Configure Credentials

Open the `main.py` file and update it with your VideoSDK API Key and Secret:

```python
VIDEOSDK_API_KEY = "your_api_key_here"
VIDEOSDK_SECRET_KEY = "your_secret_key_here"
VIDEOSDK_API_ENDPOINT = "https://api.videosdk.live/v2"
```

### 3. Setup Virtual Environment & Install Dependencies

Create and activate a virtual environment, then install the required packages.

```bash
python -m venv env
source env/bin/activate
pip install -r requirements.txt
```

### 4. Run the Server

```bash
export FLASK_APP=main
flask run
```

---

# VideoSDK RTC Ruby API Server Example

A complete Ruby on Rails server example demonstrating VideoSDK RTC API integration.

## Pre-requisites

- **Ruby** (including `ruby-dev` or `ruby-devel`)
- **Ruby Bundler** (`ruby-bundler`)
- **SQLite3** (`libsqlite3-dev`)
- **VideoSDK Account** - Get your API credentials from [VideoSDK Developer Console](https://app.videosdk.live/)
- **VideoSDK RTC API Server Examples Repo** - Clone it from [Github](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)


## Installation & Setup

### 1. Clone the Repository

```bash
git clone https://github.com/videosdk-live/videosdk-rtc-api-server-examples.git
cd ruby
```

### 2. Install Dependencies

```bash
bundle install
```

### 3. Configure Credentials

Open the `main_controller.rb` file and update it with your VideoSDK API Key and Secret:

```ruby
VIDEOSDK_API_KEY = "your_api_key_here"
VIDEOSDK_SECRET_KEY = "your_secret_key_here"
VIDEOSDK_API_ENDPOINT = "https://api.videosdk.live/v2"
```

### 4. Run the Server

```bash
rails s
```

---

# VideoSDK RTC Rust API Server Example

A complete Rust server example demonstrating VideoSDK RTC API integration.

## Pre-requisites

- **Rust**
- **Cargo** (comes with Rust)
- **libssl-dev**
- **VideoSDK Account** - Get your API credentials from [VideoSDK Developer Console](https://app.videosdk.live/)
- **VideoSDK RTC API Server Examples Repo** - Clone it from [Github](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)


## Installation & Setup

### 1. Clone the Repository

```bash
git clone https://github.com/videosdk-live/videosdk-rtc-api-server-examples.git
cd rust
```

### 2. Configure Credentials

Open the `src/handlers.rs` file and update it with your VideoSDK API Key and Secret:

```rust
videosdk_api_key = "your_api_key_here"
videosdk_secret_key = "your_secret_key_here"
VIDEOSDK_API_ENDPOINT = "https://api.videosdk.live/v2"
```

### 3. Run the Server

Cargo will automatically handle downloading and compiling the necessary dependencies before starting the server.

```bash
cargo run
```

---

# Call End - API






---

# Call Transfer - API






---

# Make Outbound Call - API






---

# Fetch All Calls - API






---

# Delete SIP Trunk - API






---

# Get All SIP Trunks - API






---

# Get SIP Trunk by ID - API






---

# Create Inbound SIP Gateway - API






---

# Delete Inbound SIP Gateway - API






---

# Fetch All Inbound SIP Gateways - API






---

# Fetch Inbound SIP Gateway by ID - API






---

# Update Inbound SIP Gateway - API






---

# Make Outbound SIP Call - API






---

# Create Outbound SIP Gateway - API






---

# Delete Outbound SIP Gateway - API






---

# Fetch All Outbound SIP Gateways - API






---

# Fetch One Outbound SIP Gateway - API






---

# Update Outbound SIP Gateway - API






---

# Create Routing Rule - API






---

# Delete Routing Rule - API






---

# Fetch All Routing Rules - API






---

# Fetch Routing Rule by ID - API






---

# Update Routing Rule - API






---

# Add SIP Trunk - API






---

# Update SIP Trunk - API






---

# Create Webhook - API






---

# Delete Webhook - API






---

# Fetch All Webhooks - API






---

# Fetch Webhook by ID - API






---

# Update Webhook - API






---

# Start HLS Stream - API






---

# Start Livestream - API






---

# Start Multiple HLS Stream - API






---

# Start Multiple Recording - API






---

# Start Multiple Livestream - API






---

# Start Participant Recording - API






---

# Start a Realtime Transcription - API






---

# Start Recording - API






---

# Start Track Recording - API






---

# Stop HLS Stream - API






---

# Stop Livestream - API






---

# Stop Multiple HLS Stream - API






---

# Stop Multiple Recording - API






---

# Stop Multiple Livestream - API






---

# Stop Participant Recording - API






---

# Stop Realtime Transcription - API






---

# Stop Recording - API






---

# Stop Track Recording - API






---

# Beginner Tutorial JavaScript

## Terminology

Let's start with the terms used in VideoSDK meeting Client SDK.

### Meeting

A Meeting represents real-time audio, video, and/or screen-share session, and is the basic building block for media sharing among participants. Supports upto 5,000 participants.

### Participants

Participants are the client applications that are connected to a Meeting and shares video & audio media with one another.

### Local Participant

Participant producing audio or video stream from the local client's media sources

### Streams

Streams are indiviual video & audio streams produced by the participants in the meeting

### Active Speaker

Active speaker represents the participant who is currently producing highest decibels audio stream (in other words speaking)

### Active presenter

Active presenter is the participant who is currently sharing his/her screen as a video stream

### Main participant

Main participant represents the client who shall be displayed on the main screen indicating that he/she is either presenting or speaking

---

## Installation

### Get an API key

Signup on the VideoSDK website to get a key pair for SDK authentication. Your **API Key** and **Secret** will be visible on the console dashboard.

### Integrate

Include this in your HTML file

```html title="index.html"
<script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
```

---

## Step 0: Access token generation (server-side code)

An access token is required to authenticate with the VideoSDK and make any API calls. You can generate one with the `API key` and `secret` mentioned in your developer portal at VideoSDK console.

## Generate access token (NodeJS)

```js {20} title="server.js"
const express = require("express");
const jwt = require("jsonwebtoken");
const cors = require("cors");
const request = require("request");

const app = express();
const port = 9000;
app.use(cors());
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

app.get("/get-token", (req, res) => {
  const API_KEY = process.env.VIDEOSDK_API_KEY;
  const SECRET_KEY = process.env.VIDEOSDK_SECRET_KEY;
  const options = { expiresIn: "10m", algorithm: "HS256" };
  const payload = {
    apikey: API_KEY,
    permissions: ["allow_join", "allow_mod", "ask_join"], // Trigger permission.
  };
  const token = jwt.sign(payload, SECRET_KEY, options);
  res.json({ token });
});

app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`);
});
```

Available permissions are:

- `allow_join`: The participant will be permitted entry without request.
- `ask_join`: The participant will not be permitted entry without request.
- `allow_mod`: Allow participant to enable/disable other participant's mic/webcam.

This generated token must be sent in the `Authorization` header for all API calls. <br/>
And it should also be used with the `VideoSDK.config(token)` method.

## Step 1: Create or join meeting

Get a meeting id for new meeting or validate an existing meeting id to join a meeting.

### Create new meeting ID



**curl:**

```js
cURL -H "Content-Type: application/json" \
 -H "Authorization: $YOUR_JWT_TOKEN" \
 -XPOST \
 https://api.videosdk.live/v1/meetings
```

---

**node:**

```js
var request = require("request");

var options = {
  method: "POST",
  url: "https://api.videosdk.live/v1/meetings",
  headers: { authorization: `${YOUR_JWT_TOKEN}` },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
```

---

**python:**

```python
import requests

url = "https://api.videosdk.live/v1/meetings"

headers = {'authorization': f'Bearer {YOUR_JWT_TOKEN}'}

response = requests.request("GET", url, headers=headers)

print(response.text)
```

---

**ruby:**

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.videosdk.live/v1/meetings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["authorization"] = "Bearer #{YOUR_JWT_TOKEN}"

response = http.request(request)
puts response.read_body
```

---

**result:**

```js
{
  "meetingId":"jpkf-iool-64ox"
}
```

OR

### Validate existing meeting ID for joining

**curl:**

```js
cURL -H "Content-Type: application/json" \
 -H "Authorization: $YOUR_JWT_TOKEN" \
 -XPOST \
 https://api.videosdk.live/v1/meetings/${meetingId}
```

---

**node:**

```js
var request = require("request");

var options = {
  method: "POST",
  url: "https://api.videosdk.live/v1/meetings/${meetingId}",
  headers: { authorization: `${YOUR_JWT_TOKEN}` },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
```

---

**python:**

```python
import requests

url = "https://api.videosdk.live/v1/meetings/${meetingId}"

headers = {'authorization': f'Bearer {YOUR_JWT_TOKEN}'}

response = requests.request("GET", url, headers=headers)

print(response.text)
```

---

**ruby:**

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.videosdk.live/v1/meetings/${meetingId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["authorization"] = "Bearer #{YOUR_JWT_TOKEN}"

response = http.request(request)
puts response.read_body
```

---

**result:**

```js
{
  "meetingId":"jpkf-iool-64ox"
}
```

## Step 2: Initialize meeting

To initialize meeting you need to provide the following parameters:

- `meetingId: string` from the previous step to specify which meeting to join in.
- `name: string` which will be displayed as username of participant in the meeting.
- `micEnabled: boolean` option to indicate if mic should be on while joining.
- `webcamEnabled: boolean` option to indicate if webcam should be on while joining.
- `maxResolution: "sd" | "hd"` defines the maximum available resolution for webcam video.

```javascript title="Intialize meeting instance"
const meeting = VideoSDK.initMeeting({
  meetingId, // required
  name, // required
  micEnabled, // optional, default: true
  webcamEnabled, // optional, default: true
  maxResolution, // optional, default: "hd"
});
```

The `meeting` object consists of:

- Properties:

  - `id: string`
  - `activeSpeakerId: string`
  - `activePresenterId: string`
  - `mainParticipantId: string`
  - `localParticipant: Participant`
  - `participants: Map<string, Participant>`
  - `messages: Array<{senderId: string, text: string, timestamp: number}>`

- Events:

  - `participant-joined`, `participant-left`
  - `speaker-changed`, `presenter-changed`
  - `main-participant-changed`
  - `entry-requested`, `entry-responded`
  - `recording-started`, `recording-stopped`
  - `stream-enabled`, `stream-disabled`
  - `chat-message`

- Methods:
  - `join()`, `leave()`
  - `muteMic()`, `unmuteMic()`
  - `disableWebcam()`, `enableWebcam()`
  - `disableScreenShare()`, `enableScreenShare()`
  - `on(eventType: string)`, `off(eventType: string)`
  - `respondEntry(participantId: string, decision: "allowed" | "denied")`
  - `startRecording(webhookUrl: string, , awsDirPath: string)`, `stopRecording()`
  - `sendChatMessage(text: string)`

## Step 3: Get local and remote participants

You can get the local streams and participant meta from `meeting.localParticipant`. And a `Map` of joined participants is always available via `meeting.participants`.

```javascript title="Access meeting participants"
const localParticipant = meeting.localParticipant;
const participants = meeting.participants;
```

Each `participant` object consists of:

- Properties:

  - `id: string`
  - `displayName: string`
  - `streams: Map<string, Stream>`

- Events:

  - `stream-enabled`
  - `stream-disabled`

- Methods:
  - `setQuality(quality: "low" | "med" | "high")`
  - `enableMic()`, `disableMic()`
  - `enableWebcam()`, `disableWebcam()`
  - `on(eventType: string)`, `off(eventType: string)`

## Step 4: Listen for entry request events

When participant asks for entry in a meeting that you are connected to, you will be notified via `entry-requested` and when you or any other participant's entry is responded, `entry-responded` will be fired.

```javascript title="Get request from user"
meeting.on("entry-requested", (participantId, name) => {
  setEntryRequests([...entryRequestsRef.current, { id: participantId, name }]);

  // you can open a dialog to respond with
  // decision "allowed" or "denied" with the following method
  meeting.respondEntry(participantId, decision);
});

meeting.on("entry-responded", (participantId, decision) => {
  // decision parameter will be: "allowed" or "denied"

  setEntryRequests(
    entryRequestsRef.current.filter((r) => r.id !== participantId)
  );
});
```

## Step 5: Listen for new & leaving participant events

When participant joins or leaves a meeting that you are connected to, you will be notified via `participant-joined` and `participant-left` events respectively.

```javascript "Listen on participant joined and left"
meeting.on("participant-joined", (participant) => {
  setParticipants(new Map(meeting.participants));
});

meeting.on("participant-left", (participant) => {
  setParticipants(new Map(meeting.participants));
});
```

## Step 6: Listen for audio/video stream events

When a participant from meeting enables or diables a audio/video stream, you will be notified via `stream-enabled` and `stream-disabled` events from the participant object.

```javascript title="Listen on stream enabled and disabled"
participant.on("stream-enabled", (stream) => {
  if (stream.kind === "video") {
    // play video track on a <video /> element
  } else if (stream.kind === "audio") {
    // play audio track on a <audio /> element
  } else if (stream.kind === "share") {
    // play screen sharing video track on a <video /> element
  }
});

participant.on("stream-disabled", (stream) => {
  if (stream.kind === "video") {
    // remove video track or the <video /> element
  } else if (stream.kind === "audio") {
    // remove audio track or the <audio /> element
  } else if (stream.kind === "share") {
    // remove screen sharing video track or the <video /> element
  }
});
```

Each `stream` object consists of:

- Properties:

  - `id: string`
  - `kind: string`
  - `codec: string`
  - `track: MediaStreamTrack`

- Methods:
  - `pause()`
  - `resume()`

### Note: Chrome Autoplay policy workaround

Chrome's autoplay policy does not allow audio autoplay unless user has interacted with the domain (click, tap, etc.) or the user's <a href="https://developers.google.com/web/updates/2017/09/autoplay-policy-changes#mei">Media engagement Index</a> threshold has been crossed. Thus, as a workaround before starting the meeting, user can either create a meeting join page or create a join meeting confirmation dialog by which we can perform a user click interaction to enable audio autoplay in chrome's newer versions.

## Step 7: Main screen video (optional)

When a participant who is currently presenting or speaking is changed in the meeting, you will be notified via `main-participant-changed` event.

```javascript title="Listen on main participant changed"
meeting.on("main-participant-changed", (participant) => {
  // show participant video stream on main screen
});
```

## Step 8: Join the meeting

After we set local participant, main-screen participant, other participants, participant event handlers and stream event handlers from the meeting, next step is to join the meeting by calling `meeting.join()`. This will trigger `participant-joined` event for all other participants.

```javascript title="Leave meeting"
meeting.join();
```

## Step 9: Utility methods & events (optional)

### Mute/Unmute mic

Toggle own mic with the `unmuteMic()` and `muteMic()` methods. Toggling mic will trigger `stream-enabled` and `stream-disabled` events for all other participants when enabling and disabling mic.

```javascript title="Mic methods"
// unmute/mute your own mic
meeting.unmuteMic();
meeting.muteMic();

// unmute/mute other participant's mic
participant.unmuteMic();
participant.muteMic();
```

### Enable/Disable Webcam

Toggle own webcam with the `enableWebcam()` and `disableWebcam()` methods. Toggling webcam will trigger `stream-enabled` and `stream-disabled` events for all other participants when enabling and disabling webcam.

```javascript title="Webcam methods"
// disable/enable your own webcam
meeting.enableWebcam();
meeting.disableWebcam();

// disable/enable other participant's webcam
participant.enableWebcam();
participant.disableWebcam();
```

### Enable/Disable Screen share

Share your screen with the `enableScreenShare()` method and stop sharing with `disableScreenShare()`. Toggling screen-share will trigger `stream-enabled` and `stream-disabled` events for all other participants when enabling and disabling screen-share.

```javascript title="Screen share methods"
meeting.enableScreenShare();
meeting.disableScreenShare();
```

### Start/Stop recording

Record the meeting session with `startRecording(webhookUrl, awsDirPath)` method and stop recording with `stopRecording()`. Toggling recording will trigger `recording-started` and `recording-stopped` events for all participants when starting and stopping recording respectively.

```javascript title="Start and stop recordings methods"
// The webhook will be called with the fileUrl as a POST request when the recording is processed.
meeting.startRecording(
  "https://your-app-server.com/api/recordings",
  "meetings/meeting-id"
);
meeting.stopRecording();

// ...

meeting.on("recording-started", () => {
  setRecordStatus("active");

  // 🔴 notify all users of recording start
});

meeting.on("recording-stopped", () => {
  setRecordStatus("inactive");

  // ⚫ notify all users of recording end
});
```

### In-meeting Chat

Send messages with the `sendChatMessage(text)` method and all other participants will be notified via `chat-message` event.

```javascript title="Send and receive chat message"
meeting.sendChatMessage("Hello world!");

// ...

meeting.on("chat-message", (data) => {
  setChatMessages([...meeting.messages]);

  const { senderId, text, timestamp } = data;

  // 📢 notify user or show in the chat window
});
```

### Active speaker event

The `speaker-changed` event will be fired whenever the loudest speaking participant changes.

```javascript title="Listen on active speaker changed"
meeting.on("speaker-changed", (participant) => {
  // indicate participant as speaking
});
```

### Active presenter event

The `presenter-changed` event will be fired whenever someone enables screen sharing.

```javascript title="Listen on presenter changed"
meeting.on("presenter-changed", (participant) => {
  // indicate participant as presenting screen
});
```

### Set participant video quality

Update the participant video quality based on use case to `"low" | "med" | "high"`.

```javascript title="Set quelity of receiving stream"
participant.setQuality("low");
```

### Start/Stop video

Share video link to play with `startVideo({ link })` method and stop video with `stopVideo()`. Toggling video will trigger `video-started` and `video-stopped` events for all participants when starting and stopping video respectively.
​

```javascript
// The webhook will be called with the fileUrl as a POST request when the video is processed.
meeting.startVideo({ link: "https://your-app-server.com/video/demo.mp4" });
meeting.stopVideo();
​
​
// Listening on start of the video stream.
meeting.on("video-started", ({ link, currentTime }) => {
  videoRef.current.src = link;
  videoRef.current.currentTime = currentTime;
});

// Listening to the stopped video stream.
meeting.on("video-stopped", () => {
  videoRef.current.pause();
  videoRef.current.src = null;
});
```

### Restream meeting on social media

Restream meeting on your favorite social media channels using RTMP key and url.

```javascript
// start livestreaming
meeting.startLivestream([
  {
    url: "rtmp://x.rtmp.youtube.com/live2/",
    streamKey: "abcd-h6a2-pqrs-vusv-prpf",
  },
]);
​
// stop livestreaming
meeting.stopLivestream();
```

## Leave the meeting

You can disconnect from the meeting with `meeting.leave()` method. This will trigger `participant-left` event for all other participants.

```javascript title="Leave meeting"
meeting.leave();
```


---

# Update a Room - API








---

# Webhooks List - API

<div class="sdk-api-ref-only-h4">

---

### participant-joined

- This webhook is called when new participant join the meeting with following payload.

#### Example

```javascript
{
	"webhookType": "participant-joined",
	"data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "fkd74h",
        "participantName": "John",
    },
}
```

---

### participant-left

- This webhook is called when participant left the meeting with following payload

#### Example

```javascript
{
	"webhookType": "participant-left",
	"data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "fkd74h",
        "participantName": "John",
    },
}
```

---

### session-started

- This webhook is called when new meeting session is successfully started

#### Example

```javascript
{
    "webhookType": "session-started",
    "data": {
        "sessionId": "613731342f27f56e4fc4b6d0",
        "meetingId": "jvsg-8rjn-j304",
        "start": "2022-07-05T15:55:35.047+00:00",
    },
}
```

---

### session-ended

- This webhook is called when all participants lefts and meeting session is closed

#### Example

```javascript
{
    "webhookType": "session-ended",
    "data": {
        "sessionId": "613731342f27f56e4fc4b6d0",
        "meetingId": "jvsg-8rjn-j304",
        "start": "2022-07-05T15:55:35.047+00:00",
        "end": "2022-07-05T15:60:35.047+00:00",
    },
}
```

---

### recording-starting

- A "Recording Starting" webhook is triggered when the recording process for a meeting is initiated.

#### Example

```javascript
{
    "webhookType": "recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-started

- Recording started webhook will be received when successfully recording is started in meeting

#### Example

```javascript
{
    "webhookType": "recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopping

- A "Recording Stopping" webhook is triggered when the recording end process for a meeting is initiated.

#### Example

```javascript
{
    "webhookType": "recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopped

- Recording stopped webhook will be received when recording is successfully stopped in meeting.

#### Example

```javascript
{
    "webhookType": "recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
        "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",

    },
}
```

---

### recording-failed

- A "Recording Failed" webhook is generated when the recording process encounters an interruption or issue during either the starting or stopping phases.

#### Example

```javascript
{
    "webhookType": "recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### participant-track-recording-starting

- A "Participant Track Recording Starting" webhook is triggered when the track recording process for a participant is initiated.

#### Example

```javascript
{
    "webhookType": "participant-track-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-started

- Participant Track Recording started webhook will be received when successfully track recording is started in meeting

#### Example

```javascript
{
    "webhookType": "participant-track-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopping

- A "Participant Track Recording Stopping" webhook is triggered when the track recording end process for a participant is initiated.

#### Example

```javascript
{
    "webhookType": "participant-track-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopped

- Participant Track Recording stopped webhook will be received when track recording is successfully stopped in meeting.

#### Example

```javascript
{
    "webhookType": "participant-track-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-track-recording-failed

- A "Participant Track Recording Failed" webhook is generated when the track recording process encounters an interruption or issue during either the starting or stopping phases.

#### Example

```javascript
{
    "webhookType": "participant-track-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-recording-starting

- A "Participant Recording Starting" webhook is triggered when the participant recording process for a participant is initiated.

#### Example

```javascript
{
    "webhookType": "participant-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-started

- Participant Recording started webhook will be received when successfully participant recording is started in meeting

#### Example

```javascript
{
    "webhookType": "participant-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopping

- A "Participant Recording Stopping" webhook is triggered when the participant recording end process for a participant is initiated.

#### Example

```javascript
{
    "webhookType": "participant-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopped

- Participant Recording stopped webhook will be received when participant recording is successfully stopped in meeting.

#### Example

```javascript
{
    "webhookType": "participant-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-recording-failed

- A "Participant Recording Failed" webhook is generated when the participant recording process encounters an interruption or issue during either the starting or stopping phases.

#### Example

```javascript
{
    "webhookType": "participant-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
    },
}
```

---

### merge-recording-completed

- A "Merge Recording Completed" webhook is triggered when the participant recordings have been successfully merged.

#### Example

```javascript
{
    "webhookType": "merge-recording-completed",
    "data": {
        "id": "bf37fabb-6e34-418b-bc29-97f053fc6cfe",
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### merge-recording-failed

- A "Merge Recording Failed" webhook is triggered when the merge operation fails due to any issue during processing (e.g., missing recordings, sync issues, internal error, etc.).

#### Example

```javascript
{
    "webhookType": "merge-recording-failed",
    "data": {
        "id": "bf37fabb-6e34-418b-bc29-97f053fc6cfe",
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "message?": "error message, if any"
    },
}
```

---

### transcription-started

- You will receive a `transcription-started` webhook when the post transcription or realtime transcription is started successfully. This webhook will be triggered against the `webhookUrl` provided during the start transcription API call.

#### Example

```javascript
{
    "webhookType": "transcription-started",
    "data": {
        "id": "40b0a4ed-9842-40c9-a288-e4b1bf98a90a",
        "type": "realtime",
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "621497578bea0d0404c35c4c"
    },
}
```

---

### transcription-stopped

- You will receive a `transcription-stopped` webhook when the post transcription or realtime transcription is stopped successfully. This webhook will be triggered against the `webhookUrl` provided during the start transcription API call.

#### Example

```javascript
{
    "webhookType": "transcription-stopped",
    "data": {
        "id": "40b0a4ed-9842-40c9-a288-e4b1bf98a90a",
        "type": "realtime",
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "621497578bea0d0404c35c4c"
    },
}
```

---

### transcription-failed

- You will receive a `transcription-failed` webhook when the post transcription or realtime transcription process encounters an interruption or issue during either the starting or stopping phases. This webhook will be triggered against the `webhookUrl` provided during the start transcription API call.

#### Example

```javascript
{
    "webhookType": "transcription-failed",
    "data": {
        "id": "40b0a4ed-9842-40c9-a288-e4b1bf98a90a",
        "type": "realtime",
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "621497578bea0d0404c35c4c"
    },
}
```

---

### livestream-starting

- A "Livestream Starting" webhook is triggered when the livestreaming process for a meeting is initiated.

#### Example

```javascript
{
    "webhookType": "livestream-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### livestream-started

- When you use live-streaming in our meeting service you will receive this webhook when livestream is successfully started.

#### Example

```javascript
{
    "webhookType": "livestream-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### livestream-stopping

- A "Livestream Stopping" webhook is triggered when the livestream end process for a meeting is initiated.

#### Example

```javascript
{
    "webhookType": "livestream-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### livestream-stopped

- When live-stream is stopped in meeting this webhook is fired with following payload

#### Example

```javascript
{
    "webhookType": "livestream-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### livestream-failed

- A "Livestream Failed" webhook is generated when the livestream process encounters an interruption or issue during either the starting or stopping phases.

#### Example

```javascript
{
    "webhookType": "livestream-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### hls-starting

- An "HLS Starting" webhook is generated when the HLS (HTTP Live Streaming) process for a meeting is initiated.

#### Example

```javascript
{
    "webhookType": "hls-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### hls-started

- When you use HTTP live streaming (HLS) in a meeting, this event will be fired when encoding of HLS has started.

#### Example

```javascript
{
    "webhookType": "hls-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "playbackHlsUrl": "https://cdn.videosdk.live/meetings-hls/b8a770ef-d713-4a27-9ab7-e5a0b724caaf/index.m3u8"
    },
}
```

---

### hls-playable

- When you start HTTP live streaming (HLS) in a meeting, this event will be fired when HLS is in a playable state. So, now you can embed `playbackHlsUrl` in the HLS player.

- On hls-playable you get `playbackHlsUrl` and `livestreamUrl`.
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

#### Example

```javascript
{
    "webhookType": "hls-playable",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "playbackHlsUrl": "https://cdn.videosdk.live/meetings-hls/b8a770ef-d713-4a27-9ab7-e5a0b724caaf/index.m3u8"
    },
}
```

---

### hls-stopping

- An "HLS Stopping" webhook is generated when the HLS (HTTP Live Streaming) end process for a meeting is initiated.

#### Example

```javascript
{
    "webhookType": "hls-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### hls-stopped

- This event is fired when you stop a http live streaming in meeting it has following payload

#### Example

```javascript
{
    "webhookType": "hls-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### hls-failed

- An "HLS Failed" webhook is generated when the HLS (HTTP Live Streaming) process encounters an interruption or issue during either the starting or stopping phases.

#### Example

```javascript
{
    "webhookType": "hls-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### resource-acquired

- Resource acquired webhook will be received when resource is successfully acquired and ready for composition.

#### Example

```javascript
{
    "webhookType": "resource-acquired",
    "data": {
        "id": "abcdef9879288c1f48339f64",
        "type": "recording",
    },
}
```

---

### ai-deployment-session-starting

- This webhook will be received when ai-deployment-session is started and is in `Queued` state

#### Example

```javascript
{
    "webhookType": "ai-deployment-session-starting",
    "data": {
        "sessionId": "session-5bf19efa-22af-41d8-8a3f-b4dbd3f8bcac",
    },
}
```

---

### ai-deployment-session-started

- This webhook will be received when ai-deployment-session is started and is in `Running` state

#### Example

```javascript
{
    "webhookType": "ai-deployment-session-started",
    "data": {
        "sessionId": "session-5bf19efa-22af-41d8-8a3f-b4dbd3f8bcac",
    },
}
```

---


### ai-deployment-session-stopping

- This webhook will be received when stop ai-deployment-session is initiated and is in `Stopping` state

#### Example

```javascript
{
    "webhookType": "ai-deployment-session-stopping",
    "data": {
        "sessionId": "session-5bf19efa-22af-41d8-8a3f-b4dbd3f8bcac",
    },
}
```

---


### ai-deployment-session-stopped

- This webhook will be received when ai-deployment-session is stopped and is in `Stopped` state

#### Example

```javascript
{
    "webhookType": "ai-deployment-session-stopped",
    "data": {
        "sessionId": "session-5bf19efa-22af-41d8-8a3f-b4dbd3f8bcac",
    },
}
```

---


### ai-deployment-session-failed

- This webhook will be received when ai-deployment-session has failed and is in `Failed` state.

#### Example

```javascript
{
    "webhookType": "ai-deployment-session-failed",
    "data": {
        "sessionId": "session-5bf19efa-22af-41d8-8a3f-b4dbd3f8bcac",
    },
}
```

---

</div>


---

# Validate a Room - API






---

# Webhook Verification - API

VideoSdk signs the webhook events it sends to your endpoints by including a signature in each event’s `videosdk-signature` header. This allows you to verify that the events were sent by VideoSdk and not by a third party. You can verify signatures by following these steps.

![webhook-verification.png](https://cdn.videosdk.live/website-resources/docs-resources/webhook-verification.png)

## Public key

Our RSA public key is available at [https://api.videosdk.live/v2/public/rsa-public-key](https://api.videosdk.live/v2/public/rsa-public-key). You can obtain it by making a GET request to this endpoint.

## Verification

Every request will have a custom `videosdk-signature` header. This header is a signature that is based on the "RSA-SHA256" hash of the request body. You can calculate the signature on your own and compare it with the value given in the header. If the two values are equal, you can safely consider that this request originated from VideoSdk.

### Sample code

<div>




</div>


---

# Create WHEP Session - API







---

# Delete WHEP Session - API






---

# Trickle ICE for WHEP - API






---

# Create WHIP Session - API







---

# Delete WHIP Session - API







---

# Trickle ICE for WHIP - API







---

## Custom Video Track - Flutter

- You can create a Video Track using `createCameraVideoTrack()` method of `VideoSDK` class.
- This method can be used to create video track using different encoding parameters, camera facing mode, and optimization mode.

### Parameters

- **cameraId**:

  - type: `String`
  - required: `false`
  - It will be the id of the camera from which the video should be captured.

- **encoderConfig**:

  - type: `CustomTrackVideoConfig`
  - required: `false`
  - default: `h720p_w1280p`

  - The video resolutions listed below are `common encoder` configuration options supported across `All Platforms`.

| Encoder Config | Resolution | Frame Rate | Optimized (kbps) | Balanced (kbps) | High Quality (kbps) |
| -------------- | :--------: | :--------: | :--------------: | :-------------: | :-----------------: |
| h144p_w192p | 192x144 | 15 fps | 60 | 100 | 150 |
| h240p_w320p | 320x240 | 15 fps | 120 | 200 | 350 |
| h480p_w640p | 640x480 | 25 fps | 300 | 500 | 750 |
| h720p_w960p | 960x720 | 30 fps | 800 | 1200 | 1600 |
| h1080p_w1440p | 1440x1080 | 30 fps | 1600 | 2200 | 2700 |
| h360p_w640p | 640x360 | 20 fps | 200 | 400 | 600 |
| h720p_w1280p | 1280x720 | 30 fps | 1000 | 1500 | 2000 |
| h1080p_w1440p | 1280x720 | 30 fps | 1600 | 2300 | 2700 |


- The video resolutions listed below are additional encoder configuration options available specifically for `Web applications`. 



| Encoder Config | Resolution | Frame Rate | Optimized (kbps) | Balanced (kbps) | High Quality (kbps) |
| -------------- | :--------: | :--------: | :----------: | :----------: | :----------: |
| h120p_w160p | 160x120 | 15 fps | 60 | 100 | 150 |
| h180p_w240p | 240x180 | 15 fps | 100 | 150 | 250 |
| h360p_w480p | 480x360 | 20 fps | 200 | 400 | 600 |
| h540p_w720p | 720×540 | 30 fps | 350 | 650 | 800 |
| h1440p_w1920p | 1920×1440 | 30 fps | 3500 | 4000 | 4500 |
| h180p_w320p | 320x180 | 15 fps | 100 | 150 | 250 |
| h216p_w384p | 384x216 | 15 fps | 120 | 200 | 350 |
| h540p_w960p | 960x540 | 25 fps | 400 | 600 | 800 |
| h1440p_w2560p | 2560x1440 | 30 fps | 5000 | 5500 | 6000 |
| h2160p_w3840p | 3840x2160 | 30 fps | 8000 | 8500 | 9000 |

:::important
The below encoder configurations can also be used in mobile applications (Android and iOS). However, the actual video resolution may differ from the requested value due to device and hardware limitations. To obtain the exact resolution being used, refer to the supported video tracks available on the mobile application.
:::

:::note
Above mentioned encoder configurations are valid for both, landscape as well as portrait mode.
:::




- **facingMode**:

  - type: `FacingMode`
  - required: `false`
  - Allowed values : `FacingMode.front` | `FacingMode.environment`
  - It will specify whether to use front or back camera for the video track.

- **multiStream**

  - type: `boolean`
  - required: `false`
  - default: `true`
  - It will specify if the stream should send multiple resolution layers or single resolution layer.

:::caution
MultiStream functionality is not supported in the Firefox browser. VideoSDK will only send one stream for Firefox browsers.
:::

:::info

- To learn more about optimizations and best practices for using custom video tracks, [follow this guide](/flutter/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track).
- This parameter is only available from `v1.0.9`.

:::

#### Returns

- `Future<CustomTrack?>`

### Example

```javascript
CustomTrack? videoTrack = await VideoSDK.createCameraVideoTrack(
      encoderConfig: CustomVideoTrackConfig.h720p_w960p,
      multiStream: true,
      facingMode:"user",
      birtrateMode: BitrateMode.HIGH_QUALITY,
      maxLayers: 2,
    );
```

## Custom Audio Track - Flutter

- You can create a Audio Track using `createMicrophoneAudioTrack()` method of `VideoSDK` class.
- This method can be used to create audio track using different encoding parameters and noise cancellation configuration.

### Parameters

- **microphoneId**:

  - type: `String`
  - required: `false`
  - It will be the id of the mic from which the audio should be captured.

- **encoderConfig**:

  - type: `CustomTrackAudioConfig`
  - required: `false`
  - default: `speech_standard`
  - You can choose from the below mentioned list of values for the encoder config.

| Encoder Config      | Bitrate  | Auto Gain | Echo Cancellation | Noise Suppression |
| ------------------- | :------: | :-------: | :---------------: | :---------------: |
| speech_low_quality  | 16 kbps  |   TRUE    |       TRUE        |       TRUE        |
| speech_standard     | 24 kbps  |   TRUE    |       TRUE        |       TRUE        |
| music_standard      | 32 kbps  |   FALSE   |       FALSE       |       FALSE       |
| standard_stereo     | 64 kbps  |   FALSE   |       FALSE       |       FALSE       |
| high_quality        | 128 kbps |   FALSE   |       FALSE       |       FALSE       |
| high_quality_stereo | 192 kbps |   FALSE   |       FALSE       |       FALSE       |

- **noiseConfig**

  - **echoCancellation**

    - type: `boolean`
    - required: `false`
    - If `true` echo cancellation will turned on else it would be turned off.

  - **autoGainControl**

    - type: `boolean`
    - required: `false`
    - If `true` auto gain will turned on else it would be turned off.

  - **noiseSuppression**
    - type: `boolean`
    - required: `false`
    - If `true` noise suppression will turned on else it would be turned off.

#### Returns

- `Future<CustomTrack?>`

### Example

```javascript
CustomTrack? audioTrack = await VideoSDK.createMicrophoneAudioTrack(
        encoderConfig: CustomAudioTrackConfig.high_quality);
```


---

# Meeting Error Codes - Flutter

If you encounter any of the errors listed below, refer to the [Developer Experience Guide](../../guide/best-practices/developer-experience.md#listen-for-error-events), which offers recommended solutions based on common error categories.



### 1. Errors associated with Organization 

This table lists errors that occur due to the configuration and limitations within your organization’s account. These include account status, participant limits, and add-on service availability.

| Type                                   | Code  | Message                                             |
|----------------------------------------|-------|-----------------------------------------------------|
| ACCOUNT_DEACTIVATED                   | 4006  | Your account has been deactivated. Please contact VideoSDK support. |
| ACCOUNT_DISCONTINUED                  | 4007  | Your account has been discontinued. Please reach out to support for more details. |
| MAX_PARTICIPANT_REACHED               | 4009  | You have reached the maximum participant limit for this meeting. |
| MAX_SPEAKER_REACHED                   | 4010  | The maximum number of speakers for this meeting has been reached. |
| MAX_SPEAKER_LIMIT_REACHED_ON_ORGANIZATION | 4026  | Your organization has reached the maximum number of speakers allowed. |
| MAX_VIEWER_LIMIT_REACHED_ON_ORGANIZATION | 4027  | Your organization has reached the maximum number of viewers allowed. |
| ADD_ON_SERVICES_DISABLED              | 4021  | Add-On services have been disabled. Please contact support to enable them. |
| MAX_RECORDING_LIMIT_REACHED_ON_ORGANIZATION              | 4028  | You have reached max limit of recording on organization. To increase contact at support@videosdk.live |
| MAX_HLS_LIMIT_REACHED_ON_ORGANIZATION  | 4029  | You have reached max limit of hls on organization. To increase contact at support@videosdk.live |
| MAX_LIVESTREAM_LIMIT_REACHED_ON_ORGANIZATION  | 4030  | You have reached max limit of livestream on organization. To increase contact at support@videosdk.live |

### 2. Errors associated with Token

Errors listed here are related to issues with the API key, authentication tokens, or permissions assigned to users. These errors can occur when tokens are missing, expired, or improperly configured.

| Type                                    | Code  | Message                                                |
|-----------------------------------------|-------|--------------------------------------------------------|
| INVALID_API_KEY                        | 4001  | The provided API key is either missing or invalid. |
| INVALID_TOKEN                          | 4002  | The provided token is empty, invalid, or has expired. |
| INVALID_PERMISSIONS                    | 4008  | The permissions in the token are incorrect. Please verify them. |
| UNAUTHORIZED_MEETING_ID                | 4022  | The provided token is not authorized for this meeting ID. |
| UNAUTHORIZED_PARTICIPANT_ID            | 4023  | The provided token is not authorized for this participant ID. |
| UNAUTHORIZED_ROLE                      | 4024  | The role specified in the token is not valid for joining this meeting. |
| UNAUTHORIZED_REQUEST                      | 4025 | Your request does not match the security configuration. |

### 3. Errors associated with Meeting and Participant

This table lists errors resulting from invalid or missing meeting or participant details, including cases where a participant attempts to join with a duplicate ID.

| Type                    | Code  | Message                                         |
|-------------------------|-------|-------------------------------------------------|
| INVALID_MEETING_ID      | 4003  | The meeting ID provided is either invalid or missing. |
| INVALID_PARTICIPANT_ID  | 4004  | The participant ID is either invalid or missing. |
| DUPLICATE_PARTICIPANT   | 4005  | This participant has joined from another device. |

### 4. Errors associated with Add-on Service

This section addresses errors that occur while using VideoSDK's add-on services such as recording, livestreaming, HLS streaming, and transcription.

### Recording-related errors

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_RECORDING_FAILED      | 4011  | Failed to start recording. Please try again.   |
| STOP_RECORDING_FAILED       | 4012  | Failed to stop recording. Please try again.    |
| RECORDING_FAILED            | 5001  | Recording was stopped due to an error.         |
| START_PARTICIPANT_RECORDING_FAILED | 4035 | Failed to start participant recording. Please check the request. |
| STOP_PARTICIPANT_RECORDING_FAILED  | 4036 | Failed to stop participant recording. |
| PARTICIPANT_RECORDING_FAILED       | 5012 | Participant recording has stopped due to an error. |
| START_TRACK_RECORDING_FAILED | 4037 | Failed to start track recording.                |
| STOP_TRACK_RECORDING_FAILED  | 4038 | Failed to stop track recording.                 |
| TRACK_RECORDING_FAILED  | 5013 | Track recording stopped due to an unknown error.                 |
| PREV_RECORDING_PROCESSING  | 4018 | Previous recording session is being processed, please try again after few seconds.                 |
| RECORDING_DURATION_LIMIT_REACHED | 5004 | Recording stopped due to maximum duration being reached. |

### Livestream-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| INVALID_LIVESTREAM_CONFIG           | 4015  | Livestream 'outputs' configuration provided was invalid            |
| START_LIVESTREAM_FAILED     | 4013  | Failed to start livestream. Please try again.  |
| STOP_LIVESTREAM_FAILED      | 4014  | Failed to stop livestream. Please try again.   |
| LIVESTREAM_FAILED           | 5002  | Livestream stopped due to an error.            |
| PREV_RTMP_RECORDING_PROCESSING | 4019 | Previous RTMP recording session is being processed, please try again after few seconds! |
| LIVESTREAM_DURATION_LIMIT_REACHED | 5005 | Livestream stopped due to maximum duration being reached. |

### HLS-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_HLS_FAILED            | 4016  | Failed to start HLS stream.                    |
| STOP_HLS_FAILED             | 4017  | Failed to stop HLS stream.                     |
| HLS_FAILED                  | 5003  | HLS streaming stopped due to an error.         |
| PREV_HLS_STREAMING_PROCESSING | 4020 | Previous HLS streaming session is still being processed. |
| HLS_DURATION_LIMIT_REACHED  | 5006  | HLS stream stopped due to maximum duration being reached. |

### Transcription-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_TRANSCRIPTION_FAILED  | 4031  | Failed to start transcription. Please try again. |
| STOP_TRANSCRIPTION_FAILED   | 4032  | Failed to stop transcription.                  |
| TRANSCRIPTION_FAILED        | 5007  | Transcription stopped due to an error.         |

### 5.Errors associated with Media

These errors involve media access, device availability, or permission-related issues affecting camera, microphone, and screen sharing.

### Device permission-related errors
| Type                                      | Code  | Message                                          |
|-------------------------------------------|-------|--------------------------------------------------|
| ERROR_CAMERA_ACCESS_UNAVAILABLE          | 3005  | Camera access unavailable: Please ensure your device is compatible and that you're on a secure website (https://).                |
| ERROR_MICROPHONE_ACCESS_UNAVAILABLE      | 3006  | Microphone access unavailable: Please ensure your device is compatible and that you're on a secure website (https://).             |
| ERROR_CAMERA_ACCESS_DENIED_OR_DISMISSED      | 3007  | Camera access was denied or dismissed. To proceed, kindly grant access manually through your device/browser settings.. |
| ERROR_MICROPHONE_ACCESS_DENIED_OR_DISMISSED      | 3008  | Microphone access was denied or dismissed. To proceed, kindly grant access through your device/browser settings. |
| ERROR_CAMERA_PERMISSION_DENIED_BY_OS     | 3009  | Camera permission denied by OS system settings. Please check the system settings and grant permission for this browser. |
| ERROR_MICROPHONE_PERMISSION_DENIED_BY_OS | 3010  | Microphone permission denied by OS system settings. Please check the system settings and grant permission for this browser. |
| ERROR_SCREENSHARE_PERMISSION_DENIED  | 3014  | Screen sharing permission was denied. To enable screen sharing, please try again and grant the necessary permissions. |

### Device-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| ERROR_CAMERA_IN_USE          | 3003  | The camera is being used by another application. Please close any programs utilizing the camera, such as video conferencing tools, screen recording software, or other browsers. Restart your browser and attempt again. |
| ERROR_MICROPHONE_IN_USE      | 3004  | The microphone is being used by another application. Please close any programs utilizing the microphone, such as video conferencing tools, screen recording software, or other browsers. Restart your browser and attempt again. |
| ERROR_STARTING_VIDEO      | 3011  | Something went wrong, and the webCam could not be enabled. Please try again. |
| ERROR_STARTING_AUDIO      | 3012  | Something went wrong, and the microphone could not be enabled. Please try again. |
| ERROR_STARTING_SCREENSHARE      | 3013  | Something went wrong, and the screenshare could not be enabled. Please try again. |
| ERROR_CAMERA_DEVICE_INCOMPATIBLE       | 3019  | Camera device cannot produce video: Unable to produce video stream. Please ensure your device is compatible. |
| ERROR_MICROPHONE_DEVICE_INCOMPATIBLE   | 3020  | Microphone device cannot produce audio: Unable to produce audio stream. Please ensure your device is compatible. |
| ERROR_SCREENSHARE_NOT_SUPPORTED  | 3015  | Screenshare not supported: Unable to generate a screenshare stream. Please ensure your device/browser is compatible. |

### 6.Errors associated with Track

These errors occur when there are issues with video or audio tracks, such as disconnections or invalid custom tracks.

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| ERROR_CREATING_VIDEO_TRACK      | 3017  | An error occurred while creating the video track. Please try again. |
| ERROR_CREATING_AUDIO_TRACK      | 3018  | An error occurred while creating the audio track. Please try again. |
| ERROR_CUSTOM_VIDEO_TRACK_DISPOSED      | 3001  | The provided custom video track has been disposed of, and is now in an ended state. Reverting to the default video track. |
| ERROR_CUSTOM_AUDIO_TRACK_DISPOSED      | 3002  | The provided custom audio track has been disposed of, and is now in an ended state. Reverting to the default audio track. |


### 7.Errors associated with Actions

Below error is triggered when an action is attempted before joining a meeting.

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| ERROR_ACTION_PERFORMED_BEFORE_MEETING_JOINED     | 3022  | Oops! Something went wrong. The room was in a connecting state, and during that time, an action encountered an issue. Please try again after joining a meeting. |
| ERROR_JOINING_MEETING     | 3023  | Something went wrong. The meeting could not be joined. Please try again. |
| ERROR_CHANGING_MODE     | 3021  | Something went wrong, and the mode could not be changed. Please try again. |
| ERROR_STARTING_FOREGROUND_SERVICE | 3016 | An error occurred while initializing the foreground service, preventing screenshare from being enabled. Please try again. |


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# MeetingBuilder widget - Flutter

<div class="sdk-api-ref">

MeetingBuilder is a widget provided by the SDK, which handles building a widget for the [`Meeting`](../meeting-class/introduction) instance initialized.

## MeetingBuilder()

```js
MeetingBuilder(
  meetingId: "<meeting-id>",
  token: "<token>",
  displayName: "<your-name>",
  participantId: "abcdefgh",
  micEnabled: true,
  webcamEnabled: true,
  maxResolution: "hd",
  notification: const NotificationInfo(
    title: "Video SDK",
    message: "Video SDK is sharing screen in the meeting",
    icon: "notification_share", // drawable icon name
  ),
  builder: (Meeting meeting) {
    return Text("Meeting screen");
  },
)
```

## Meeting Initialization Parameters

---

### meetingId

- Unique Id of the meeting, where that participant will be joining.

  - type : `String`
  - `REQUIRED`

Please refer this [documentation](/api-reference/realtime-communication/create-room) to create a room.

---

### token

- Token, which is used for authentication purposes.

  - type: `String`
  - `REQUIRED`

Please refer this [documentation](/api-reference/realtime-communication/intro/) to generate a token.

---

### displayName

- Name of the participant, who will be joining the meeting, this name will be displayed to other participants in the same meeting.

  - type : String
  - `REQUIRED`

---

### participantId

- Unique Id of the participant. If not passed then SDK will create an Id by itself and will use that id.

  - type : `String`
  - `OPTIONAL`

---

### micEnabled

- Whether `mic` of the participant will be `on`, while joining the meeting. If it is set to `false`, then mic of that participant will be `disabled` by default, but can be `enabled` or `disabled` later.

  - type: `Boolean`
  - `REQUIRED`

---

### webcamEnabled

- Whether `webcam` of the participant will be `on`, while joining the meeting. If it is set to `false`, then webcam of that participant will be `disabled` by default, but can be `enabled` or `disabled` later.

  - type: `Boolean`
  - `REQUIRED`

---

### maxResolution

- Sets the maximum upload resolution of that participant's webcam stream.

  - type: `String`
  - value: `sd` | `hd`
  - defaultValue: `sd`
  - `OPTIONAL`

### notification

- Notification, that will be shown, while screen-sharing.

  - type: `NotificationInfo`

    - title: `String`
    - message: `String`
    - icon: `String`

  - `REQUIRED`

### builder

- This will take builder method with [`Meeting`](../meeting-class/introduction) instance as a parameter.

  - type: `Widget Function(Meeting)`
  - `REQUIRED`

</div>


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Meeting Builder Widget - Flutter

The entry point into real-time communication SDK.

## Using Meeting Builder Widget

The `Meeting Builder Widget` includes methods and events to initialize and configure the SDK. It is a factory class.




### Properties


  
    
    
    
    
    
    
  </MethodListGroup>
</MethodListGroup>

## Example

```js title="Configure MeetingBuilder Example"
MeetingBuilder(
  meetingId: "<meeting-id>",
  displayName: "Chintan",
  token: "<token>",
  micEnabled: true,
  webcamEnabled: true,
  notification: const NotificationInfo(
    title: "Video SDK",
    message: "Video SDK is sharing screen in the meeting",
    icon: "notification_share", // drawable icon name
  ),
  builder: (Meeting meeting) {
    return Text("Meeting screen");
  },
)
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Meeting Class Events - Flutter

<div class="sdk-api-ref-only-h4">

---

### meetingJoined

- This event will be emitted when a [localParticipant](properties#localparticipant) successfully joined the meeting.

#### Example

```javascript
meeting.on(Events.meetingJoined, (){
  // do something
});
```

---

### meetingLeft

- This event will be emitted when a [localParticipant](properties#localparticipant) left the meeting.

#### Example

```javascript
meeting.on(Events.meetingLeft, () {
  // do something
});
```

---

### participantJoined

- This event will be emitted when a new [participant](../participant-class/introduction) joined the meeting.

#### Event handler parameters

- **participant**: [Participant](../participant-class/introduction)

#### Example

```javascript
meeting.on(Events.participantJoined, (participant) {
  // do something
});
```

---

### participantLeft

- This event will be emitted when a joined [participant](../participant-class/introduction) left the meeting.

#### Event handler parameters

- **participant**: [Participant](../participant-class/introduction)

#### Example

```javascript
meeting.on(Events.participantLeft, (participant) {
  // do something
});
```

---

### speakerChanged

- This event will be emitted when a active speaker changed.
- If you want to know which participant is actively speaking, then this event will be used.
- If no participant is actively speaking, then this event will pass `null` as an event handler parameter.

#### Event handler parameters

- **activeSpeakerId**: String?

#### Example

```javascript
meeting.on(Events.speakerChanged, (activeSpeakerId) {
  // do something
});
```

---

### presenterChanged

- This event will be emitted when any [participant](../participant-class/introduction) starts or stops screen sharing.
- It will pass `participantId` as an event handler parameter.
- If a participant stops screen-sharing, then this event will pass `null` as en event handler parameter.

#### Event handler parameters

- **activePresenterId**: String?

#### Example

```javascript
meeting.on(Events.presenterChanged, (activePresenterId) {
  // do something
});
```

---

### entryRequested

- This event will be emitted when a new [participant](../participant-class/introduction), who is trying to join the meeting, is having permission **`ask_join`** in token.
- This event will only be emitted to the [participants](properties#participants) in the meeting, who is having the permission **`allow_join`** in token.
- This event will pass following parameters as an event parameters, `participantId` and `name` of the new participant who is trying to join the meeting, `allow()` and `deny()` to take required actions.

#### Event handler parameters

- **data**: `Map{'<'}String, dynamic>`\{ **"allow"**: Function; **"deny"**: Function; **"name"**: String; **"participantId"**: String }
  - **allow**: Function
  - **deny**: Function
  - **name**: String
  - **participantId**: String

#### Example

```javascript
meeting.on(Events.entryRequested, (data){
  String? participantId = data["participantId"];
  String? name = data["name"];

  Function allow = data["allow"];
  Function deny = data["deny"];

  print("$name requested to join the meeting.");

  // If you want to allow the entry request
  allow();

  // if you want to deny the entry request
  deny();
});
```

---

### entryResponded

- This event will be emitted when the `join()` request is responded.
- This event will be emitted to the [participants](properties#participants) in the meeting, who is having the permission **`allow_join`** in token.
- This event will be also emitted to the [participant](../participant-class/introduction), who requested to join the meeting.

#### Event handler parameters

- **participantId**: _String_
- **decision**: _"allowed"_ | _"denied"_

#### Example

```javascript
meeting.on(Events.entryResponded, (participantId, decision) {
  // participantId will be id of participant, who requested to join meeting

  if (decision === "allowed") {
    // entry allowed
  } else {
    // entry denied
  }
});
```

---

### webcamRequested

- This event will be emitted to the participant `B` when any other participant `A` requests to enable webcam of participant `B`.
- On accepting the request, webcam of participant `B` will be enabled.

#### Event handler parameters

- **data**: `Map{'<'}String, dynamic>`\{ **accept**: Function; **participantId**: String; **reject**: Function }
  - **accept**: Function
  - **participantId**: String
  - **reject**: Function

#### Example

```javascript
meeting.on(Events.webcamRequested, (data) {
  String? participantId = data["participantId"];

  Function accept = data["accept"];
  Function reject = data["deny"];

  // participantId, will be the id of participant who requested to enable webcam

  // if accept request
  accept();

  // if reject request
  reject();
});
```

---

### micRequested

- This event will be emitted to the participant `B` when any other participant `A` requests to enable mic of participant `B`.
- On accepting the request, mic of participant `B` will be enabled.

#### Event handler parameters

- **data**: Map{'<'}String{','} dynamic>\{ **accept**: Function; **participantId**: String; **reject**: Function }
  - **accept**: Function
  - **participantId**: String
  - **reject**: Function

#### Example

```javascript
meeting.on(Events.micRequested, (data) {
  String participantId = data["participantId"];

  Function accept = data["accept"];
  Function reject = data["reject"];

  // participantId, will be the id of participant who requested to enable webcam

  // if accept request
  accept();

  // if reject request
  reject();
});
```

---

### recordingStarted

- This event will be emitted when recording of the meeting is started.

#### Example

```javascript
meeting.on(Events.recordingStarted, () {
  // do something
});
```

---

### recordingStopped

- This event will be emitted when recording of the meeting is stopped.

#### Example

```javascript
meeting.on(Events.recordingStopped, () {
  // do something
});
```

---

### liveStreamStarted

- This event will be emitted when `RTMP` live stream of the meeting is started.

#### Example

```javascript
meeting.on(Events.liveStreamStarted, () {
  // do something
});
```

---

### liveStreamStopped

- This event will be emitted when `RTMP` live stream of the meeting is stopped.

#### Example

```javascript
meeting.on(Events.liveStreamStopped, () {
  // do something
});
```

</div>


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Video SDK Meeting Class - Flutter

<div id="tailwind" class="sdk-api-ref">

## Introduction

The `Meeting` class includes properties, methods and events for managing a meeting, participants, video, audio and share streams, messaging and UI customization.





## Meeting Properties

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [id](./properties.md#id)

</div>
<div class="col col--4 margin-bottom--sm" >

- [activeSpeakerId](./properties.md#activespeakerid)

</div>
<div class="col col--4 margin-bottom--sm" >

- [activePresenterId](./properties.md#activepresenterid)

</div>
<div class="col col--4 margin-bottom--sm" >

- [selectedWebcamId](./properties.md#selectedwebcamid)

</div>
<div class="col col--4 margin-bottom--sm" >

- [selectedMicId](./properties.md#selectedmicid)

</div>
<div class="col col--4 margin-bottom--sm" >

- [localParticipant](./properties.md#localparticipant)

</div>
<div class="col col--4 margin-bottom--sm" >

- [participants](./properties.md#participants)

</div>
<div class="col col--4 margin-bottom--sm" >

- [PubSub](./properties.md#pubsub)

</div>

</div>

## Meeting Methods

<div class="row">
<div class="col col--4 margin-bottom--sm" >

- [join](./methods#join)

</div>
<div class="col col--4 margin-bottom--sm" >

- [leave](./methods#leave)

</div>
<div class="col col--4 margin-bottom--sm" >

- [enableWebcam](./methods#enablewebcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disableWebcam](./methods#disablewebcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [unmuteMic](./methods#unmutemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [muteMic](./methods#mutemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [enableScreenShare](./methods#enablescreenshare)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disableScreenShare](./methods#disablescreenshare)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startRecording](./methods#startrecording)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopRecording](./methods#stoprecording)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startLivestream](./methods#startlivestream)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopLivestream](./methods#stoplivestream)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getWebcams](./methods#getwebcams)

</div>
<div class="col col--4 margin-bottom--sm" >

- [changeWebcam](./methods#changewebcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [on](./methods#on)

</div>
</div>

## Meeting Events

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [meetingJoined](./events.md#meetingjoined)

</div>
<div class="col col--4 margin-bottom--sm" >

- [meetingLeft](./events.md#meetingleft)

</div>
<div class="col col--4 margin-bottom--sm" >

- [participantJoined](./events.md#participantjoined)

</div>
<div class="col col--4 margin-bottom--sm" >

- [participantLeft](./events.md#participantleft)

</div>
<div class="col col--4 margin-bottom--sm" >

- [speakerChanged](./events.md#speakerchanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [presenterChanged](./events.md#presenterchanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [entryRequested](./events.md#entryrequested)

</div>
<div class="col col--4 margin-bottom--sm" >

- [entryResponded](./events.md#entryresponded)

</div>
<div class="col col--4 margin-bottom--sm" >

- [webcamRequested](./events.md#webcamrequested)

</div>
<div class="col col--4 margin-bottom--sm" >

- [micRequested](./events.md#micrequested)

</div>
<div class="col col--4 margin-bottom--sm" >

- [recordingStarted](./events.md#recordingstarted)

</div>
<div class="col col--4 margin-bottom--sm" >

- [recordingStopped](./events.md#recordingstopped)

</div>
<div class="col col--4 margin-bottom--sm" >

- [livestreamStarted](./events.md#livestreamstarted)

</div>
<div class="col col--4 margin-bottom--sm" >

- [livestreamStopped](./events.md#livestreamstopped)

</div>

</div>

</div>


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Meeting Class Example - Flutter

```js title="Play with meeting instance"
// Join the meeting
meeting?.join();

// Get local participants
meeting?.localParticipant;

// Get remote participants
meeting?.participants;

// Adding event listner
meeting.on(Events.participantJoined, (Participant participant) {
  print("new participant => $participant");
  },
);
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Meeting Class - Flutter

## Using Meeting Class {#h2}

The `Meeting Class` includes methods and events for managing meetings, participants, video & audio streams, data channels and UI customization.




## Properties {#h2}

### id {#h3}

- `type`: String
- `id` represents the meetingId for the current meeting

### localParticipant {#h3}

- `type`: Participant
- `localParticipant` represents the local participant of the meeting

### participants {#h3}

- `type`: Map{'<'}String, Participant>
- `participants` represents all remote participants in the meeting

### pubSub {#h3}

- `type`: PubSub
- `pubSub` represents Publisher-Subscriber feature

### selectedWebcamId {#h3}

- `type`: String?
- `selectedWebcamId` represents the id of currently selected webcam

## Events

### Events.meetingJoined

- `Events.meetingJoined` will be emitted when local participant joins the meeting successfully

### Events.meetingLeft {#h3}

- `Events.meetingLeft` will be emitted when local participant leaves the meeting

### Events.entryRequested {#h3}

- `Events.entryRequested` will be emitted when remote participant requests for entry in your meeting

### Events.entryResponded {#h3}

- `Events.entryResponded` will be emitted when meeting host responds to your entry request

### Events.micRequested {#h3}

- `Events.micRequested` will be emitted when mic is requested

### Events.webcamRequested {#h3}

- `Events.webcamRequested` will be emitted when webcam is requested

### Events.participantJoined {#h3}

- `Events.participantJoined` will be emitted when new participant joins the meeting

### Events.participantLeft {#h3}

- `Events.participantLeft` will be emitted when any participant from the meeting leaves

### Events.recordingStarted {#h3}

- `Events.recordingStarted` will be emitted when recording of the meeting is started successfully

### Events.recordingStopped {#h3}

- `Events.recordingStopped` will be emitted when recording of the meeting is stopped

### Events.liveStreamStarted {#h3}

- `Events.liveStreamStarted` will be emitted when live streaming of the meeting in social media is started successfully

### Events.liveStreamStopped {#h3}

- `Events.liveStreamStopped` emitted when live streaming of the meeting is stopped

### Events.speakerChanged {#h3}

- `Events.speakerChanged` will be emitted when active speaker is changed

### Events.presenterChanged {#h3}

- `Events.presenterChanged` will be emitted when any participant started presenting

## Methods {#h2}

### join() {#h3}

- Return Type : `void`
- `join()` is used to join a meeting.
- Events associated with `join()` method :

  - Local Participant will receive a [`Events.meetingJoined`](/flutter/0.0.x/api/sdk-reference/meeting-class/meeting-class#eventsmeetingjoined) event, when successfully joined.
  - Remote Participant will receive a `Events.participantJoined` event with `participant`.

- When `join()` is called and the permission in the token is `ask_join`, then direct joining is not preformed.
  - In this case `onEntryRequested()` will be emitted to the participant with permission `allow_join`. Once the participant with permission `allow_join` responds to the request, `onEntryResponded({participantId, decision})`.
  - If the `decision` is `allowed`, participant will be joined else if `decision` is `denied` participant showed not be joined.

### leave() {#h3}

- Return Type : `void`
- `leave()` is used to leave current meeting.
- Events associated with `leave()` method :
  - Local Participant will receive a `Events.meetingLeft` event.
  - Remote Participant will receive a `Events.participantLeft` event with `participantId`.

### enableWebcam() {#h3}

- Return Type : `void`
- `enableWebcam()` is used to enable self camera.
- Every Participant will receive a `Events.streamEnabled` event with `stream` object.

### disableWebcam() {#h3}

- Return Type : `void`
- `disableWebcam()` is used to disable self camera.
- Every Participant will receive a `Events.streamDisabled` event with `stream` object.

### unmuteMic() {#h3}

- Return Type : `void`
- `unmuteMic()` is used to enable self microphone.
- Every Participant will receive a `Events.streamEnabled` event with `stream` object.

### muteMic() {#h3}

- Return Type : `void`
- `muteMic()` is used to disable self microphone.
- Every Participant will receive a `Events.streamDisabled` event with `stream` object.

### enableScreenShare() {#h3}

- Return Type : `void`
- `enableScreenShare()` is used to enable screen-sharing.
- Every Participant will receive a `Events.streamEnabled` event with `stream` object.

### disableScreenShare() {#h3}

- Return Type : `void`
- `disableScreenShare()` is used to disable screen-sharing.
- Every Participant will receive a `Events.streamDisabled` event with `stream` object.

### getWebcams() {#h3}

- Return Type : `List<MediaDeviceInfo>`
- `getWebcams()` is used to get list of available cameras.

### getMics() {#h3}

- Return Type : `List<MediaDeviceInfo>`
- `getMics()` is used to get list of available microphones.

### changeWebcam() {#h3}

- Return Type : `void`
- `changeWebcam` is used to change self camera.
- Every Participant will receive `Events.streamEnabled` event with `stream` object and `Events.streamDisabled` event with `stream` object.

### startRecording() {#h3}

- Return Type : `void`
- `startRecording()` is used to start meeting recording.
- Every Participant will receive `Events.recordingStarted` event.

### stopRecording() {#h3}

- Return Type : `void`
- `stopRecording()` is used to stop meeting recording.
- Every Participant will receive `Events.recordingStopped` event.

### startLivestream() {#h3}

- Return Type : `void`
- `startLivestream()` is used to start meeting livestreaming.
- Every Participant will receive `Events.liveStreamStarted` event.

### stopLivestream() {#h3}

- Return Type : `void`
- `stopLivestream()` is used to stop meeting livestreaming.
- Every Participant will receive `Events.liveStreamStopped` event.

### on(Events event, Function handler) {#h3}

- Return Type : `void`
- `on()` is used to handle custom events.
- This method takes an event and handler. Handler function will be called when given event is emitted.

## Example

```js title="Play with meeting instance"
// Join the meeting
meeting?.join();

// Get local participants
meeting?.localParticipant;

// Get remote participants
meeting?.participants;

// Adding event listner
meeting.on(Events.participantJoined, (Participant participant) {
  print("new participant => $participant");
  },
);
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Meeting Class Methods - Flutter

<div class="sdk-api-ref-only-h4">

### join()

- It is used to join a meeting.
- After meeting initialization by [`MeetingBuilder Widget`](../meeting-builder/introduction), it returns a new instance of [Meeting](introduction.md). However by default, it will not automatically join the meeting. Hence, to join the meeting you should call `join()`.

#### Events associated with `join()`:

- Local Participant will receive a [`meetingJoined`](/flutter/0.0.x/api/sdk-reference/meeting-class/events#meetingjoined) event, when successfully joined.
- Remote Participant will receive a [`participantJoined`](events#participantjoined) event with the newly joined [`Participant`](../participant-class/introduction.md) object from the event handler.

#### Participant having `ask_join` permission inside token

- If a token contains the permission `ask_join`, then the participant will not join the meeting directly after calling `join()`, but an event will be emitted to the participant having the permission `allow_join` called [`entryRequested`](events#entryrequested).

- After the decision from the remote participant, an event will be emitted to participant called [`entryResponded`](events#entryresponded). This event will contain the decision made by the remote participant.

#### Participant having `allow_join` permission inside token

- If a token containing the permission `allow_join`, then the participant will join the meeting directly after calling `join()`.

#### Returns

- _`void`_

---

### leave()

- It is used to leave the current meeting.

#### Events associated with `leave()`:

- Local participant will receive a [`meetingLeft`](events#meetingleft) event.
- All remote participants will receive a [`participantLeft`](events#participantleft) event with `participantId` string from the event handler.

#### Returns

- _`void`_

---



### enableWebcam()

- It is used to enable self camera.
- [`streamEnabled`](../participant-class/events#streamenabled) event will be emitted with [`stream`](../stream-class/introduction) object from the event handler, inside that [participant](../participant-class/introduction) object.

#### Returns

- _`void`_

---

### disableWebcam()

- It is used to enable self camera.
- [`streamDisabled`](../participant-class/events#streamdisabled) event will be emitted with [`stream`](../stream-class/introduction) object from the event handler, inside that [participant](../participant-class/introduction) object.

#### Returns

- _`void`_

---

### unmuteMic()

- It is used to enable self microphone.
- [`streamEnabled`](../participant-class/events#streamenabled) event will be emitted with [`stream`](../stream-class/introduction) object from the event handler, inside that [participant](../participant-class/introduction) object.

#### Returns

- _`void`_

---

### muteMic()

- It is used to disable self microphone.
- [`streamDisabled`](../participant-class/events#streamdisabled) event will be emitted with [`stream`](../stream-class/introduction) object from the event handler, inside that [participant](../participant-class/introduction) object.

#### Returns

- _`void`_

---

### enableScreenShare()

- it is used to enable screen-sharing.
- [`streamEnabled`](../participant-class/events#streamenabled) event will be emitted with [`stream`](../stream-class/introduction) object from the event handler, inside that [participant](../participant-class/introduction) object.
- [presenterChanged](./events#presenterchanged) will also receive a callback with the `presenterId`.

#### Returns

- _`void`_

---

### disableScreenShare()

- It is used to disable screen-sharing.
- [`streamDisabled`](../participant-class/events#streamdisabled) event will be emitted with [`stream`](../stream-class/introduction) object from the event handler, inside that [participant](../participant-class/introduction) object.
- [presenterChanged](./events#presenterchanged) will also receive a callback with the `null`.

#### Returns

- _`void`_

---

### startRecording()

- It is used to start meeting recording.
- All [participants](properties#participants) and [localParticipant](properties#localparticipant), will receive [`recordingStarted`](events#recordingstarted) event.

- `webhookUrl` will be triggered when the recording is completed and stored into server. Read more about webhooks [here](https://en.wikipedia.org/wiki/Webhook).

#### Parameters

- **webhookUrl**: String

#### Returns

- _`void`_

#### Example

```javascript
const webhookUrl = "https://webhook.your-api-server.com";

meeting.startRecording(webhookUrl);
```

---

### stopRecording()

- It is used to stop meeting recording.
- All [participants](properties#participants) and [localParticipant](properties#localparticipant), will receive [`recordingStopped`](events#recordingstopped) event.

#### Returns

- _`void`_

#### Example

```javascript
meeting.stopRecording();
```

---

### startLivestream()

- It is used to start meeting livestreaming.
- You will be able to start livestream the meeting to another platforms such as Youtube, Facebook, etc. that supports [`rtmp`](https://en.wikipedia.org/wiki/Real-Time_Messaging_Protocol) streaming.
- All [participants](properties#participants) and [localParticipant](properties#localparticipant), will receive [`liveStreamStarted`](events#livestreamstarted) event.

#### Parameters

- **outputs**: `List{'<'}Map{'<'}String{','} String{'>'}{'>'}` \[\{ **url**: String, **streamKey**: String }]

#### Returns

- _`void`_

---

#### Example

```javascript
var outputs = [
  {
    url: "rtmp://a.rtmp.youtube.com/live2",
    streamKey: "<STREAM_KEY>",
  },
  {
    url: "rtmps://",
    streamKey: "<STREAM_KEY>",
  },
];

meeting.startLivestream(outputs);
```

### stopLivestream()

- It is used to stop meeting livestreaming.
- All [participants](properties#participants) and [localParticipant](properties#localparticipant), will receive [`livestreamStopped`](events#livestreamstopped) event.

#### Returns

- _`void`_

#### Example

```javascript
meeting.stopLivestream();
```

---

### getWebcams()

- It will return all camera devices connected.

#### Returns

- List< [`MediaDeviceInfo`](https://api.flutter.dev/flutter/dart-html/MediaDeviceInfo-class.html) >

#### Example

```javascript
List<MediaDeviceInfo> webcams = meeting.getWebcams();
print(webcams);
```

---

### changeWebcam()

- It is used to change the webcam device.
- If multiple webcam devices are connected, by using `changeWebcam()`, one can change the camera device.

#### Parameters

- **deviceId**: String

#### Returns

- _`void`_

#### Example

```javascript
meeting.changeWebcam(deviceId);
```

---

### on()

- It is used to listen [`Meeting`](introduction) related events.

#### Parameters

- event

  - type: [`Events`](events)
  - This will specify the event to be listened.

- eventHandler
  - type: [`Function`](https://api.dart.dev/stable/2.15.1/dart-core/Function-class.html)
  - This will be invoked whenever, specified event occurred.

#### Returns

- _`void`_

#### Example

```js
meeting.on(Events.meetingJoined, () {
  // do something
});
```

</div>


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Meeting Class Properties - Flutter

<div class="sdk-api-ref-only-h4">

### id

- type: [`String`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)

- Unique id of the meeting where the participant has joined.

---

### activeSpeakerId

- type: [`String?`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)

- It will be the `id` of the participant who is actively speaking in the meeting. If no participant is speaking, at that time value of `activeSpeakerId` will be `null`.

---

### activePresenterId

- type: [`String?`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)

- It will be the `id` of the participant who started `Presenting` / `Screen sharing` in the meeting. If no participant is sharing the screen, at that time value of `activePresenterId` will be `null`.

---

### selectedWebcamId

- type: [`String?`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)
- It will be the `id` of webcam, which is currently selected. If no webcam is selected, at that time, value of `selectedWebCamId` will be `null`.

---

### selectedMicId

- type: [`String?`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)
- It will be the `id` of microphone, which is currently selected. If no microphone is selected, at that time, value of `selectedMicId` will be `null`.

---

### localParticipant

- type: [Participant](../participant-class/introduction)

- It will be the instance of [Participant](../participant-class/introduction) class for the local participant(You) who joined the meeting.

---

### participants

- type: [`Map`](https://api.dart.dev/stable/2.15.1/dart-core/Map-class.html) of [`String`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html) and [Participant](../participant-class/introduction)

- `Map<String, Participant>`

  - Map{'<'}`participantId`, [Participant](../participant-class/introduction)>

- It will contain all joined participants in the meeting except the `localParticipant`.

- This will be the [`Map`](https://api.dart.dev/stable/2.15.1/dart-core/Map-class.html) what will container all participants attached with the key as id of that participant.

```javascript
String remoteParticipantId = "ajf897";

Participant? remoteParticipant = meeting.participants[remoteParticipantId];
```

---

### pubSub

- type: [`PubSub`](../pubsub-class/introduction)
- It is used to enable Publisher-Subscriber feature in [`meeting`](introduction) class.

Learn more about `PubSub`, [here](../pubsub-class/introduction)

</div>


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Meeting Class - Flutter

## Using Meeting Class

The `Meeting Class` includes methods and events for managing meetings, participants, video & audio streams, data channels and UI customization.




### Properties


      
      
      
      
      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>

### Events


      
            
      
      
      
      
      
      
      
      
      </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>

### Methods


      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>

## Example

```js title="Play with meeting instance"
// Join the meeting
meeting?.join();

// Get local participants
meeting?.localParticipant;

// Get remote participants
meeting?.participants;

// Adding event listner
meeting.on(Events.participantJoined, (Participant participant) {
  print("new participant => $participant");
  },
);
```


---

# Participant Class Events - Flutter

<div class="sdk-api-ref-only-h4">

---

### streamEnabled

- This event will be emitted when any [participant](introduction) starts consuming or producing stream of any type.

#### Example

```javascript
room.localParticipant.on(Events.streamEnabled, (Stream stream){
  // do something
});
```

---

### streamDisabled

- This event will be emitted when any [participant](introduction) stops consuming or producing stream of any type.

#### Example

```javascript
room.localParticipant.on(Events.streamDisabled, (Stream stream){
  // do something
});
```

---

### streamPaused

- This event will be emitted when any [participant](introduction) pauses consuming or producing stream of any type.

#### Example

```javascript
room.localParticipant.on(Events.streamPaused, (Stream stream){
  // do something
});
```

---

### streamResumed

- This event will be emitted when any [participant](introduction) resumes consuming or producing stream of any type.

#### Example

```javascript
room.localParticipant.on(Events.streamResumed, (Stream stream){
  // do something
});
```

---

### videoQualityChanged

- `videoQualityChanged` is a callback which gets triggered whenever a participant's video quality changes.

- `currentQuality` and `prevQuality` can have values `HIGH` | `MEDIUM` | `LOW`.

#### Example

```js
participant.on(Events.videoQualityChanged, (data) {
  String currentQuality = data["currentQuality"];
  String prevQuality = data["prevQuality"];
});
```

---

</div>


---

# Video SDK Participant Class - Flutter

<div id="tailwind" class="sdk-api-ref">

## Introduction

`Participant` class includes all the properties, methods and events related to the participants joined in a particular room.

## Participant Properties

<div class="row">
<div class="col col--4 margin-bottom--sm" >

- [id](properties#id)

</div>
<div class="col col--4 margin-bottom--sm" >

- [displayName](properties#displayname)

</div>
<div class="col col--4 margin-bottom--sm" >

- [isLocal](properties#islocal)

</div>
<div class="col col--4 margin-bottom--sm" >

- [pinState](properties#pinstate)

</div>

<div class="col col--4 margin-bottom--sm" >

- [mode](properties#mode)

</div>
<div class="col col--4 margin-bottom--sm" >

- [streams](properties#streams)

</div>
<div class="col col--4 margin-bottom--sm" >

- [metaData](properties#metadata)

</div>
</div>

## Participant Methods

<div class="row">
<div class="col col--4 margin-bottom--sm" >

- [enableCam](methods#enablecam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disableCam](methods#disablecam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [unmuteMic](methods#unmutemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [muteMic](methods#mutemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [setQuality](methods#setquality)

</div>
<div class="col col--4 margin-bottom--sm" >

- [pin](methods#pin)

</div>
<div class="col col--4 margin-bottom--sm" >

- [unpin](methods#unpin)

</div>
<div class="col col--4 margin-bottom--sm" >

- [setViewPort](methods#setviewport)

</div>
<div class="col col--4 margin-bottom--sm" >

- [remove](methods#remove)

</div>
<div class="col col--4 margin-bottom--sm" >

- [on](methods#on)

</div>

<div class="col col--4 margin-bottom--sm">

- [captureImage](methods#captureimage)

</div>

<div class="col col--4 margin-bottom--sm" >

- [getVideoStats](methods#getvideostats)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getAudioStats](methods#getaudiostats)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getShareStats](methods#getsharestats)

</div>
</div>

## Participant Events

<div class="row">
<div class="col col--4 margin-bottom--sm" >

- [streamEnabled](events#streamenabled)

</div>
<div class="col col--4 margin-bottom--sm" >

- [streamDisabled](events#streamdisabled)

</div>
<div class="col col--4 margin-bottom--sm" >

- [streamPaused](events#streampaused)

</div>
<div class="col col--4 margin-bottom--sm" >

- [streamResumed](events#streamresumed)

</div>
</div>
</div>


---

# Participant Class Methods - Flutter

<div class="sdk-api-ref-only-h4">

### enableCam()

- `enableCam()` is used to enable participant's camera.

#### Events associated with `enableCam()`:

- First the participant will get a callback on [cameraRequested](../room-class/events#camerarequested) and once the participant accepts the request, camera device will be enabled.
- Every Participant will receive a `streamEnabled` event with `stream` object.

#### Returns

- _`void`_

#### Example

```js
participant.enableCam();
```

---

### disableCam()

- `disableCam()` is used to disable participant camera.

#### Events associated with `disableCam()`:

- Every Participant will receive a `streamDisabled` event with `stream` object.

#### Returns

- _`void`_

#### Example

```js
participant.disableCam();
```

---

### unmuteMic()

- `unmuteMic()` is used to enable participant microphone.

#### Events associated with `unmuteMic()`:

- First the participant will get a callback on [micRequested](../room-class/events#micrequested) and once the participant accepts the request, mic will be enabled.
- Every Participant will receive a `streamEnabled` event with `stream` object.

#### Returns

- _`void`_

#### Example

```js
participant.unmuteMic();
```

---

### muteMic()

- `muteMic()` is used to disable participant microphone.

#### Events associated with `muteMic()`:

- Every Participant will receive a `streamDisabled` event with `stream` object.

#### Returns

- _`void`_

#### Example

```js
participant.muteMic();
```

---

### setQuality()

- It is used to set the quality of the participant's video stream.

#### Parameters

- **quality**: `"low"`|| `"med"` | `"high"`

#### Returns

- _`void`_

#### Example

```js
participant.setQuality("high");
```

---

### pin()

- It is used to set pin state of the participant. You can use it to pin the screen share, camera or both of the participant. It accepts a optional parameter of type `PinType`. Default PinType is `SHARE_AND_CAM`

#### Parameters

- **pinType**: `PinType.SHARE_AND_CAM` | `PinType.CAM` | `PinType.SHARE`

#### Returns

- _`void`_

#### Example

```js
participant.pin(PinType.CAM);
```

---

### unpin()

- It is used to unpin participant. You can use it to unpin the screen share, camera or both of the participant. It accepts a optional parameter of type `PinType`. Default PinType is `SHARE_AND_CAM`

#### Parameters

- **pinType**: `PinType.SHARE_AND_CAM` | `PinType.CAM` | `PinType.SHARE`

#### Returns

- _`void`_

#### Example

```js
participant.unpin(PinType.CAM);
```

---

### setViewPort()

- `setViewPort()` is used to set the quality of the participant's video stream based on the viewport height and width.

#### Parameters

- **width**: int
- **height**: int

#### Returns

- `void`

#### Example

```js
participant.setViewPort(480, 360);
```

---

### remove()

- It is used to remove participant from the room.

#### Returns

- _`void`_

#### Example

```js
participant.remove();
```

---

### on()

- It is used to listen [`Participant`](introduction) related events.

#### Parameters

- event

  - type: [`Events`](events)
  - This will specify the event to be listened.

- eventHandler
  - type: [`Function`](https://api.dart.dev/stable/2.15.1/dart-core/Function-class.html)
  - This will be invoked whenever, specified event occurred.

#### Returns

- _`void`_

#### Example

```js
participant.on(Events.streamEnabled, (Stream stream){
    // do something
});
```
---

### captureImage()

- It is used to capture image of local participant's current videoStream.
- It will return image in a form of base64.

#### Parameters

- **height**: int
- **width**: int

#### Returns

- `base64` - image in form of base64 string.

---
### getVideoStats()

- `getVideoStats()` will return an `List<dynamic>?` which will contain details regarding the participant's critical video metrics such as **Jitter**, **Packet Loss** etc.

#### Returns

- `object`
  - `jitter` : It represents the distortion in the stream.
  - `bitrate` : It represents the bitrate of the stream which is being transmitted.
  - `totalPackets` : It represents the total packet count which were transmitted for that particiular stream.
  - `packetsLost` : It represents the total packets lost during the transimission of the stream.
  - `rtt` : It represents the time between the stream being reached to client from the server in milliseconds(ms).
  - `codec`: It represents the codec used for the stream.
  - `network`: It represents the network used to transmit the stream
  - `size`: It is object containing the height, width and frame rate of the stream.

:::note

getVideoStats() will return the metrics for the participant at that given point of time and not average data of the complete meeting.

To view the metrics for the complete meeting using the stats API documented [here](/api-reference/realtime-communication/fetch-session-quality-stats).

:::

:::info
If you are getting `rtt` greater than 300ms, try using a different region which is nearest to your user. To know more about changing region [visit here](/api-reference/realtime-communication/create-room).
:::

---

### getAudioStats()

- `getAudioStats()` will return an `List<dynamic>?` which will contain details regarding the participant's critical audio metrics such as **Jitter**, **Packet Loss** etc.

#### Returns

- `List`
  - `jitter` : It represents the distortion in the stream.
  - `bitrate` : It represents the bitrate of the stream which is being transmitted.
  - `totalPackets` : It represents the total packet count which were transmitted for that particiular stream.
  - `packetsLost` : It represents the total packets lost during the transimission of the stream.
  - `rtt` : It represents the time between the stream being reached to client from the server in milliseconds(ms).
  - `codec`: It represents the codec used for the stream.
  - `network`: It represents the network used to transmit the stream

:::note

getAudioStats() will return the metrics for the participant at that given point of time and not average data of the complete meeting.

To view the metrics for the complete meeting using the stats API documented [here](/api-reference/realtime-communication/fetch-session-quality-stats).

:::

:::info

If you are getting `rtt` greater than 300ms, try using a different region which is nearest to your user. To know more about changing region [visit here](/api-reference/realtime-communication/create-room).

:::

### getShareStats()

- `getShareStats()` will return an `List<dynamic>?` which will contain details regarding the participant's critical video metrics such as **Jitter**, **Packet Loss** etc.

#### Returns

- `List`
  - `jitter` : It represents the distortion in the stream.
  - `bitrate` : It represents the bitrate of the stream which is being transmitted.
  - `totalPackets` : It represents the total packet count which were transmitted for that particiular stream.
  - `packetsLost` : It represents the total packets lost during the transimission of the stream.
  - `rtt` : It represents the time between the stream being reached to client from the server in milliseconds(ms).
  - `codec`: It represents the codec used for the stream.
  - `network`: It represents the network used to transmit the stream
  - `size`: It is object containing the height, width and frame rate of the stream.

:::note

getShareStats() will return the metrics for the participant at that given point of time and not average data of the complete meeting.

To view the metrics for the complete meeting using the stats API documented [here](/api-reference/realtime-communication/fetch-session-quality-stats).

:::

:::info

If you are getting `rtt` greater than 300ms, try using a different region which is nearest to your user. To know more about changing region [visit here](/api-reference/realtime-communication/create-room).

:::

</div>


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Participant Class - Flutter

## Using Participant Class

The `Participant Class` includes methods and events for participants and their associated video & audio streams, data channels and UI customization.




### Properties


      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>

### Methods


      
      
      
      
      
      
      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>

### Events


      
      
      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>



## Example

```js title="Play with Participant instance"
// get displayName
participant.displayName;

// Set video quality of that participant to low
participant.setQuality("low");

// Adding event listeners in participant
participant.on(Events.streamEnabled, (Stream stream) {
  // this stream is enabled
});

participant.on(Events.streamDisabled, (Stream stream) {
  // this stream is disabled
});
```


---

# Participant Class Properties - Flutter

<div class="sdk-api-ref-only-h4">

### id

- type: [`String`](https://api.flutter.dev/flutter/dart-core/String-class.html)

- Unique id of the participant, who has joined the room.

---

### displayName

- type: [`String`](https://api.flutter.dev/flutter/dart-core/String-class.html)

- It will be the `displayName` of the participant, who has joined the room.

---

### isLocal

- type: [`bool`](https://api.flutter.dev/flutter/dart-core/bool-class.html)

- It will represents whether the participant is [`LocalParticipant`](../room-class/properties#localparticipant)(You) or not. If it is true, then participant is [`LocalParticipant`](../room-class/properties#localparticipant) otherwise RemoteParticipant.

---

### streams

- type: [`Map<String, Stream>`](https://api.flutter.dev/flutter/dart-core/Map-class.html)

- It will represents the stream for that particular participant who has joined the room. Stream could be `audio` , `video` or `share`.

---

### pinState

- type: `ParticipantPinState`

- It will represents the current pin state of the participant. It has properties `cam` and `share` of type boolean.

---

### mode

- type: `Mode`

- It will represents the participants current mode.

---

### metaData

- type: `Map<String,dynamic>`

- It will represents the additional information, that you have passed in [`createRoom()`](../videosdk-class/methods.md).

</div>


---

# Video SDK PubSub Class - Flutter

<div class="sdk-api-ref">

## Introduction

PubSub class provides the methods to implement Publisher-Subscriber feature in your Flutter Application.

## PubSub Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [publish](methods#publish)

</div>
<div class="col col--4 margin-bottom--sm" >

- [subscribe](methods#subscribe)

</div>

<div class="col col--4 margin-bottom--sm" >

- [unsubscribe](methods#unsubscribe)

</div>
</div>
</div>


---

# PubSub Class Methods - Flutter

<div class="sdk-api-ref-only-h4">

### publish()

- `publish()` is used to publish messages on a specified topic in the room.

#### Parameters

- topic

  - type: [`String`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)
  - This is the name of the topic, for which message will be published.

- message

  - type: [`String`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)
  - This is the actual message.

- options
  - type: [`PubSubPublishOptions`](pubsub-publish-options-class)
  - This specifies the options for publish.

- payload
  - type: `Map<String,dynamic>`
  - If you need to include additional information along with a message, you can pass here as `Map<String, dynamic>`. This is optional parameter.


#### Returns

- _`Future<void>`_

#### Example

```js
// Publishing message
room.pubSub
    .publish(
      "CHAT",
      "Hii",
      const PubSubPublishOptions(persist: true),
    );
```

---

### subscribe()

- `subscribe()` is used to subscribe a particular topic to get all the messages of that particular topic in the room.

#### Parameters

- topic:

  - type: [`String`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)
  - Participants can listen to messages on that particular topic.

- messageHandler:

  - type: [`Function(PubSubMessage)`](pubsub-message-class)
  - This function will be called, whenever pubsub message received.

#### Returns

- [_`Future<PubSubMessages>`_](pubsub-message-class)

#### Example

```js
// Subscribing 'CHAT' Topic

void handleMessage(PubSubMessage pubsubMessage) {
  print(pubsubMessage.message);
}

void subscribePubSubTopic() async {
  PubSubMessages pubsubMessages =
      room.pubSub.subscribe("CHAT", handleMessage);

  // do something
}

subscribePubSubTopic();
```

---

### unsubscribe()

- `unsubscribe()` is used to unsubscribe a particular topic on which you have subscribed priviously.

#### Parameters

- topic:

  - type: [`String`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)
  - This is the name of the topic to be unsubscribed.

- messageHandler:

  - type: [`Function(PubSubMessage)`](https://api.dart.dev/stable/2.15.1/dart-core/Function-class.html)
  - This is the message handler to be unsubscribed.

#### Returns

- _`Future<void>`_

#### Example

```js
// Unsubscribing 'CHAT' topic
room.pubSub.unsubscribe("CHAT", handleMessage);
```

</div>


---

# PubSubMessage Class - Flutter

<div class="sdk-api-ref-only-h4">

## Properties

### id

- type: [`String`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)

- Unique id of the pubsub message.

---

### message

- type: [`String`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)

- Message that has been published on the specific topic.

---

### topic

- type: [`String`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)

- Name of the topic.

---

### senderId

- type: [`String`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)

- This is the id of the participant, who has sent this pubsub message.

---

### senderName

- type: [`String`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)

- This is the name of the participant, who has sent this pubsub message.

---

### timestamp

- type: [`DateTime`](https://api.dart.dev/stable/2.15.1/dart-core/DateTime-class.html)

- Timestamp of when a message has been published.

---

### payload

- type: `Map<String,dynamic>`

- This is the data that you have send with message.

</div>


---

# PubSubPublishOptions Class - Flutter

<div class="sdk-api-ref-only-h4">

## Properties

### persist

- type: [`bool`](https://api.dart.dev/stable/2.15.1/dart-core/bool-class.html)

- defaultValue: `false`

- This property specifies whether to store messages on server for upcoming participants.

- If the value of this property is true, then server will store pubsub messages for the upcoming participants.

---

### sendOnly

- type: `List<String>`

- If you want to send a message to specific participants, you can pass their respective `participantId` here. If you don't provide any IDs, the message will be sent to all participants by default.

:::note
Make sure that participantId present in the array must be subscribe to that specific topic.
:::

</div>


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# PubSubMessage Class - Flutter

## using PubSubMessage Class

The `PubSubMessage` includes properties of PubSub message.




### Properties


      
      
      
      
      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# PubSubOptions Class - Flutter

## using PubSubOptions Class

The `PubSubOptions` includes properties of PubSub options.




### Properties


      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>


---

# RealtimeStore Methods - Flutter

<div class="sdk-api-ref-only-h4">

### `setValue()`

The `setValue()` method is used to store or update data in the RealtimeStore. If a key already exists, it will be overwritten with the new value. Passing `null` as the value deletes the key.

#### Key Notes

- Supports **String** values only.
- Each key can store up to **1 KB** of data.
- A maximum of **100 keys** are allowed per session.
- Deletion is performed by setting the value to `null`.
- Throws an error if:
  - The key is missing or empty.
  - The request fails.
  - The session exceeds the 100-key limit.

#### Parameters

- **`key`** (`String`)  
  The unique key to store the data under.

- **`value`** (`String?`)  
  The string value to be stored. Pass `null` to delete the key.

#### Returns

- _`Future<void>`_


#### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    _room = VideoSDK.createRoom(
      roomId: widget.meetingId,
      token: widget.token,
      displayName: "User1",
      micEnabled: true,
      camEnabled: true,
      defaultCameraIndex: 0,
      multiStream: true,
      mode: Mode.SEND_AND_RECV,
    );
    _room.join();
  }

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      //highlight-start
      ElevatedButton(
        String key = "BLOCK_CHAT";
        String value = "true";
        onPressed: () async {
        try{
          await _room.realtimeStore.setValue(key, value);
        } catch(e){
          print("Error:$e");
        }
       
        },
        child: const Text("Realtime Store Set Value"),
      ),
      //highlight-end
    ]);
  }
}
```

---

### `getValue()`

The `getValue()` method retrieves the current value associated with a given key.

#### Key Notes

- Returns the current string value for the given key.
- Useful for fetching shared state when joining a meeting or reloading a view.
- Throws an error if the key is missing/empty or if the request fails.

#### Parameters

- **`key`** (`String`)  
  The key whose value you want to retrieve.

#### Returns

- _`Future<String?>`_- The stored value or `null` if there was a problem fetching the value.

#### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    _room = VideoSDK.createRoom(
      roomId: widget.meetingId,
      token: widget.token,
      displayName: "User1",
      micEnabled: true,
      camEnabled: true,
      defaultCameraIndex: 0,
      multiStream: true,
      mode: Mode.SEND_AND_RECV,
    );
    _room.join();
  }

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      //highlight-start
       ElevatedButton(
        String key = "BLOCK_CHAT";
        String response= "";
        onPressed: () async {
        try {
          response = await _room.realtimeStore.getValue(key);
        } catch(e){
          print("Error:$e");
        }
        },
        child: const Text("Realtime Store Get Value:$response"),
      ),
      //highlight-end
    ]);
  }
}
```
---

### `observe()`

The `observe()` method subscribes to real-time updates for a given key. When the key’s value changes, a delegate method on your listener is automatically triggered for all connected participants.

#### Key Notes

- Returns an `observerId` which you can later use to stop observing.
- The callback receives the new value and information about who updated it.
- Ideal for syncing live data like timers, shared notes, or agendas.


#### Parameters

- **`key`** (`String`)  
  The key to observe.

- **`callback`** (`function`)
  Function triggered on each update. Receives:

  - `value` (`String?`) → Updated value or `null` if deleted
  - `updatedBy` (`Participant?`) → Object of participant who made the update

#### Returns

- _`Future<String>`_


#### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    _room = VideoSDK.createRoom(
      roomId: widget.meetingId,
      token: widget.token,
      displayName: "User1",
      micEnabled: true,
      camEnabled: true,
      defaultCameraIndex: 0,
      multiStream: true,
      mode: Mode.SEND_AND_RECV,
    );
    _room.join();
  }

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      //highlight-start
       ElevatedButton(
        String key = "BLOCK_CHAT";
          onPressed: () async {
         try {
            observerId = await meeting.realtimeStore.observe(key,(value, updatedBy) { 
            // as participant can be null so kept in try catch
            print("Updated by: ${updatedBy!.id}"); 
          },
        );
        } catch(e){
        print("Error:$e");
        }
       }
      child: const Text("Realtime Store Observe"),
      ),
      //highlight-end
    ]);
  } 
}
```

---

### `stopObserving()`

Stops receiving updates for a specific key and listener combination.

#### Key Notes

- Should be called when the listener is no longer needed (e.g., component unmount).
#### Parameters

- **`observerId`** (`String`)
  The observer ID returned from `observe()`.

#### Returns

- _`Future<void>`_


#### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    _room = VideoSDK.createRoom(
      roomId: widget.meetingId,
      token: widget.token,
      displayName: "User1",
      micEnabled: true,
      camEnabled: true,
      defaultCameraIndex: 0,
      multiStream: true,
      mode: Mode.SEND_AND_RECV,
    );
    _room.join();
  }

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      //highlight-start
       ElevatedButton(
         onPressed: () async {
          try{
            if (observerId != null) {
              await meeting.realtimeStore
                  .stopObserving(observerId!);
              print(
                  "Stopped observing with ID: $observerId");
              observerId = null; // Clear the observer ID
            } else {
              print("No active observer to stop");
            }
          } catch(e){
            print("Error:$e");
          }
          Navigator.pop(context);
        },        
      ),
      //highlight-end
    ]);
  }
}
```
---

</div>


---

# RealtimeStore

The `RealtimeStore` class allows you to store, update, retrieve, and observe custom key-value data within a meeting — in real time. It acts as a shared data layer across all connected participants, ensuring asynchronized states throughout the session.

## RealtimeStore Methods

<div class="row">

<div  class="col col--4 margin-bottom--sm" >

- [setValue()](methods#setValue)

</div>

<div  class="col col--4 margin-bottom--sm" >

- [getValue()](methods#getValue)

</div>

<div  class="col col--4 margin-bottom--sm" >

- [observe()](methods#observe)

</div>

<div  class="col col--4 margin-bottom--sm" >

- [stopObserving()](methods#stopobserving)

</div>
</div>


---

# Room Class Events - Flutter

<div class="sdk-api-ref-only-h4">

---

### roomJoined

- This event will be emitted when a [localParticipant](properties#localparticipant) successfully joined the room.

#### Example

```javascript
room.on(Events.roomJoined, (){
  // do something
});
```

---

### roomLeft

- This event will be emitted when a [localParticipant](properties#localparticipant) left the room.

#### Event handler parameters

- **reason**: LeaveReason

The table below outlines the possible reason codes and their descriptions:

| **Reason** | **Code** | **Message** |
|---------|------|----------|
| WEBSOCKET_DISCONNECTED | 1001 | Socket disconnected |
| REMOVE_PEER | 1002 | Participant was removed from the meeting |
| REMOVE_PEER_VIEWER_MODE_CHANGED | 1003 | Participant removed because viewer mode was changed |
| REMOVE_PEER_MEDIA_RELAY_STOP | 1004 | Participant removed because media relay was stopped |
| SWITCH_ROOM | 1005 | Participant switched to a different room |
| ROOM_CLOSE | 1006 | The meeting has been closed |
| UNKNOWN | 1007 | Participant disconnected due to an unknown reason |
| REMOVE_ALL | 1008 | Remove All from the meeting |
| MEETING_END_API | 1009 | Meeting Ended. |
| REMOVE_PEER_API | 1010 | Participant removed from the meeting |
| MANUAL_LEAVE_CALLED | 1101 | Participant manually called the leave() method to exit the meeting |
| WEBSOCKET_CONNECTION_ATTEMPTS_EXHAUSTED | 1102 | Meeting left after multiple failed websocket connection attempts. |
| JOIN_ROOM_FAILED | 1103 | Meeting left due to an error while joining the room. |
| SWITCH_ROOM_FAILED | 1104 | Meeting left due to an error while switching rooms. |

#### Example

```javascript
room.on(Events.roomLeft, (LeaveReason? reason) {
  // do something
});
```

---

### participantJoined

- This event will be emitted when a new [participant](../participant-class/introduction) joined the room.

#### Event handler parameters

- **participant**: [Participant](../participant-class/introduction)

#### Example

```javascript
room.on(Events.participantJoined, (participant) {
  // do something
});
```

---

### participantLeft

- This event will be emitted when a joined [participant](../participant-class/introduction) left the room.

#### Event handler parameters

- **participantId**: String
- **reason**: LeaveReason

The table below outlines the possible reason codes and their descriptions:

| **Reason** | **Code** | **Message** |
|---------|------|----------|
| WEBSOCKET_DISCONNECTED | 1001 | Socket disconnected |
| REMOVE_PEER | 1002 | Participant was removed from the meeting |
| REMOVE_PEER_VIEWER_MODE_CHANGED | 1003 | Participant removed because viewer mode was changed |
| REMOVE_PEER_MEDIA_RELAY_STOP | 1004 | Participant removed because media relay was stopped |
| SWITCH_ROOM | 1005 | Participant switched to a different room |
| ROOM_CLOSE | 1006 | The meeting has been closed |
| UNKNOWN | 1007 | Participant disconnected due to an unknown reason |
| REMOVE_ALL | 1008 | Remove All from the meeting |
| MEETING_END_API | 1009 | Meeting Ended. |
| REMOVE_PEER_API | 1010 | Participant removed from the meeting |
| MANUAL_LEAVE_CALLED | 1101 | Participant manually called the leave() method to exit the meeting |
| WEBSOCKET_CONNECTION_ATTEMPTS_EXHAUSTED | 1102 | Meeting left after multiple failed websocket connection attempts. |
| JOIN_ROOM_FAILED | 1103 | Meeting left due to an error while joining the room. |
| SWITCH_ROOM_FAILED | 1104 | Meeting left due to an error while switching rooms. |
#### Example

```javascript
room.on(Events.participantLeft, (
  String participantId,
  LeaveReason reason,
) {
  // do something
});
```

---

### speakerChanged

- This event will be emitted when a active speaker changed.
- If you want to know which participant is actively speaking, then this event will be used.
- If no participant is actively speaking, then this event will pass `null` as an event handler parameter.

#### Event handler parameters

- **activeSpeakerId**: String?

#### Example

```javascript
room.on(Events.speakerChanged, (activeSpeakerId) {
  // do something
});
```

---

### presenterChanged

- This event will be emitted when any [participant](../participant-class/introduction) starts or stops screen sharing.
- It will pass `participantId` as an event handler parameter.
- If a participant stops screen-sharing, then this event will pass `null` as en event handler parameter.

#### Event handler parameters

- **activePresenterId**: String?

#### Example

```javascript
room.on(Events.presenterChanged, (activePresenterId) {
  // do something
});
```

---

### pinStateChanged

- This event will be emitted when any [participant](../participant-class/introduction) pin state gets changed.
- It will pass `participantId`, `state`, and `pinnedBy` as `Map

#### Example

```javascript
room.on(Events.participantModeChanged, (data) {
  // do something
});
```

---

### entryRequested

- This event will be emitted when a new [participant](../participant-class/introduction), who is trying to join the room, is having permission **`ask_join`** in token.
- This event will only be emitted to the [participants](properties#participants) in the room, who is having the permission **`allow_join`** in token.
- This event will pass following parameters as an event parameters, `participantId` and `name` of the new participant who is trying to join the room, `allow()` and `deny()` to take required actions.

#### Event handler parameters

- **data**: `Map<String, dynamic>`\{ **"allow"**: Function; **"deny"**: Function; **"name"**: String; **"participantId"**: String }
  - **allow**: Function
  - **deny**: Function
  - **name**: String
  - **participantId**: String

#### Example

```javascript
room.on(Events.entryRequested, (data){
  String? participantId = data["participantId"];
  String? name = data["name"];

  Function allow = data["allow"];
  Function deny = data["deny"];

  print("$name requested to join the room.");

  // If you want to allow the entry request
  allow();

  // if you want to deny the entry request
  deny();
});
```

---

### entryResponded

- This event will be emitted when the `join()` request is responded.
- This event will be emitted to the [participants](properties#participants) in the room, who is having the permission **`allow_join`** in token.
- This event will be also emitted to the [participant](../participant-class/introduction), who requested to join the room.

#### Event handler parameters

- **participantId**: _String_
- **decision**: _"allowed"_ | _"denied"_

#### Example

```javascript
room.on(Events.entryResponded, (participantId, decision) {
  // participantId will be id of participant, who requested to join room

  if (decision === "allowed") {
    // entry allowed
  } else {
    // entry denied
  }
});
```

---

### cameraRequested

- This event will be emitted to the participant `B` when any other participant `A` requests to enable camera of participant `B`.
- On accepting the request, camera of participant `B` will be enabled.

#### Event handler parameters

- **data**: `Map<String, dynamic>`\{ **accept**: Function; **reject**: Function }
  - **accept**: Function
  - **reject**: Function

#### Example

```javascript
room.on(Events.cameraRequested, (data) {

  Function accept = data["accept"];
  Function reject = data["deny"];

  // if accept request
  accept();

  // if reject request
  reject();
});
```

---

### micRequested

- This event will be emitted to the participant `B` when any other participant `A` requests to enable mic of participant `B`.
- On accepting the request, mic of participant `B` will be enabled.

#### Event handler parameters

- **data**: Map{'<'}String{','} dynamic>\{ **accept**: Function; **reject**: Function }
  - **accept**: Function
  - **reject**: Function

#### Example

```javascript
room.on(Events.micRequested, (data) {

  Function accept = data["accept"];
  Function reject = data["reject"];

  // if accept request
  accept();

  // if reject request
  reject();
});
```

---

### recordingStarted

_`This event will be deprecated soon`_

- This event will be emitted when recording of the room is started.

#### Example

```javascript
room.on(Events.recordingStarted, () {
  // do something
});
```

---

### recordingStopped

_`This event will be deprecated soon`_

- This event will be emitted when recording of the room is stopped.

#### Example

```javascript
room.on(Events.recordingStopped, () {
  // do something
});
```

---

### recordingStateChanged

- This event will be emitted when the meeting's recording status changed.

#### Event callback parameters

- **status**: String

`status` has following values

- `RECORDING_STARTING` - Recording is in starting phase and hasn't started yet.
- `RECORDING_STARTED` - Recording has started successfully.
- `RECORDING_STOPPING` - Recording is in stopping phase and hasn't stopped yet.
- `RECORDING_STOPPED` - Recording has stopped successfully.

#### Example

```javascript
room.on(Events.recordingStateChanged, (String status) {
  log("Meeting recording status : $status");
});
```

---

### liveStreamStarted

_`This event will be deprecated soon`_

- This event will be emitted when `RTMP` live stream of the room is started.

#### Example

```javascript
room.on(Events.liveStreamStarted, () {
  // do something
});
```

---

### liveStreamStopped

_`This event will be deprecated soon`_

- This event will be emitted when `RTMP` live stream of the room is stopped.

#### Example

```javascript
room.on(Events.liveStreamStopped, () {
  // do something
});
```

---

### livestreamStateChanged

- This event will be emitted when the meeting's livestream status changed.

#### Event callback parameters

- **status**: String

`status` has following values

- `LIVESTREAM_STARTING` - Livestream is in starting phase and hasn't started yet.
- `LIVESTREAM_STARTED` - Livestream has started successfully.
- `LIVESTREAM_STOPPING` - Livestream is in stopping phase and hasn't stopped yet.
- `LIVESTREAM_STOPPED` - Livestream has stopped successfully.

#### Example

```javascript
room.on(Events.liveStreamStateChanged, (String status) {
  log("Meeting live streaming status : $status");
});
```

---

### hlsStateChanged

- This event will be emitted when the meeting's HLS(Http Livestreaming) status changed.

#### Event callback parameters

- **data**: \{ **status**: String , **playbackHlsUrl**: String , **livestreamUrl**: String }
  - **status**: String
  - **playbackHlsUrl**: String _`will receive this property only in HLS_STARTED status`_
  - **livestreamUrl**: String _`will receive this property only in HLS_STARTED status`_

`status` has following values

- `HLS_STARTING` - Hls is in starting phase and hasn't started yet.
- `HLS_STARTED` - Hls has started successfully.
- `HLS_PLAYABLE` - Hls has started can be played now, it will return `playbaclHlsUrl` and `livestreamUrl`.
- `HLS_STOPPING` - Hls is in stopping phase and hasn't stopped yet.
- `HLS_STOPPED` - Hls has stopped successfully.

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

#### Example

```javascript
room.on(Events.hlsStateChanged, (Map<String, dynamic> data) {
    toastMsg("Meeting HLS status : ${data['status']}");
    if (data['status'] == "HLS_PLAYABLE"){
     // [data] : { status: String,  playbackHlsUrl: String, livestreamUrl: String  }
     log("PLAYBACKHLS URL -- " + data['playbackHlsUrl']);
    }
});
```

---

### hlsStarted

_`This event will be deprecated soon`_

- This event will be emitted when `HLS` of the meeting is started.

#### Event callback parameters

- **playbackHlsUrl**: String
- **livestreamUrl**: String

#### Example

```javascript
room.on(Events.hlsStarted, (String playbackHlsUrl, String livestreamUrl) => {
  //
});
```

---

### hlsStopped

_`This event will be deprecated soon`_

- This event will be emitted when `HLS` of the meeting is stopped.

#### Example

```javascript
room.on(Events.hlsStopped, () => {
  //
});
```

---

---

### transcriptionStateChanged

- This event will be triggered whenever state of realtime transcription is changed.

#### Event callback parameters

- **data**: \{ **status**: String, **id**: String }
  - **status**: String
  - **id**: String

`status` has following values

- `TRANSCRIPTION_STARTING` - Realtime Transcription is in starting phase and hasn't started yet.
- `TRANSCRIPTION_STARTED` - Realtime Transcription has started successfully.
- `TRANSCRIPTION_STOPPING` - Realtime Transcription is in stopping phase and hasn't stopped yet.
- `TRANSCRIPTION_STOPPED` - Realtime Transcription has stopped successfully.

#### Example

```javascript
room.on(Events.transcriptionStateChanged, (Map<String, dynamic> data) {
    //Status can be :: TRANSCRIPTION_STARTING
    //Status can be :: TRANSCRIPTION_STARTED
    //Status can be :: TRANSCRIPTION_STOPPING
    //Status can be :: TRANSCRIPTION_STOPPED
  log("Meeting transcription status : ${data['status']}");
});
```

---

### transcriptionText

- This event will be emitted when text for running realtime transcription received.

#### Example

```javascript
room.on(Events.transcriptionText, (TranscriptionText data) {
  var participantId = data.participantId;
  var participantName = data.participantName;
  var text = data.text;
  var timestamp = data.timestamp;
  var type = data.type;
  print(
        "Meeting Transcription started. Participant name: $participantName , Participant Id $participantId ");

});
```

---

### error

- This event will be emitted when and error occurs in the room.

#### Example

```javascript
room.on(Events.error, (error) {
  log("VIDEOSDK ERROR :: " +
      error['code'].toString() +
      "  :: " +
      error['name'].toString() +
      " :: " +
      error['message'].toString());
});
```

---

### whiteboardStarted

- This event will be emitted when a whiteboard session is succesfully started.
-  It returns a `URL` that can be used to render the whiteboard in the app or in a web view.

#### Example

```javascript
room.on(Events.whiteboardStarted, (url) {
  // do something
});
```

---

### whiteboardStopped

- This event will be emitted when a whiteboard session succesfully ends.

#### Example

```javascript
room.on(Events.whiteboardStopped, () {
  // do something
});
```

---

### roomStateChanged

- This event is triggered whenever the room's state changes. 
- The current state of the room is passed as a callback parameter.
- All available states are `connecting`, `connected`, `disconnected` , `reconnecting`.

#### Event callback parameters

- **state**: `RoomState`

#### Example

```javascript
room.on(Events.roomStateChanged, (RoomState state) {
    switch (state) {
      case RoomState.connecting:
        print('Meeting is Connecting');
        break;
      case RoomState.connected:
        print('Meeting is Connected');
        break;
      case RoomState.disconnected:
        print('Meeting connection disconnected abruptly');
        break;
     case RoomState.reconnecting:
        print('Meeting in reconnection state');
      default:
        print('default');
    }
});
```

---

### pausedAllStreams
- This event is triggered when all or specified media streams within the meeting are successfully paused.
#### Parameters
- **`kind`**: Specifies the type of media stream that was paused.  
  - **Type**: `String`  
  - **Possible values**:
    - `"audio"`: Indicates that audio streams have been paused.
    - `"video"`: Indicates that video streams have been paused.
    - `"share"`: Indicates that screen-sharing video streams have been paused.
#### Example
```js
room.on(Events.pausedAllStreams, (kind) {
  print("Pause $kind Consumer");
});
```
---
### resumedAllStreams
- This event is triggered when all or specified media streams within the meeting are successfully resumed.
#### Parameters
- **`kind`**: Specifies the type of media stream that was resumed.  
  - **Type**: `String`  
  - **Possible values**:
    - `"audio"`: Indicates that audio streams have been resumed.
    - `"video"`: Indicates that video streams have been resumed.
    - `"share"`: Indicates that screen-sharing video streams have been resumed.
#### Example
```js
room.on(Events.resumedAllStreams, (kind) {
  print("resumed $kind Consumer");
});
```
---
### mediaRelayRequestReceived()

- This callback is triggered when a request is recieved for media relay in the destination meeting.

#### Parameters

- **`peerId - (String)`**: Specifies the participantId who requested the media relay.

- **`meetingId - (String)`**: Specifies the meeting from where the media relay request was made.

- **`displayName - (String)`**: Specifies the displayName of the participant who requested the media relay.

- **`accept - (Function)`**: Specifies the function to accept the media relay request.

- **`reject - (Function)`**: Specifies the function to reject the media relay request..

#### Example

```javascript
 room.on(Events.mediaRelayReceived, (meetingId, peerId, displayName, accept, reject) {
      print("Media Realy received: ${displayName}");
    });
```

---

### mediaRelayRequestResponse()

- This callback is triggered when a response is recieved for media relay request in the source meeting.

#### Parameters

- **`decidedBy - (String)`**: Specifies the participantId who responded the request for the media relay.

- **`decision - (String)`**: Specifies the decision whether the request for media relay was accepted or not.

- **`meetingId - (String)`**: Specifies the meeting from where the media relay request was made.


#### Example

```javascript
 room.on(Events.mediaRelayResponse, (decidedBy, decision, meetingId) {
      print("Media Realy response by: ${decidedBy}, decision: ${decision}, meetingId: ${meetingId}");
    });
```

---

### mediaRelayStarted()

- This callback is triggered when the media relay to the destination meeting succesfully starts.

#### Parameters

- **`meetingId - (String)`**: Specifies the meeting where the media relay started.

#### Example

```javascript
   _meeting.on(Events.mediaRelayStarted, (meetingId) {
      print("Media relay started: $meetingId");
    });
```

---

### mediaRelayStopped()

- This callback is triggered when the media relay to the destination meeting stops for any reason.

#### Parameters

- **`meetingId - (String)`**: Specifies the meeting where the media relay stopped.

- **`reason - (String)`**: Specifies the reason why the media relay stopped

#### Example

```javascript
   _meeting.on(Events.mediaRelayStopped, (meetingId, reason) {
      String _reason = reason;
      switch (_reason) {
        case "user_stopped":
          toastMsg("Media relay stopped");
          break;
        case "connection_lost":
          toastMsg("Media relay ended");
          break;
        default:
          toastMsg("Media relay stopped");
      }
    });
```

---

### mediaRelayError()

- This callback is triggered when an error occurs during media relay to the destination meeting.

#### Parameters

- **`meetingId - (String)`**: Specifies the meeting where the media relay stopped.

- **`reason - (String)`**: Specifies the reason why the media relay stopped

#### Example

```javascript
 room.on(Events.mediaRelayError, (meetingId, reason) {
      print("Media Relay error: ${reason}");
    });

```

---


### qualityLimitation

- This event is triggered when a quality limitation is detected or resolved during the meeting.

#### Parameters

- **`type`**: Specifies the type of limitation.

  - **Type**: `String`
  - **Possible values**:
    - `"congestion"`: Network congestion detected.
    - `"bandwidth"`: Insufficient network bandwidth.
    - `"cpu"`: High CPU usage on the device.

- **`state`**: Specifies whether the limitation is currently active or resolved.

  - **Type**: `String`
  - **Possible values**:
    - `"detected"`: Limitation has been detected.
    - `"resolved"`: Limitation has been resolved.

- **`timestamp`**: The time (in milliseconds since epoch) when the event occurred.
  - **Type**: `int`

#### Example

```javascript
import 'package:videosdk/videosdk.dart';
Room room;
room.on(Events.qualityLimitation, (type, state, timestamp) {
  print("Quality Limitiation for $type on $state at $timestamp");
});
```

---

</div>


---

# Video SDK Room Class- Flutter

<div id="tailwind" class="sdk-api-ref">

## Introduction

The `Room` class includes properties, methods and events for managing a VideoSDK Room, participants, video, audio and share streams, messaging and UI customization.





## Room Properties

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [id](./properties#id)

</div>
<div class="col col--4 margin-bottom--sm" >

- [activeSpeakerId](./properties#activespeakerid)

</div>
<div class="col col--4 margin-bottom--sm" >

- [activePresenterId](./properties#activepresenterid)

</div>

<div class="col col--4 margin-bottom--sm" >

- [camEnabled](./properties#camenabled)

</div>

<div class="col col--4 margin-bottom--sm" >

- [selectedCamId](./properties#selectedcam)

</div>

<div class="col col--4 margin-bottom--sm" >

- [selectedCam](./properties#selectedcamid)

</div>

<div class="col col--4 margin-bottom--sm" >

- [micEnabled](./properties#micenabled)

</div>

<div class="col col--4 margin-bottom--sm" >

- [hlsState](./properties#hlsstate)

</div>

<div class="col col--4 margin-bottom--sm" >

- [livestreamState](./properties#livestreamstate)

</div>

<div class="col col--4 margin-bottom--sm" >

- [recordingState](./properties#recordingstate)

</div>

<div class="col col--4 margin-bottom--sm" >

- [hlsDownstreamUrl](./properties#hlsdownstreamurl)

</div>

<div class="col col--4 margin-bottom--sm" >

- [selectedMicId](./properties#selectedmicid)

</div>

<div class="col col--4 margin-bottom--sm" >

- [selectedMic](./properties#selectedmic)

</div>

<div class="col col--4 margin-bottom--sm" >

- [localParticipant](./properties#localparticipant)

</div>
<div class="col col--4 margin-bottom--sm" >

- [participants](./properties#participants)

</div>
<div class="col col--4 margin-bottom--sm" >

- [pinnedParticipants](./properties#pinnedparticipants)

</div>
<div class="col col--4 margin-bottom--sm" >

- [pubSub](./properties#pubsub)

</div>

<div class="col col--4 margin-bottom--sm" >

- [selectedSpeakerId](./properties#selectedspeakerid)

</div>
<div class="col col--4 margin-bottom--sm" >

- [selectedSpeaker](./properties#selectedspeaker)

</div>

</div>

## Room Methods

<div class="row">
<div class="col col--4 margin-bottom--sm" >

- [join](./methods#join)

</div>
<div class="col col--4 margin-bottom--sm" >

- [leave](./methods#leave)

</div>
<div class="col col--4 margin-bottom--sm" >

- [end](./methods#end)

</div>
<div class="col col--4 margin-bottom--sm" >

- [enableCam](./methods#enablecam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disableCam](./methods#disablecam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [unmuteMic](./methods#unmutemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [muteMic](./methods#mutemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getScreenShareSources](./methods#getscreensharesources)

</div>
<div class="col col--4 margin-bottom--sm" >

- [enableScreenShare](./methods#enablescreenshare)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disableScreenShare](./methods#disablescreenshare)

</div>

<div class="col col--4 margin-bottom--sm" >

- [changeMode](./methods#changemode)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startRecording](./methods#startrecording)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopRecording](./methods#stoprecording)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startLivestream](./methods#startlivestream)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopLivestream](./methods#stoplivestream)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startHls](./methods#starthls)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopHls](./methods#stophls)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startTranscription](./methods#starttranscription)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopTranscription](./methods#stoptranscription)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startWhiteboard](./methods#startwhiteboard)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopWhiteboard](./methods#stopwhiteboard)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getCameras](./methods#getcameras)

</div>
<div class="col col--4 margin-bottom--sm" >

- [changeCam](./methods#changecam)

</div>

<div class="col col--4 margin-bottom--sm" >

- [uploadBase64File](./methods#uploadbase64file)

</div>

<div class="col col--4 margin-bottom--sm" >

- [fetchBase64File](./methods#fetchbase64file)

</div>

<div class="col col--4 margin-bottom--sm" >

- [getAudioOutputDevices](./methods#getaudiooutputdevices)

</div>
<div class="col col--4 margin-bottom--sm" >

- [switchAudioDevice](./methods#switchaudiodevice)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getMics](./methods#getmics)

</div>
<div class="col col--4 margin-bottom--sm" >

- [changeMic](./methods#changemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [requestMediaRelay](./methods#requestmediarelay)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopMediaRelay](./methods#stopmediarelay)

</div>
<div class="col col--4 margin-bottom--sm" >

- [switchTo](./methods#switchto)

</div>
<div class="col col--4 margin-bottom--sm" >

- [on](./methods#on)

</div>

<div class="col col--4 margin-bottom--sm" >

- [pauseAllStreams](./methods#pauseallstreams)

</div>

<div class="col col--4 margin-bottom--sm" >

- [resumeAllStreams](./methods#resumeallstreams)

</div>

</div>

## Room Events

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [roomJoined](./events#roomjoined)

</div>
<div class="col col--4 margin-bottom--sm" >

- [roomLeft](./events#roomleft)

</div>
<div class="col col--4 margin-bottom--sm" >

- [participantJoined](./events#participantjoined)

</div>
<div class="col col--4 margin-bottom--sm" >

- [participantLeft](./events#participantleft)

</div>
<div class="col col--4 margin-bottom--sm" >

- [speakerChanged](./events#speakerchanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [presenterChanged](./events#presenterchanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [participantModeChanged](./events#participantmodechanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [pinStateChanged](./events#pinstatechanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [entryRequested](./events#entryrequested)

</div>
<div class="col col--4 margin-bottom--sm" >

- [entryResponded](./events#entryresponded)

</div>
<div class="col col--4 margin-bottom--sm" >

- [cameraRequested](./events#camerarequested)

</div>
<div class="col col--4 margin-bottom--sm" >

- [micRequested](./events#micrequested)

</div>
<div class="col col--4 margin-bottom--sm" >

- [recordingStarted](./events#recordingstarted)

</div>
<div class="col col--4 margin-bottom--sm" >

- [recordingStopped](./events#recordingstopped)

</div>

<div class="col col--4 margin-bottom--sm" >

- [livestreamStarted](./events#livestreamstarted)

</div>
<div class="col col--4 margin-bottom--sm" >

- [livestreamStopped](./events#livestreamstopped)

</div>

<div class="col col--4 margin-bottom--sm" >

- [transcriptionStateChanged](./events#transcriptionstatechanged)

</div>

<div class="col col--4 margin-bottom--sm" >

- [transcriptionText](./events#transcriptiontext)

</div>

<div class="col col--4 margin-bottom--sm" >

- [whiteboardStarted](./events#whiteboardstarted)

</div>
<div class="col col--4 margin-bottom--sm" >

- [whiteboardStopped](./events#whiteboardstopped)

</div>

<div class="col col--4 margin-bottom--sm" >

- [mediaRelayReceived](./events#mediarelayreceived)

</div>

<div class="col col--4 margin-bottom--sm" >

- [mediaRelayResponse](./events#mediarelayresponse)

</div>

<div class="col col--4 margin-bottom--sm" >

- [mediaRelayStarted](./events#mediarelaystarted)

</div>
<div class="col col--4 margin-bottom--sm" >

- [mediaRelayStopped](./events#mediarelaystopped)

</div>
<div class="col col--4 margin-bottom--sm" >

- [mediaRelayError](./events#mediarelayerror)

</div>

<div class="col col--4 margin-bottom--sm" >

- [error](./events#error)

</div>

<div class="col col--4 margin-bottom--sm" >

- [pausedAllStreams](./events#pausedallstreams)

</div>

<div class="col col--4 margin-bottom--sm" >

- [resumedAllStreams](./events#resumedallstreams)

</div>

<div class="col col--4 margin-bottom--sm" >

- [qualityLimitation](./events#qualitylimitation)

</div>

</div>

</div>

---

# Room Class Methods - Flutter

<div class="sdk-api-ref-only-h4">

### join()

- After creating the instance of VideoSDK Room, you can join VideoSDK Room by calling `join()` method.

#### Events associated with `join()`:

- Local Participant will receive a [`roomJoined`](events#roomjoined) event, when successfully joined.
- Remote Participant will receive a [`participantJoined`](events#participantjoined) event with the newly joined [`Participant`](../participant-class/introduction) object from the event handler.

#### Participant having `ask_join` permission inside token

- If a token contains the permission `ask_join`, then the participant will not join the room directly after calling `join()`, but an event will be emitted to the participant having the permission `allow_join` called [`entryRequested`](events#entryrequested).

- After the decision from the remote participant, an event will be emitted to participant called [`entryResponded`](events#entryresponded). This event will contain the decision made by the remote participant.

#### Participant having `allow_join` permission inside token

- If a token containing the permission `allow_join`, then the participant will join the room directly after calling `join()`.

#### Returns

- _`void`_

---

### leave()

- It is used to leave the current running room session.

#### Events associated with `leave()`:

- Local participant will receive a [`roomLeft`](events#roomleft) event.
- All remote participants will receive a [`participantLeft`](events#participantleft) event with `participantId` string from the event handler.

#### Returns

- _`void`_

---

### end()

- It is used to end the current running room session.
- By calling `end()`, all joined [participants](properties#participants) including [localParticipant](properties#localparticipant) of that session will leave the room.

#### Events associated with `end()`:

- All [participants](properties#participants) and [localParticipant](properties#localparticipant), will receive [`roomLeft`](events#roomleft) event.

#### Returns

- _`void`_

---

### enableCam()

- It is used to enable camera device.
- [`streamEnabled`](../participant-class/events#streamenabled) event will be emitted with [`stream`](../stream-class/introduction) object from the event handler, inside that [participant](../participant-class/introduction) object.

#### Returns

- _`void`_

---

### disableCam()

- It is used to disable camera device.
- [`streamDisabled`](../participant-class/events#streamdisabled) event will be emitted with [`stream`](../stream-class/introduction) object from the event handler, inside that [participant](../participant-class/introduction) object.

#### Returns

- _`void`_

---

### unmuteMic()

- It is used to enable microphone device.
- [`streamEnabled`](../participant-class/events#streamenabled) event will be emitted with [`stream`](../stream-class/introduction) object from the event handler, inside that [participant](../participant-class/introduction) object.

#### Returns

- _`void`_

---

### muteMic()

- It is used to disable microphone device.
- [`streamDisabled`](../participant-class/events#streamdisabled) event will be emitted with [`stream`](../stream-class/introduction) object from the event handler, inside that [participant](../participant-class/introduction) object.

#### Returns

- _`void`_

---

### getScreenShareSources()

- It will return all available screens and opened windows.
- This method only supports desktop apps.

#### Returns

- `Future

- [`participantModeChange`](./events#participantmodechanged) event will be emitted with `participantId` and `mode` of the participant

#### Parameters

- **requestedMode**: `Mode.SEND_AND_RECV` | `Mode.SIGNALLING_ONLY` | `Mode.RECV_ONLY`

#### Returns

- _`void`_

#### Example

```javascript
room.changeMode(Mode.SEND_AND_RECV);
```

---

### startRecording()

- It is used to start room recording.
- All [participants](properties#participants) and [localParticipant](properties#localparticipant), will receive [`recordingStarted`](events#recordingstarted) event.

- `webhookUrl` will be triggered when the recording is completed and stored into server. Read more about webhooks [here](https://en.wikipedia.org/wiki/Webhook).

#### Parameters

- **webhookUrl**: String

- **awsDirPath**: String

- **config**:

  - **layout**:
    - **type**: _"GRID"_ | _"SPOTLIGHT"_ | _"SIDEBAR"_
    - **priority**: _"SPEAKER"_ | _"PIN"_
    - **gridSize**: Number _\`max 4\`_
  - **theme**: _"DARK"_ | _"LIGHT"_ | _"DEFAULT"_
  - **mode**: _"video-and-audio"_ | _"audio"_
  - **quality**: _"low"_ | _"med"_ | _"high"_
  - **orientation**: _"landscape"_ | _"portrait"_

- **postTranscriptionConfig**:
  - **PostTranscriptionConfig.enabled**: Boolean
  - **PostTranscriptionConfig.summaryConfig**:
    - **SummaryConfig.enabled**: Boolean
    - **SummaryConfig.prompt**: String
  - **PostTranscriptionConfig.modelId**: String

#### Returns

- _`void`_

#### Example

```javascript
const String webhookUrl = "https://webhook.your-api-server.com";

Map<String, dynamic> config = {
  'layout': {
    'type': 'GRID',
    'priority': 'SPEAKER',
    'gridSize': 4,
  },
  'theme': "LIGHT",
  "mode": "video-and-audio",
};

PostTranscriptionConfig postTranscriptionConfig = PostTranscriptionConfig(
  enabled: true,
  modelId: "raman_v1",
  summaryConfig: SummaryConfig(
    enabled: true,
    prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
  ),
);

room.startRecording(
  webhookUrl: webhookUrl,
  config: config,
  postTranscriptionConfig: postTranscriptionConfig
);
```

---

### stopRecording()

- It is used to stop room recording.
- All [participants](properties#participants) and [localParticipant](properties#localparticipant), will receive [`recordingStopped`](events#recordingstopped) event.

#### Returns

- _`void`_

#### Example

```javascript
room.stopRecording();
```

---

### startLivestream()

- It is used to start room livestreaming.
- You will be able to start livestream the room to another platforms such as Youtube, Facebook, etc. that supports [`rtmp`](https://en.wikipedia.org/wiki/Real-Time_Messaging_Protocol) streaming.
- All [participants](properties#participants) and [localParticipant](properties#localparticipant), will receive [`liveStreamStarted`](events#livestreamstarted) event.

#### Parameters

- **outputs**: `List<Map<String, String>>` \[\{ **url**: String, **streamKey**: String }]

- **config**:

  - **layout**:
    - **type**: _"GRID"_ | _"SPOTLIGHT"_ | _"SIDEBAR"_
    - **priority**: _"SPEAKER"_ | _"PIN"_
    - **gridSize**: Number _\`max 4\`_
  - **theme**: _"DARK"_ | _"LIGHT"_ | _"DEFAULT"_

- **postTranscriptionConfig**:
  - **PostTranscriptionConfig.enabled**: Boolean
  - **PostTranscriptionConfig.summaryConfig**:
    - **SummaryConfig.enabled**: Boolean
    - **SummaryConfig.prompt**: String
  - **PostTranscriptionConfig.modelId**: String

#### Returns

- _`void`_

#### Example

```javascript
var outputs = [
  {
    url: "rtmp://a.rtmp.youtube.com/live2",
    streamKey: "<STREAM_KEY>",
  },
  {
    url: "rtmps://",
    streamKey: "<STREAM_KEY>",
  },
];
var liveStreamConfig =  {
  'layout': {
    'type': 'GRID',
    'priority': 'SPEAKER',
    'gridSize': 4,
  },
  'theme': "LIGHT",
};
PostTranscriptionConfig postTranscriptionConfig = PostTranscriptionConfig(
  enabled: true,
  modelId: "raman_v1",
  summaryConfig: SummaryConfig(
    enabled: true,
    prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
  ),
);
room.startLivestream(outputs, config: livestreamConfig, postTranscriptionConfig: postTranscriptionConfig);
```

---

### stopLivestream()

- It is used to stop room livestreaming.
- All [participants](properties#participants) and [localParticipant](properties#localparticipant), will receive [`livestreamStopped`](events#livestreamstopped) event.

#### Returns

- _`void`_

#### Example

```javascript
room.stopLivestream();
```

---

### startHls()

- It is used to start HLS.
- All [participants](properties#participants) and [localParticipant](properties#localparticipant), will receive [`hlsStarted`](events#hlsstarted) event with the `playbackHlsUrl` and `livestreamUrl` of the HLS feed.
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

#### Parameters

- **config**:

  - **layout**:
    - **type**: _"GRID"_ | _"SPOTLIGHT"_ | _"SIDEBAR"_
    - **priority**: _"SPEAKER"_ | _"PIN"_
    - **gridSize**: Number _\`max 25\`_
  - **theme**: _"DARK"_ | _"LIGHT"_ | _"DEFAULT"_
  - **mode**: _"video-and-audio"_ | _"audio"_
  - **quality**: _"low"_ | _"med"_ | _"high"_
  - **oreintation**: _"landscape"_ | _"portrait"_

- **postTranscriptionConfig**:
  - **PostTranscriptionConfig.enabled**: Boolean
  - **PostTranscriptionConfig.summaryConfig**:
    - **SummaryConfig.enabled**: Boolean
    - **SummaryConfig.prompt**: String
  - **PostTranscriptionConfig.modelId**: String

#### Returns

- _`void`_

#### Example

```javascript

Map<String, dynamic> config = {
  'layout': {
    'type': 'GRID',
    'priority': 'SPEAKER',
    'gridSize': 4,
  },
  'theme': "LIGHT",
  "mode": "video-and-audio"
};

PostTranscriptionConfig postTranscriptionConfig = PostTranscriptionConfig(
  enabled: true,
  modelId: "raman_v1",
  summaryConfig: SummaryConfig(
    enabled: true,
    prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
  ),
);
room.startHls(config: config, postTranscriptionConfig: postTranscriptionConfig);
```

---

### stopHls()

- It is used to stop HLS.
- All [participants](properties#participants) and [localParticipant](properties#localparticipant), will receive [`hlsStopped`](events#hlsstopped) event.

#### Returns

- _`void`_

#### Example

```javascript
room.stopHls();
```

---

### startTranscription()

- It is used to start realtime transcription.

- All [participants](properties#participants) and [localParticipant](properties#localparticipant), will receive [`TRANSCRIPTION_STARTING`](./events.md#transcriptionstatechanged) event state and [`transcription-text`](./events.md#transcriptiontext) event.

#### Parameters

#### 1. transcriptionConfig

- type : `TranscriptionConfig`

- required : `false`

- This specifies the configurations for realtime transcription. You can specify following properties.
  - `TranscriptionConfig.webhookUrl`: Webhooks will be triggered when the state of realtime transcription is changed. Read more about webhooks [here](https://en.wikipedia.org/wiki/Webhook)
  - `TranscriptionConfig.summaryConfig`:
    - `SummaryConfig.enabled`: Indicates whether realtime transcription summary generation is enabled. Summary will be available after realtime transcription stopped. Default: `false`
    - `SummaryConfig.prompt`: provides guidelines or instructions for generating a custom summary based on the realtime transcription content.

#### Returns

- _`void`_

#### Example

```javascript
TranscriptionConfig transcriptionConfig = TranscriptionConfig(
    webhookUrl: "https://webhook.your-api-server.com",
    summaryConfig: SummaryConfig(
        enabled: true,
        prompt:
            "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"));

room.startTranscription(transcriptionConfig: transcriptionConfig);
```

---

### stopTranscription()

- It is used to stop realtime transcription.
- All [participants](../participant-class/introduction.md) and [localParticipant](../participant-class/introduction.md), will receive [`TRANSCRIPTION_STOPPING`](./events.md#transcriptionstatechanged) event state.

#### Returns

- _`void`_

#### Example

```javascript
room.stopTranscription();
```

---

### startWhiteboard()

- It is used to initialize a whiteboard session.

#### Returns

- _`void`_

#### Example

```javascript
room.startWhiteboard();
```

---

### stopWhiteboard()

- It is used to end a whiteboard session.

#### Returns

- _`void`_

#### Example

```javascript
room.stopWhiteboard();
```

---

:::danger
The `getCameras()` method has been completely removed starting from version 1.2.0. Please use [`VideoSDK.getVideoDevices()`](../videosdk-class/methods#getvideodevices) instead.
:::

### getCameras()

- It will return all connected camera devices.

#### Returns

- List< [`MediaDeviceInfo`](https://api.flutter.dev/flutter/dart-html/MediaDeviceInfo-class.html) >

#### Example

```javascript
List<MediaDeviceInfo> cams = room.getCameras();
print(cams);
```

---

### changeCam()

- It is used to change the camera device.
- If multiple camera devices are connected, by using `changeCam()`, one can change the camera device with camera device id.
- You can get list of connected video devices using [`VideoSDK.getVideoDevices()`](../videosdk-class/methods#getvideodevices)

#### Parameters

- **device**: VideoDeviceInfo

#### Returns

- _`void`_

#### Example

```javascript
room.changeCam(device);
```

---

### uploadBase64File()

- It is used to upload your file to Videosdk's Temporary storage

- `base64Data` convert your file to base64 and pass here.
- `token` pass your videosdk token. Read more about token [here](/flutter/guide/video-and-audio-calling-api-sdk/authentication-and-tokens)
- `fileName` provide your fileName with extension

- The method will return the corresponding fileUrl, which will use to retrieve the file from the VideoSDK's storage system.

#### Parameters

- **base64Data**: String
- **token**: String
- **fileName**: String

#### Returns

- `fileUrl` - It will use to retrieve the file from the VideoSDK's storage system.

#### Example

```js
String? fileUrl = await room.uploadBase64File(
  base64Data: "<Your File's base64>", // Convert your file to base64 and pass here
  token: "<VIDEOSDK_TOKEN>",
  fileName: "myImage.jpeg", // Provide name with extension here,
);

print("fileUrl $fileUrl");
```
---

### fetchBase64File()

- It is used to retrieve your file from the Videosdk's Temporary storage
- `url` pass fileUrl which is returned by uploadBase64File()
- `token` pass your videosdk token. Read more about token [here](/flutter/guide/video-and-audio-calling-api-sdk/authentication-and-tokens)

- The method will return image in form of base64 string.

#### Parameters

- **url**: String
- **token**: String

#### Returns

- `base64` - image in form of base64 string.

#### Example

```js
String? base64 = await room.fetchBase64File(
  url: "<Your FileUrl>"; // Provide fileUrl which is returned by uploadBase64File(),
  token :"<VIDEOSDK_TOKEN>",
);

print("base64 $base64");
```
---

:::danger
The `getAudioOutputDevices()` method has been completely removed starting from version 1.2.0. Please use [`VideoSDK.getAudioDevices()`](../videosdk-class/methods#getaudiodevices) instead.
:::

### getAudioOutputDevices()

- It will return all the available audio output devices.

:::note

For iOS devices:

- `EARPIECE` is not supported whenever `WIRED_HEADSET` or `BLUETOOTH` device is connected.
- `WIRED_HEADSET` and `BLUETOOTH` devices are not supported simultaneously. Priority is given to the most recently connected device.

:::

#### Returns

- List< [`MediaDeviceInfo`](https://api.flutter.dev/flutter/dart-html/MediaDeviceInfo-class.html) >

#### Example

```javascript
List<MediaDeviceInfo> audioOutputDevices = room.getAudioOutputDevices();
print(audioOutputDevices);
```

---

### switchAudioDevice()

- It is used to change the audio output device.
- You can get list of connected audio output devices using [`VideoSDK.getAudioDevices()`](../videosdk-class/methods#getaudiodevices)

#### Parameters

- **device**: AudioDeviceInfo

#### Returns

- _`void`_

#### Example

```javascript
room.switchAudioDevice(device);
```

---

:::caution
On the web, the `microphone` will now be `muted` when the input audio device is `disconnected`. Users will need to `unmute` it to continue.
:::


:::danger
The `getMics()` method has been completely removed starting from version 1.2.0. Please use [`VideoSDK.getAudioDevices()`](../videosdk-class/methods#getaudiodevices) instead.
:::

### getMics()

- It will return all the available audio input devices.

#### Returns

- List< [`MediaDeviceInfo`](https://api.flutter.dev/flutter/dart-html/MediaDeviceInfo-class.html) >

#### Example

```javascript
List<MediaDeviceInfo> audioInputDevices = room.getMics();
print(audioInputDevices);
```

---

### changeMic()

- It is used to change the audio input device.
- You can get list of connected audio input devices using [`VideoSDK.getAudioDevices()`](../videosdk-class/methods#getaudiodevices)

#### Parameters

- **device**: AudioDeviceInfo

#### Returns

- _`void`_

:::info

- The `changeMic()` method is not supported on Mobile Applications.

:::

#### Example

```javascript
room.changeMic(device);
```
---

### pauseAllStreams()

This method pauses active media streams within the meeting.

#### Parameters

- **kind**:  Specifies the type of media stream to be paused. If this parameter is omitted, all media streams (audio, video, and screen share) will be paused.

  - **Type**: `String`  
  - **Optional**: Yes

    - Possible values:
    - `"audio"`: Pauses audio streams.
    - `"video"`: Pauses video streams.
    - `"share"`: Pauses screen-sharing video streams.

#### Returns

- _`void`_

#### Example

```js
meeting.pauseAllStreams();
```

---

### resumeAllStreams()

This method resumes media streams that have been paused

#### Parameters

- **kind**:  Specifies the type of media stream to be resumed. If this parameter is omitted, all media streams (audio, video, and screen share) will be resumed.

  - **Type**: `String`  
  - **Optional**: Yes

    - Possible values:
    - `"audio"`: Resumes audio streams.
    - `"video"`: Resumes video streams.
    - `"share"`:Resumes screen-sharing video streams.

#### Returns

- _`void`_

#### Example

```js
meeting.resumeAllStreams();
```
---

### requestMediaRelay

This method starts relaying selected media streams (like camera video, microphone audio, screen share, etc.) from the current meeting to a specified destination meeting.

#### Parameters

- **MeetingId (String) – Required**: ID of the target meeting where media should be relayed.

- **token (String) – Optional**: Authentication token for the destination meeting.

- **kinds (List of Strings) – Optional**: Array of media types to relay. 
  - Possible values:
    - `"audio"`: Resumes audio streams.
    - `"video"`: Resumes video streams.
    - `"share"`:Resumes screen-sharing video streams.
    - `"share_audio"`:Resumes screen-sharing audio streams.

#### Returns

- _`void`_

#### Example

```js
room.requestMediaRelay("<Destination-meetingId>","<token>",["audio", "video"]);
```
---

### stopMediaRelay
This method stops the ongoing media relay to a specific destination meeting.

#### Parameters

- **MeetingId (String) – Required**: ID of the destination meeting where the media relay should be stopped.

#### Returns

- _`void`_

#### Example

```js
room.stopMediaRelay("<Destination-meetingId>");
```

---

### switchTo

This method enables a seamless transition from the current meeting to another, without needing to disconnect and reconnect manually.

#### Parameters

- **meetingId (String) – Required**: ID of the new meeting to switch to.

- **token (String) – Optional**: Authentication token for the new meeting.

- **localParticipantId (String) - Required**: Local PartiticpantId for switching the meeting
#### Returns

- _`void`_

#### Example

```js
room.switchTo("<meeitngId>", "<token>","<localParticipantId>");
```

--- 

### on()

- It is used to listen [`Room`](introduction) related events. - It is used to listen [`Room`](introduction) related events.

#### Parameters

- event

  - type: [`Events`](events)
  - This will specify the event to be listened.

- eventHandler
  - type: [`Function`](https://api.dart.dev/stable/2.15.1/dart-core/Function-class.html)
  - This will be invoked whenever, specified event occurred.

#### Returns

- _`void`_

#### Example

```js
room.on(Events.roomJoined, () {
  // do something
});
```
</div>

---

# Room Class Properties - Flutter

<div class="sdk-api-ref-only-h4">

### id

- type: [`String`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)

- Unique id of the room where the participant has joined.

---

### activeSpeakerId

- type: [`String?`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)

- It will be the `id` of the participant who is actively speaking in the room. If no participant is speaking, at that time value of `activeSpeakerId` will be `null`.

---

### activePresenterId

- type: [`String?`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)

- It will be the `id` of the participant who started `Presenting` / `Screen sharing` in the room. If no participant is sharing the screen, at that time value of `activePresenterId` will be `null`.

---

### camEnabled

- type: [`bool`](https://api.dart.dev/stable/2.15.1/dart-core/bool-class.html)
- It indicates if camera device is enabled or not.

---

### selectedCamId

- type: [`String?`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)
- It will be the `id` of camera device, which is currently selected. 
---

### selectedCam

- type: `VideoDeviceInfo`
- It will be the object of the camera device, which is currently selected. 
---

### micEnabled

- type: [`bool`](https://api.dart.dev/stable/2.15.1/dart-core/bool-class.html)
- It indicates if microphone device is enabled or not.

---

### selectedMicId

- type: [`String?`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)
- It will be the `id` of microphone, which is currently selected.

---

### selectedMic

- type: `AudioDeviceInfo`
- It will be the object of the microphone device, which is currently selected.

---

### localParticipant

- type: [Participant](../participant-class/introduction)

- It will be the instance of [Participant](../participant-class/introduction) class for the local participant(You) who joined the room.

---

### participants

- type: [`Map`](https://api.dart.dev/stable/2.15.1/dart-core/Map-class.html) of [`String`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html) and [Participant](../participant-class/introduction)

- `Map<String, Participant>`

  - Map{'<'}`participantId`, [Participant](../participant-class/introduction)>

- It will contain all joined participants in the room except the `localParticipant`.

- This will be the [`Map`](https://api.dart.dev/stable/2.15.1/dart-core/Map-class.html) what will container all participants attached with the key as id of that participant.

```javascript
String remoteParticipantId = "ajf897";

Participant? remoteParticipant = room.participants[remoteParticipantId];
```

---

### pinnedParticipants

- type: [`Map`](https://api.dart.dev/stable/2.15.1/dart-core/Map-class.html) of [`String`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html) and `ParticipantPinState`

- `Map<String, ParticipantPinState>`

  - Map{'<'}`participantId`, `ParticipantPinState`>

- It will contain all participants who are pinned in the room.

- This will be the [`Map`](https://api.dart.dev/stable/2.15.1/dart-core/Map-class.html) which will contain all participant who are currently pinned's pin state attached with the key as id of that

---

### hlsState

- type: String

- It will return the state of HLS for the room.

---

### liveStreamState

- type: String

- It will return the state of Live stream for the room.

---

### recordingState

- type: String

- It will return the state of Recording for the room.

---

### hlsDownstreamUrl

- type: String?

- It will return the downstream URL for the ongoing HLS of the room if any.

---

### pubSub

- type: [`PubSub`](../pubsub-class/introduction)
- It is used to enable Publisher-Subscriber feature in [`room`](introduction) class.

Learn more about `PubSub`, [here](../pubsub-class/introduction)

---

### selectedSpeakerId

- type: [`String?`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)
- It will be the `id` of the speaker, which is currently selected.

---

### selectedSpeaker

- type: `AudioDeviceInfo`
- It will be the object of the speaker device, which is currently selected.

---

</div>


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Room Class Example - Flutter

```js title="Play with room instance"
// Join the room
room?.join();

// Get local participants
room?.localParticipant;

// Get remote participants
room?.participants;

// Adding event listner
room.on(Events.participantJoined, (Participant participant) {
  print("new participant => $participant");
  },
);
```


---

# Setup - Flutter

Flutter SDK is client for real-time communication for android and ios devices. It inherits the same terminology as all other SDKs does.

## Minimum OS/SDK versions

Android: minSdkVersion >= 23



## Use this package as a library

### Step 1: Add this package in your flutter project

Run this command:

```js
flutter pub add videosdk
```

This will add a line like this to your package's pubspec.yaml (and run an implicit flutter pub get):

```js
dependencies:
  videosdk: ^1.0.0
```

Alternatively, your editor might support or flutter pub get. Check the docs for your editor to learn more.

### Step 2: Import it

Now in your Dart code, you can use:

```js
import "package:videosdk/videosdk.dart";
```


---

# Stream Class Events - Flutter

<div class="sdk-api-ref-only-h4">

---


### streamStateChanged

- `streamStateChanged` is a event which is triggered when the state of a video or screen-share video stream of the remote participant changes. It helps track whether the stream is active, stuck, frozen, resolved, or ended.

:::note
This event is emitted exclusively for remote participants, specifically for their video and screen share video streams.
:::

#### Parameters

- **`state`**: Specifies the current state of the stream.

  - **Type**: `String`
  - **Possible values**:
    - `"active"`: Stream is working normally.
    - `"stuck"`: Stream is not progressing as expected.
    - `"freeze-detected"`: Video freeze has been detected.
    - `"freeze-resolved"`: Video freeze has been resolved.
    - `"ended"`: Stream has ended.

- **`timestamp`**: The time (in milliseconds since epoch) when the state change occurred.
  - **Type**: `int`

#### Example

```js
import 'package:videosdk/videosdk.dart';
Stream videoStream; 
videoStream.on(Events.streamStateChanged, (state, timestamp){
    print("Stream State changed to state: $state at time:$timestanp");
});
```
---

</div>


---

# Video SDK Stream Class - Flutter

<div class="sdk-api-ref">

## Introduction

Stream class is responsible for handling audio, video and screen sharing streams.

Stream class defines instance of audio, video and shared screen stream of participants.

## Stream Properties

<div class="row">
<div class="col col--4 margin-bottom--sm" >

- [id](properties#id)

</div><div class="col col--4 margin-bottom--sm" >

- [kind](properties#kind)

</div><div class="col col--4 margin-bottom--sm" >

- [track](properties#track)

</div><div class="col col--4 margin-bottom--sm" >

- [renderer](properties#renderer)

</div>
</div>

## Stream Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [resume()](./methods#resume)

</div>
<div class="col col--4 margin-bottom--sm" >

- [pause()](./methods#pause)

</div>

</div>

## Stream Events

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [streamStateChanged](./events#streamstatechanged)

</div>

</div>

</div>


---

# Stream Class Methods - Flutter

<div class="sdk-api-ref-only-h4">

### resume()

- By using `resume()`, a participant can resume the stream of Remote Participant.

#### Returns

- `void`

---

### pause()

- By using `pause()`, a participant can pause the stream of Remote Participant.

#### Returns

- `void`

</div>


---

# Stream Class Properties - Flutter

<div class="sdk-api-ref-only-h4">

### id

- type: `String`

- Represents the id for that stream .

---

### kind

- type: `String?`

- `kind` represents the type of stream which could be `audio` | `video` or `share` .

---

### renderer

- type: `RTCVideoRenderer?`

- This is a renderer, which is passed to RTCVideoView widget.

---

### track

- type: `Consumer`

- It represents a single media track within a stream.

- You can call `pause()` method to pause MediaStreamTrack. And you can also call `resume()` method to resume MediaStreamTrack. [Learn more](../../../guide/video-and-audio-calling-api-sdk/features/pause-resume-video-stream)

</div>


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Stream Class - Flutter

## using Stream Class

The `Stream Class` includes methods and events video & audio streams.




### Properties


      
      
      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>

### Methods


      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>

## Example

```js title="Play with Stream instance"
// pause stream
stream?.pause();

// resume stream
stream?.resume();
```


---

<h1> {props.title} </h1>{" "}

When integrating VideoSDK, you will come across with multiple terms like meeting, room, session and many more.

Let's discuss each term in detail so while integrating VideoSDK you don't get confused.

### Meeting / Room

- A Meeting or Room is a VideoSDK object which represents a real-time audio, video, and/or screen-share session, and is the basic building block for media sharing among participants which is returned by the VideoSDK once a successful connection is established.
- Meeting or Room can be uniquely identified by `meetingId` or `roomId`.

:::note
Meeting and Room are both the same. Similarly `meetingId` and `roomId` are same.
:::

### Session

- A Session is the instance of an ongoing meeting/room which has one or more participants in it. A single room or meeting can have multiple sessions.
- Each session can be uniquely identified by `sessionId`.
- All the sessions are associated with `meetingId`/`roomId` and can be listed using it.

### Participant

- Participant is a VideoSDK object which represents each user/client in the meeting or room and can share audio/video media with other.
- There can be multiple participants in a meeting/room and each participant can be uniquely identified by `participantId`.

### MediaStream

- MediaStream is the collection of audio and video tracks which holds the segments of audio/video media that are send and received by all the participants in the meeting.

### RTMP Live Stream

- RTMP live streaming is used to live stream your video conferencing apps to platforms like YouTube, Twitch, Facebook, etc. by providing the platform specific `streamKey` and `streamUrl`.

### Interactive Live streaming (HLS)

- Interactive live streaming is used to live stream your video conferencing apps within your own platform to allow a larger number of viewers who can not be accomodated in a real-time conference.



---

# VideoSDK Class Events - Flutter

<div class="sdk-api-ref-only-h4">



### deviceChanged

- `deviceChanged` event is emitted whenever any media devices, such as a camera, microphone or speaker is connected to or removed from the device.

:::info

- The `deviceChanged` event is not supported in macOS applications.

:::

#### Example

```js
VideoSDK.on(Events.deviceChanged, (devices) {
  print("device changed ${devices}");
});
```

:::info
Ensure that media permissions are granted on the device; otherwise, this event will not return the list of devices.
:::

---

### error

- This event will be emitted when and error occurs in the VideoSDK methods.

#### Example

```javascript
VideoSDK.on(Events.error, (error) {
  log("VIDEOSDK ERROR :: " +
      error['code'].toString() +
      "  :: " +
      error['name'].toString() +
      " :: " +
      error['message'].toString());
});
```


</div>


---

# VideoSDK Class - Flutter

<div div id="tailwind" class="sdk-api-ref">

## Introduction

VideoSDK Class is a core class of SDK that provides methods to create and configure [`VideoSDK Room`](../room-class/introduction).




## VideoSDK Class Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [createRoom](./methods#createroom)

</div>



<div class="col col--4 margin-bottom--sm" >

- [getDevices](./methods#getdevices)

</div>

<div class="col col--4 margin-bottom--sm" >

- [getVideoDevices](./methods#getvideodevices)

</div>

<div class="col col--4 margin-bottom--sm" >

- [getAudioDevices](./methods#getaudiodevices)

</div>

<div class="col col--4 margin-bottom--sm" >

- [checkPermissions](./methods#checkpermissions)

</div>

<div class="col col--4 margin-bottom--sm" >

- [requestPermissions](./methods#requestpermissions)

</div>

<div class="col col--4 margin-bottom--sm" >

- [checkBluetoothPermission](./methods#checkbluetoothpermission)

</div>

<div class="col col--4 margin-bottom--sm" >

- [requestBluetoothPermission](./methods#requestbluetoothpermission)

</div>

<div class="col col--4 margin-bottom--sm" >

- [on](./methods#on)

</div>

<div class="col col--4 margin-bottom--sm" >

- [createCameraVideoTrack](./methods#createcameravideotrack)

</div>

<div class="col col--4 margin-bottom--sm" >

- [createMicrophoneAudioTrack](./methods#createmicrophoneaudiotrack)

</div>

<div class="col col--4 margin-bottom--sm" >

- [applyVideoProcessor](./methods#applyvideoprocessor)

</div>

<div class="col col--4 margin-bottom--sm" >

- [removeVideoProcessor](./methods#removevideoprocessor)

</div>

</div>

## VideoSDK Class Events

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [deviceChanged](./events#devicechanged)

</div>

<div class="col col--4 margin-bottom--sm" >

- [error](./events#error)

</div>

</div>

## VideoSDK Native Android Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [getInstance](./native-android-methods.md#getinstance)

</div>

<div class="col col--4 margin-bottom--sm" >

- [registerVideoProcessor](./native-android-methods.md#registervideoprocessor)

</div>

</div>

## VideoSDK Native iOS Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [getInstance](./native-ios-methods.md#getinstance)

</div>

<div class="col col--4 margin-bottom--sm" >

- [registerVideoProcessor](./native-ios-methods.md#registervideoprocessor)

</div>

</div>

</div>


---

# VideoSDK Class Methods - Flutter

<div class="sdk-api-ref-only-h4">

### createRoom()

- This method is provided by SDK to build instance of [`VideoSDK Room`](../room-class/introduction) based on given configuration.

#### Parameters

- roomId

  - type: [`String`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)
  - `REQUIRED`
  - Id of the Room to be created.

- token

  - type: [`String`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)
  - `REQUIRED`
  - Sets AuthToken, which is used for authentication purposes.

- displayName

  - type: [`String`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)
  - `REQUIRED`
  - Sets name of the LocalParticipant to be displayed.

- notification

  - type: [`NotificationInfo`]
  - `OPTIONAL`
  - Sets configuration for the notification, that will be shown, while screen-sharing.

- micEnabled

  - type: [`bool`](https://api.dart.dev/stable/2.15.1/dart-core/bool-class.html)
  - `OPTIONAL`
  - Whether `mic` of the participant will be `on`, while joining the room. If it is set to `false`, then mic of that participant will be `disabled` by default, but can be `enabled` or `disabled` later.
  - Default value of `micEnabled` is true.

- camEnabled

  - type: [`bool`](https://api.dart.dev/stable/2.15.1/dart-core/bool-class.html)
  - `OPTIONAL`
  - Whether `camera` of the participant will be `on`, while joining the room. If it is set to `false`, then camera of that participant will be `disabled` by default, but can be `enabled` or `disabled`
  - Default value of `camEnabled` is true.

- multiStream

  - type: [`bool`](https://api.dart.dev/stable/2.15.1/dart-core/bool-class.html)
  - `OPTIONAL`
  - Default value is `true`.
  - It will specify if the stream should send multiple resolution layers or single resolution.

- participantId

  - type: [`String`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)
  - `OPTIONAL`
  - Unique Id of the participant. If not passed then SDK will create an Id by itself and will use that id.

- maxResolution

  - type: [`String`](https://api.dart.dev/stable/2.15.1/dart-core/String-class.html)
  - `OPTIONAL`
  - Sets the maximum upload resolution of that participant's camera video stream.

- defaultCameraIndex

  - type: [`int`](https://api.dart.dev/stable/2.15.1/dart-core/int-class.html)
  - `OPTIONAL`
  - Sets camera, which will be used by default, while joining the VideoSDK Room.
  - Default value of `defaultCameraIndex` is `0`.

- customCameraVideoTrack

  - type: `CustomTrack`
  - `OPTIONAL`
  - Set the initial custom video track using different encoding parameters, camera facing mode, and optimization mode.

- customMicrophoneAudioTrack

  - type: `CustomTrack`
  - `OPTIONAL`
  - Set the initial custom audio track using different encoding parameters and optimization mode.

- mode

  - type: `Mode`
  - `OPTIONAL`
  - Set the participant mode i.e. `SEND_AND_RECV` or `SIGNALLING_ONLY`.
  - Default value is `SEND_AND_RECV`.

- metaData

  - type: `Map<String,dynamic>`
  - `OPTIONAL`
  - If you want to provide additional details about a user joining a meeting, such as their profile image, you can pass that information in this parameter.

- debugMode

  - type: `Boolean`
  - `OPTIONAL`
  - If you want to enable users to view detailed error logs generated by our SDK directly on the VideoSDK's dashboard, set this parameter to true. 

---

#### Returns

- _[`Room`](../room-class/introduction)_

#### Example

```js

CustomTrack? videoTrack = await VideoSDK.createCameraVideoTrack(
  encoderConfig: CustomVideoTrackConfig.h1440p_w1920p,
  multiStream: false,
);

//Creating Custom Audio Track
CustomTrack? audioTrack = await VideoSDK.createMicrophoneAudioTrack(
    encoderConfig: CustomAudioTrackConfig.high_quality);

// Create VideoSDK Room
Room room = VideoSDK.createRoom(
  roomId: "<ROOM-ID>",
  token: "<TOKEN>",
  displayName: "<DISPLAY-NAME>",
  micEnabled: false,
  camEnabled: false,
  maxResolution: 'hd',
  multiStream: false,
  defaultCameraIndex: 1, // Front Camera
  customCameraVideoTrack: videoTrack, // custom video track :: optional
  customMicrophoneAudioTrack: audioTrack, // custom audio track :: optional
  notification: const NotificationInfo(
    title: "Video SDK",
    message: "Video SDK is sharing screen in the room",
    icon: "notification_share",
  ),
  metaData: {},
  debugMode: true
);
```

---



### getDevices()

- The `getDevices()` method returns a list of the currently available media input and output devices, such as microphones, cameras, headsets, and so forth. The method returns a list of `DeviceInfo` objects describing the devices.

- `DeviceInfo` class has four properties :

  1. `DeviceInfo.deviceId`

     - Returns a string that is an identifier for the represented device, persisted across sessions.

  2. `DeviceInfo.kind`

     - Returns an enumerated value that is either `videoinput` , `audiooutput` or `audioinput`.

  3. `DeviceInfo.label`

     - Returns a string describing this device (for example `BLUETOOTH`).

  4. `DeviceInfo.groupId`

     - Returns a string describing this group in which the device belongs (Two devices have the same groupId if they belong to the same physical device; for example, a monitor with both a built-in camera and microphone).

:::note

For iOS devices:

- `EARPIECE` is not supported whenever `WIRED_HEADSET` or `BLUETOOTH` device is connected.
- `WIRED_HEADSET` and `BLUETOOTH` devices are not supported simultaneously. Priority is given to the most recently connected device.

:::

#### Returns

- `Future<List<DeviceInfo>?>`

#### Example

```js
import 'package:videosdk/videosdk.dart';

void getDeviceList() async {
  try {
    List<DeviceInfo>? devices = await VideoSDK.getDevices();
  } catch (ex) {
    print("Error in getDevices ");
  }
}
```

---

### getVideoDevices()

- The `getVideoDevices` method returns a list of currently available video devices. The method returns a list of `VideoDeviceInfo` objects describing the video devices.

- `VideoDeviceInfo` class has four properties :

  1. `VideoDeviceInfo.deviceId`

     - Returns a string that is an identifier for the represented device, persisted across sessions.

  2. `VideoDeviceInfo.kind`

     - Returns an enumerated value that is `videoinput`.

  3. `VideoDeviceInfo.label`

     - Returns a string describing this device (for example `BLUETOOTH`).

  4. `VideoDeviceInfo.groupId`

     - Returns a string describing this group in which the device belongs (Two devices have the same groupId if they belong to the same physical device; for example, a monitor with both a built-in camera and microphone).

#### Returns

- `Future<List<VideoDeviceInfo>?>`

#### Example

```js
import 'package:videosdk/videosdk.dart';

void getVideoDeviceList() async {
  try {
    List<VideoDeviceInfo>? videoDevices = await VideoSDK.getVideoDevices();
  } catch (ex) {
    print("Error in getVideoDevices");
  }
}
```

---

### getAudioDevices()

- The `getAudioDevices` method returns a list of currently available audio devices. The method returns a list of `AudioDeviceInfo` objects describing the audio devices.

- `AudioDeviceInfo` class has four properties :

  1. `AudioDeviceInfo.deviceId`

     - Returns a string that is an identifier for the represented device, persisted across sessions.

  2. `AudioDeviceInfo.kind`

     - Returns an enumerated value that is `audioinput` or `audiooutput`.

  3. `AudioDeviceInfo.label`

     - Returns a string describing this device (for example `BLUETOOTH`).

  4. `AudioDeviceInfo.groupId`

     - Returns a string describing this group in which the device belongs (Two devices have the same groupId if they belong to the same physical device; for example, a monitor with both a built-in camera and microphone).

:::note

For iOS devices:

- `EARPIECE` is not supported whenever `WIRED_HEADSET` or `BLUETOOTH` device is connected.
- `WIRED_HEADSET` and `BLUETOOTH` devices are not supported simultaneously. Priority is given to the most recently connected device.

:::

#### Returns

- `Future<List<AudioDeviceInfo>?>`

#### Example

```js
import 'package:videosdk/videosdk.dart';
import 'dart:io';

List<AudioDeviceInfo> audioInputDevices = [];
List<AudioDeviceInfo> audioOutputDevices = [];

void getAudioDeviceList() async {
  try {
    // This function returns only `audiooutput` devices when executed on mobile platforms.
    List<AudioDeviceInfo>? audioDevices = await VideoSDK.getAudioDevices();
    for (AudioDeviceInfo device in audioDevices!) {
      // For Mobile Applications
      // Note: Changing the audioDevice using `switchAudioDevice()` will affect both the microphone and the speaker.
      if (!kIsWeb) {
        if (Platform.isAndroid || Platform.isIOS) {
          audioOutputDevices.add(device);
        }
      } else {
        // For Web and Desktop Applications
        // The input and output devices must be filtered separately to switch the respective device.
          if (device.kind == 'audioinput') {
            audioInputDevices.add(device);
          } else {
            audioOutputDevices.add(device);
          }
        }
      }
    }
  catch (ex) {
    print("Error in getAudioDevices ");
  }
}
```

---

### requestPermissions()

- The `requestPermissions()` method prompts the user for permission to access camera and microphone devices. It returns a `Map<String, bool>` object, where the keys in the map can be `'audio'` for the microphone and `'video'` for the camera.
- To enable requesting of microphone and camera permissions on iOS devices, add the following to your `Podfile`:

```js
post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
    //Add this into your podfile
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
        'PERMISSION_CAMERA=1',
        'PERMISSION_MICROPHONE=1',
      ]
    end
  end
end
```

#### Parameters

- `Permissions`
  - A `Permissions` specifying the specific kinds of media, that you want to request.
  - `Optional`
  - Allowed Values : `audio` ,`video`,`audio_video`
  - Default : `audio_video`

#### Returns

- `Future<Map<String, bool>>`

:::info

- `requestPermissions()` method is not supported on Desktop Applications and Firefox Browser.

:::

#### Example

```js
import 'package:videosdk/videosdk.dart';

void requestMediaPermissions() async {
  try {
      //By default both audio and video permissions will be requested.
      Map<String, bool> reqPermissions = await VideoSDK.requestPermissions();
      //For requesting just audio permission.
      Map<String, bool> reqAudioPermissions = await VideoSDK.requestPermissions(Permissions.audio);
      //For requesting just video permission.
      Map<String, bool> reqVideoPermissions = await VideoSDK.requestPermissions(Permissions.video);
      //For requesting both audio and video permissions.
      Map<String, bool> reqAudioVideoPermissions = await VideoSDK.requestPermissions(Permissions.audio_video);

      print("Request Permissions ${reqAudioVideoPermissions['audio']} ${reqAudioVideoPermissions['video']} ");
  } catch (ex) {
    print("Error in requestPermission ");
  }
}
```

:::tip
`requestPermissions()` will throw an UnsupportedError when the Platform doesn't support permission request functionality.
:::

---

### checkPermissions()

- The `checkPermission()` method checks for permission to access camera and microphone devices. It returns a `Map<String, bool>` object, where the keys in the map can be `'audio'` for the microphone and `'video'` for the camera.
- To enable checking of microphone and camera permissions on iOS devices, add the following to your `Podfile`:

```js
post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
    //Add this into your podfile
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
        'PERMISSION_CAMERA=1',
        'PERMISSION_MICROPHONE=1',
      ]
    end
  end
end
```

#### Parameters

- `Permissions`
  - A `Permissions` specifying the types of media to check.
  - `Optional`
  - Allowed Values : `audio` ,`video`,`audio_video`
  - Default : `audio_video`

#### Returns

- `Future<Map<String, bool>>`

:::info

- `checkPermissions()` method is not supported on Desktop Applications and Firefox Browser.

:::

#### Example

```js
import 'package:videosdk/videosdk.dart';

void checkMediaPermissions() async {
  try {
      //By default both audio and video permissions will be checked.
      Map<String, bool> checkPermissions = await VideoSDK.checkPermissions();
      //For checking just audio permission.
      Map<String, bool> checkAudioPermissions = await VideoSDK.checkPermissions(Permissions.audio);
      //For checking just video permission.
      Map<String, bool> checkVideoPermissions = await VideoSDK.checkPermissions(Permissions.video);
      //For checking both audio and video permissions.
      Map<String, bool> checkAudioVideoPermissions = await VideoSDK.checkPermissions(Permissions.audio_video);

      print("Check Permissions ${checkAudioVideoPermissions['audio']} ${checkAudioVideoPermissions['video']} ");
  } catch (ex) {
    print("Error in checkPermission ");
  }
}
```

:::tip
`checkPermissions()` will throw an UnsupportedError when the Platform doesn't support permission check functionality.
:::

---

### checkBluetoothPermission()

- The `checkBluetoothPermission` method checks if the application has permission to access Bluetooth on the device. It returns a boolean value indicating whether Bluetooth permission is granted or not.

#### Returns

- `Future<bool>`

:::info

- `checkBluetoothPermission()` method is only supported on Android devices running Android 12 or later.
  :::

#### Example

```js
import 'package:videosdk/videosdk.dart';

void checkBluetooth() async {
  try {
      bool bluetoothPerm = await VideoSDK.checkBluetoothPermission();
  } catch (ex) {
    print("Error in checkBluetoothPermission ");
  }
}
```

:::tip
`checkBluetoothPermission()` will throw an UnsupportedError when the Platform doesn't support bluetooth permission check functionality.
:::

---

### requestBluetoothPermission()

- The `requestBluetoothPermission()` method requests permission to access Bluetooth on the device. It returns a boolean value indicating whether the permission request was successful or not.

#### Returns

- `Future<bool>`

:::info

- `requestBluetoothPermission()` method is only supported on Android devices running Android 12 or later.

:::

#### Example

```js
import 'package:videosdk/videosdk.dart';

void requestBluetooth() async {
  try {
      bool bluetoothPerm = await VideoSDK.requestBluetoothPermission();
  } catch (ex) {
    print("Error in requestBluetoothPermission ");
  }
}
```

:::tip
`requestBluetoothPermission()` will throw an UnsupportedError when the Platform doesn't support bluetooth permission request functionality.
:::

---

### on()

- It is used to listen to `VideoSDK` related events and perform actions based on those events.

#### Parameters

- event

  - type: [`Events`](events)
  - This will specify the event to be listened. It defines which particular event from the VideoSDK class you are subscribing to.

- eventHandler
  - type: [`Function`](https://api.dart.dev/stable/2.15.1/dart-core/Function-class.html)
  - This will be invoked whenever the specified event occurs. The function is executed with relevant data whenever the event is triggered.

#### Returns

- _`void`_

#### Example

```js
VideoSDK.on(Events.deviceChanged, () {
  // do something
});
```

---

### createCameraVideoTrack

- You can create a Video Track using `createCameraVideoTrack()` method of `VideoSDK` class.
- This method can be used to create video track using different encoding parameters, camera facing mode, and optimization mode.

#### Parameters

- **cameraId**:

  - type: `String`
  - required: `false`
  - It will be the id of the camera from which the video should be captured.

- **encoderConfig**:

  - type: `CustomVideoTrackConfig`
  - required: `false`
  - default: `h360p_w640p`
  - Allowed values : `h90p_w160p` | `h180p_w320p` | `h216p_w384p` | `h360p_w640p` | `h540p_w960p` | `h720p_w1280p` | `h1080p_w1920p` | `h1440p_w2560p` | `h2160p_w3840p` | `h120p_w160p` | `h180p_w240p` | `h240p_w320p` | `h360p_w480p` | `h480p_w640p` | `h540p_w720p` | `h720p_w960p` | `h1080p_w1440p` | `h1440p_w1920p`
  - It will be the encoderConfigs you can want to use for the Video Track.

:::note

Above mentioned encoder configurations are valid for both, landscape as well as portrait mode.

:::

- **facingMode**:

  - type: `FacingMode`
  - required: `false`
  - Allowed values : `FacingMode.front` | `FacingMode.environment`
  - It will specify whether to use front or back camera for the video track.

- **multiStream**

  - type: `boolean`
  - required: `false`
  - default: true
  - It will specify if the stream should send multiple resolution layers or single resolution layer.

  :::info

  - For meetings with fewer than or equal to four participants, setting `multiStream:false` is regarded as best practice.
  - This parameter is only available from `v1.0.9`.

  :::

#### Returns

- `Future<CustomTrack?>`

#### Example

```javascript
CustomTrack? videoTrack = await VideoSDK.createCameraVideoTrack(
      encoderConfig: CustomVideoTrackConfig.h1440p_w1920p,
      multiStream: false,
      facingMode:"user",
    );
```

---

### createMicrophoneAudioTrack

- You can create a Audio Track using `createMicrophoneAudioTrack()` method of `VideoSDK` class.
- This method can be used to create audio track using different encoding parameters and noise cancellation configuration.

#### Parameters

- **microphoneId**:

  - type: `String`
  - required: `false`
  - It will be the id of the mic from which the audio should be captured.

- **encoderConfig**:

  - type: `CustomTrackAudioConfig`
  - required: `false`
  - default: `speech_standard`
  - Allowed values : `speech_low_quality` | `speech_standard` | `music_standard` | `standard_stereo` | `high_quality` | `high_quality_stereo`
  - It will be the encoder configuration you want to use for Audio Track.

- **noiseConfig**

  - **echoCancellation**

    - type: `boolean`
    - required: `false`
    - If `true` echo cancellation will turned on else it would be turned off.

  - **autoGainControl**

    - type: `boolean`
    - required: `false`
    - If `true` auto gain will turned on else it would be turned off.

  - **noiseSuppression**
    - type: `boolean`
    - required: `false`
    - If `true` noise suppression will turned on else it would be turned off.

#### Returns

- `Future<CustomTrack?>`

#### Example

```javascript
CustomTrack? audioTrack = await VideoSDK.createMicrophoneAudioTrack(
        encoderConfig: CustomAudioTrackConfig.high_quality);
```

### applyVideoProcessor

- This method enables the application of a video processor to incorporate effects into the video stream. It takes the name of a processor that was registered during initialization. 

:::info 

Only processors that have been registered during app initialization are available for use during the meeting. To learn how to register your own cutom video processor, check out this guide, for [Android](../../../guide/video-and-audio-calling-api-sdk/video-processor/android-setup.md) and  for [iOS](../../../guide/video-and-audio-calling-api-sdk/video-processor/ios-setup.md)

:::

#### Parameters

- **videoProcessorName**:

  - type: `String`
  - required: `true`
  - The name of the processor whose effect you wish to apply.
  
#### Returns

- `void`

#### Example

```javascript
VideoSDK.applyVideoProcessor(videoProcessorName: "VirtualBGProcessor");
```

### removeVideoProcessor

- This method removes a previously applied video processor from the video stream. This allows users to disable specific effects or revert to the original video state.
- The `removeVideoProcessor` method will remove the effect of the currently active video processor.
  
#### Returns

- `void`

#### Example

```javascript
VideoSDK.removeVideoProcessor();
```

</div>


---

# VideoSDK Class Native Android Methods - Flutter

<div class="sdk-api-ref-only-h4">

### getInstance()

- This method is used to get an instance of the `VideoSDK` class.


#### Returns

- `VideoSDK` instance

#### Example

**Kotlin:**

```js "
val videoSDK = VideoSDK.getInstance()
```

---

**Java:**

```js "
VideoSDK videoSDK = VideoSDK.getInstance();
```

---

### registerVideoProcessor()

- This method is used to register your custom video processor during app initialization. It takes a string representing the unique processor name along with an instance of your processor to complete the registration. 

#### Parameters

- customVideoProcessorName

  - type: `String`
  - required: `true`
  - The name of the processor whose effect you wish to apply.

- customVideoProcessorInstance

  - required: `true`
  - The instance of the processor whose effect you wish to apply.


#### Returns

- `void`

#### Example



**Kotlin:**

```js
val customVideoProcessor = CustomVideoProcessor()
val videoSDK = VideoSDK.getInstance()
videoSDK.registerVideoProcessor("customVideoProcessorName", customVideoProcessor)
```

---

**Java:**

```js 
CustomVideoProcessor customVideoProcessor = new CustomVideoProcessor();
VideoSDK videoSDK = VideoSDK.getInstance();
videoSDK.registerVideoProcessor("customVideoProcessorName", customVideoProcessor);
```

</div>


---

# VideoSDK Class Native iOS Methods - Flutter

<div class="sdk-api-ref-only-h4">

### getInstance()

- This method is used to get an instance of the `VideoSDK` class.


#### Returns

- `VideoSDK` instance

#### Example

**Swift:**

```js "
let videoSDK = VideoSDK.getInstance
```

---

### registerVideoProcessor()

- This method is used to register your custom video processor during app initialization. It takes a string representing the unique processor name along with an instance of your processor to complete the registration. 

#### Parameters

- videoProcessorName

  - type: `String`
  - required: `true`
  - The name of the processor whose effect you wish to apply.

- videoProcessor

  - required: `true`
  - The instance of the processor whose effect you wish to apply.


#### Returns

- `void`

#### Example



**Swift:**

```js title="AppDelegate.swift"
let customVideoProcessor = CustomVideoProcessor()
let videoSDK = VideoSDK.getInstance
videoSDK.registerVideoProcessor(videoProcessorName: "customVideoProcessorName", videoProcessor: customVideoProcessor)
```

</div>


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# VideoSDK Class Properties - Flutter

<div class="sdk-api-ref-only-h4">

### mediaDevices

- type: [`Map<MediaDeviceType, List<MediaDeviceInfo>>`](https://api.dart.dev/stable/2.15.1/dart-core/Map-class.html)

- It contains all the connected media devices i.e. Video Devices, Audio Devices.

- This will be the [`Map`](https://api.dart.dev/stable/2.15.1/dart-core/Map-class.html) of `MediaDeviceType` and [`List<MediaDeviceInfo>`](https://api.flutter.dev/flutter/dart-html/MediaDeviceInfo-class.html).

```javascript
// Audio Devices
List<MediaDeviceInfo> audioDevices = VideoSDK.mediaDevices[MediaDeviceType.audioInput];

// Video Devices
List<MediaDeviceInfo> videoDevices = VideoSDK.mediaDevices[MediaDeviceType.videoInput];
```

---

</div>


---

# VideoSDKMediaEffects Plugin - Flutter

<div id="tailwind" class="sdk-api-ref">

## Introduction

The `VideoSDKMediaEffects` plugin enhances video applications with advanced media effects, including virtual backgrounds. Seamlessly integrating with your video SDK, it supports real-time processing and is optimized for Android and iOS devices, making it essential for adding professional-grade effects to mobile apps.

:::info

- The Virtual Background methods from the `VideoSDKMediaEffects` plugin are supported only on Android and iOS devices.
- The Virtual Background feature in VideoSDK can be utilized regardless of the meeting environment, including the pre-call screen.

:::

## VideoSDKMediaEffects Plugin Methods

<div class="sdk-api-ref-only-h4">

### applyVirtualBackground()

- This method allows users to dynamically apply virtual background to their video stream during a live session.

#### Parameters

- backgroundSource

  - type: [`Uri`](https://api.dart.dev/stable/3.4.4/dart-core/Uri-class.html)
  - `REQUIRED`
  - It specifies the URI of the background image to be used for the virtual background effect.

#### Returns

- _`void`_

#### Example

```js
Uri backgroundImageURI = Uri.parse("https://cdn.videosdk.live/virtual-background/cloud.jpeg");
VideosdkMediaEffects.applyVirtualBackground(backgroundSource: backgroundImageURI);
```
---

### changeVirtualBackground()

- This method allows users to easily switch their virtual background to a new image, enabling dynamic customization and enhancing the video experience.

#### Parameters

- backgroundSource

  - type: [`Uri`](https://api.dart.dev/stable/3.4.4/dart-core/Uri-class.html)
  - `REQUIRED`
  - It specifies the URI of the new background image that user wants to switch to, for virtual background effect.

#### Returns

- _`void`_

#### Example

```js
Uri newBackgroundImageURI = Uri.parse("https://cdn.videosdk.live/virtual-background/san-fran.jpeg");
VideosdkMediaEffects.changeVirtualBackground(backgroundSource: newBackgroundImageURI);
```
---

### removeVirtualBackground()

- This method provides users with a convenient way to revert their video background to its original state, removing any previously applied virtual background.

#### Returns

- _`void`_

#### Example

```js
VideosdkMediaEffects.removeVirtualBackground();
```


</div>
</div>


---

# App Size Optimization - Flutter

This guide is designed to help developers optimize app size, enhancing performance and efficiency across different devices. By following these best practices, you can reduce load times, minimize storage requirements, and deliver a more seamless experience to users, all while preserving essential functionality.

## Deliver Leaner Apps with App Bundles

Using Android App Bundles (AAB) is an effective way to optimize the size of your application, making it lighter and more efficient for users to download and install. App Bundles allow Google Play to dynamically generate APKs tailored to each device, so users only download the resources and code relevant to their specific configuration. This approach reduces app size significantly, leading to faster installs and conserving storage space on users’ devices.

Recommended Practices:

- `Enable App Bundles`: Configure your build to use the App Bundle format instead of APKs. This will allow Google Play to optimize your app for each device type automatically.

- `Organize Resources by Device Type`: Ensure that resources (like images and layouts) are organized by device type (such as screen density or language) to maximize the benefits of App Bundles.

- `Test Modularization`: If your app contains large, optional features, use dynamic feature modules to let users download them on demand. This reduces the initial download size and provides features only as needed.

- `Monitor Size Reductions`: Regularly analyze your app size to see where the most savings occur, and make sure that App Bundle optimizations are effectively reducing your app size across different device configurations.

## Optimize Libraries for a Leaner App Experience

Managing dependencies carefully is essential for minimizing app size and improving performance. Every library or dependency included in your app adds to its overall size, so it’s crucial to only incorporate what’s necessary. Optimizing dependencies helps streamline your app, reduce load times, and enhance maintainability.

Recommended Practices:

- `Use Only Essential Libraries`: Review all libraries and dependencies, removing any that are not critical to your app’s functionality. This helps avoid unnecessary bloat.

- `Leverage Lightweight Alternatives`: Whenever possible, choose lightweight libraries or modularized versions of larger ones. For example, opt for a specific feature module rather than including an entire library.

- `Monitor Library Updates`: Regularly update your dependencies to take advantage of any optimizations or size reductions made by the library maintainers. Newer versions are often more efficient.

- `Minimize Native Libraries`: If your app uses native libraries, ensure they’re essential and compatible across platforms, as they can significantly increase app size.

- `Analyze Dependency Tree`: Use tools like Gradle’s dependency analyzer to identify unnecessary or redundant dependencies, ensuring your app’s dependency tree is as lean as possible.


## Optimize with ProGuard

ProGuard is a powerful tool for shrinking, optimizing, and obfuscating your code, which can significantly reduce your app's size and improve performance. By removing unused code and reducing the size of classes, fields, and methods, ProGuard helps to minimize the footprint of your app without sacrificing functionality. Additionally, ProGuard’s obfuscation feature enhances security by making reverse engineering more difficult. You can refer to the official [documentation](https://developer.android.com/build/shrink-code) for more information.

Recommended Practices:

- `Enable ProGuard`: To enable ProGuard in your project, ensure that your `proguard-rules.pro` file is properly configured, and add the following lines to your `build.gradle` file:

```js title="build.gradle"
buildTypes {
    release {
        minifyEnabled true
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    }
}
```

- `Customize ProGuard Rules`: Carefully review and customize ProGuard rules in the proguard-rules.pro file to avoid stripping essential code. For example, to keep a specific class, add:

```js
-keep class com.example.myapp.MyClass { *; }
```

---

# Developer Experience Guidelines - Flutter

This section provides best practices for creating a smooth and efficient development process when working with VideoSDK. From handling errors gracefully to managing resources and event subscriptions, these guidelines help developers build more reliable and maintainable applications. Following these practices can simplify troubleshooting, prevent common pitfalls, and improve overall application performance.

### Initiate Key Features After Meeting Join Event

To provide a seamless and reliable meeting experience, initiate specific features **only** after the [roomJoined](https://docs.videosdk.live/flutter/api/sdk-reference/room-class/events#roomjoined) event has been triggered.

- **Trigger Key Actions After Joining the Meeting** : Initiating crucial actions after the `roomJoined` event helps avoid errors and optimizes the meeting setup, ensuring a smoother experience for participants. If your application utilizes any of the following features or you want to perform any action as soon as meeting joins, it's recommended to call them only after the meeting has successfully started:

    - `Chat Subscription`: To enable in-meeting chat functionality, subscribe to the chat topic after the `roomJoined` event is triggered. This ensures that messages are reliably received by participants.

    <br/>
    <div style={{textAlign: 'center'}}>

    <img src="https://cdn.videosdk.live/docs/best-practices/mobile/flutter_chat_correct_incorrect_code.png" />

    </div>

    - `Device Management`: If you need users to use specific audio or video devices when the meeting is first joined, you can utilize the custom track. Pass the `cameraId` to the [createCameraVideoTrack()](https://docs.videosdk.live/flutter/api/sdk-reference/custom-tracks#custom-video-track---flutter) method for video, and the `microphoneId` to the [createMicrophoneAudioTrack()](https://docs.videosdk.live/flutter/api/sdk-reference/custom-tracks#custom-audio-track---flutter) method for audio. Once the track is created, provide it to the [createRoom()](https://docs.videosdk.live/flutter/api/sdk-reference/videosdk-class/methods#createroom) method.

    - `Recording and Transcription`: To automatically start recording or transcription as soon as the meeting begins, configure the `autoStartConfig` in the `createMeeting` API. For detailed information, refer to the documentation [here](https://docs.videosdk.live/api-reference/realtime-communication/create-room#autoCloseConfig).

### Dispose Custom Tracks When Necessary

Proper disposal of custom tracks is essential for managing system resources and ensuring a smooth experience. In most scenarios, tracks are automatically disposed of by the SDK, ensuring efficient resource management. However, in specific cases outlined below, you will need to dispose of custom tracks explicitly:

1. **When Enabling/Disabling the Camera on a Precall Screen**:
    - If your application includes a precall screen and you want to ensure that the device's camera is not used when the camera is disabled, you must dispose of the custom video track. Otherwise, the device’s camera will continue to be used even when the camera is off.
    - Additionally, remember to create a new track when the user enables the camera again.
    - If you don’t need to manage the camera's usage on the device level (i.e., you’re okay with the camera being used whether it’s enabled or disabled), you can skip this step.
    - Here's how you can manage customTrack on a precall screen :

    <br/>
    ```js
    class _JoinScreenState extends State<JoinScreen> with WidgetsBindingObserver {
        bool isCameraOn = false;
        CustomTrack? cameraTrack;
        // Renderer to display the camera video feed
        RTCVideoRenderer? cameraRenderer;

        @override
        Widget build(BuildContext context) {
            // Build the UI components for the join screen
            //...
        }

        void toggleCamera() async {
            if (isCameraOn)
            {
                cameraTrack?.dispose(); // Dispose of cameraTrack
                setState(() {
                    cameraRenderer = null;
                    cameraTrack = null;
                    isCameraOn = false;
                });
            }
            else {
                // Create a new camera track and renderer
                CustomTrack? track = await VideoSDK.createCameraVideoTrack(
                    // passes deviceId of the user's selected device
                    cameraId: selectedVideoDevice?.deviceId
                );
                RTCVideoRenderer render = RTCVideoRenderer();
                await render.initialize();
                render.setSrcObject(
                    stream: track?.mediaStream, // Set the media stream from the camera track
                    trackId: track?.mediaStream.getVideoTracks().first.id // Set the video track ID
                );
                setState(() {
                    cameraTrack = track;
                    cameraRenderer = render;
                    isCameraOn = true;
                });
            }
        }
    }
    ```

## Listen for Error Events

Listening to error events enables your application to handle unexpected issues efficiently, providing users with clear feedback and potential solutions. Error codes pinpoint specific problems, whether from configuration settings, account restrictions, permission limitations, or device constraints. Here are recommended solutions based on common error categories:

1. [Errors associated with Organization](../../api/sdk-reference/error-codes#1-errors-associated-with-organization): If you encounter errors related to your organization (e.g., account status or participant limits), reach out to support at support@videosdk.live or reach out to us on [Discord](https://discord.com/invite/Qfm8j4YAUJ) for assistance.

2. [Errors associated with Token](../../api/sdk-reference/error-codes#2-errors-associated-with-token): For errors related to authentication tokens, ensure the token is valid and hasn’t expired, then try the request again.

3. [Errors associated with Meeting and Participant](../../api/sdk-reference/error-codes#3-errors-associated-with-meeting-and-participant): Check that meetingId and participantId are correctly passed and valid. Also, ensure each participant has a unique participantId to avoid duplicate entries.

4. [Errors associated with Add-on Service](../../api/sdk-reference/error-codes#4-errors-associated-with-add-on-service): If you encounter errors with add-on services (such as recording or streaming), try restarting the service after receiving a failure event. For example, if a `START_RECORDING_FAILED` error event occurs, attempt to call the `startRecording()` method again. If you're using webhooks, you can also retry on [recording-failed](https://docs.videosdk.live/api-reference/realtime-communication/user-webhooks#recording-failed) hook.

5. [Errors associated with Media](../../api/sdk-reference/error-codes#5errors-associated-with-media): Inform the user about media access issues, such as microphone or camera permissions. Design the UI to clearly indicate what is preventing the mic or camera from enabling, helping the user understand the problem.

6. [Errors associated with Track](../../api/sdk-reference/error-codes#6errors-associated-with-track): Ensure that the track you’ve created and passed to enable the mic or camera methods meets the required specifications.

7. [Errors associated with Actions](../../api/sdk-reference/error-codes#7errors-associated-with-actions): If you need to perform actions as soon as a meeting joins, only initiate them after receiving the [roomJoined](https://docs.videosdk.live/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmeetingjoined) event, otherwise it will not work well.

- Here's how to listen for the error event:

```js
import 'dart:developer';

import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //Existing configuration
    
    setupVideoSDKEventListener();
    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  void setupVideoSDKEventListener() {
    VideoSDK.on(Events.error, (error) {
      log("VIDEOSDK ERROR :: ${error['code']}  :: ${error['name']} :: ${error['message']}");
    });
  }

  void setupRoomEventListener() {
    room.on(Events.error, (error) {
      log("VIDEOSDK ERROR :: ${error['code']}  :: ${error['name']} :: ${error['message']}");
    });
  }
}
```

---

# Handle Large Rooms - Flutter

Managing large meetings requires specific strategies to ensure performance, stability, and a seamless user experience. This section provides best practices for optimizing VideoSDK applications to handle high participant volumes effectively. By implementing these recommendations, you can reduce lag, maintain video and audio quality, and provide a smooth experience even in large rooms.

## User Interface Optimization

When hosting large meetings, an optimized UI helps manage participant visibility and ensures smooth performance.

Recommended Practices:

- `Limit Visible Participants`: Display only a limited number of participants on screen at any given time, adapting the view based on screen size. Use pagination to allow users to browse or switch between additional participants seamlessly. For example, you could display only users whose video stream is enabled, or you could choose to display all active speakers. This approach helps manage screen space efficiently, ensuring that the most relevant participants are visible without overwhelming the interface.
- `Prioritize Active Speakers`: Ensure all active speakers are displayed on the screen to highlight who is currently talking, helping participants stay engaged and aware of ongoing discussions. To identify which participant is speaking, you can use the [speakerChanged](https://docs.videosdk.live/flutter/api/sdk-reference/room-class/events#speakerchanged) event.

## Optimizing Media Streams 

In large video calls, it’s important to manage media streams effectively to optimize system resources while maintaining a smooth user experience. 

Recommended Practices:

- `Pause Streams for Non-Visible Participants`: To optimize performance, pause the video and/or audio streams of participants who are not currently visible on the screen. This reduces unnecessary resource consumption.
- `Resume Streams When Visible`: Once a participant comes into view, resume their stream to provide an uninterrupted experience as they appear on the screen.

For detailed setup instructions on how to achieve this, check out our in-depth documentation [here](https://docs.videosdk.live/flutter/guide/video-and-audio-calling-api-sdk/render-media/layout-and-grid-management#grid-with-pagination).

## Media Stream Quality Adjustment

In large meetings, managing media stream quality is essential to balance performance and user experience. 

Recommended Practices:

- `High Quality for Active Speakers`: For all active speakers, set the video stream quality to a higher level using the setQuality method (e.g., `setQuality("high")`). This ensures that participants will receive higher-quality video for active speakers, providing a clearer and more engaging experience.
- `Lower Quality for Non-Speaking Participants`: For other participants who are not actively speaking, set their video stream quality to a lower level (e.g., `setQuality("low")`). This helps conserve bandwidth and system resources while maintaining overall meeting performance.

Checkout the documentation for `setQuality()` method [here](https://docs.videosdk.live/flutter/api/sdk-reference/participant-class/methods#setquality) 

---

# User Experience Guidelines - Flutter

This guide aims to help developers optimize the user experience and functionality of video conferencing applications with VideoSDK. By following these best practices, you can create smoother interactions, minimize common issues, and deliver a more reliable experience for users.

Here are our recommended best practices to enhance the user experience in your application:

| **Section**                          | **Description**                                                                                                                                                      |
|--------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Configure Precall for Effortless Meeting Join](#configure-precall-for-effortless-meeting-join) | Users may enter meetings unprepared due to device or connection issues. A Precall setup can help them configure devices and settings beforehand for a smooth start. |
| [Listen Key Events for Optimal User Experience](#listen-key-events-for-optimal-user-experience) | Users can feel lost without real-time updates on meeting status, events, and errors. Event monitoring and notifications keep them informed and engaged.              |
| [Handling Media Devices](#handling-media-devices)                                             | Users may want to change their audio or video setup mid-meeting but struggle to manage device controls. Providing easy device switching enhances control and flexibility. |
| [Monitoring Real-Time Participant Statistics](#monitoring-real-time-participant-statistics)   | Poor video or audio quality without real-time feedback leaves users frustrated. Real-time stats let them assess connection quality and troubleshoot issues actively.    |

## Configure Precall for Effortless Meeting Join

A Precall step is crucial for ensuring users are set up correctly and have no device before joining a meeting. This step allows users to configure their devices and settings before entering a meeting, leading to a smoother experience and minimizing technical issues once the call begins.

Recommended Practices:

- `Request Permissions`: Prompt users to grant microphone, and camera permissions before entering the meeting, ensuring seamless access to their devices.
- `Device Selection`: Allow users to select their preferred camera, and microphone giving them control over their setup from the start.
- `Entry Preferences`: Provide options to join with the microphone and camera either on or off, letting users choose their level of engagement upon entry.
- `Camera Preview`: Show a live camera preview, allowing users to adjust angles and lighting to ensure they appear clearly and professionally.
- `Virtual Backgrounds`: Allow users to choose from different virtual backgrounds or enter with a virtual background enabled, enhancing privacy and creating a more polished appearance.

For detailed setup instructions on each of these features, check out our in-depth documentation [here](https://docs.videosdk.live/flutter/guide/video-and-audio-calling-api-sdk/setup-call/precall).

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_precall.gif" />

</div>

## Monitor Key Events for Optimal User Experience

Listening for crucial events is vital for providing users with a responsive and engaging experience in your application. By effectively managing state changes and user notifications, you can keep participants informed and enhance their overall experience during meetings.

Recommended Practices:

- `Monitor State Change Events`: Listen for state change events, such as `Events.recordingStateChanged`, and notify users promptly about these transitions. Keeping users informed helps them understand the current state of the meeting.

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_meeting_state.jpg" />

</div>

- `UI Handling on Event Trigger`: Update the user interface only in response to specific events. For instance, display that the meeting is recording only when the `recordingStateChanged` event with the status `RECORDING_STARTED` is received, rather than when the record button is clicked. This ensures users receive accurate and timely updates.

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_recording.gif" />

</div>

- `Notify Participants of Join/Leave Events`: Keep users informed about participant activity by notifying them when someone joins or leaves the meeting. This fosters a sense of presence and awareness of who is currently available to engage.
- `Listen for Error Events`: It is crucial to monitor error events and notify users promptly when issues arise. Clear communication about errors can help users troubleshoot and address problems quickly, minimizing disruptions to the meeting.


## Handling Media Devices

Providing seamless control over devices enhances user convenience and allows participants to adjust their setup for the best meeting experience. Proper device management within the UI also helps users stay informed about their current settings and troubleshoot issues effectively.

Recommended Practices:

- `Allow Device Switching`: Provide users with the option to switch between available microphone, and camera devices during the meeting. This flexibility is essential, especially if users want to adjust their setup mid-call.
- `Display Selected Devices`: Ensure the UI shows users which microphone, and camera devices are currently selected. Clear device labeling in the interface can reduce confusion and help users verify their setup at a glance.

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_audio_selected_device.jpg" />

</div>

## Monitoring Real-Time Participant Statistics

Providing real-time insights into stream quality allows participants to monitor and optimize their connection for the best experience. With detailed metrics on video, audio, and screen sharing, users can assess and troubleshoot quality issues, ensuring smooth and uninterrupted meetings. To display these statistics, you can use the [getVideoStats()](https://docs.videosdk.live/flutter/api/sdk-reference/participant-class/methods#getvideostats), [getAudioStats()](https://docs.videosdk.live/flutter/api/sdk-reference/participant-class/methods#getaudiostats), and [getShareStats()](https://docs.videosdk.live/flutter/api/sdk-reference/participant-class/methods#getsharestats) methods.


<div style={{textAlign: 'center'}}>



</div>

<br/>



---

# Face Match API (BETA)


This API verifies whether two provided images are same or not. It returns a boolean value indicating whether the faces match.

:::important

This API is available in Enterprise plan only.

:::

## HTTP Method and Endpoint

**<span style={{ color: "#86EFAC", fontWeight: "bold" }}>POST</span>** | `https://api.videosdk.live/ai/v1/face-verification/verify`

## Headers Parameter

### Authorization

**values** : YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

_Note_ : the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by referring to this Guide: [Generate Auth token](https://docs.videosdk.live/api-reference/realtime-communication/intro)

### Content-Type

**values** : `application/json`

This is useful for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.

## Data Parameter

#### Base64 Encoding Format

The images should be converted from binary format to a Base64 string




Images must be Base64 encoded in the following format:

```
data:image/jpeg;base64,${Base64data}
```

#### Request Format

The request body should contain two Base64-encoded images in the following format:

```js
const data = {
  img1: "data:image/jpeg;base64,${Base64data}", // Base64-encoded image 1
  img2: "data:image/jpeg;base64,${Base64data}", // Base64-encoded image 2
};
```

## Sending Image Comparison Request

The request is made using the following code:




This sends the encoded images to the specified URL for comparison.

## Code Snippet for API Integration

Below is a code snippet demonstrating how to use the Face Match API (BETA) with Node.js:

```js




// Load environment variables from .env file
dotenv.config();

// Get the directory of the current file
const __dirname = path.resolve();

// Function to read image files and convert them to base64
function getBase64Image(imageName) {
  const filePath = path.join(__dirname, "image", imageName);
  console.log(`Resolved file path: ${filePath}`);
  try {
    const image = readFileSync(filePath);
    const base64Data = Buffer.from(image).toString("base64");
    return `data:image/jpeg;base64,${base64Data}`;
  } catch (error) {
    console.error(`Error reading image file: ${filePath}`, error.message);
    throw error;
  }
}

// Function to perform Face Match
async function faceMatch(ovdImageName, selfieImageName) {
  const url = "https://api.videosdk.live/ai/v1/face-verification/verify";
  const headers = {
    Authorization: `${process.env.API_KEY}`,
    "Content-Type": "application/json",
  };

  const data = {
    img1: getBase64Image(ovdImageName),
    img2: getBase64Image(selfieImageName),
  };

  try {
    const response = await axios.post(url, data, { headers });
    console.log("Face Match Result:", response.data);
  } catch (error) {
    console.error(
      "Error during face match:",
      error.response ? error.response.data : error.message
    );
  }
}

// Main function to run the API calls
async function main() {
  const ovdImageName = "img1.jpg";
  const selfieImageName = "img2.jpg";

  await faceMatch(ovdImageName, selfieImageName);
}

// Run the main function
main().catch((error) =>
  console.error("Error in main function:", error.message)
);
```

## Examples of Face Match API (BETA) Usage

### Example 1 : Matching Images of the Same Person

In this scenario, we take two different pictures of the same individual. For instance:

<div
  style={{ display: "flex", justifyContent: "center", alignItems: "center" }}
>
  <div style={{ textAlign: "center", marginRight: "-15px" }}>
    <img
      src="https://cdn.videosdk.live/website-resources/docs-resources/face_match_girl_1.png"
      alt="Image 1"
      width="90%"
    />
    <p>Image 1</p>
  </div>
  <div style={{ textAlign: "center", marginLeft: "-15px" }}>
    <img
      src="https://cdn.videosdk.live/website-resources/docs-resources/face_match_girl_2.png"
      alt="Image 2"
      width="90%"
    />
    <p>Image 2</p>
  </div>
</div>

When these images are sent to the Face Match API (BETA), the expected output would be:

```
Face Match Result: { "verified": true }
```

This result indicates that despite differences in lighting, angle, or expression, the API successfully recognizes that both images depict the same individual.

### Example 2 : Matching Images of Different Persons

In this case, we compare two photos of different individuals. For example:

<div
  style={{ display: "flex", justifyContent: "center", alignItems: "center" }}
>
  <div style={{ textAlign: "center", marginRight: "-15px" }}>
    <img
      src="https://cdn.videosdk.live/website-resources/docs-resources/face_match_male_1.png"
      alt="Image 1"
      width="90%"
    />
    <p>Image 1</p>
  </div>
  <div style={{ textAlign: "center", marginLeft: "-15px" }}>
    <img
      src="https://cdn.videosdk.live/website-resources/docs-resources/face_match_male_2.png"
      alt="Image 2"
      width="90%"
    />
    <p>Image 2</p>
  </div>
</div>

When these images are processed through the Face Match API (BETA), the expected output would be:

```
Face Match Result: { "verified": false }
```

This result demonstrates the API's ability to differentiate between distinct individuals accurately.



---

# Face Spoof Detection (BETA)


This API verifies if the image is original or spoofed. It returns a boolean value spoof_detected in output.

:::important

This API is available in Enterprise plan only.

:::

## HTTP Method and Endpoint

**<span style={{ color: "#86EFAC", fontWeight: "bold" }}>POST</span>** | `POST https://api.videosdk.live/ai/v1/face-verification/detect-spoof`

## Headers Parameter

### Authorization

**values** : YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

_Note_ : the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by refering this Guide: [Generate Auth token](https://docs.videosdk.live/api-reference/realtime-communication/intro)

### Content-Type

**values** : `application/json`

This is usefull for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.




## Data Parameter

#### Base64 Encoding Format

The images should be converted from binary format to a Base64 string




Images must be Base64 encoded in the following format:

```
data:image/jpeg;base64,${Base64data}
```

#### Request Format

The request body should contain two Base64-encoded images in the following format:

```js
const data = {
  img: "data:image/jpeg;base64,${Base64data}", // Base64-encoded image
};
```

## Sending Image Comparison Request

The request is made using the following code:




This sends the encoded images to the specified URL for comparison.

## Code Snippet for API Integration

Below is a code snippet demonstrating how to use the Face Spoof Detection API (BETA) with Node.js:

```js




// Load environment variables from .env file
dotenv.config();

// Get the directory of the current file
const __dirname = path.resolve();

// Function to read image files and convert them to base64
function getBase64Image(imageName) {
  const filePath = path.join(__dirname, "image", imageName);
  console.log(`Resolved file path: ${filePath}`);
  try {
    const image = readFileSync(filePath);
    const base64Data = Buffer.from(image).toString("base64");
    return `data:image/jpeg;base64,${base64Data}`;
  } catch (error) {
    console.error(`Error reading image file: ${filePath}`, error.message);
    throw error;
  }
}

async function spoofDetection(spoofimg) {
  const url = "https://api.videosdk.live/ai/v1/face-verification/detect-spoof";
  const headers = {
    Authorization: `${process.env.API_KEY}`,
    "Content-Type": "application/json",
  };
  const data = {
    img: getBase64Image(spoofimg),
  };

  try {
    const response = await axios.post(url, data, { headers });
    console.log(response.data);
  } catch (error) {
    console.error(
      "Error during spoof detection:",
      error.response ? error.response.data : error.message
    );
  }
}

// Main function to run the API calls
async function main() {
  const spoofimg = "img.jpg";
  await spoofDetection(spoofimg);
}

// Run the main function
main().catch((error) =>
  console.error("Error in main function:", error.message)
);
```

##### Given below is a test run of the example.

**Input Image** :

<div
  style={{
    display: "flex",
    justifyContent: "left",
    alignItems: "left",
    gap: "10px",
  }}
>
  <img
    src="https://cdn.videosdk.live/website-resources/docs-resources/input_spoof.jpg"
    alt="Image 1"
    width="45%"
  />
</div>

When this image is sent to the Face Spoof Detection API (BETA), the response will return a boolean value spoof_detected in output :

```js
{
  spoof_detected: true; // true if spoof detected in image else false
  accuracy: 0.9899068176746368; // accuracy of spoof detection
}
```



---

# Number of Face Detection (BETA)


This API checks how many faces are there in the image and returns an int value number_of_faces in output.

:::important

This API is available in Enterprise plan only.

:::

## HTTP Method and Endpoint

**<span style={{ color: "#86EFAC", fontWeight: "bold" }}>POST</span>** | `https://api.videosdk.live/ai/v1/face-verification/detect-faces`

## Headers Parameter

### Authorization

**values** : YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

_Note_ : the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by refering this Guide: [Generate Auth token](https://docs.videosdk.live/api-reference/realtime-communication/intro)

### Content-Type

**values** : `application/json`

This is usefull for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.




## Data Parameter

#### Base64 Encoding Format

The images should be converted from binary format to a Base64 string




Images must be Base64 encoded in the following format:

```
data:image/jpeg;base64,${Base64data}
```

#### Request Format

The request body should contain two Base64-encoded images in the following format:

```js
const data = {
  img: "data:image/jpeg;base64,${Base64data}", // Base64-encoded image
};
```

## Sending Image Comparison Request

The request is made using the following code:




This sends the encoded images to the specified URL for comparison.

## Code Snippet for API Integration

Below is a code snippet demonstrating how to use the number of faces detection API with Node.js:

```js




// Load environment variables from .env file
dotenv.config();

// Get the directory of the current file
const __dirname = path.resolve();

// Function to read image files and convert them to base64
function getBase64Image(imageName) {
  const filePath = path.join(__dirname, "image", imageName);
  console.log(`Resolved file path: ${filePath}`);
  try {
    const image = readFileSync(filePath);
    const base64Data = Buffer.from(image).toString("base64");
    return `data:image/jpeg;base64,${base64Data}`;
  } catch (error) {
    console.error(`Error reading image file: ${filePath}`, error.message);
    throw error;
  }
}

async function noOfFaces(getImg) {
  const url = "https://api.videosdk.live/ai/v1/face-verification/detect-faces";
  const headers = {
    Authorization: `${process.env.API_KEY}`,
    "Content-Type": "application/json",
  };
  const data = {
    img: getBase64Image(getImg),
  };

  try {
    const response = await axios.post(url, data, { headers });
    console.log(response.data);
  } catch (error) {
    console.error(
      "Error during Number of face detection :",
      error.response ? error.response.data : error.message
    );
  }
}

// Main function to run the API calls
async function main() {
  const getImg = "img1.jpg";
  await spoofDetection(getImg);
}

// Run the main function
main().catch((error) =>
  console.error("Error in main function:", error.message)
);
```

##### Given below is a test run of the example.

**Input Image** : group_photo.jpg - A photo showing a group of five people.

<div style={{ display: "flex", alignItems: "center", gap: "10px" }}>
  <img
    src="https://cdn.videosdk.live/website-resources/docs-resources/group_of_people.jpg"
    alt="Image 1"
    width="45%"
  />
</div>

When this image is sent to the Face Detection API, The response will return an int value number_of_faces in output :

```js
{
  number_of_faces: 5; // number of faces detected
}
```



---

# OCR API (BETA)


---
title: Ocr | Android SDK Documentation | VideoSDK
description: Learn how to implement ocr using VideoSDK's Android SDK. Step-by-step integration guide for seamless identity verification or SIP connectivity.
---

This API will take front and back part of the document in input, scan through the document and return all the available fields of the document in JSON formatted response. Fields can vary as per type of document in response..

:::important

This API is available in Enterprise plan only.

:::

## HTTP Method and Endpoint

**<span style={{ color: "#86EFAC", fontWeight: "bold" }}>POST</span>** | `https://api.videosdk.live/ai/v1/ocr`

## Headers Parameter

### Authorization

**values** : YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

_Note_ : the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by referring this Guide: [Generate Auth token](https://docs.videosdk.live/api-reference/realtime-communication/intro)

### Content-Type

**values** : `application/json`

This is useful for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.




## Data Parameter

#### Base64 Encoding Format

The images should be converted from binary format to a Base64 string




Images must be Base64 encoded in the following format:

```
data:image/jpeg;base64,${Base64data}
```

#### Request Format

The request body should contain two Base64-encoded images in the following format:

```
const data = {
   "frontpart": "data:image/jpeg;base64,${Base64data}", // Base64-encoded image
   "backpart": "data:image/jpeg;base64,${Base64data}", // Base64-encoded image
}
```

## Sending Image Comparison Request

The request is made using the following code:




This sends the encoded images to the specified URL for comparison.

## Response

The response will return all the available fields of document in JSON formated response :

```javascript
{
   idType: "", // document Type
   idNumber: "", // document Number
   name: "", // name
   dateOfBirth: "",
   address: "",
   gender: "",
   mobileNumber: ""
};
```

## Code Snippet for API Integration

Below is a code snippet demonstrating how to use OCR API (BETA) with Node.js:

```javascript




// Load environment variables from .env file
dotenv.config();

// Get the directory of the current file
const __dirname = path.resolve();

// Function to read image files and convert them to base64
function getBase64Image(imageName) {
  const filePath = path.join(__dirname, "image", imageName);
  console.log(`Resolved file path: ${filePath}`);
  try {
    const image = readFileSync(filePath);
    const base64Data = Buffer.from(image).toString("base64");
    return `data:image/jpeg;base64,${base64Data}`;
  } catch (error) {
    console.error(`Error reading image file: ${filePath}`, error.message);
    throw error;
  }
}

async function ocr(frontImg, backImg) {
  const url = "https://api.videosdk.live/ai/v1/ocr";
  const headers = {
    Authorization: `${process.env.API_KEY}`,
    "Content-Type": "application/json",
  };
  const data = {
    frontPart: getBase64Image(frontImg),
    backPart: getBase64Image(backImg),
  };

  try {
    const response = await axios.post(url, data, { headers });
    console.log(response.data);
  } catch (error) {
    console.error(
      "Error during OCR :",
      error.response ? error.response.data : error.message
    );
  }
}

// Main function to run the API calls
async function main() {
  const frontImg = "img4.jpg";
  const backImg = "img5.jpg";
  await ocr(frontImg, backImg);
}

// Run the main function
main().catch((error) =>
  console.error("Error in main function:", error.message)
);
```



---

# Understanding Analytics Dashboard - Flutter

Welcome to the world of actionable insights and empowered decision-making. VideoSDK's session analytics dashboard is your gateway to understanding, optimizing, and elevating every aspect of your sessions.

## Accessing Analytics Made Easy

Navigating through session data is a breeze with VideoSDK. Simply head to your session page at https://app.videosdk.live/meetings/sessions, where a treasure trove of session information awaits.

### How to Access Analytics?

Open Session Analytics effortlessly by following these steps:

1. **Click on Meeting-ID:**
    - Directly access analytics by clicking on the meeting-ID within the session table.
2. **Hover and Click View Analytics:**
    - Hover over a specific meeting row to reveal the **View Analytics** button in the Actions Column.
    - Click on **View Analytics** to open the Session Overview sidebar, unlocking a wealth of insights.

![Access Analytics](https://cdn.videosdk.live/website-resources/docs-resources/access_analytics.png)

---

There are three tabs available within the session analytics view:

## **1. Session Overview**

This tab provides an overview of the session, including its duration and participant details. You can explore individual participant statistics to understand their session performance better.

## **2. Errors**

In this tab, you can find information about any errors encountered during the session. It helps you identify and address issues like network problems or technical glitches promptly.

## **3. Session Stats**

Explore data and metrics sent and received by participants to measure performance of the session in this tab. It offers insights into data exchange among participants, including metrics on jitter, RTT, and packet loss, resolutions, and fps aiding in assessing communication efficiency.

Let's dive deeper into each of these tabs to gain a better understanding of session analytics.

# Session Overview

The session overview page is your compass in the sea of data. Here's what you'll uncover:

- **Meeting ID:** Unique identifier for the meeting in the format of `abcd-efgh-ijkl`.
- **Session ID:** Unique identifier for each session, uniquely identified by its `sessionId`.
- **Session Status:** Indicates if the session is ongoing or ended.
- **Session Initiating Time:** Time taken by the first participant to establish the connection.
- **Start and End Time:** Marks the start and end of the session.
- **Total Unique Participants Joined:** Total number of unique participants in the session.
- **Total Session Duration:** Overall duration of the session from start to end.
- **Total Participant Minutes:** A sum of all participant duration.
- **Recording, HLS, RTMP:** Additional services used in the session.

### Participant Table List

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for each participant.
- **Join Time:** Time taken by the participant to establish connection.
- **Duration:** Total time spent by this participant in the session.

### Efficient Session Management with Actions

Enhance your session management with streamlined actions:

- **Kick Out Participants:** Effortlessly remove/kickout participants from ongoing sessions.
- **Detailed Participant Analytics:**
- Hover over a specific participant row to reveal the `View Stats` button at the end of the row.
- Click on `View Stats` to open the Participant Overview sidebar.
    
![View Stats](https://cdn.videosdk.live/website-resources/docs-resources/view_stats.png)

## Explore Participant Insights

Discover valuable participant data that provides a clear view of engagement and experience:

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for better interaction.
- **Joined At:** Indicates the precise moment when participant connects to the session.
- **Left At:** Indicates the precise moment when participant left the session.
- **Total Duration:** Total duration of participant within that session.
- **Joining Time:** Time taken by the this participant to establish the connection.
- **Location:** Approx. geographic location from where the participant joined.
- **Platform:** Specifies whether participants are using a desktop or mobile device.
- **Device Info:** Offers details regarding the participant's device.
- **OS:** Provides information about the participant's OS.
- **Browser:** Provides specifics about the participant's browser
- **SDK Version:** Indicates the version of the SDK used by participants.

### Understanding Participant Call Health

We've developed call health to offer a rapid assessment of participant performance during calls. This feature highlights the performance of audio, video, and screen sharing audio-video separately. We've utilized color theory, with green indicating good performance, orange for moderate, and red for poor performance, to enhance clarity. For detailed insights, simply hover over the bars

![Participant Call Health](https://cdn.videosdk.live/website-resources/docs-resources/participant_call_health.png)

## Participant Session Stats

Dive into Participant Session Stats for valuable insights into your session experience! With just a click on `View Session Stats` at the bottom of the page, unlock a treasure trove of data crucial for understanding audio and video experiences.

Within this section, you can observe quality metrics for the selected participant, comparing them to others. Additionally, the `Sessions Stats` covers quality stats comparison for every participant. Keep reading to explore more about Session Stats.

**Visualizing Session Performance from Both Sides**

This section provides a two-sided view of your session's metrics.

- **Left Side: Sender Participant Graph** This section displays graphs representing the metrics sent by the sender participant.. Here, you can see how the various factors impacted the data you transmitted.
- **Right Side: Receiver Participant Graph** On the right side, you'll find a dropdown menu where you can select a specific participant. Choosing a receiver will display graphs showcasing the metrics **received by that participant**. This allows you to compare the sending experience (left side) with the receiving experience (right side) for different participants.

![VideoSDK Jitter Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_jitter_graph.png)

**See How Your Session Performed**

These metrics give you a clear picture of your session's quality. Understanding them helps you spot any issues and keep things running smoothly. Let's dive into what each metric means!

**Jitter:** Imagine your internet connection like a bumpy road. Jitter is how much those bumps cause your signal to bounce around. Less jitter means a smoother ride for your data (audio and video, threshold ≤ 30ms).

**RTT (Latency):** This is how long it takes for data to travel between you and the server you're connected to. Think of it like the time it takes for a message to get delivered – a lower RTT means a faster delivery (affects both audio and video, threshold ≤ 300ms).

**Bitrate:** This measures the amount of data flowing through your connection per second. Imagine it like the width of a water pipe – a higher bitrate allows for more data to flow, which can be good for high-quality audio/video or fast downloads.

**Packet Loss:** Think of data traveling in tiny packets. Packet loss is when some of those packets get dropped along the way. More packet loss means information might be missing, affecting things like audio/video quality or lag in games (threshold ≤ 5%).

**Resolution:** This refers to the sharpness and detail of an image or video. Think of it like the number of pixels on your screen – a higher resolution means a crisper picture (**Video Only**).

**FPS (Frames Per Second):** This measures how many images (frames) are displayed on your screen every second. Imagine it like a flipbook – a higher FPS creates a smoother and more fluid animation or video experience (**Video Only**).

![VideoSDK FPS Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_fps_graph.png)

![VideoSDK Resolution Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_resolution_graph.png)

---

# **Investigate Session Errors**

Get to the root of smoother sessions by addressing errors directly. Use the Errors tab to explore details of errors encountered during your session. Note: Session errors are visible with JS SDK v0.0.82 or higher, React SDK v0.1.85 or higher, and React Native v0.1.6 or newer versions.

- **Participant Name & ID:** Quickly identify the participant associated with each error for swift resolution.
- **Error Types:** Understand the different types of errors encountered, such as network issues or connection disruptions.
- **Detailed Descriptions:** Access clear explanations of errors to take actionable steps towards solution.

![VideoSDK Error Details](https://cdn.videosdk.live/website-resources/docs-resources/error_new.png)

# **Analyse Session Stats**

Similar to `Participant Session Stats`, this tab covers quality statistics sent by individual participants. You can select any participant to compare effectively with others.

Choose a sender participant from the dropdown menu on the left and select a recipient on the right to compare data over different time frames. This allows you to identify and explore issues within specific durations.

This tab covers the same metrics as covered in the `participant session stats`: Jitter, RTT (Latency), Bitrate, Packet-loss, Resolution (Video only), and FPS (Video only).

![VideoSDK Session Stats](https://cdn.videosdk.live/website-resources/docs-resources/session_stats.png)


---

# Understanding Call Quality - Flutter

When developing a video call app, customer satisfaction heavily depends on the app's video and audio quality and its fluctuation.

## Call Quality

From the user's perspective, good video quality is defined as smooth and clear video, along with crystal clear audio. Developers consider good video quality as high-resolution, high-frame-rate video with minimal latency and high-bitrate audio with minimal audio loss.

## Factors affecting Quality

When measuring video and audio quality, several variables come into play. The common factors affecting quality are as follows:

### `1. Network Bandwidth`

- Network bandwidth is the measure of a user's network capacity, indicating how much data can be received and sent.
- If the participant's bandwidth is low, they are likely to experience pixelated or frozen video, along with robotic voice or minor audio interruptions.
- Frequent changes in network providers can also lead to significant fluctuations in internet bandwidth, resulting in poor video quality.

### `2. Latency`

- Latency refers to the time it takes for data to transfer from one machine to another.
- If the meeting is hosted in `Ohio` region, and users are joining from `Singapore` region, this can result in a long delay for data to transfer between mackines. Therefore, it is advisable to choose a server based on your user base.
- With VideoSDK, you can specify the server during the creation of a Meeting/Room.

### `3. CPU Usage`

- CPU Usage is also a determining factor, as all the audio and video streams going out and coming in need to be encoded or decoded, requiring a significant amount of computation.
- The higher the resolution and frame rate of the videos, the greater the computation required, which can lead to a bottleneck in delivering good-quality video.
- If the CPU is heavily consumed, it can also result in choppy or robotic audio.

### `4. Camera and Mic Quality`

- The camera and microphone should capture high-quality streams to ensure that remote users don't receive a low-quality stream even if they have bad network bandwidth.

## Identifying various issues related to Quality.

In order to identify potential issues, VideoSDK collects various audio and video-related metrics that can help pinpoint quality concerns. Take a look at these metrics and understand what they indicate.

### `1. Resolution and Framerate`

- Resolution and frame rate serve as crucial metrics for video quality in a video call app. Resolution indicates the number of pixels in a video image, while frame rate denotes the number of frames displayed per second.

- While higher resolutions and frame rates can enhance video quality, they also demand more bandwidth and processing power. It's essential to optimize these metrics based on the devices and network conditions of your users.

- For instance, if the majority of your users are on mobile devices, opting for a lower resolution and frame rate may be more suitable to ensure smooth playback and minimize bandwidth usage.

- If your user base comprises both mobile and desktop devices, adopting higher resolution for desktops and mid-resolutions for mobile devices can contribute to improved performance and quality while conserving bandwidth on mobile devices.

### `2. Bitrate`

- Bitrate represents the number of bits per second transmitted or received during the transmission of audio or video streams. It is a crucial parameter for assessing the quality of audio or video streams and should be adjusted for each resolution to strike a balance between performance and bandwidth utilization.

- In scenarios with excellent network conditions, a higher bitrate can lead to significantly improved video quality. However, it's essential to be cautious when dealing with very high bitrates on mobile devices, as it may result in heating issues due to the substantial computational requirements for encoding and decoding videos.

##### Example

We used the same phone **(iPhone 14)**, for both participants, but there were differences in resolution and bitrate. The first participant had a resolution of **`1280x720`** with a bitrate of **`1442 kbps`**, while the second participant had a resolution of **`960x540`** with a bitrate of **`642 kbps`**. Surprisingly, both participants' videos appeared to be of equal quality despite variations in resolution and bitrate.

![resolution-and-bitrate](/img/resolution-and-bitrate.png)

### `3. Packet Loss`

- Packet loss is a metric that reveals the number of lost data packets during transmission from the sender to the receiver. It can happen due to network congestion, hardware or software issues, or network latency. Increased packet loss can lead to degraded video and audio quality, as the absence of packets may cause gaps or distortions in the media stream.


<div style={{textAlign: 'center'}}>



</div>

### `4. Jitter`

- The audio and video packets are sent out at random intervals over a specified time frame as they travel between the server and client. Jitter occurs when there is a variation in transmitting or receiving these data packets due to a faulty network connection.

- When data packets experience delays during transmission to the participant, usually because the network is busy, they may result in pixelated video during a video call or sound choppy, distorted, or robotic in a voice call upon arrival. This creates jitter, with packets arriving at random intervals.

### `5. Round Trip Time (Latency)`

- Round trip time refers to the duration it takes for data packets to be transmitted from the user's device to the server and back. If the servers are located far from the user's location, they may experience high latency (delay).

- With VideoSDK, this factor is addressed as we automatically choose the nearest available server for participants. However, if you are geofencing to a specific region, ensure that you choose the server nearest to your users.

<center>

![resolution-and-bitrate](/img/rtt.png)

</center>

## Checking Realtime Statistics

VideoSDK provides methods to check the realtime statistics of audio and video of all the participants.

### `getVideoStats()`

- The `getVideoStats()` method returns an object containing the different quality parameters for video stream, which can be accessed through the `Participant` Class.

- This object will contain values for the specific participant's video stream, including resolution, frame rate, bitrate, jitter, round trip time, and packet loss.

<div style={{textAlign: 'center'}}>



</div>

### `getAudioStats()`

- The `getAudioStats()` method returns an object containing the different quality parameters for audio stream, which can be accessed through the `Participant` Class.

- This object will contain values for the specific participant's audio stream, including bitrate, jitter, round trip time and packet loss.

### `getShareStats()`

- The `getShareStats()` method returns an object containing the different quality parameters for screen share stream, which can be accessed through the `Participant` class.

- This objects will contain values for the specific participant's screen share stream, including resolution, frame rate, bitrate, jitter, round trip time, and packet loss.


## Quality analysis Graphs

For all sessions conducted using VideoSDK, you can access quality analysis graphs from the [VideoSDK Dashboard](https://app.videosdk.live/meetings/sessions). These graphs help you visualize real-time data and identify spikes in certain parameters during calls, aiding in understanding the reasons for quality issues.

![quality analysis](/img/quality-analysis.png)

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [getVideoStats()](/flutter/api/sdk-reference/participant-class/methods#getvideostats)
- [getAudioStats()](/flutter/api/sdk-reference/participant-class/methods#getaudiostats)
- [getShareStats()](/flutter/api/sdk-reference/participant-class/methods#getsharestats)


---

# Change Mode - Flutter

In a live stream, audience members usually join in `RECV_ONLY` mode, meaning they can only view and listen to the hosts. However, if a host invites an audience member to actively participate (e.g., to speak or present), the audience member can switch their mode to `SEND_AND_RECV` using the changeMode() method.

This guide explains how to use the changeMode() method and walks through a sample implementation where a host invites an audience member to become a host using PubSub.

### `changeMode()`

- The `changeMode()` method from the `Room` class allows a participant to switch between modes during a live stream—for example, from audience to host.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class LivestreamScreen extends StatefulWidget {
  const LivestreamScreen({Key? key}) : super(key: key);

  @override
  _LiveStreamScreenState createState() => _LiveStreamScreenState();
}

class _LiveStreamScreenState extends State

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [changeMode()](/flutter/api/sdk-reference/room-class/methods#changemode)
- [Paticipant Class](/flutter/api/sdk-reference/participant-class/properties)
- [Room Class](/flutter/api/sdk-reference/room-class/properties)
- [PubSub Class](/flutter/api/sdk-reference/pubsub-class/methods)

---

# Remove Participant - Flutter

When hosting a live stream, it's essential for the host to have the capability to to remove a participant from the live stream. This can be useful in various scenarios where a participant is causing disturbance, behaving inappropriately, or is not following the guidelines. This guide focuses on this very aspect of removing a particpant from the live stream.

VideoSDK provides three ways to do so:

1. [Using SDK](#1-using-sdk)
2. [Using VideoSDK Dashboard](#2-using-videosdk-dashboard)
3. [Using Rest API](#3-using-rest-api)

## 1. Using SDK

### `remove()`

The `remove()` method allows for the removal of a participant during an on-going session. This can be helpful when moderation is required in a particular live stream.

### Events associated with remove

Following callbacks are received when a participant is removed from the Livestream.

- Participant who was removed from the Livestream will receive a callback on[`roomLeft`](/flutter/api/sdk-reference/room-class/events#roomleft) on `Room` object.
- All other [remote participants](/flutter/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a callback [`participantLeft`](/flutter/api/sdk-reference/room-class/events#participantleft) with `participantId`.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;
  const ParticipantTile({super.key, required this.participant});

  @override
  State

</div>

## 3. Using Rest API

- You can also remove a particular participant from the live stream [using the REST API](/api-reference/realtime-communication/remove-participant).
- To employ this method, you need the `sessionId` of the live stream and the `participantId` of the individual you intend to remove.

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [remove()](/flutter/api/sdk-reference/participant-class/methods#remove)
- [Events.roomLeft](/flutter/api/sdk-reference/room-class/events#roomleft)
- [Events.participantLeft](/flutter/api/sdk-reference/room-class/events#participantleft)


---

# Audience Polls during Live Stream - Flutter


Interactive polls are a great way to increase engagement during livestreams. Using VideoSDK’s PubSub mechanism, you can easily implement real-time audience polling, where viewers can vote and see live results instantly.

This guide walks you through how to create, send, and visualize poll results during a livestream.

### Step 1: Creating and Publishing a Poll

To initiate a poll, use the `PubSub` object with a `POLL` topic. The poll structure should include a question and multiple options. This message will be published to all participants.

```js
import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class PollHostView extends StatelessWidget {
  final Room room;

  const PollHostView({required this.room});

  void startPoll() {
    final pollData = {
      "id": DateTime.now().millisecondsSinceEpoch,
      "question": "Which feature do you love the most?",
      "options": ["Reactions", "Screen Share", "Whiteboard", "Polls"],
      "responses": {},
    };

    room.pubSub.publish(
      "POLL",
      jsonEncode(pollData),
      const PubSubPublishOptions(persist: true),
    );
  }

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: startPoll,
      child: const Text("Start Poll"),
    );
  }
}
```
### Step 2: Subscribing to Polls and Displaying Options

Participants can listen to the POLL topic and render voting options dynamically based on the incoming data.

```js
import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class PollAudienceView extends StatefulWidget {
  final Room room;

  const PollAudienceView({required this.room});

  @override
  State<PollAudienceView> createState() => _PollAudienceViewState();
}

class _PollAudienceViewState extends State<PollAudienceView> {
  Map<String, dynamic>? activePoll;

  @override
  void initState() {
    super.initState();
    widget.room.pubSub.subscribe("POLL", handlePollReceived);
  }

  @override
  void dispose() {
    widget.room.pubSub.unsubscribe("POLL", handlePollReceived);
    super.dispose();
  }

  void handlePollReceived(PubSubMessage message) {
    setState(() {
      activePoll = jsonDecode(message.message);
    });
  }

  void submitVote(String option) {
    if (activePoll != null) {
      widget.room.pubSub.publish(
        "POLL_RESPONSE",
        jsonEncode({
          "pollId": activePoll!['id'],
          "option": option,
        }),
        const PubSubPublishOptions(persist: true),
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    if (activePoll == null) return const SizedBox();

    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        Text(
          activePoll!['question'],
          style: const TextStyle(fontSize: 18, fontWeight: FontWeight.bold),
        ),
        const SizedBox(height: 10),
        ...(activePoll!['options'] as List<dynamic>).map((option) {
          return Padding(
            padding: const EdgeInsets.symmetric(vertical: 4),
            child: ElevatedButton(
              onPressed: () => submitVote(option.toString()),
              child: Text(option.toString()),
            ),
          );
        }).toList(),
      ],
    );
  }
}
```

### Step 3: Aggregating and Displaying Poll Results
The host can subscribe to the POLL_RESPONSE topic to collect responses and render the result in real-time.

```js

import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class PollResultsView extends StatefulWidget {
  final Room room;

  const PollResultsView({required this.room});

  @override
  State<PollResultsView> createState() => _PollResultsViewState();
}

class _PollResultsViewState extends State<PollResultsView> {
  final Map<String, Map<String, int>> results = {};

  @override
  void initState() {
    super.initState();
    widget.room.pubSub.subscribe("POLL_RESPONSE", handleResponse);
  }

  @override
  void dispose() {
    widget.room.pubSub.unsubscribe("POLL_RESPONSE", handleResponse);
    super.dispose();
  }

  void handleResponse(PubSubMessage message) {
    final data = jsonDecode(message.message);
    final pollId = data['pollId'].toString();
    final option = data['option'].toString();

    setState(() {
      final pollResult = results[pollId] ?? {};
      pollResult[option] = (pollResult[option] ?? 0) + 1;
      results[pollId] = pollResult;
    });
  }

  @override
  Widget build(BuildContext context) {
    if (results.isEmpty) return const Text("No poll results yet.");

    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: results.entries.map((entry) {
        final pollId = entry.key;
        final pollResult = entry.value;

        return Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text("Poll ID: $pollId", style: const TextStyle(fontWeight: FontWeight.bold)),
            ...pollResult.entries.map((e) => Text("${e.key}: ${e.value} votes")).toList(),
            const SizedBox(height: 16),
          ],
        );
      }).toList(),
    );
  }
}

```


## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [usePubSub()](/flutter/api/sdk-reference/pubsub-class/introduction)

---

<h1> {props.title} </h1>{" "}

### Why we are using JWT based Token ?

Token based authentication allows users to verify their identity by providing generated API key and secret.

We use JWT token for the authentication purpose because Token-based authentication is **widely used** in modern web applications and APIs because it offers several benefits over traditional authentication. For example, it can **reduce the risk of the credentials being misused**, and it allows for **more fine-grained control** over access to resources. Additionally, tokens can be easily revoked or expired, making it easier to manage access rights.

### How to generate Token ?

To manage secured communication, every participant that connects to the meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key` which you can get from [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

#### 1. Generating token from Dashboard

If you are looking to do **testing or for development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for getting token includes generating it from your backend server which will help in **keeping your credentials safe**.
:::

#### 2. Generating token in your backend

- Your server will generate access token using your API key and secret.
  - While generating a token, you can provide **expiration time, permissions and roles** which are discussed later in this section.
- Your client obtains token from your backend server.
- For token validation, client will pass this token to VideoSDK server.
- VideoSDK server will only allow entry in the meeting if the token is valid.

![img2.png](../../static/img/authentication-and-token.png)




Follow our official example repositories to setup token API [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)

### Payload while generating token

```js
{
 apikey: API_KEY, //MANDATORY
 permissions: [`allow_join`], //`ask_join` || `allow_mod` //MANDATORY
 version: 2, //OPTIONAL
 roomId: ROOM_ID, //OPTIONAL,
 participantId: PARTICIPANT_ID, //OPTIONAL
 roles: ['crawler', 'rtc'], //OPTIONAL
}
```

- **`apikey`(Mandatory)**: This must be the API Key generated from the VideoSDK Dashboard. You can get it from [here](https://app.videosdk.live/api-keys).

- **`permissions`(Mandatory)**: By providing the permissions, you can control what a participant can do in the meeting and whether he can join the meeting directly.

  Available permissions are:

  - **`allow_join`**: The participant is **allowed to join** the meeting directly.
  - **`ask_join`**: The participant is required to **ask for permission to join** the meeting. The participant having the permission `allow_join` can accept or reject a participant whenever someone wants to join.
  - **`allow_mod`**: The participant is **allowed to toggle** webcam & mic of other participants.

- **`version`(optional)**: For accessing the [v2 API](/api-reference/realtime-communication/intro), you need to provide `2` as the version value.

  - For passing `roomId`, `participantId` or `roles` parameters in payload, it is essential to set the version value to `2`.

- **`roomId`(optional)**: To provide customised access control, you can make the token applicable to a particular room by including the `roomId` in the payload.

- **`participantId`(optional)**: You can include the `participantId` in the payload to limit the token's access to a particular participant.

- **`roles`(optional)**:

  - **`crawler`**: This role is only for accessing [v2 API](/api-reference/realtime-communication/intro), you can not use this token for running the `Meeting`/`Room`.
  - **`rtc`**: This role is only allowed for running the `Meeting` / `Room`, with this role you can not use [server-side APIs](/api-reference/realtime-communication/intro).

Then, you have to sign this payload with your **`SECRET KEY`** and `jwt` options using the **`HS256 algorithm`**.

### Expiration time

You can set any expiration time to the token. But in the **production environment**, it is recommended to generate a token with **short expiration time** because by any chance if someone gets hold of the token, it won't be valid for a longer period of time.

### What happens if token is expired?

If your token is expired, the user won't be able to join the meeting and all the API calls will give error with message `Token is invalid or expired`.

:::note
Token is validated only once while joining the meeting, so if a person joins the meeting and the token gets expired after that, there won't be any issue in the current meeting.
:::

## How to check validity of token?

1. After generating the token, visit [jwt.io](https://jwt.io) and paste your token in the given area.
2. You will be able to see the payload you passed while generating the token and also be able to see the expiration time and token creation time.

![img1.png](../../static/img/validate-token.png)

## API Settings & Controls

The VideoSDK Dashboard provides a powerful [API Settings](https://app.videosdk.live/api-keys) section where you can configure various services and controls for your meetings. These settings allow you to customize the behavior of different features directly from the dashboard without requiring code changes.

## Audio/Video Configurations

:::note
Runtime configuration from the dashboard has higher precedence than static SDK configurations.
If a value is modified in the dashboard, it will override any previously defined SDK settings for that session.

Example:
Code: Video = HD → Dashboard: Video = Full HD → Applied: Full HD
:::

### Maximum Send Bitrate Per Participant

Control the maximum total upload bandwidth for all media streams from a single participant.

![Maximum Send Bitrate](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.00.11%E2%80%AFPM.png)

**Available Options:**
- **Auto**: Removes the upload bitrate limit (recommended for best quality)
- **SD (800kbps)**: Standard definition bitrate
- **HD (1500kbps)**: High definition bitrate
- **Full HD (3000kbps)**: Full high definition bitrate

:::tip
Setting this to **Auto** provides the best video quality as it removes upload bitrate constraints, allowing adaptive streaming based on network conditions.
:::

## Recording & Streaming Configuration

:::note
Recording and HLS follow a precedence-based configuration model:

API/SDK configuration → Highest priority
Dashboard configuration → Used only when no API values are defined

Any parameters explicitly set via the API will not be overridden by dashboard changes.
:::

### Recording Configuration

Configure recording settings for your meetings including layout, quality, and auto-start options.

![Recording Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.01.00%E2%80%AFPM.png)

**Recording Controls:**
- **Enabled**: Toggle to enable/disable recording functionality
- **Enabled Modes**: Choose between Video & Audio or Audio Only recording
- **Start Recording Automatically**: Auto-start recording when meeting begins
- **Layout Style**: Select Grid layout for recording composition
- **Maximum Tiles In Grid**: Set the number of participants visible in grid (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme for recordings
- **Video Orientation**: Choose between Landscape or Portrait mode
- **Recording Quality**: Select quality level (e.g., HD Medium)
- **Recording Mode**: Choose between Video & Audio or Audio Only

### HLS Streaming Configuration

Configure HTTP Live Streaming (HLS) settings for broadcasting your meetings.

![HLS Streaming Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.02.18%E2%80%AFPM.png)

**HLS Streaming Controls:**
- **Enabled**: Toggle to enable/disable HLS streaming
- **Enabled Modes**: Choose between Video & Audio or Audio Only streaming
- **Auto Start HLS**: Automatically start HLS when meeting begins
- **Record HLS Stream**: Enable recording of the HLS stream
- **Layout Style**: Select Grid layout for stream composition
- **Maximum Tiles In Grid**: Set the number of participants visible (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme
- **HLS Orientation**: Choose between Landscape or Portrait mode
- **HLS Quality**: Select streaming quality (e.g., HD Medium)
- **HLS Streaming Mode**: Choose between Video & Audio or Audio Only

### Additional Service Controls

Enable or disable additional services for your API key.

![Service Controls](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.08%E2%80%AFPM.png)

**Available Services:**
- **RTMP Output**: Enable RTMP streaming to external platforms
- **SIP Integration**: Enable SIP (Session Initiation Protocol) integration for telephony
- **Realtime Translation**: Enable real-time language translation in meetings

### Transcription & Summary

Configure transcription and domain whitelisting for your API key.

![Transcription Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.50%E2%80%AFPM.png)

**Transcription Controls:**
- **Enabled**: Toggle to enable/disable transcription and summary features
- **Whitelist Domain**: Add domain restrictions for API key usage
  - Enter domain names in the format `https://domain.name`
  - Click "Add Domain" to whitelist specific domains
  - Only whitelisted domains can use this API key
  - When no domains are whitelisted, the API key can be used from any domain


---

# App Size Optimization - Flutter

This guide is designed to help developers optimize app size, enhancing performance and efficiency across different devices. By following these best practices, you can reduce load times, minimize storage requirements, and deliver a more seamless experience to users, all while preserving essential functionality.

## Deliver Leaner Apps with App Bundles

Using Android App Bundles (AAB) is an effective way to optimize the size of your application, making it lighter and more efficient for users to download and install. App Bundles allow Google Play to dynamically generate APKs tailored to each device, so users only download the resources and code relevant to their specific configuration. This approach reduces app size significantly, leading to faster installs and conserving storage space on users’ devices.

Recommended Practices:

- `Enable App Bundles`: Configure your build to use the App Bundle format instead of APKs. This will allow Google Play to optimize your app for each device type automatically.

- `Organize Resources by Device Type`: Ensure that resources (like images and layouts) are organized by device type (such as screen density or language) to maximize the benefits of App Bundles.

- `Test Modularization`: If your app contains large, optional features, use dynamic feature modules to let users download them on demand. This reduces the initial download size and provides features only as needed.

- `Monitor Size Reductions`: Regularly analyze your app size to see where the most savings occur, and make sure that App Bundle optimizations are effectively reducing your app size across different device configurations.

## Optimize Libraries for a Leaner App Experience

Managing dependencies carefully is essential for minimizing app size and improving performance. Every library or dependency included in your app adds to its overall size, so it’s crucial to only incorporate what’s necessary. Optimizing dependencies helps streamline your app, reduce load times, and enhance maintainability.

Recommended Practices:

- `Use Only Essential Libraries`: Review all libraries and dependencies, removing any that are not critical to your app’s functionality. This helps avoid unnecessary bloat.

- `Leverage Lightweight Alternatives`: Whenever possible, choose lightweight libraries or modularized versions of larger ones. For example, opt for a specific feature module rather than including an entire library.

- `Monitor Library Updates`: Regularly update your dependencies to take advantage of any optimizations or size reductions made by the library maintainers. Newer versions are often more efficient.

- `Minimize Native Libraries`: If your app uses native libraries, ensure they’re essential and compatible across platforms, as they can significantly increase app size.

- `Analyze Dependency Tree`: Use tools like Gradle’s dependency analyzer to identify unnecessary or redundant dependencies, ensuring your app’s dependency tree is as lean as possible.

## Optimize with ProGuard

ProGuard is a powerful tool for shrinking, optimizing, and obfuscating your code, which can significantly reduce your app's size and improve performance. By removing unused code and reducing the size of classes, fields, and methods, ProGuard helps to minimize the footprint of your app without sacrificing functionality. Additionally, ProGuard’s obfuscation feature enhances security by making reverse engineering more difficult. You can refer to the official [documentation](https://developer.android.com/build/shrink-code) for more information.

Recommended Practices:

- `Enable ProGuard`: To enable ProGuard in your project, ensure that your `proguard-rules.pro` file is properly configured, and add the following lines to your `build.gradle` file:

```js title="build.gradle"
buildTypes {
    release {
        minifyEnabled true
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    }
}
```

- `Customize ProGuard Rules`: Carefully review and customize ProGuard rules in the proguard-rules.pro file to avoid stripping essential code. For example, to keep a specific class, add:

```js
-keep class com.example.myapp.MyClass { *; }
```


---

# Developer Experience Guidelines - Flutter

This section provides best practices for creating a smooth and efficient development process when working with VideoSDK. From handling errors gracefully to managing resources and event subscriptions, these guidelines help developers build more reliable and maintainable applications. Following these practices can simplify troubleshooting, prevent common pitfalls, and improve overall application performance.

### Initiate Key Features After Meeting Join Event

To provide a seamless and reliable meeting experience, initiate specific features **only** after the [roomJoined](https://docs.videosdk.live/flutter/api/sdk-reference/room-class/events#roomjoined) event has been triggered.

- **Trigger Key Actions After Joining the Meeting** : Initiating crucial actions after the `roomJoined` event helps avoid errors and optimizes the meeting setup, ensuring a smoother experience for participants. If your application utilizes any of the following features or you want to perform any action as soon as meeting joins, it's recommended to call them only after the meeting has successfully started:

    - `Chat Subscription`: To enable in-meeting chat functionality, subscribe to the chat topic after the `roomJoined` event is triggered. This ensures that messages are reliably received by participants.

    <br/>
    <div style={{textAlign: 'center'}}>

    <img src="https://cdn.videosdk.live/docs/best-practices/mobile/flutter_chat_correct_incorrect_code.png" />

    </div>

    - `Device Management`: If you need users to use specific audio or video devices when the meeting is first joined, you can utilize the custom track. Pass the `cameraId` to the [createCameraVideoTrack()](https://docs.videosdk.live/flutter/api/sdk-reference/custom-tracks#custom-video-track---flutter) method for video, and the `microphoneId` to the [createMicrophoneAudioTrack()](https://docs.videosdk.live/flutter/api/sdk-reference/custom-tracks#custom-audio-track---flutter) method for audio. Once the track is created, provide it to the [createRoom()](https://docs.videosdk.live/flutter/api/sdk-reference/videosdk-class/methods#createroom) method.

    - `Recording and Transcription`: To automatically start recording or transcription as soon as the meeting begins, configure the `autoStartConfig` in the `createMeeting` API. For detailed information, refer to the documentation [here](https://docs.videosdk.live/api-reference/realtime-communication/create-room#autoCloseConfig).

### Dispose Custom Tracks When Necessary

Proper disposal of custom tracks is essential for managing system resources and ensuring a smooth experience. In most scenarios, tracks are automatically disposed of by the SDK, ensuring efficient resource management. However, in specific cases outlined below, you will need to dispose of custom tracks explicitly:

1. **When Enabling/Disabling the Camera on a Precall Screen**:
    - If your application includes a precall screen and you want to ensure that the device's camera is not used when the camera is disabled, you must dispose of the custom video track. Otherwise, the device’s camera will continue to be used even when the camera is off.
    - Additionally, remember to create a new track when the user enables the camera again.
    - If you don’t need to manage the camera's usage on the device level (i.e., you’re okay with the camera being used whether it’s enabled or disabled), you can skip this step.
    - Here's how you can manage customTrack on a precall screen :

    <br/>
    ```js
    class _JoinScreenState extends State<JoinScreen> with WidgetsBindingObserver {
        bool isCameraOn = false;
        CustomTrack? cameraTrack;
        // Renderer to display the camera video feed
        RTCVideoRenderer? cameraRenderer;

        @override
        Widget build(BuildContext context) {
            // Build the UI components for the join screen
            //...
        }

        void toggleCamera() async {
            if (isCameraOn)
            {
                cameraTrack?.dispose(); // Dispose of cameraTrack
                setState(() {
                    cameraRenderer = null;
                    cameraTrack = null;
                    isCameraOn = false;
                });
            }
            else {
                // Create a new camera track and renderer
                CustomTrack? track = await VideoSDK.createCameraVideoTrack(
                    // passes deviceId of the user's selected device
                    cameraId: selectedVideoDevice?.deviceId
                );
                RTCVideoRenderer render = RTCVideoRenderer();
                await render.initialize();
                render.setSrcObject(
                    stream: track?.mediaStream, // Set the media stream from the camera track
                    trackId: track?.mediaStream.getVideoTracks().first.id // Set the video track ID
                );
                setState(() {
                    cameraTrack = track;
                    cameraRenderer = render;
                    isCameraOn = true;
                });
            }
        }
    }
    ```

## Listen for Error Events

Listening to error events enables your application to handle unexpected issues efficiently, providing users with clear feedback and potential solutions. Error codes pinpoint specific problems, whether from configuration settings, account restrictions, permission limitations, or device constraints. Here are recommended solutions based on common error categories:

1. [Errors associated with Organization](/flutter/api/sdk-reference/error-codes#1-errors-associated-with-organization): If you encounter errors related to your organization (e.g., account status or participant limits), reach out to support at support@videosdk.live or reach out to us on [Discord](https://discord.com/invite/Qfm8j4YAUJ) for assistance.

2. [Errors associated with Token](/flutter/api/sdk-reference/error-codes#2-errors-associated-with-token): For errors related to authentication tokens, ensure the token is valid and hasn’t expired, then try the request again.

3. [Errors associated with Meeting and Participant](/flutter/api/sdk-reference/error-codes#3-errors-associated-with-meeting-and-participant): Check that meetingId and participantId are correctly passed and valid. Also, ensure each participant has a unique participantId to avoid duplicate entries.

4. [Errors associated with Add-on Service](/flutter/api/sdk-reference/error-codes#4-errors-associated-with-add-on-service): If you encounter errors with add-on services (such as recording or streaming), try restarting the service after receiving a failure event. For example, if a `START_RECORDING_FAILED` error event occurs, attempt to call the `startRecording()` method again. If you're using webhooks, you can also retry on [recording-failed](https://docs.videosdk.live/api-reference/realtime-communication/user-webhooks#recording-failed) hook.

5. [Errors associated with Media](/flutter/api/sdk-reference/error-codes#5errors-associated-with-media): Inform the user about media access issues, such as microphone or camera permissions. Design the UI to clearly indicate what is preventing the mic or camera from enabling, helping the user understand the problem.

6. [Errors associated with Track](/flutter/api/sdk-reference/error-codes#6errors-associated-with-track): Ensure that the track you’ve created and passed to enable the mic or camera methods meets the required specifications.

7. [Errors associated with Actions](/flutter/api/sdk-reference/error-codes#7errors-associated-with-actions): If you need to perform actions as soon as a meeting joins, only initiate them after receiving the [roomJoined](https://docs.videosdk.live/android/api/sdk-reference/meeting-class/meeting-event-listener-class#onmeetingjoined) event, otherwise it will not work well.

- Here's how to listen for the error event:

```js
import 'dart:developer';

import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //Existing configuration
    
    setupVideoSDKEventListener();
    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  void setupVideoSDKEventListener() {
    VideoSDK.on(Events.error, (error) {
      log("VIDEOSDK ERROR :: ${error['code']}  :: ${error['name']} :: ${error['message']}");
    });
  }

  void setupRoomEventListener() {
    room.on(Events.error, (error) {
      log("VIDEOSDK ERROR :: ${error['code']}  :: ${error['name']} :: ${error['message']}");
    });
  }
}
```

---

# Handle Large Rooms - Flutter

Managing large meetings requires specific strategies to ensure performance, stability, and a seamless user experience. This section provides best practices for optimizing VideoSDK applications to handle high participant volumes effectively. By implementing these recommendations, you can reduce lag, maintain video and audio quality, and provide a smooth experience even in large rooms.

## User Interface Optimization

When hosting large meetings, an optimized UI helps manage participant visibility and ensures smooth performance.

Recommended Practices:

- `Limit Visible Participants`: Display only a limited number of participants on screen at any given time, adapting the view based on screen size. Use pagination to allow users to browse or switch between additional participants seamlessly. For example, you could display only users whose video stream is enabled, or you could choose to display all active speakers. This approach helps manage screen space efficiently, ensuring that the most relevant participants are visible without overwhelming the interface.
- `Prioritize Active Speakers`: Ensure all active speakers are displayed on the screen to highlight who is currently talking, helping participants stay engaged and aware of ongoing discussions. To identify which participant is speaking, you can use the [speakerChanged](https://docs.videosdk.live/flutter/api/sdk-reference/room-class/events#speakerchanged) event.

## Optimizing Media Streams 

In large video calls, it’s important to manage media streams effectively to optimize system resources while maintaining a smooth user experience. 

Recommended Practices:

- `Pause Streams for Non-Visible Participants`: To optimize performance, pause the video and/or audio streams of participants who are not currently visible on the screen. This reduces unnecessary resource consumption.
- `Resume Streams When Visible`: Once a participant comes into view, resume their stream to provide an uninterrupted experience as they appear on the screen.

For detailed setup instructions on how to achieve this, check out our in-depth documentation [here](https://docs.videosdk.live/flutter/guide/video-and-audio-calling-api-sdk/render-media/layout-and-grid-management#grid-with-pagination).

## Media Stream Quality Adjustment

In large meetings, managing media stream quality is essential to balance performance and user experience. 

Recommended Practices:

- `High Quality for Active Speakers`: For all active speakers, set the video stream quality to a higher level using the setQuality method (e.g., `setQuality("high")`). This ensures that participants will receive higher-quality video for active speakers, providing a clearer and more engaging experience.
- `Lower Quality for Non-Speaking Participants`: For other participants who are not actively speaking, set their video stream quality to a lower level (e.g., `setQuality("low")`). This helps conserve bandwidth and system resources while maintaining overall meeting performance.

Checkout the documentation for `setQuality()` method [here](https://docs.videosdk.live/flutter/api/sdk-reference/participant-class/methods#setquality) 

---

# User Experience Guidelines - Flutter

This guide aims to help developers optimize the user experience and functionality of video conferencing applications with VideoSDK. By following these best practices, you can create smoother interactions, minimize common issues, and deliver a more reliable experience for users.

Here are our recommended best practices to enhance the user experience in your application:

| **Section**                          | **Description**                                                                                                                                                      |
|--------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Configure Precall for Effortless Meeting Join](#configure-precall-for-effortless-meeting-join) | Users may enter meetings unprepared due to device or connection issues. A Precall setup can help them configure devices and settings beforehand for a smooth start. |
| [Listen Key Events for Optimal User Experience](#listen-key-events-for-optimal-user-experience) | Users can feel lost without real-time updates on meeting status, events, and errors. Event monitoring and notifications keep them informed and engaged.              |
| [Handling Media Devices](#handling-media-devices)                                             | Users may want to change their audio or video setup mid-meeting but struggle to manage device controls. Providing easy device switching enhances control and flexibility. |
| [Monitoring Real-Time Participant Statistics](#monitoring-real-time-participant-statistics)   | Poor video or audio quality without real-time feedback leaves users frustrated. Real-time stats let them assess connection quality and troubleshoot issues actively.    |

## Configure Precall for Effortless Meeting Join

A Precall step is crucial for ensuring users are set up correctly and have no device before joining a meeting. This step allows users to configure their devices and settings before entering a meeting, leading to a smoother experience and minimizing technical issues once the call begins.

Recommended Practices:

- `Request Permissions`: Prompt users to grant microphone, and camera permissions before entering the meeting, ensuring seamless access to their devices.
- `Device Selection`: Allow users to select their preferred camera, and microphone giving them control over their setup from the start.
- `Entry Preferences`: Provide options to join with the microphone and camera either on or off, letting users choose their level of engagement upon entry.
- `Camera Preview`: Show a live camera preview, allowing users to adjust angles and lighting to ensure they appear clearly and professionally.
- `Virtual Backgrounds`: Allow users to choose from different virtual backgrounds or enter with a virtual background enabled, enhancing privacy and creating a more polished appearance.

For detailed setup instructions on each of these features, check out our in-depth documentation [here](https://docs.videosdk.live/flutter/guide/video-and-audio-calling-api-sdk/setup-call/precall).

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_precall.gif" />

</div>

## Monitor Key Events for Optimal User Experience

Listening for crucial events is vital for providing users with a responsive and engaging experience in your application. By effectively managing state changes and user notifications, you can keep participants informed and enhance their overall experience during meetings.

Recommended Practices:

- `Monitor State Change Events`: Listen for state change events, such as `Events.recordingStateChanged`, and notify users promptly about these transitions. Keeping users informed helps them understand the current state of the meeting.

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_meeting_state.jpg" />

</div>

- `UI Handling on Event Trigger`: Update the user interface only in response to specific events. For instance, display that the meeting is recording only when the `recordingStateChanged` event with the status `RECORDING_STARTED` is received, rather than when the record button is clicked. This ensures users receive accurate and timely updates.

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_recording.gif" />

</div>

- `Notify Participants of Join/Leave Events`: Keep users informed about participant activity by notifying them when someone joins or leaves the meeting. This fosters a sense of presence and awareness of who is currently available to engage.
- `Listen for Error Events`: It is crucial to monitor error events and notify users promptly when issues arise. Clear communication about errors can help users troubleshoot and address problems quickly, minimizing disruptions to the meeting.


## Handling Media Devices

Providing seamless control over devices enhances user convenience and allows participants to adjust their setup for the best meeting experience. Proper device management within the UI also helps users stay informed about their current settings and troubleshoot issues effectively.

Recommended Practices:

- `Allow Device Switching`: Provide users with the option to switch between available microphone, and camera devices during the meeting. This flexibility is essential, especially if users want to adjust their setup mid-call.
- `Display Selected Devices`: Ensure the UI shows users which microphone, and camera devices are currently selected. Clear device labeling in the interface can reduce confusion and help users verify their setup at a glance.

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_audio_selected_device.jpg" />

</div>

## Monitoring Real-Time Participant Statistics

Providing real-time insights into stream quality allows participants to monitor and optimize their connection for the best experience. With detailed metrics on video, audio, and screen sharing, users can assess and troubleshoot quality issues, ensuring smooth and uninterrupted meetings. To display these statistics, you can use the [getVideoStats()](https://docs.videosdk.live/flutter/api/sdk-reference/participant-class/methods#getvideostats), [getAudioStats()](https://docs.videosdk.live/flutter/api/sdk-reference/participant-class/methods#getaudiostats), and [getShareStats()](https://docs.videosdk.live/flutter/api/sdk-reference/participant-class/methods#getsharestats) methods.


<div style={{textAlign: 'center'}}>



</div>

<br/>



---

# Chat during Live Stream - Flutter

Enhance your live stream experience by enabling real-time audience chat using VideoSDK's `PubSub` class. Whether you’re streaming a webinar, online event, or an interactive session, integrating a chat system lets your viewers engage, ask questions, and react instantly. This guide shows how to build a group or private chat interface for a live stream using the Publish-Subscribe (PubSub) mechanism.

This guide focuses on using PubSub to implement Chat functionality. If you are not familiar with the PubSub mechanism and `PubSub` class, you can [follow this guide](/flutter/api/sdk-reference/pubsub-class/methods).

## Implementing Chat

### `Group Chat`(Public Chat for All Viewers)

1. First step in creating a group chat is choosing the topic which all the participants will publish and subscribe to send and receive the messages. We will be using `CHAT` as the topic for this one. So let us lets create a message input and send button to publish the messages using the `pubSub` from the `Room` object.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ChatView extends StatefulWidget {
  final Room room;
  ...
}

class _ChatViewState extends State<ChatView> {

  final msgTextController = TextEditingController();


  @override
  void initState() {
    //highlight-next-line
    ...

    //highlight-start
    // Subscribing 'CHAT' Topic
    widget.meeting.pubSub
      .subscribe("CHAT", messageHandler)
      .then((value) => setState((() => messages = value)));
    //highlight-end
  }

  //highlight-start
  //Handler which will be called when new mesasge is received
  void messageHandler(PubSubMessage message) {
    setState(() => messages!.messages.add(message));
  }
  //highlight-end

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        Row(
          children: [
            Expanded(
              child: TextField(
                style: TextStyle(
                  fontSize:16,
                  fontWeight: FontWeight.w500,
                ),
                controller: msgTextController,
                onChanged: (value) => setState(() {
                  msgTextController.text;
                }),
                decoration: const InputDecoration(
                  hintText: "Write your message",
                  border: InputBorder.none,
                ),
              ),
            ),
            ElevatedButton(
              onPressed:(){
                if(!msgTextController.text.trim().isEmpty){
                  widget.room.pubSub
                        .publish(
                          "CHAT",
                          msgTextController.text,
                          const PubSubPublishOptions(
                              persist: true),
                        )
                        .then(
                            (value) => msgTextController.clear())
                }
              },
              child: const Text("Send Message"),
            ),
          ],
        ),
    //highlight-end
      ]
    );
  }

}
```

2. Final step in the group chat would be to display the messages others send. For this will use the `messages` and display all the messages by subscribing to the topic `CHAT`.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ChatView extends StatefulWidget {
  final Room room;
  ...
}

class _ChatViewState extends State<ChatView> {

  // PubSubMessages
  PubSubMessages? messages;

  @override
  void initState() {
    //highlight-next-line
    ...

    //highlight-start
    // Subscribing 'CHAT' Topic
    widget.meeting.pubSub
      .subscribe("CHAT", messageHandler)
      .then((value) => setState((() => messages = value)));
    //highlight-end
  }

  //highlight-start
  //Handler which will be called when new mesasge is received
  void messageHandler(PubSubMessage message) {
    setState(() => messages!.messages.add(message));
  }
  //highlight-end

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        Expanded(
          child: messages == null
              ? const Center(child: CircularProgressIndicator())
              : SingleChildScrollView(
                  reverse: true,
                  child: Column(
                    children: messages!.messages
                        .map(
                          (message) => Text(
                            message.message
                          ),
                        )
                        .toList(),
                  ),
                ),
        ),

        ...
        //Send Message code Here
    //highlight-end
      ]
    );
  }

  @override
  void dispose() {
    //highlight-start
    // Unsubscribe
    widget.room.pubSub.unsubscribe("CHAT", messageHandler);
    //highlight-end
    super.dispose();
  }
}
```

### `Private Chat` (1:1 between Host and Viewer)

Private messaging is ideal when a host or moderator needs to directly respond to a viewer’s question. This can be achieved using the `sendOnly`parameter in `PubSubPublishOptions`.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ChatView extends StatefulWidget {
  final Room room;
  ...
}

class _ChatViewState extends State<ChatView> {

  //...

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        Row(
          children: [
            Expanded(
              child: TextField(
                style: TextStyle(
                  fontSize:16,
                  fontWeight: FontWeight.w500,
                ),
                controller: msgTextController,
                onChanged: (value) => setState(() {
                  msgTextController.text;
                }),
                decoration: const InputDecoration(
                  hintText: "Write your message",
                  border: InputBorder.none,
                ),
              ),
            ),
            ElevatedButton(
              onPressed:(){
                if(!msgTextController.text.trim().isEmpty){
                  //highlight-start
                  // Pass the participantId of the participant to whom you want to send the message.
                  widget.room.pubSub
                        .publish(
                          "CHAT",
                          msgTextController.text,
                          const PubSubPublishOptions(
                            persist: true, sendOnly: ["xyz"]),
                        )
                        .then(
                            (value) => msgTextController.clear())
                  //highlight-end
                }
              },
              child: const Text("Send Message"),
            ),
          ],
        ),
      ]
    );
  }

}
```

### Displaying Latest Message Notificaiton


You may want to show the notification to the user when new message arrives. So lets continue our example and add alert for the new images.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ChatView extends StatefulWidget {
  final Room room;
  ...
}

class _ChatViewState extends State<ChatView> {

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  //highlight-start
  //Handler which will be called when new mesasge is received
  void messageHandler(PubSubMessage message) {
    //Show snackbar on new message
    if(context.mounted){
      ScaffoldMessenger.of(context).showSnackBar(SnackBar(
        content: Text(
          message.message,
          overflow: TextOverflow.fade,
        ),
      ));
    }
    setState(() => messages!.messages.add(message));
  }
  //highlight-end

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ...
         //highlight-end
      ]
    );
  }

  @override
  void dispose() {
    //highlight-next-line
    ...
  }
}
```

## Downloading Chat Messages

All the messages from the PubSub which where published with `persist : true` and can be downloaded as an `.csv` file. This file will be available in the VideoSDK dashboard as well as throught the [Sessions API](/api-reference/realtime-communication/fetch-session-using-sessionid).

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub](/flutter/api/sdk-reference/pubsub-class/introduction)

---

# Cloud Proxy - Flutter


Our SDK features a Cloud Proxy that allows you to manage how your streaming content is routed through different network paths. This feature ensures compliance with various regional internet regulations by restricting traffic to specified proxy servers, based on your needs and the geographical location of users.

This capability is crucial for adhering to local data protection laws and optimizes the streaming experience by overcoming geographical network constraints. By directing user connections to appropriate regional servers, Cloud Proxy enhances overall service performance and reliability.

Cloud Proxy offers three straightforward operating modes to fit different business and firewall requirements:

- **UDP_OVER_TCP (Default)**: In this mode, the connection starts by attempting to establish a UDP connection for media transmission. If that fails, it will automatically shifts to a secure TCP connection, which is compatible with most firewalls.

- **Force UDP**: This mode uses only UDP to send media, ensuring high-quality streams. It's ideal for environments where media quality is critical and the firewall can be configured accordingly.

- **Force TCP**: Only uses TCP for secure media transmission, suitable for strict firewall settings that only permit TCP traffic over centain ports. This might require additional firewall configuration and could affect media quality under poor network conditions.




### In this sequence diagram:
- Client to Proxy Server: The client sends a request to the proxy server, which processes and forwards it based on predefined rules.
- Proxy Server to Destination Server: The proxy server sends the request to the destination server, receives the response, and relays it back to the client.

:::info

Cloud Proxy is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Implementation

```js
Room room = VideoSDK.createRoom(
  roomId: "<ROOM-ID>",
  token: "<TOKEN>",
  displayName: "<DISPLAY-NAME>",
  preferredProtocol: PreferredProtocol.UDP_ONLY,
  signalingBaseUrl: "proxy.yourwebsite.com"
);
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [createRoom](/flutter/api/sdk-reference/videosdk-class/methods#createroom)

---

# Concept and Architecture - Flutter

Before diving into the concept, let's understand the VideoSDK, VideoSDK is a software development kit that offers tools and APIs for creating apps that are based on video and audio. It typically includes features such as video and audio calls, chat, cloud recording, simulcasting (RTMP), interactive live streaming (HLS), and many more across a wide range of platforms and devices.

## Concepts

![img.png](../../../../static/img/room-concept.png)

### `1. Meeting / Room`

- Meeting or Room objects in the VideoSDK provide a virtual place for participants to interact and engage in real-time voice, video, and screen-sharing sessions. The object is in charge of handling media streams and participant communication.

- Meeting or Room can be uniquely identified by `meetingId` or `roomId`.

### `2. Participant`

- Participant is a VideoSDK object that represents each user/client in the meeting or room and allows them to share audio/video assets.

- `2.1 Local Participant` :
  The local participant is the one that runs on the user's device. The local participant has control over their own media streams, including the ability to start and stop audio and video.

  - The local participant in a meeting/room can also connect with other participants by transmitting and receiving audio and video streams, exchanging chat messages, and more.

- `2.2 Remote Participant` :
  The remote participant receives audio and video streams from the local participant and other remote participants and also has the ability to exchange audio, video, and chat messages with the local participant.

- Each participant in VideoSDK can be uniquely identified by `participantId`.

### `3. MediaStream & Track`

- A mediastream is a collection of audio & video tracks that can be transmitted between participants in real-time.

- A track is a continuous flow of audio or video data and can be thought of as a stream of media frames.

- A mediastream can contain multiple tracks. One video track for the video feed from the camera and one audio track for the audio feed from the microphone. These tracks can be transmitted between participants in VideoSDK Meeting / Room.

### `4. Events / Notifications`

- Events / Notifications can be used to inform users about various activities happening in a Meeting / Room, including participant join/leave and new messages. They can also be used to alert users about any SDK-level errors that occur during a call.

---

### `5. Session`

- A Session is the instance of an ongoing meeting/room which has one or more participants in it. A single room or meeting can have multiple sessions.
- Each session can be uniquely identified by `sessionId`.

![img.png](../../../../static/img/meeting-session.jpg)

---

![img.png](../../../../static/img/recording-hls-rtmp.png)

### `6. Cloud Recording`

- Cloud recording in VideoSDK refers to the process of recording audio or video content and storing it on a remote server or VideoSDK server.

### `7. Simulcasting (RTMP)`

- RTMP is a popular protocol for live streaming video content from a VideoSDK to platforms such as YouTube, Twitch, Facebook, and others.
- By providing the platform-specific `stream key` and `stream URL`, the VideoSDK can connect to the platform's RTMP server and transmit the live video stream.

### `8. Http Live Streaming (HLS)`

- Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

- In an interactive live stream (HLS), viewers can take part in a variety of activities like live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

## Architecture

This diagram demonstrates end-to-end flow to implement video & audio calls, record calls, and go live on social media.

![Video-sdk-architecture!](/img/video-sdk-archietecture.svg)


---

# Custom Audio Sources - Flutter

For a high-quality streaming experience, fine-tuning audio tracks becomes essential—especially when delivering content to a broader live audience.

To enhance your live audio pipeline, we've introduced the capability to provide a custom audio track for a hosts's stream both before and during a live session.


## Custom Audio Track

This feature allows you to integrate advanced audio layers like background noise suppression, echo cancellation, and more—so your stream sounds polished and professional to every viewer.

### `How to Create a Custom Audio Track ?`

- You can create a Audio Track using `createMicrophoneAudioTrack()` method of `VideoSDK` class.
- This method can be used to create audio track using different encoding parameters and noise cancellation configuration.

### Example 

```js
CustomTrack? audioTrack = await VideoSDK.createMicrophoneAudioTrack(
        encoderConfig: CustomAudioTrackConfig.high_quality);
```

Here are different configurations for customizing audio tracks based on specific use cases:

- `speech_standard` : This config is optimised for normal voice communication.
- `high_quality` : This config is used for obtaining RAW audio, allowing you to apply your `noiseConfig`.
- `music_standard` : This config is optimised for communication scenarios, where the sharing of musical elements, such as songs or instrumental sounds, is crucial.

### `How to Setup Custom Audio Track ?`

You can plug in your custom audio track either before going live or dynamically while the session is ongoing.

1. [Setup during live stream initialization](/react/guide/interactive-live-streaming/custom-media-sources/custom-audio-sources#1-setup-during-live-stream-initialization)
2. [Setup dynamically using methods](/react/guide/interactive-live-streaming/custom-media-sources/custom-audio-sources#2-setup-dynamically-using-methods)

##### 1. Setup during live stream initialization

If you are passing `micEnabled: true` in the `createRoom` and want to use custom tracks from start of the livestream, you can pass custom track in the `createRoom` as shown below.

```javascript
CustomTrack? audioTrack = await VideoSDK.createMicrophoneAudioTrack(
        encoderConfig: CustomAudioTrackConfig.high_quality);

Room room = VideoSDK.createRoom(
      roomId: widget.livestreamId,
      token: widget.token,
      displayName: widget.displayName,
      micEnabled: widget.micEnabled,
      camEnabled: widget.camEnabled,
      maxResolution: 'hd',
      defaultCameraIndex: 1,
      multiStream: false,

      // Pass the custom track here
      customMicrophoneAudioTrack: audioTrack, // custom audio track :: optional
      notification: const NotificationInfo(
        title: "Video SDK",
        message: "Video SDK is sharing screen in the livestream",
        icon: "notification_share", // drawable icon name
      ),
    );
```
#### 2. Setup dynamically using methods

In order to switch tracks during the livestream, you have to pass the `CustomTrack` in the `room.unmuteMic()` method.

:::note

Make sure to call `muteMic()` before you create a new track as it may lead to unexpected behavior.

:::

```javascript
CustomTrack? audioTrack = await VideoSDK.createMicrophoneAudioTrack(
        encoderConfig: CustomAudioTrackConfig.high_quality);

room.unmuteMic(customTrack);
```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [Custom Audio Track](/flutter/api/sdk-reference/videosdk-class/methods#createmicrophoneaudiotrack)



---

# Custom Video Sources - Flutter

## Custom Video Track

In a livestream, your webcam feed plays a central role. With custom video tracks, you can:
- Define the resolution and frame rate using encoder settings
- Select optimization modes that suit your stream content (e.g., motion for dynamic scenes, text for documents).
- Apply real-time background effects or filters using libraries like [videosdk-media-processor](https://www.npmjs.com/package/@videosdk.live/videosdk-media-processor-web)
- Stream directly from custom MediaStreams, including canvas or virtual backgrounds.


### `How to Create a Custom Video Track ?`

- You can create a Video Track using `createCameraVideoTrack()` method of `VideoSDK` class.
- This method can be used to create video track using different encoding parameters, camera facing mode, and optimization mode.

```javascript
CustomTrack? videoTrack = await VideoSDK.createCameraVideoTrack(
      encoderConfig: CustomVideoTrackConfig.h1440p_w1920p,
      multiStream: false,
      facingMode:"user",
    );
```

:::caution
The behavior of custom track configurations is influenced by the capabilities of the device. For example, if you set the encoder configuration to 1080p but the webcam only supports 720p, the encoder configuration will automatically adjust to the highest resolution that the device can handle, which in this case is 720p.
:::

##### What is `optimizationMode`?

- This parameter specifies the optimization mode for the video track being generated.
- `motion` : This type of track focuses more on motion video such as webcam video, movies or video games.
  - It will degrade `resolution` in order to maintain `frame rate`.
- `text` : This type of track focuses on significant sharp edges and areas of consistent color that can change frequently such as presentations or web pages with text content.
  - It will degrade `frame rate` in order to maintain `resolution`.
- `detail` : This type of track focuses more on the details of the video such as, presentations, painting or line art.
  - It will degrade `frame rate` in order to maintain `resolution`.

##### What is `multiStream`?

- By enabling multiStream, your livestream will broadcast multiple resolutions (e.g., 720p, 480p, 360p), allowing viewers to receive the best stream quality based on their network.
The **`multiStream : true`** configuration indicates that VideoSDK, by default, sends multiple resolution video streams to the server. For example, if a user's device capability is 720p, VideoSDK sends streams in 720p, 640p, and 480p resolution. This enables VideoSDK to deliver the appropriate stream to each participant based on their network bandwidth.


<center>

![Multi Stream False](/img/multistream_true.png)

</center>

Setting **`multiStream : false`** restricts VideoSDK to send only one stream, helping to maintain quality by focusing on a single resolution.

<center>

![Multi Stream False](/img/multistream_false.png)

</center>

:::danger
The `setQuality` parameter will not have any effect if multiStream is set to `false`.
:::

### `How to Setup a Custom Video Track ?`

You can plug in your custom video track either before going live or dynamically while the session is ongoing.

1. [Setup during live stream initialization](/react/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track#1-setup-during-live-stream-initialization)
2. [Setup dynamically using methods](/react/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track#2-setup-dynamically-using-methods)

##### 1. Setting up a Custom Track during the initialization of a livestream

If you are passing `webcamEnabled: true` in the `createRoom` and want to use custom tracks from start of the livestream, you can pass custom track in the `createRoom` params as shown below.

```javascript
CustomTrack? videoTrack = await VideoSDK.createCameraVideoTrack(
      encoderConfig: CustomVideoTrackConfig.h1440p_w1920p,
      multiStream: false,
      facingMode:"user",
    );

Room room = VideoSDK.createRoom(
      roomId: widget.livestreamId,
      token: widget.token,
      displayName: widget.displayName,
      micEnabled: widget.micEnabled,
      camEnabled: widget.camEnabled,
      maxResolution: 'hd',
      defaultCameraIndex: 1,
      multiStream: false,

      // Pass the custom track here
      customCameraVideoTrack: videoTrack, // custom video track :: optional
      notification: const NotificationInfo(
        title: "Video SDK",
        message: "Video SDK is sharing screen in the livestream",
        icon: "notification_share", // drawable icon name
      ),
    );
```

#### 2. Setting up a Custom Track with methods

In order to switch tracks during the livestream, you have to pass the `CustomTrack` in the `room.enableCam()` method.

:::note

Make sure to call `disableCam()` before you create a new track as it may lead to unexpected behavior.

:::

```javascript
CustomTrack? track = await VideoSDK.createCameraVideoTrack(
  facingMode: "environment",
  encoderConfig: CustomVideoTrackConfig.h1440p_w1920p,
  multiStream: true,
);
room.enableCam(track);
```

:::info
Using custom video tracks is not just limited to the video tracks created using the `createCameraVideoTrack` method. You can use any `MediaStream` object as a replacement, including a [custom canvas track created by you](https://developer.chrome.com/blog/capture-stream/).
:::

### `Which configuration is suitable for me ?`

In this section, the focus is on understanding participant size and platform-wise `encoder(Resolution)` and `multiStream` configuration.

##### 1. For Desktop Browser

![web_browser](/img/web_browser.png)

##### 2. For Mobile Browser

![web_browser](/img/mobile_browser.png)

##### 3. For Desktop + Mobile Browser

![web_browser](/img/mobile+web.png)


## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [Custom Video Track](/flutter/api/sdk-reference/videosdk-class/methods#createcameravideotrack)

---

# Customized Live Stream - Flutter

VideoSDK is a platform that offers a range of video streaming tools and solutions for content creators, publishers, and developers.

## Custom Template

- Custom template is template for live stream, which allows users to add real-time graphics to their streams.
- With custom templates, users can create unique and engaging video experiences by overlaying graphics, text, images, and animations onto their live streams. These graphics can be customized to match the branding.
- Custom templates enable users to create engaging video content with real-time graphics, with live scoreboards, social media feeds, and other customizations, users can easily create unique and visually appealing streams that stands out from the crowd.

:::note

Custom templates can be used with recordings and RTMP service provided by VideoSDK as well.

:::

### What you can do with Custom Template

Using a custom template, you may create a variety of various modes. Here are a few of the more well-known modes that you can create.

- **`PK Host:`** Host can organise player vs player battle. Below image is example of gaming battle.

- **`Watermark:`** Host can add & update watermark anywhere in the template. In below image we have added VideoSDK watermark on top right side of the screen.

- **`News Mode:`** Host can add dynamic text in lower third banner. in below image we have added some sample text in bottom left of the screen.

![Mobile Custom Template](https://cdn.videosdk.live/website-resources/docs-resources/mobile_custom_template.png)

### Custom template with VideoSDK

In this section, we will discuss how Custom Templates work with VideoSDK.

- **`Host`**: The host is responsible for starting the live streaming by passing the `templateURL`. The `templateURL` is the URL of the hosted template webpage. The host is also responsible for managing the template, such as changing text, logos, and switching template layout, among other things.

- **`VideoSDK Template Engine`** : The VideoSDK Template Engine accepts and opens the templateURL in the browser. It listens to all the events performed by the Host and enables customization of the template according to the Host's preferences.

- **`Viewer`**: The viewer can stream the content. They can watch the live stream with the added real-time graphics, which makes for a unique and engaging viewing experience.

![custom template](https://cdn.videosdk.live/website-resources/docs-resources/custom_template.png)

### Understanding Template URL

The template URL is the webpage that VideoSDK Template Engine will open while composing the live stream.

The template URL will appear as shown below.

![template url](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_url.png)

The Template URL consists of two parts:

- Your actual page URL, which will look something like `https://example.com/videosdk-template`.
- Query parameters, which will allow the VideoSDK Template Engine to join the meeting when the URL is opened. There are a total of three query parameters:
  - `token`: This will be your token, which will be used to join the meeting.
  - `meetingId`: This will be the meeting ID that will be joined by the VideoSDK Template Engine.
  - `participantId`: This will be the participant ID of the VideoSDK Template Engine, which should be passed while joining the template engine in your template so that the tempalte engine participant is not visible to other participants. **This parameter will be added by the** **VideoSDK**.

:::info

Above mentioned query parameters are mandatory. Apart from these parameters, you can pass any other extra parameters which are required according to your use-case.

:::

### **Creating Template**

**`Step 1:`** Create a new React App using the below command

```js
npx create-react-app videosdk-custom-template
```

:::note

You can use VideoSDK's React or JavaScript SDK to create custom template. Following is the example of building custom template with React SDK.

:::

**`Step 2:`** Install the VideoSDK using the below-mentioned npm command.

Make sure you are in your react app directory before you run this command.

```js
npm install "@videosdk.live/react-sdk"

//For the Participants Video
npm install "react-player"
```

###### App Architecture

![template architechture](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_arch.png)

###### Structure of the Project

```jsx title="Project Structure"
   root
   ├── node_modules
   ├── public
   ├── src
   │    ├── components
   │          ├── MeetingContainer.js
   │          ├── ParticipantsAudioPlayer.js
   │          ├── ParticipantsView.js
   │          ├── Notification.js
   │    ├── icons
   │    ├── App.js
   │    ├── index.js
   ├── package.json
   .
```

**`Step 3:`** Next we will fetch the query parameters, from the URL which we will later use to initialize the meeting

```js title=App.js
function App() {
  const { meetingId, token, participantId } = useMemo(() => {
    //highlight-start
    const location = window.location;

    const urlParams = new URLSearchParams(location.search);

    const paramKeys = {
      meetingId: "meetingId",
      token: "token",
      participantId: "participantId",
    };

    Object.keys(paramKeys).forEach((key) => {
      paramKeys[key] = urlParams.get(key)
        ? decodeURIComponent(urlParams.get(key))
        : null;
    });

    return paramKeys;
    //highlight-end
  }, []);
}
```

**`Step 4:`** Now we will initialize the meeting with the parameters we extracted from the URL. Make sure `joinWithoutUserInteraction` is specified, so that the template engine is able to join directly into the meeting, on the page load.

```js title=App.js
function App(){
//highlight-next-line
...

return meetingId && token && participantId ? (
  <div>
    
    </MeetingProvider>
  </div>
) : null;

}
```

**`Step 5:`** Let us create the `MeetingContainer` which will render the meeting view for us.

- It will also listen to the PubSub messages from the `CHANGE_BACKGROUND` topic, which will change the background color of the meeting.
- It will have `Notification` component which will show any messages share by Host

:::note

We will be using the PubSub mechanism to communicate with the template. You can learn more about [PubSub from here](../video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

:::

```js title=MeetingContainer.js




export const MeetingContainer = () => {
  const { isMeetingJoined, participants, localParticipant } = useMeeting();
  //highlight-next-line
  const { messages } = usePubSub("CHANGE_BACKGROUND");

  const remoteSpeakers = [...participants.values()].filter((participant) => {
    return participant.mode == Constants.modes.SEND_AND_RECV && !participant.local;
  });

  return isMeetingJoined ? (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        height: "100vh",
        //highlight-start
        backgroundColor:
          messages.length > 0
            ? messages.at(messages.length - 1).message
            : "#fff",
        //highlight-end
      }}
    >
      //highlight-next-line
      
      <div
        style={{
          display: "grid",
          gridTemplateColumns: remoteSpeakers?.length > 1 ? "1fr 1fr" : "1fr",
          flex: 1,
          maxHeight: `100vh`,
          overflowY: "auto",
          gap: "20px",
          padding: "20px",
          alignItems: "center",
          justifyItems: "center",
        }}
      >
        {[...remoteSpeakers].map((participant) => {
          return (
            //highlight-start
            
            //highlight-end
          );
        })}
      </div>
      //highlight-next-line
      
    </div>
  ) : (
    <div
      style={{
        display: "flex",
        justifyContent: "center",
        alignItems: "center",
        height: "100vh",
      }}
    >
      <div class="loader"></div>
    </div>
  );
};
```

**`Step 6:`** Let us create the `ParticipantView` and `ParticipantsAudioPlayer` which will render the video and audio of the participants respectively.

```js title=ParticipantView.js




export const ParticipantView = (props) => {
  const { webcamStream, webcamOn, displayName, micOn } = useParticipant(
    props.participantId
  );

  const videoStream = useMemo(() => {
    if (webcamOn && webcamStream) {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(webcamStream.track);
      return mediaStream;
    }
  }, [webcamStream, webcamOn]);

  return (
    <div
      style={{
        width: "100%",
        height: "400px",
        maxWidth: "600px",
        display: "flex",
        flex: 1,
        alignItems: "center",
        justifyContent: "center",
        position: "relative",
        backgroundColor: "#1A1C22",
        borderRadius: "10px",
        overflow: "hidden",
      }}
      class="video-cover"
    >
      {webcamOn && webcamStream ? (
        
      ) : (
        <div
          style={{
            fontSize: "50px",
            color: "#fff",
          }}
        >
          {String(displayName).charAt(0).toUpperCase()}
        </div>
      )}
      <div
        style={{
          position: "absolute",
          left: "10px",
          bottom: "10px",
          backgroundColor: "#050A0E",
          color: "#fff",
          padding: "4px",
          borderRadius: "4px",
          alignItems: "center",
          justifyItems: "center",
          display: "flex",
        }}
      >
        {displayName}{" "}
        {!micOn && }
      </div>
    </div>
  );
};
```

```js title=ParticipantsAudioPlayer.js


const ParticipantAudio = ({ participantId }) => {
  const { micOn, micStream, isLocal } = useParticipant(participantId);
  const audioPlayer = useRef();

  useEffect(() => {
    if (!isLocal && audioPlayer.current && micOn && micStream) {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(micStream.track);

      audioPlayer.current.srcObject = mediaStream;
      audioPlayer.current.play().catch((err) => {});
    } else {
      audioPlayer.current.srcObject = null;
    }
  }, [micStream, micOn, isLocal, participantId]);

  return <audio autoPlay playsInline controls={false} ref={audioPlayer} />;
};

export const ParticipantsAudioPlayer = () => {
  const mMeeting = useMeeting();

  const participants = mMeeting?.participants;

  return participants ? (
    [...participants.keys()].map((participantId) => (
      
    ))
  ) : (
    <></>
  );
};
```

**`Step 7:`** Let us create the `Notification` component which will listen to PubSub messages for the topic `SIGNALLING_ONLY_MESSAGE` and show a notification on the lower left corner.

```js title=Notification.js


export const Notification = () => {
  const timeoutRef = useRef(null);
  const handleChatMessage = (msg) => {
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
    }
    setMessage(msg);
    timeoutRef.current = setTimeout(() => {
      setMessage(null);
    }, 3200);
  };
  const [message, setMessage] = useState(null);
  const { publish } = usePubSub("SIGNALLING_ONLY_MESSAGE", {
    onMessageReceived: handleChatMessage,
  });
  useEffect(() => {
    return () => {
      if (timeoutRef.current) {
        clearTimeout(timeoutRef.current);
      }
    };
  }, []);
  return message ? (
    <div
      style={{
        backgroundColor: "#232830",
        padding: "10px",
        textAlign: "center",
        color: "#fff",
        position: "absolute",
        bottom: "50px",
        left: "30px",
        borderRadius: "10px",
        animation: "fadein 0.5s",
      }}
    >
      <strong>
        {message.senderName} says {message.message}
      </strong>
    </div>
  ) : null;
};
```

:::note

For the CSS stylings and animations used in the project, please [refer to this file](https://github.com/videosdk-live/quickstart/blob/main/react-custom-template-manager/src/index.css).

:::

**`Step 9:`** Once tested, you can deploy it using your backend or host it on services like [firebase](https://www.geeksforgeeks.org/how-to-deploy-react-project-on-firebase/) or vercel.

:::tip

You can checkout the github repository for sample custom template we just [created here](https://github.com/videosdk-live/videosdk-custom-recording-template-react-example).

:::

### Setup Livestream Using Custom Template

- To use Custom Template, you will need Host and Viewer setup from where the host will start the livestream and viewer can watch them.

![Flutter Custom Template Example](https://cdn.videosdk.live/website-resources/docs-resources/flutter_custom_template.png)

- You can clone this example and run it on your system.

```bash
git clone https://github.com/videosdk-live/quickstart.git
```

- The cloned example will have a directory `flutter-custom-template-manager` which has to runned.

```js
cd flutter-custom-template-manager
flutter pub get
flutter run
```

- To use the custom template which we just deployed, we will call the [Start HLS API](https://docs.videosdk.live/api-reference/realtime-communication/start-hlsStream) instead of the `startHls` method from the `Room` class. This code has already been added in the example you cloned.

```js
void startHls() async {
  //Update your Custom Template URL here if you have deployed your own, if not deployed you can use this template from our URL.
    //highlight-start
  String templateUrl =
      'https://lab.videosdk.live/react-custom-template-demo?meetingId=${widget.room.id}&token=${token}';
  //highlight-end
  final body = utf8.encode(
    json.encode(
      

</div>

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start HLS API](/api-reference/realtime-communication/start-hlsStream)
- [Events.hlsStateChanged](/flutter/api/sdk-reference/room-class/events#hlsstatechanged)


---

# Manage Audio and Video Devices - Flutter

This feature allows hosts to switch their microphone, speaker, or camera devices during a live stream. Only hosts (in `SEND_AND_RECV` mode) can change input/output devices, ensuring they maintain control over their audio and video quality, while audience members (in `RECV_ONLY` mode) continue to receive the broadcast seamlessly.

### Changing Audio Input Device

During the livestream at any point a host wishes to switch his/her input audio device, it can be done using the below mentioned methods.

:::important
This feature is only available on the **Web** and **Desktop**; if you want to use it on **Mobile**, please refer [this guide](/flutter/guide/interactive-live-streaming/device-management/change-devices#changing-audio-output-device).
:::

### `getAudioDevices()`

- The `getAudioDevices()` method will help you to list down all possible connected audio input devices which will return a list of `AudioDeviceInfo` objects.

- The `AudioDeviceInfo` object will contain the `deviceId` , `kind` , `groupId` and `label` for the device.

### `changeMic()`

- After selecting the desired device, you can switch the audio input by passing the corresponding `AudioDeviceInfo` object as a parameter to the `changeMic()` method.

#### Example

```js
import 'dart:io';

import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class LiveStreamScreen extends StatefulWidget {
  const LiveStreamScreen({Key? key}) : super(key: key);

  @override
  _LiveStreamScreenState createState() => _LiveStreamScreenState();
}

class _LiveStreamScreenState extends State<LiveStreamScreen> {
  late Room _room;
  List<AudioDeviceInfo>? mics = [];

  @override
  void initState() {
    super.initState();
    fetchMics();
  }

  void fetchMics() async {
    //highlight-start
    List<AudioDeviceInfo>? audioDevices = await VideoSDK.getAudioDevices();
    //highlight-end
    if (kIsWeb || Platform.isMacOS || Platform.isWindows) {
      for (AudioDeviceInfo device in audioDevices!) {
        if (device.kind == 'audioinput') {
          mics?.add(device);
        }
      }
    }
    setState(() {});
  }

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      ElevatedButton(
          child: Text("Change Input Device"),
          onPressed: () => {
                showDialog(
                  context: context,
                  builder: (context) => AlertDialog(
                    title: const Text("Select Audio Device"),
                    content: Column(
                      mainAxisAlignment: MainAxisAlignment.center,
                      mainAxisSize: MainAxisSize.min,
                      children: <Widget>[
                        SingleChildScrollView(
                          reverse: true,
                          //highlight-start
                          child: mics != null && mics!.isNotEmpty
                              ? Column(
                                  children: mics!
                                      .map(
                                        (device) => ElevatedButton(
                                          child: Text(device.label),
                                          onPressed: () {
                                            _room.changeMic(device);
                                            Navigator.pop(context);
                                          },
                                        ),
                                      )
                                      .toList(),
                                )
                              : const Text("No Microphone Devices found."),
                          //highlight-end
                        )
                      ],
                    ),
                  ),
                )
              }),
    ]);
  }
}
``` 

### Changing Audio Output Device

During the livestream at any point a host wishes to switch his/her output audio like from headphones to speaker, it can be done using the below mentioned methods.

:::important
This feature works for input and output device on **Mobile** apps, and for output device on **Web** and **Desktop** apps.
:::


### `getAudioDevices()`

- The `getAudioDevices()` method will help you to list down all possible connected audio output devices which will return a list of `AudioDeviceInfo` objects.

- The `AudioDeviceInfo` object will contain the `deviceId` , `kind` , `groupId` and `label` for the device.

### `switchAudioDevice()`

- After selecting the desired device, you can switch the audio output by passing the corresponding `AudioDeviceInfo` object as a parameter to the `switchAudioDevice()` method.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class LiveStreamScreen extends StatefulWidget {
  const LiveStreamScreen({Key? key}) : super(key: key);

  @override
  _LiveStreamScreenState createState() => _LiveStreamScreenState();
}

class _LiveStreamScreenState extends State<LiveStreamScreen> {
  late Room _room;
  List<AudioDeviceInfo>? speakers = [];

  @override
  void initState() {
    super.initState();
    fetchSpeakers();
  }

  void fetchSpeakers() async {
    //highlight-start
    List<AudioDeviceInfo>? audioDevices = await VideoSDK.getAudioDevices();
    //highlight-end
      for (AudioDeviceInfo device in audioDevices!) {
        if (device.kind == 'audiooutput') {
          speakers?.add(device);
        }
      }
    setState(() {});
  }

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      ElevatedButton(
          child: const Text("Change Audio Device"),
          onPressed: () => {
                showDialog(
                  context: context,
                  builder: (context) => AlertDialog(
                    title: const Text("Select Audio Device"),
                    content: Column(
                      mainAxisAlignment: MainAxisAlignment.center,
                      mainAxisSize: MainAxisSize.min,
                      children: <Widget>[
                        SingleChildScrollView(
                          reverse: true,
                          child: speakers != null && speakers!.isNotEmpty
                              ? Column(
                                  children: speakers!
                                      .map(
                                        (device) => ElevatedButton(
                                          child: Text(device.label),
                                          onPressed: () {
                                            _room.switchAudioDevice(device);
                                            Navigator.pop(context);
                                          },
                                        ),
                                      )
                                      .toList(),
                                )
                              : const Text("No Speaker Devices found."),
                        )
                      ],
                    ),
                  ),
                )
              }),
    ]);
  }
}
```

:::note

For iOS devices:
- `EARPIECE` is not supported whenever `WIRED_HEADSET` or `BLUETOOTH` device is connected.
- `WIRED_HEADSET` and `BLUETOOTH` devices are not supported simultaneously. Priority is given to the most recently connected device.

:::

:::caution
On the web, the `microphone` will now be `muted` when the input audio device is `disconnected`. Users will need to `unmute` it to continue.
:::

## Changing Camera Input Device

During the livestream at any point a host wishes to switch his/her input video device, it can be done using the below mentioned methods.

### `getVideoDevices()` 

- This method of the `VideoSDK` class will give you the list of all the available cameras which can be shown in a list.

- This method will return an array of `VideoDeviceInfo` which will contain the `deviceId` , `label` , `kind` and `groupId` of the camera input devices.

### `changeCam()`

- After selecting the desired device, you can switch the camera input by passing the corresponding `VideoDeviceInfo` object as a parameter to the `changeCam()` method.

#### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class LiveStreamScreen extends StatefulWidget {
  const LiveStreamScreen({Key? key}) : super(key: key);

  @override
  _LiveStreamScreenState createState() => _LiveStreamScreenState();
}

class _LiveStreamScreenState extends State<LiveStreamScreen> {
  late Room _room;
  List<VideoDeviceInfo>? cameras = [];

  @override
  void initState() {
    super.initState(); 
    fetchCameras();
  }

  void fetchCameras() async {
    //highlight-start
    cameras = await VideoSDK.getVideoDevices();
    //highlight-end
    setState(() {});  
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        ElevatedButton(
          child: const Text("Change Camera"),
          onPressed: () {
            showDialog(
              context: context,
              builder: (context) => AlertDialog(
                title: const Text("Select Camera Device"),
                content: Column(
                  mainAxisAlignment: MainAxisAlignment.center,
                  mainAxisSize: MainAxisSize.min,
                  children: <Widget>[
                    SingleChildScrollView(
                      reverse: true,
                      //highlight-start
                      child: cameras != null && cameras!.isNotEmpty
                          ? Column(
                              children: cameras!.map(
                                (device) => ElevatedButton(
                                  child: Text(device.label),
                                  onPressed: () {
                                    _room.changeCam(device);
                                    Navigator.pop(context);
                                  },
                                ),
                              ).toList(),
                            )
                          : const Text("No Camera Devices found."),
                      //highlight-end
                    ),
                  ],
                ),
              ),
            );
          },
        ),
      ],
    );
  }
}
``` 

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [getAudioDevices()](/flutter/api/sdk-reference/videosdk-class/methods#getaudiodevices)
- [switchAudioDevice()](/flutter/api/sdk-reference/room-class/methods#switchaudiodevice)
- [getVideoDevices](/flutter/api/sdk-reference/videosdk-class/methods#getvideodevices)
- [changeCam()](/flutter/api/sdk-reference/room-class/methods#changecam)
- [getVideoDevices](/flutter/api/sdk-reference/videosdk-class/methods#getvideodevices)
- [changeCam()](/flutter/api/sdk-reference/room-class/methods#changecam)




---

# Mute / Unmute Mic - Flutter

This feature allows hosts to communicate with each other during the livestream by enabling or disabling their microphones. While only hosts (participants in SEND_AND_RECV mode) can speak, audience members (in RECV_ONLY mode) can listen to the conversation in real time.

### `unmuteMic()`

- By using the `unmuteMic()` function of the `Room` class, the host can publish their audio to other hosts and audience members.


- You can also pass a customised audio track in the `unmuteMic()` method by using [Custom Audio Track](/flutter/guide/interactive-live-streaming/custom-Media-Resources/custom-audio-sources).

- Audio stream of the participant can be accessed from the `stream` map of the `Participant` object.

### `muteMic()`

- By using the `muteMic()` function of the `Room` class, the host can stop publishing their audio to other hosts and audience members.

### Events associated with unmuteMic

- Every Participant will receive a callback on [`Events.streamEnabled`](/flutter/api/sdk-reference/participant-class/events#streamenabled) of the [`Participant`](/flutter/api/sdk-reference/participant-class/introduction) object with `Stream` object.

### Events associated with muteMic

- Every Participant will receive a callback on [`Events.streamDisabled`](/flutter/api/sdk-reference/participant-class/events#streamdisabled) of the [`Participant`](/flutter/api/sdk-reference/participant-class/introduction) object with `Stream` object.


```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;
  const ParticipantTile({super.key, required this.participant});

  @override
  State

</center>


## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [unmuteMic()](/flutter/api/sdk-reference/room-class/methods#unmutemic)
- [muteMic()](/flutter/api/sdk-reference/room-class/methods#mutemic)
- [Events.streamEnabled](/flutter/api/sdk-reference/participant-class/events#streamenabled)
- [Events.streamDisabled](/flutter/api/sdk-reference/participant-class/events#streamdisabled)



---

---
title: On / Off Camera | Video SDK
hide_title: true
hide_table_of_contents: false
description: Camera Controls features quick integrate in Javascript, React JS, Android, IOS, React Native, Flutter with Video SDK to add live video & audio conferencing to your applications.
sidebar_label: On / Off Camera
pagination_label: On / Off Camera
keywords:
  - audio calling
  - video calling
  - real-time communication
  - collaboration
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: on-off-camera
--- 

# On / Off Camera - Flutter

This feature enables hosts to turn their cameras on or off to share their video stream with other hosts and audience members during the livestream. Only hosts (in `SEND_AND_RECV` mode) can broadcast their camera feed, while audience members (in `RECV_ONLY` mode) can view it in real time.

### `enableCam()`

- By using the `enableCam()` function of the `Room` class, the host can publish their video to to other hosts and audience members.

- You can also pass a customised video track in `enableCam()` by using [Custom Video Track](/flutter/guide/interactive-live-streaming/custom-Media-Resources/custom-video-sources).

- Video stream of the participant can be accessed from the `streams` property of `Participant` object.

### `disableCam()`

- By using the `disableCam()` function of the `Room` Class, the host can stop publishing their video to to other hosts and audience members.

### Events associated with enableCam

- Every Participant will receive a callback on [`Events.streamEnabled`](/flutter/api/sdk-reference/participant-class/events#streamenabled) of the [`Participant`](/flutter/api/sdk-reference/participant-class/introduction) object with `Stream` object.

### Events associated with disableCam

- Every Participant will receive a callback on [`Events.streamDisabled`](/flutter/api/sdk-reference/participant-class/events#streamdisabled) of the [`Participant`](/flutter/api/sdk-reference/participant-class/introduction) object with `Stream` object.

```jsx
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class LiveStreamScreen extends StatefulWidget {
  ...
}

class _LiveStreamScreenState extends State

</center>


### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [enableCam()](/flutter/api/sdk-reference/room-class/methods#enablecam)
- [disableCam()](/flutter/api/sdk-reference/room-class/methods#disablecam)
- [Events.streamEnabled](/flutter/api/sdk-reference/participant-class/events#streamenabled)
- [Events.streamDisabled](/flutter/api/sdk-reference/participant-class/events#streamdisabled)

---

# Screen Share for Desktop apps - Flutter

Screen sharing in a liveStream is the process of sharing your device screen with other hosts and audience members in the liveStream. It allows everyone in the liveStream to see exactly what you are seeing on your screen, which can be helpful for presentations, demonstrations, or collaborations.

### `getScreenShareSources()`

- `getScreenShareSources()` method will help you to list down all available screens and opened windows.

- This method will return a list of `DesktopCapturerSource` objects which will contain the `name`, `thumbnail` and `type` for the source.

#### Example

```javascript
livestream.getScreenShareSources().then((value) => print("Sources : $value"));
```

### `enableScreenShare()`

- By using `enableScreenShare()` function of `Room` object, host can share his/her screen or window to other hosts and audience members.

- `enableScreenShare()` will take the `DesktopCapturerSource` object as parameter to which you want to share the particular source(screen or window).

- Screen Share stream of the participant can be accessed from the `streams` property of `Participant` object.

### `disableScreenShare()`

- By using `disableScreenShare()` function of `Room` object, local participant can stop sharing his/her screen or window to hosts and audience members.

### Example

#### Step 1 : Create source selection dialogue

- Create dialog box for selecting a screen or window to share during a liveStream. It retrieves the available sources using `getScreenShareSources()` method, allows the user to select a source, and provides buttons to share or cancel the selection.

```jsx title="screen_select_dialog.dart"
import 'package:flutter/material.dart';
import 'package:videosdk_webrtc/flutter_webrtc.dart';
import 'package:videosdk/videosdk.dart';
import 'tab_widget.dart';

// ignore: must_be_immutable
class ScreenSelectDialog extends Dialog {
  ScreenSelectDialog({Key? key, required this.room}) : super(key: key) {
    // get all available screen sources
    //highlight-next-line
    room.getScreenShareSources().then((value) => _setSources(value));
  }

  void _setSources(List

</center>

#### Step 2 : Pass selected source to `enableScreenShare()` method

- Show the screen sharing source selection dialogue that we created in step 1 and start screenShare by using the `_room.enableScreenShare()` method with the chosen source.

```jsx title="LiveStreamScreen.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
import 'screen_select_dialog.dart';

class LiveStreamScreen extends StatefulWidget {
  ...
}

class _LiveStreamScreenState extends State

</div>

<br/>

:::note

If you do not pass a `DesktopCapturerSource` object to the `enableScreenShare()` method, by default SDK will choose your entire screen to share.

:::

### Rendering Screen Share Stream

1. To render the screenshare, you will need the `participantId` who is presenting the screen, which can be found from the `presenterId` property of `Room` object.

We will listen for the `Events.presenterChanged` on `Room` object to check if some other participant starts screen share, `Events.streamEnabled` and `Events.streamDisabled` on the `localParticipant`'s object to identify if the local participant is presenting or not.

```js title="LiveStreamScreen.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
import './screen_share_view.dart';

class LiveStreamScreen extends StatefulWidget {
  final String liveStremId;
  final String token;

  const LiveStreamScreen(
      {super.key, required this.liveStremId, required this.token});

  @override
  State<LiveStreamScreen> createState() => _LiveStreamScreenState();
}

class _LiveStreamScreenState extends State<LiveStreamScreen> {
  late Room _room;
  String? _presenterId;


  @override
  void initState() {
    // create room
    _room = VideoSDK.createRoom(
      roomId: widget.liveStremId,
      token: widget.token,
      displayName: "John Doe",
      micEnabled: true,
      camEnabled: true,
      defaultCameraIndex:
          1, // Index of MediaDevices will be used to set default camera
    );

    setLivestreamEventListener();

    // Join room
    _room.join();

    super.initState();
  }

  // listening to livestream events
  void setLivestreamEventListener() {
    _room.on(Events.roomLeft, () {
      participants.clear();
      Navigator.popUntil(context, ModalRoute.withName('/'));
    });
    //highlight-start
    //Listening if remote participant starts presenting
    _room.on(Events.presenterChanged, (String? presenterId) {
      setState(() => {_presenterId = presenterId});
    });

    //Listening if local participant starts presenting
    _room.localParticipant.on(Events.streamEnabled, (Stream stream) {
      if (stream.kind == "share") {
        setState(() => {_presenterId = _room.localParticipant.id});
      }
    });

    _room.localParticipant.on(Events.streamDisabled, (Stream stream) {
      if (stream.kind == "share") {
        setState(() => {_presenterId = null});
      }
    });
    //highlight-end
  }

  // onbackButton pressed leave the room
  Future<bool> _onWillPop() async {
    _room.leave();
    return true;
  }

  @override
  Widget build(BuildContext context) {
    return WillPopScope(
      onWillPop: () => _onWillPop(),
      child: Scaffold(
        appBar: AppBar(
          title: const Text('VideoSDK QuickStart'),
        ),
        body: Padding(
          padding: const EdgeInsets.all(8.0),
          child: Column(
            children: [
              Text(widget.liveStremId),
              //highlight-start
              //we will render the screenshare view if the presenterId is not null
              if (_presenterId != null)
                ScreenShareView(
                  participant: _presenterId == _room.localParticipant.id
                      ? _room.localParticipant
                      : _room.participants[_presenterId],
                ),
                //highlight-end
              ElevatedButton(
                  onPressed: () {
                    if (_presenterId != null) {
                      _room.disableScreenShare();
                    } else {
                      _room.enableScreenShare();
                    }
                  },
                  child: const Text('Toggle Screnshare')),
            ],
          ),
        ),
      ),
    );
  }
}

```

2. Now that we know if there is an active presenter, let us get the screen share stream from the `Participant` object and render it.

```js title="screen_share_view.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ScreenShareView extends StatelessWidget {
  final Participant? participant;

  ScreenShareView({super.key, required this.participant}) {
    //highlight-start
  //intialize the shareStream
    participant?.streams.forEach((key, value) {
      if (value.kind == "share") {
        shareStream = value;
      }
    });
    //highlight-end
  }
  Stream? shareStream;

  @override
  Widget build(BuildContext context) {
    return Container(
      color: Colors.grey.shade800,
      height: 300,
      width: 200,
      //highlight-start
      //show the screen share stream
      child: shareStream != null
          ? RTCVideoView(
              shareStream?.renderer as RTCVideoRenderer,
              objectFit: RTCVideoViewObjectFit.RTCVideoViewObjectFitCover,
            )
          : null,
          //highlight-end
    );
  }
}
```

### Events associated with enableScreenShare

- Every Participant will receive a callback on [`Events.streamEnabled`](/flutter/api/sdk-reference/participant-class/events#streamenabled) of the [`Participant`](/flutter/api/sdk-reference/participant-class/introduction) object with `Stream` object.

- Every Remote Participant will receive [`Events.presenterChanged`](/flutter/api/sdk-reference/room-class/events#presenterchanged) callback on the [`Room`](/flutter/api/sdk-reference/room-class/introduction) object with the participantId as `presenterId` who started the screen share.

### Events associated with disableScreenShare

- Every Participant will receive a callback on [`Events.streamDisabled`](/flutter/api/sdk-reference/participant-class/events#streamdisabled) of the [`Participant`](/flutter/api/sdk-reference/participant-class/introduction) object with `Stream` object.

- Every Remote Participant will receive [`Events.presenterChanged`](/flutter/api/sdk-reference/room-class/events#presenterchanged) callback on the [`Room`](/flutter/api/sdk-reference/room-class/introduction) object with the `presenterId` as `null`.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;
  ...
}

class _ParticipantTileState extends State<ParticipantTile> {

  @override
  void initState() {
    ...

    //highlight-next-line
    _initStreamListeners();
    super.initState();
  }

  //highlight-start
  //Change state according to the events received
  _initStreamListeners() {
    widget.participant.on(Events.streamEnabled, (Stream stream) {
      if (stream.kind == 'share') {
        //Screen share Turned On
      }
    });

    widget.participant.on(Events.streamDisabled, (Stream stream) {
      if (stream.kind == 'share') {
        //Screen Share Turned Off
      }
    });
  }
  //highlight-end

  @override
  Widget build(BuildContext context) {
    return YourParticipantWidget();
  }
}

class LiveStreamScreen extends StatefulWidget {
  ...
}

class _LiveStreamScreenState extends State<LiveStreamScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    ...

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourLiveStreamWidget();
  }

  //highlight-start
  void setupRoomEventListener() {

    room.on(Events.presenterChanged, (String? presenterId) {
      //Room screen presenter has changed
      //Participant ID of current presenter is presenterId
    });
  }
  //highlight-end
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [enableScreenShare()](/flutter/api/sdk-reference/room-class/methods#enablescreenshare)
- [disableScreenShare()](/flutter/api/sdk-reference/room-class/methods#disablescreenshare)
- [Events.streamEnabled](/flutter/api/sdk-reference/participant-class/events#streamenabled)
- [Events.streamDisabled](/flutter/api/sdk-reference/participant-class/events#streamdisabled)


---

---
title: Screen Share | Video SDK
hide_title: true
hide_table_of_contents: false
description: Share your Screen features quick integrate in Javascript, React JS, Android, IOS, React Native, Flutter with Video SDK to add live video & audio conferencing to your applications.
sidebar_label: Screen Share
pagination_label: Screen Share
keywords:
  - audio calling
  - video calling
  - real-time communication
  - collaboration
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: screen-share
--- 

# Screen Share - Flutter

This feature enables hosts to start or stop sharing their screen with other hosts and audience members during the live stream. Only hosts (in `SEND_AND_RECV` mode) can broadcast their screen, while audience members (in `RECV_ONLY` mode) can view it in real time.

### `enableScreenShare()`

- By using `enableScreenShare()` function of `Room` object, host can share his/her screen or window to other host and audience member.

- Screen Share stream of the participant can be accessed from the `streams` property of `Participant` object.

- To enable Screenshare in Android devices, you need to provide the following permissions in `AndroidManifest.xml`

```js title="AndroidManifest.xml"
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
//For Android devices versioned 14 and above.
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
```


### `disableScreenShare()`

- By using `disableScreenShare()` function of `Room` object, host can stop sharing his/her screen or window to other host or audience member.

### Events associated with enableScreenShare

- Every Participant will receive a callback on [`Events.streamEnabled`](/flutter/api/sdk-reference/participant-class/events#streamenabled) of the [`Participant`](/flutter/api/sdk-reference/participant-class/introduction) object with `Stream` object.

- Every Remote Participant will receive [`Events.presenterChanged`](/flutter/api/sdk-reference/room-class/events#presenterchanged) callback on the [`Room`](/flutter/api/sdk-reference/room-class/introduction) object with the participantId as `presenterId` who started the screen share.

### Events associated with disableScreenShare

- Every Participant will receive a callback on [`Events.streamDisabled`](/flutter/api/sdk-reference/participant-class/events#streamdisabled) of the [`Participant`](/flutter/api/sdk-reference/participant-class/introduction) object with `Stream` object.

- Every Remote Participant will receive [`Events.presenterChanged`](/flutter/api/sdk-reference/room-class/events#presenterchanged) callback on the [`Room`](/flutter/api/sdk-reference/room-class/introduction) object with the `presenterId` as `null`.

```jsx
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class LiveStreamScreen extends StatefulWidget {
  ...
}

class _LiveStreamScreenState extends State<LiveStreamScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
     _initStreamListeners();
  }
//highlight-start
  //Change state according to the events received
  _initStreamListeners() {
    widget.participant.on(Events.streamEnabled, (Stream stream) {
      if (stream.kind == 'share') {
        //Screen share Turned On
      }
    });

    widget.participant.on(Events.streamDisabled, (Stream stream) {
      if (stream.kind == 'share') {
        //Screen Share Turned Off
      }
    });
  }
  //highlight-end
  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ElevatedButton(
          onPressed:(){
            _room.enableScreenShare();
          },
          child: const Text("Enable Screen Share"),
        ),
        ElevatedButton(
          onPressed:(){
            _room.disableScreenShare();
          },
          child: const Text("Disable Screen Share"),
        ),
    //highlight-end
      ]
    );
  }
}
class LiveStreamScreen extends StatefulWidget {
  ...
}

class _LiveStreamScreenState extends State<LiveStreamScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    ...

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourLiveStreamWidget();
  }

  //highlight-start
  void setupRoomEventListener() {

    room.on(Events.presenterChanged, (String? presenterId) {
      //Room screen presenter has changed
      //Participant ID of current presenter is presenterId
    });
  }
  //highlight-end
}
```

### iOS Setup

:::note

For Flutter iOS Screen Share feature, you need to follow this guide [Flutter iOS Screen Share](/flutter/guide/video-and-audio-calling-api-sdk/extras/flutter-ios-screen-share)

:::


### Rendering Screen Share Stream

1. To render the screenshare, you will need the `participantId` who is presenting the screen, which can be found from the `presenterId` property of `Room` object.

We will listen for the `Events.presenterChanged` on `Room` object to check if some other participant starts screen share, `Events.streamEnabled` and `Events.streamDisabled` on the `localParticipant`'s object to identify if the local participant is presenting or not.

```js title="LiveStreamScreen.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
import './screen_share_view.dart';

class LiveStreamScreen extends StatefulWidget {
  final String liveStreamId;
  final String token;

  const LiveStreamScreen(
      {super.key, required this.liveStreamId, required this.token});

  @override
  State<LiveStreamScreen> createState() => _LiveStreamScreenState();
}

class _LiveStreamScreenState extends State<LiveStreamScreen> {
  late Room _room;
  String? _presenterId;


  @override
  void initState() {
    // create room
    _room = VideoSDK.createRoom(
      roomId: widget.liveStreamId,
      token: widget.token,
      displayName: "John Doe",
      micEnabled: true,
      camEnabled: true,
      defaultCameraIndex:
          1, // Index of MediaDevices will be used to set default camera
    );

    setLivestreamEventListener();

    // Join room
    _room.join();

    super.initState();
  }

  // listening to livestream events
  void setLivestreamEventListener() {
    _room.on(Events.roomLeft, () {
      participants.clear();
      Navigator.popUntil(context, ModalRoute.withName('/'));
    });
    //highlight-start
    //Listening if remote participant starts presenting
    _room.on(Events.presenterChanged, (String? presenterId) {
      setState(() => {_presenterId = presenterId});
    });

    //Listening if local participant starts presenting
    _room.localParticipant.on(Events.streamEnabled, (Stream stream) {
      if (stream.kind == "share") {
        setState(() => {_presenterId = _room.localParticipant.id});
      }
    });

    _room.localParticipant.on(Events.streamDisabled, (Stream stream) {
      if (stream.kind == "share") {
        setState(() => {_presenterId = null});
      }
    });
    //highlight-end
  }

  // onbackButton pressed leave the room
  Future<bool> _onWillPop() async {
    _room.leave();
    return true;
  }

  @override
  Widget build(BuildContext context) {
    return WillPopScope(
      onWillPop: () => _onWillPop(),
      child: Scaffold(
        appBar: AppBar(
          title: const Text('VideoSDK QuickStart'),
        ),
        body: Padding(
          padding: const EdgeInsets.all(8.0),
          child: Column(
            children: [
              Text(widget.liveStreamId),
              //highlight-start
              //we will render the screenshare view if the presenterId is not null
              if (_presenterId != null)
                ScreenShareView(
                  participant: _presenterId == _room.localParticipant.id
                      ? _room.localParticipant
                      : _room.participants[_presenterId],
                ),
                //highlight-end
              ElevatedButton(
                  onPressed: () {
                    if (_presenterId != null) {
                      _room.disableScreenShare();
                    } else {
                      _room.enableScreenShare();
                    }
                  },
                  child: const Text('Toggle Screnshare')),
            ],
          ),
        ),
      ),
    );
  }
}

```

2. Now that we know if there is an active presenter, let us get the screen share stream from the `Participant` object and render it.

```js title="screen_share_view.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ScreenShareView extends StatelessWidget {
  final Participant? participant;

  ScreenShareView({super.key, required this.participant}) {
    //highlight-start
  //intialize the shareStream
    participant?.streams.forEach((key, value) {
      if (value.kind == "share") {
        shareStream = value;
      }
    });
    //highlight-end
  }
  Stream? shareStream;

  @override
  Widget build(BuildContext context) {
    return Container(
      color: Colors.grey.shade800,
      height: 300,
      width: 200,
      //highlight-start
      //show the screen share stream
      child: shareStream != null
          ? RTCVideoView(
              shareStream?.renderer as RTCVideoRenderer,
              objectFit: RTCVideoViewObjectFit.RTCVideoViewObjectFitCover,
            )
          : null,
          //highlight-end
    );
  }
}
```
### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [enableScreenShare()](/flutter/api/sdk-reference/room-class/methods#enablescreenshare)
- [disableScreenShare()](/flutter/api/sdk-reference/room-class/methods#disablescreenshare)
- [Events.streamEnabled](/flutter/api/sdk-reference/participant-class/events#streamenabled)
- [Events.streamDisabled](/flutter/api/sdk-reference/participant-class/events#streamdisabled)


---

# Getting Started - Flutter SDK




---

# Geo Fencing - Flutter


Our SDK includes a region geofencing feature to comply with local laws and regulations worldwide. It restricts connections to servers within specified regions, ensuring users connect only to designated areas, regardless of their location. 

This helps meet regional data protection requirements and enhances user experience by addressing geographical network limitations.




### In this sequence diagram:
- User 1 (India) tries to connect to a meeting. In a regular scenario, the meeting would connect to the India region, but due to the geofence configuration, the meeting will connect to North America.

## Considerations
- If the user’s location differs from the chosen region, the network quality between these locations may be poor, affecting audio and video quality.
- Avoid using geofencing unless your scenario requires regional compliance.

:::info

Geo Fencing is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Available Regions
- INDIA
- USA
- UAE
- EUROPE
- SINGAPORE
- AUSTRALIA


---

---
title: Host vs Audience Modes | Video SDK
hide_title: true
hide_table_of_contents: false
description: Understand the differences between Host and Audience modes in Video SDK's Interactive Live Stream (ILS), their capabilities, and how participants transition between them.
sidebar_label: Host vs Audience Modes
pagination_label: Host vs Audience Modes
keywords:
  - audio calling
  - video calling
  - real-time communication
  - collaboration
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: join-meeting
--- 

# Host vs Audience Modes - Flutter

Before diving into implementation, it's important to understand the two core modes of participation in an `Interactive Live Stream (ILS)` session powered by VideoSDK:

### Mode Architecture

Here’s a visual representation of how these modes function within an ILS session:

![Interactive Live Streaming architecture diagram](https://assets.videosdk.live/images/interactive-live-streaming-architecture.png)


By clearly separating hosts from viewers, and offering seamless transitions between roles, VideoSDK ILS ensures high performance, low latency, and exceptional flexibility for all live streaming scenarios.

:::note

Throughout the rest of this documentation, whenever we mention "Host", we are specifically referring to a participant in the `SEND_AND_RECV` mode. Similarly, when we mention "Audience" or "Viewer", we are referring to participants in the `RECV_ONLY` mode. These distinctions are important, as each mode comes with its own set of capabilities and limitations.

:::

### `1. SEND_AND_RECV` – Host / Co-host Mode

This mode is designed for Hosts or Co-hosts who need to broadcast their audio and video to the audience and potentially interact with other hosts. Following is the list of everything a host is capable of:

- Publish and receive media (audio/video/screen share)
- Participate in conversations with other hosts
- Engage with the audience using chat, polls, reactions, and more
- Moderate the stage and manage participants
- Invite audience members on stage to become temporary broadcasters

🔢 Scales to 2,000+ real-time viewers (Need more? Contact support@videosdk.live)

### `2. RECV_ONLY` – Audience Mode

This mode is optimized for audience members who are viewing the live stream and engaging via non-verbal interaction tools. Following is the list of everything audience is capable of:

- Receive media from all active hosts in real time (audio/video/screen share)
- No media publishing – cannot share their own audio/video unless promoted
- Engage via:
  - Live chat
  - Polls and quizzes
  - Reactions (emojis, claps, hearts, etc.)
  - Virtual gifts
  - Hand raise to request stage access

🔢 Scales to 2,000+ real-time viewers (Need more? Contact support@videosdk.live)


### Seamless Transition Between Modes

VideoSDK offers a dynamic role management system, making it easy to transition a participant from audience to stage. If a host invites an audience member on stage, they can seamlessly switch from `RECV_ONLY` mode to `SEND_AND_RECV` mode. This allows them to publish their audio/video and interact like a host or co-host. Once their role is revoked, they can return to the audience mode.



---

# Overview - Flutter
Interactive Live Streaming (ILS) is a low-latency streaming solution designed for real-time engagement at scale. Unlike traditional streaming protocols like HTTP Live Streaming (HLS), which typically have a delay of 15–30 seconds, ILS offers latency as low as 300 milliseconds—making it ideal for experiences that rely on immediate interaction.

While originally designed for meetings, VideoSDK seamlessly adapts to live streaming—supporting 100+ simultaneous hosts/co-hosts (Need more? Contact support@videosdk.live) and 2,000+ real-time viewers (scalable on request). This flexible architecture empowers dynamic events with multiple speakers, performers, or presenters.

ILS is not just about watching—it's about participating. While hosts and co-hosts can interact via audio/video and screen share, the audience consumes the content in real time and engages through interactive features like chat, polls and virtual gifting.

:::info

If you're already using VideoSDK for meetings, throughout this documentation you will learn how to extend its capabilities to support interactive live streaming. 
Much of the core structure remains the same, but you'll discover how to adapt roles, scale the audience, and integrate interactive features to build engaging live stream experiences—all using the familiar tools and APIs you're used to.

:::

### Key Benefits:

- `Ultra-low latency`: Sub-second delivery for seamless interaction

- `Multiple host support`: Up to 100 simultaneous broadcasters

- `Scalable viewer capacity`: Handle up to 2,000 real-time audience members

- `Interactive tools`: Chat, polls, virtual gifts, hand raise, and more

- `Cross-platform compatibility`: Works across mobile, web, and desktop

<div style={{ textAlign: 'center' }}>
    <img
        src="https://cdn.videosdk.live/docs/images/android/ils/overview.png"
        alt="Waiting Screen"
         style={{height: '450px'}}
    />
</div>



## When to Use ILS?

Use Interactive Live Streaming when you need to:

- Run virtual events with multiple speakers
- Engage your audience actively during webinars
- Host fitness or coaching sessions with feedback
- Stream concerts, shows, or ceremonies with real-time reactions
- Organize town halls, investor calls, or product launches
- Facilitate audio rooms for casual or topic-based discussions
- Power social experiences like live meetups, talent shows, or community hangouts



:::info

If your requirement is strictly one-way broadcasting where interactivity is minimal and latency isn't critical (e.g., sports highlights, pre-recorded shows), http live streaming (HLS) may be more appropriate. To learn more about HLS, go through the [documentation](/flutter/guide/interactive-live-streaming/integrate-hls/overview).

:::

---

# Display Attendees Count - Flutter

In this guide, we will see how you can display the number of attendees in realtime.

:::note
Before going forward in this guide, do make sure all the attendees join the meeting with mode as `SIGNALLING_ONLY`
:::




**`Step 1:`** We will get the `participants` from the `Room` object. and filter the `SIGNALLING_ONLY` participants from it. We will also added the `participantJoined`, `participantLeft` and `participantModeChanged` listerners to keep the list of attendees updated.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ViewerScreen extends StatefulWidget {
  ...
}

class _ViewerScreenState extends State<ViewerScreen> {
  late Room room;

  Map<String, Participant> _attendees = {};

  @override
  void initState() {
    //highlight-next-line
    ...

    updateAttendees();

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void updateAttendees(){
    Map<String, Participant> attendees = {};
    if(room.localParticipant.mode == Mode.SIGNALLING_ONLY);
    attendees.putIfAbsent(
        room.localParticipant.id, () => room.localParticipant);
    room.participants.values.forEach((participant) {
      if (participant.mode == Mode.SIGNALLING_ONLY) {
        attendees.putIfAbsent(participant.id, () => participant);
      }
    });
    setState(()=>_attendees = attendees);
  }
  //highlight-end

  void setupRoomEventListener() {
    room.on(Events.roomJoined, () {
      //highlight-start
      updateAttendees();
      //highlight-end
    });

    room.on(Events.participantModeChanged, (Map<String, dynamic> data){
      //highlight-start
      updateAttendees()
      //highlight-end
    });

    room.on(Events.participantJoined, (Participant participant) {
      //highlight-start
      updateAttendees();
      //highlight-end
    });


    room.on(Events.participantLeft, (String participantId , Map<String,dynamic> reason) {
      //highlight-start
      updateAttendees();
      //highlight-end
    });
  }
}
```

**`Step 2:`** With all the participants, we will filter out participants who have joined as a `SIGNALLING_ONLY` and then display that count.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ViewerScreen extends StatefulWidget {
  ...
}

class _ViewerScreenState extends State<ViewerScreen> {
  late Room room;

  Map<String, Participant> attendees = {};

  @override
  void initState() {
    //highlight-next-line
    ...

    attendees.putIfAbsent(
        room.localParticipant.id, () => room.localParticipant);
    room.participants.values.forEach((participant) {
      if (participant.mode == Mode.SIGNALLING_ONLY) {
        attendees.putIfAbsent(participant.id, () => participant);
      }
    });

    setupRoomEventListener();
  }

  //higlight-start
  @override
  Widget build(BuildContext context) {
    return Text("Total attendees :: ${attendees.length}");
  }
  //higlight-end

  void setupRoomEventListener() {
    //highlight-next-line
    ...
  }
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [participants](/flutter/api/sdk-reference/room-class/properties#participants)


---

# Invite Guest on Stage - Flutter

In this guide, we will see how you can request a viewer to join your livestream by using the `changeMode()`.

:::note
Before going forward in this guide, do make sure all the attendees join the meeting with mode as `SIGNALLING_ONLY` and the host joins with mode as `SEND_AND_RECV`
:::




Let's first have a look at how we will be using the `PubSub` mechanism to acheive the requesting and switching of the participant's mode.

![invite-guest-pubsub](https://cdn.videosdk.live/website-resources/docs-resources/invite_guest_pubsub.png)

### Step 1: Loading Viewer List

The host will see a list of participants who have joined as `SIGNALLING_ONLY` along with a button that, when selected, will invite that user to join the livestream.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class SpeakerScreen extends StatefulWidget {
  ...
}

class _SpeakerScreenState extends State

### Step 2: Requesting a Viewer to Join Livestream

We have a Viewer list ready. Now, let us handle the click event for the Join Livestream button.

We will be using `CHANGE_MODE_$participantId` as the topic for PubSub.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class SpeakerScreen extends StatefulWidget {
  ...
}

class _SpeakerScreenState extends State

### Step 4: Pin the participant

We need to pin the participant so that he/she can appears on the livestream. To achieve this, we will listen to the callback on the `participantModeChanged` of `Room` object. Here, we are already calling the `updateAttendees()` which we will update to pin only the `SEND_AND_RECV` mode participants.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class SpeakerScreen extends StatefulWidget {
  ...
}

class _SpeakerScreenState extends State

</div>

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Room](/flutter/api/sdk-reference/room-class/introduction)
- [PubSub](/flutter/api/sdk-reference/pubsub-class/introduction)
- [changeMode](/flutter/api/sdk-reference/room-class/methods#changemode)


---

# Manage On-Screen Participants - Flutter

It is important that only the necessary person are present on the screen when livestream is on. To handle this, we will be using the `pin` and `unpin` methods of the `Participant` object.

:::note
To ensure only the hosts/speakers are shown in the grid, you should use the `SPOTLIGHT` layout and `pin` as the priority when starting the interactive livestream.
:::

Let us first explore two methods that we will be using to manage on-screen participats.

### `pin()`

With these method you can pin any participant's Camera, Screen Share or both. This can be useful to identify the participants based on which you can perform rendering participant grid.

### `unpin()`

With these methods you can unpin any participant's Camera, Screen Share or both. This can be useful to reset pin state of the participant.




### Managing On-Screen Participants

1. If you want to pin all the hosts/speakers automatically, you can do it by listenting to the `Events.roomJoined` callback and `Events.participantModeChanged`, where you can `pin` and `unpin` based on the mode.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    ...

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {
    room.on(Events.roomJoined, () {
      //highlight-start
      //We will pin the participant if mode is SEND_AND_RECV
      if(room.localParticipant.mode == Mode.SEND_AND_RECV){
        room.localParticipant.pin();
      }
      //highlight-end
    });

    room.on(Events.participantModeChanged, (Map<String, dynamic> data){
      //highlight-start
      //We will pin the participant if mode is SEND_AND_RECV else unpin him
      if (data['participantId'] == room.localParticipant.id) {
        if (room.localParticipant.mode == Constants.modes.SEND_AND_RECV) {
          room.localParticipant.pin();
        } else {
          room.localParticipant.unpin();
        }
      }
      //highlight-end
    });
  }
  //highlight-end
}
```

2. When rendering the participant grid on the Speaker side, make sure to show only the participants who are in `SEND_AND_RECV` mode. You can filter the participants as shown in below examples.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  Map<String, Participant> _speakers = {};

  @override
  void initState() {
    //highlight-next-line
    ...

    updateSpekers();

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void updateSpeakers(){
    Map<String, Participant> speakers = {};
    if(room.localParticipant.mode == Mode.SEND_AND_RECV);
    speakers.putIfAbsent(
        room.localParticipant.id, () => room.localParticipant);
    room.participants.values.forEach((participant) {
      if (participant.mode == Mode.SEND_AND_RECV) {
        speakers.putIfAbsent(participant.id, () => participant);
      }
    });
    setState(()=>_speakers = speakers);
  }
  //highlight-end

  void setupRoomEventListener() {
    room.on(Events.roomJoined, () {
      //highlight-start
      updateSpeakers();
      //highlight-end
    });

    room.on(Events.participantModeChanged, (Map<String, dynamic> data){
      //highlight-start
      updateSpeakers()
      //highlight-end
    });

    room.on(Events.participantJoined, (Participant participant) {
      //highlight-start
      updateSpeakers();
      //highlight-end
    });


    room.on(Events.participantLeft, (String participantId, Map<String,dynamic> reason) {
      //highlight-start
      updateSpeakers();
      //highlight-end
    });
  }
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [pin](/flutter/api/sdk-reference/participant-class/methods#pin)
- [unpin](/flutter/api/sdk-reference/participant-class/methods#unpin)
- [participants](/flutter/api/sdk-reference/room-class/properties#participants)


---

# Manage Roles - Flutter

## Roles with VideoSDK

When doing interactive live streaming maintaining the role of users is quite important. To help manage these roles better, VideoSDK allows a participant with two types of modes:

**`1. SEND_AND_RECV`** When a participant is joining with mode set to `SEND_AND_RECV`, we will be able to **publish and consume the media** of other participants and also interact with them using the features like chat, poll etc.

**`2. SIGNALLING_ONLY`** When a participant is joining with mode set to `SIGNALLING_ONLY`, that participant is **not allowed to publish or consume any media** from other participants. Although they can interact with other participants using chat, polls etc.




![manage-roles](https://cdn.videosdk.live/website-resources/docs-resources/meeting_modes.jpg)

## When to use the Roles?

##### 1. Simple Adaptive Streaming

- Simple Adaptive Streaming (SAS) is a type of livestreaming that requires minimal interaction between the host and viewers.

- It is particularly useful for events with a large number of viewers who prefer not to engage with the host.

- In SAS, each speaker attends a VideoSDK meeting in `SEND_AND_RECV` mode, while viewers can simply watch the livestream using the `playbackHlsUrl` or `livestreamUrl`. Unlike the speakers, viewers do not need to join the meeting in `SEND_AND_RECV` or `SIGNALLING_ONLY` mode. This allows for a seamless streaming experience without any unnecessary interruptions or distractions.
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::


<div style={{textAlign: 'center'}}>



</div>

##### 2. Adaptive Streaming with increased engagement

- If you're looking to increase engagement with your audience during a live streaming event, consider using Adaptive Streaming technology. With this approach, you can incorporate interactive features such as polls and conversations, and give viewers the ability to join and leave the livestream as the host decides.

- To set this up, have all speakers join as `SEND_AND_RECV` mode participants, while the audience joins as `SIGNALLING_ONLY` mode participants. This way, everyone can participate in the interactive elements of the live stream and create a more dynamic and engaging experience for all.

<div style={{textAlign: 'center'}}>



</div>

## Using roles

The mode of the participants is set during the creating the room.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  final String meetingId;
  final String token;

  const MeetingScreen(
      {super.key, required this.meetingId, required this.token});

  @override
  State<MeetingScreen> createState() => _MeetingScreenState();
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  Mode? localParticipantMode;

  @override
  void initState() {
    //Creating a new Room based on the passed meetingId and token from the Joining Screen
    // create room
    _room = VideoSDK.createRoom(
      roomId: widget.meetingId,
      token: widget.token,
      displayName: "John Doe",
      micEnabled: true,
      camEnabled: true,
      defaultCameraIndex:
          1, // Index of MediaDevices will be used to set default camera
      //highlight-next-line
      mode: Mode.SEND_AND_RECV, // or Mode.SIGNALLING_ONLY
    );

    _room.join();

    setRoomEventListener();

    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return  SafeArea(
      child: Scaffold(
        backgroundColor: Colors.black,
        //highlight-start
        //Show Speaker view if mode is SEND_AND_RECV else show Viewer View
        body: localParticipantMode != null
            ? localParticipantMode == Mode.SEND_AND_RECV
                ? ILSSpeakerView(room: _room)
                : localParticipantMode == Mode.SIGNALLING_ONLY
                    ? ILSViewerView(room: _room)
                    : null
            : const Center(
                child: Text("Joining...")),
                //highlight-end
      ),
    );
  }

  void setRoomEventListener(){
    _room.on(Events.roomJoined, (){
      setState(()=>localParticipantMode = _room.localParticipant.mode);
    });

    _room.on(Events.participantModeChanged, (Map<String, dynamic> data){
      if(data['participantId']){
        setState(()=>localParticipantMode = _room.localParticipant.mode);
      }
    });
  }
}
```

## Getting Participant Mode

You can identify the participants role by using `mode` property from `Participant` object.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;
  const ParticipantTile({super.key, required this.participant});

  @override
  State<ParticipantTile> createState() => _ParticipantTileState();
}

class _ParticipantTileState extends State<ParticipantTile> {

  @override
  Widget build(BuildContext context) {
    //highlight-next-line
    return Text("${widget.participant.displayName} is in ${widget.participant.mode.name}");
  }
}
```

## Changing Participant's Mode

Let's say you are hosting a livestream and you want one of your viewer to join the livestream with you. In this case you can change the mode of the participant using the `changeMode()` of the `Room` object.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        ElevatedButton(
          onPressed:(){
            //highlight-next-line
            _room.changeMode(Mode.SIGNALLING_ONLY);
          },
          child: const Text("Change Mode to Viewer"),
        ),
        ElevatedButton(
          onPressed:(){
            //highlight-next-line
            _room.changeMode(Mode.SEND_AND_RECV);
          },
          child: const Text("Change Mode to Speaker"),
        ),
      ]
    );
  }
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [createRoom](/flutter/api/sdk-reference/videosdk-class/methods#createroom)
- [Room](/flutter/api/sdk-reference/room-class/introduction)
- [Participant](/flutter/api/sdk-reference/participant-class/introduction)
- [changeMode](/flutter/api/sdk-reference/room-class/methods#changemode)


---

# Interactive Livestream (HLS) - Flutter

### What is Interactive Livestream (HLS)?

Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

In an interactive live stream (HLS), viewers can take part in a variety of activities like live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

### What is Adaptive Live Streaming?

Livestream experience is important while undertaking interactive live streaming in order to increase audience. To do this, the livestream should be able to respond to the viewer's network bandwidth, and change the stream's resolution as necessary. Therefore, adaptive live streaming refers to a feed that automatically adjusts to a lower or higher resolution dependent on the user's preferences.

### What is Latency?

Latency is the delay between capturing video content and its playback. Key factors that affecting latency :

- **Buffering**: Balance buffer size for smoother playback against latency.
- **Network Conditions**: Efficient servers and network health contribute to lower latency.

Standard HLS has a latency around 5-6 seconds.

### HLS Architecture of VideoSDK

<center>

![VideoSDK HLS](https://cdn.videosdk.live/website-resources/docs-resources/mobile_hls.png)

</center>

When a host starts the interactive live stream, VideoSDK will use a deafult theme or user specified template to compose and encode a live stream which will be delivered to the viewers through a `M3U8` video file which can be played directly on the viewer end which will adapt to the viewer's network bandwidth.

When using VideoSDK for interactive live stream, you get multiple types of URLs which you can use based on your requirements.

**`1. Standard Streaming:`** This type of streaming is where the user is not allowed to go back in the live and can just stream it.

**`2. Rolling Playback:`** This type of streaming is where the user is allowed to do rewind and do a playback of the complete stream.

**`3. VoD Playback`** With this, users can playback the complete live stream on demand whenever needed.

## Using HLS with VideoSDK

You can use HLS with VideoSDK in two different ways.

#### 1. Simple Adaptive Streaming

When we talk about simple adaptive streaming, we imply that there is hardly any interaction between the hosts and the viewers.

These livestreams are helpful when there are a lot of viewers, and they don't want to engage with the host. In this scenario, every presenter attends a VideoSDK meeting, while every viewer only watches the livestream.


<div style={{textAlign: 'center'}}>



</div>

#### 2. Adaptive Streaming with increased engagement

When you want to communicate with your audience by enabling polls, conversations, and the ability for viewers to join and leave the livestream based on the host's decision, adaptive streaming with enhanced engagement will be the best fit for you.

In this scenario, both the host and the viewer will have to join a VideoSDK meeting with different roles. To learn more about the roles [follow these guide.](../handling-participants/manage-roles)

<div style={{textAlign: 'center'}}>



</div>


---

# Setup HLS Player - Flutter

In this guide, we will create a new Component which will be responsible for playing the HLS stream.
Before starting this guide, make sure you have a VideoSDK meetings setup allowing you to join the room. To learn more about setting up a VideoSDK meeting, follow this quick start guide.

To play the HLS stream we will be using the [flutter_vlc_player](https://pub.dev/packages/flutter_vlc_player) library.

### `1. Setup Component with HLS events`

**`Step 1:`** Let us first start by creating the new `StatefulWidget` named `HlsScreen` which will listen to all the HLS related events and play the HLS stream whenever available.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class HlsScreen extends StatefulWidget {
  final Room room;
  const HlsScreen({super.key, required this.room});

  @override
  State

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startHls](/flutter/api/sdk-reference/room-class/methods#starthls)
- [stopHls](/flutter/api/sdk-reference/room-class/methods#stophls)
- [Events.hlsStateChanged](/flutter/api/sdk-reference/room-class/events#hlsstatechanged)


---

# Start HLS - Flutter

Before starting the HLS, the prequisite steps require you to have a VideoSDK Meeting running which you want to use for interactive livestream. To learn more about setting up a interactive live streaming, you can follow the steps [here in the quick start guide.](/flutter/guide/video-and-audio-calling-api-sdk/quick-start-ils)





## Starting HLS

`startHls()` can be used to start a interactive livestream of the meeting which can be accessed from the `Room` object. This method accepts one parameter:

- `config (optional)`: This parameter will define how the livestream layout should look like.

```js
Map<String, dynamic> config = {
  // highlight-next-line
  // Layout Configuration
  "layout": {
    "type": "GRID", // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
    "priority": "SPEAKER", // "PIN", Default : "SPEAKER"
    "gridSize": 4, // MAX : 4
  },

  // highlight-next-line
  // Theme of recording
  "theme": "DARK", //  "LIGHT" | "DEFAULT"

  // highlight-next-line
  // `mode` is used to either record video & audio both or only audio.
  "mode": "video-and-audio", // "audio", Default : "video-and-audio"

  // highlight-next-line
  // Quality of recording and is only applicable to `video-and-audio` type mode.
  "quality": "high", /* Default : "med"
   "low" (SD HLS) | "med" (HD HLS) | "high" (FHD HLS) */

  //highlight-start
  // This mode refers to orientation of recording.
  // landscape : Record the meeting in horizontally
  // portrait : Record the meeting in vertically (Best for mobile view)
  //highlight-end
  "orientation": "landscape", // "portrait",  Default : "landscape"
};

room.startHls(config: config);
```

:::note
If you want only the SEND_AND_RECV participants to be seen in the livestream, you can `pin` all the participants in the SEND_AND_RECV mode and start the livestream with the `SPOTLIGHT` layout and `PIN` as the `PRIORITY`.
:::

### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ElevatedButton(
          onPressed:(){
            Map<String, dynamic> config = {
              "layout": {
                "type": "GRID",
                "priority": "SPEAKER",
                "gridSize": 4,
              },
              "theme": "DARK",
              "mode": "video-and-audio",
              "quality": "high",
              "orientation": "portrait",
            };
            _room.startHls(config: config);
          },
          child: const Text("Start HLS"),
        ),
    //highlight-end
      ]
    );
  }
}
```

## Understanding Layouts

##### 1. GRID Layout

This layout is default layout if no participants are pinned, it will look same as a normal meeting grid layout, when any participant is pinned that participant will be moved on top of the main screen grid above all non pinned participants

While screenshare as well the main view will contain only screenshare media but the side panel view of participant grid will maintain same order of pinned and unpinned participants.

|                       Grid                        |                     Grid with Screenshare                     |
| :-----------------------------------------------: | :-----------------------------------------------------------: |
| ![prebuilt-grid](/img/prebuilt/prebuilt-grid.png) | ![prebuilt-grid-share](/img/prebuilt/prebuilt-grid-share.png) |

##### 2. SIDEBAR Layout

This layout will have one main screen view and other sidebar grid layout. Only pinned participant will be visible in this layout, all unpinned participants will not be visible in this layout. If more than one participant is pinned then the first participant who was pinned will appear in main screen layout and all other remaining pinned particiapants will be visible in sidebar.

If any pinned participant started screenshare then the screenshare media will be visible in main screen layout and all other pinned participants webcam view will be visible in sidebar

|                         Sidebar                         |                      Sidebar with Screenshare                       |
| :-----------------------------------------------------: | :-----------------------------------------------------------------: |
| ![prebuilt-sidebar](/img/prebuilt/prebuilt-sidebar.png) | ![prebuilt-sidebar-share](/img/prebuilt/prebuilt-sidebar-share.png) |

##### 3. SPOTLIGHT Layout

This layout will only contain main screen layout, multiple pinned participants will be visible in main screen view. Same as `SIDEBAR` layout only pinned participants will be visible in main screen.

If any pinned participant started screenshare then only screenshare view will be visible in main screen, no webcam view will be visible when any pinned participant started screenshare.

|                          Spotlight                          |                       Spotlight with Screenshare                        |
| :---------------------------------------------------------: | :---------------------------------------------------------------------: |
| ![prebuilt-spotlight](/img/prebuilt/prebuilt-spotlight.png) | ![prebuilt-spotlight-share](/img/prebuilt/prebuilt-spotlight-share.png) |

## Event associated with HLS

- **hlsStateChanged** - Whenever meeting HLS state changes, then `hlsStateChanged` event will trigger.

- You can get the `playbackHlsUrl` and ` livestreamUrl` of the HLS to play it on the Viewer side when the state changes to `HLS_PLAYABLE`
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    ...

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {
    room.on(Events.hlsStateChanged, (Map<String, dynamic> data) {
      //Status can be :: HLS_STARTING
      //Status can be :: HLS_STARTED
      //Status can be :: HLS_PLAYABLE
      //Status can be :: HLS_STOPPING
      //Status can be :: HLS_STOPPED
      log("Meeting HLS status : ${data['status']}");
      if (data['status'] == "HLS_PLAYABLE")
        log("PLAYBACKHLS URL -- " + data['playbackHlsUrl']);
    });
  }
  //highlight-end
}
```

## Custom Template

With VideoSDK, you can also use your own custom designed layout template to livestream the meetings. In order to use the custom template, you need to create a template for which you can [follow this guide](/react/guide/interactive-live-streaming/custom-template). Once you have setup the template, you can use the [REST API to start](/api-reference/realtime-communication/start-livestream) the livestream with the `templateURL` parameter.

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startHls](/flutter/api/sdk-reference/room-class/methods#starthls)
- [stopHls](/flutter/api/sdk-reference/room-class/methods#stophls)
- [Events.hlsStateChanged](/flutter/api/sdk-reference/room-class/events#hlsstatechanged)


---

# Stop HLS - Flutter

This could refer to stopping the transmission of an ongoing HLS stream, which would mean the stream is no longer available to viewers.

## Stopping HLS

`stopHls()` can be used to stop a interactive livestream of the meeting which can be accessed from the `Room` object.

### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ElevatedButton(
          onPressed:(){
            _room.stopHls();
          },
          child: const Text("Stop HLS"),
        ),
    //highlight-end
      ]
    );
  }
}
```

## Event associated with HLS

- **hlsStateChanged** - Whenever meeting HLS state changes, then `hlsStateChanged` event will trigger.

- You will get `HLS_STOPPING` and `HLS_STOPPED` status on calling `stopHls()`.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    ...

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {
    room.on(Events.hlsStateChanged, (Map<String, dynamic> data) {
      //Status can be :: HLS_STARTING
      //Status can be :: HLS_STARTED
      //Status can be :: HLS_PLAYABLE
      //Status can be :: HLS_STOPPING
      //Status can be :: HLS_STOPPED
      log("Meeting HLS status : ${data['status']}");
      if (data['status'] == "HLS_STOPPING")
        log("HLS Stopping");
      if (data['status'] == "HLS_STOPPED")
        log("HLS Stopped");
    });
  }
  //highlight-end
}
```

## Custom Template

With VideoSDK, you can also use your own custom designed layout template to livestream the meetings. In order to use the custom template, you need to create a template for which you can [follow this guide](/react/guide/interactive-live-streaming/custom-template). Once you have setup the template, you can use the [REST API to start](/api-reference/realtime-communication/start-livestream) the livestream with the `templateURL` parameter.

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startHls](/flutter/api/sdk-reference/room-class/methods#starthls)
- [stopHls](/flutter/api/sdk-reference/room-class/methods#stophls)
- [Events.hlsStateChanged](/flutter/api/sdk-reference/room-class/events#hlsstatechanged)


---

# Chat using PubSub - Flutter

For the communication or any kind of messaging in between the participants, VideoSDK provides `pubSub` which use Publish-Subsciribe mechanism and can be used to develope wide varitey of functionalities. For example, participants could use it to send chat messages to each other, share files or other media, or even trigger actions like muting or unmuting audio or video.

Now we will see, how we can use PubSub to implement Chat functionality. If you are not familiar with the PubSub mechanism, you can [follow this guide](/flutter/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

## Implementing Chat

1. First step in creating a group chat is choosing the topic which all the participants will publish and subscribe to send and receive the messages. We will be using `CHAT` as the topic for this one. So let us lets create a message input and send button to publish the messages using the `pubSub` from the `Room` object.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ChatView extends StatefulWidget {
  final Room room;
  ...
}

class _ChatViewState extends State<ChatView> {

  final msgTextController = TextEditingController();


  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        Row(
          children: [
            Expanded(
              child: TextField(
                style: TextStyle(
                  fontSize:16,
                  fontWeight: FontWeight.w500,
                ),
                controller: msgTextController,
                onChanged: (value) => setState(() {
                  msgTextController.text;
                }),
                decoration: const InputDecoration(
                  hintText: "Write your message",
                  border: InputBorder.none,
                ),
              ),
            ),
            ElevatedButton(
              onPressed:(){
                if(!msgTextController.text.trim().isEmpty){
                  widget.room.pubSub
                        .publish(
                          "CHAT",
                          msgTextController.text,
                          const PubSubPublishOptions(
                              persist: true),
                        )
                        .then(
                            (value) => msgTextController.clear())
                }
              },
              child: const Text("Send Message"),
            ),
          ],
        ),
    //highlight-end
      ]
    );
  }

}
```

2. Final step in the group chat would be to display the messages others send. For this will use the `messages` and display all the messages by subscribing to the topic `CHAT`.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ChatView extends StatefulWidget {
  final Room room;
  ...
}

class _ChatViewState extends State<ChatView> {

  // PubSubMessages
  PubSubMessages? messages;

  @override
  void initState() {
    //highlight-next-line
    ...

    //highlight-start
    // Subscribing 'CHAT' Topic
    widget.meeting.pubSub
      .subscribe("CHAT", messageHandler)
      .then((value) => setState((() => messages = value)));
    //highlight-end
  }

  //highlight-start
  //Handler which will be called when new mesasge is received
  void messageHandler(PubSubMessage message) {
    setState(() => messages!.messages.add(message));
  }
  //highlight-end

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        Expanded(
          child: messages == null
              ? const Center(child: CircularProgressIndicator())
              : SingleChildScrollView(
                  reverse: true,
                  child: Column(
                    children: messages!.messages
                        .map(
                          (message) => Text(
                            message.message
                          ),
                        )
                        .toList(),
                  ),
                ),
        ),

        ...
        //Send Message code Here
    //highlight-end
      ]
    );
  }

  @override
  void dispose() {
    //highlight-start
    // Unsubscribe
    widget.room.pubSub.unsubscribe("CHAT", messageHandler);
    //highlight-end
    super.dispose();
  }
}
```

### Displaying Latest Message Notificaiton

You may want to show the notification to the user when new message arrives. So lets continue our example and add alert for the new images.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ChatView extends StatefulWidget {
  final Room room;
  ...
}

class _ChatViewState extends State<ChatView> {

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  //highlight-start
  //Handler which will be called when new mesasge is received
  void messageHandler(PubSubMessage message) {
    //Show snackbar on new message
    if(context.mounted){
      ScaffoldMessenger.of(context).showSnackBar(SnackBar(
        content: Text(
          message.message,
          overflow: TextOverflow.fade,
        ),
      ));
    }
    setState(() => messages!.messages.add(message));
  }
  //highlight-end

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ...
         //highlight-end
      ]
    );
  }

  @override
  void dispose() {
    //highlight-next-line
    ...
  }
}
```

## Downloading Chat Messages

All the messages from the PubSub which where published with `persist : true` and can be downloaded as an `.csv` file. This file will be available in the VideoSDK dashboard as well as throught the [Sessions API](/api-reference/realtime-communication/fetch-session-using-sessionid).

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub](/flutter/api/sdk-reference/pubsub-class/introduction)


---

# Notify Attendees in Realtime - Flutter

When doing livestream, you may want to broadcast message to all the viewers at once.

Let us see, how we can use PubSub to implement this functionality. If you are not familiar with the PubSub mechanism you can [follow this guide](/flutter/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

### Notifying Attendees

1. We will be creating a button and text input to take the message input and we will publish a message to the topic `NOTIFY_ATTENDEES`

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class NotifyView extends StatefulWidget {
  final Room room;
  ...
}

class _NotifyViewState extends State<NotifyView> {

  final msgTextController = TextEditingController();


  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        Row(
          children: [
            Expanded(
              child: TextField(
                style: TextStyle(
                  fontSize:16,
                  fontWeight: FontWeight.w500,
                ),
                controller: msgTextController,
                onChanged: (value) => setState(() {
                  msgTextController.text;
                }),
                decoration: const InputDecoration(
                  hintText: "Write your message",
                  border: InputBorder.none,
                ),
              ),
            ),
            ElevatedButton(
              onPressed:(){
                if(!msgTextController.text.trim().isEmpty){
                  widget.room.pubSub
                        .publish(
                          "NOTIFY_ATTENDEES",
                          msgTextController.text,
                          const PubSubPublishOptions(
                              persist: true),
                        )
                        .then(
                            (value) => msgTextController.clear())
                }
              },
              child: const Text("Notify Attendees"),
            ),
          ],
        ),
    //highlight-end
      ]
    );
  }

}
```

2. Now let us show an alert to all the viewers displaying the message posted by the speaker.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ViewerView extends StatefulWidget {
  final Room room;
  ...
}

class _ViewerViewState extends State<ViewerView> {

  @override
  void initState() {
    //highlight-next-line
    ...

    //highlight-start
    // Subscribing 'NOTIFY_ATTENDEES' Topic
    widget.meeting.pubSub
      .subscribe("NOTIFY_ATTENDEES", messageHandler);
    //highlight-end
  }

  //highlight-start
  //Handler which will be called when new mesasge is
  //These is where we will show the message
  void messageHandler(PubSubMessage message) {
    if(context.mounted && widget.room.localParticipant.mode == MOde.SIGNALLING_ONLY){
      ScaffoldMessenger.of(context).showSnackBar(SnackBar(
        content: Text(
          message.message,
          overflow: TextOverflow.fade,
        ),
      ));
    }
  }
  //highlight-end

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-next-line
        ...
      ]
    );
  }

  @override
  void dispose() {
    //highlight-start
    // Unsubscribe
    widget.room.pubSub.unsubscribe("NOTIFY_ATTENDEES", messageHandler);
    //highlight-end
    super.dispose();
  }
}
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [PubSub](/flutter/api/sdk-reference/pubsub-class/introduction)


---

# Raise Hand - Flutter

Let us see, how we can use PubSub to implement Raise hand functionality. If you are not familiar with the PubSub mechanism you can [follow this guide](/flutter/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

### Implementing Raise Hand

1. We will be creating a button when clicked, we will publish a message it the topic `RAISE_HAND`

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class NotifyView extends StatefulWidget {
  final Room room;
  ...
}

class _NotifyViewState extends State<NotifyView> {

  final msgTextController = TextEditingController();


  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ElevatedButton(
          onPressed:(){
            widget.room.pubSub
                  .publish(
                    "RAISE_HAND",
                    "Raised Hand",
                    const PubSubPublishOptions(
                        persist: true),
                  );
          },
          child: const Text("Raise Hand"),
        ),
    //highlight-end
      ],
    );
  }

}
```

2. Now let us show an alert to all the speakers showing who raised the hand.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class SpeakerView extends StatefulWidget {
  final Room room;
  ...
}

class _SpeakerViewState extends State<SpeakerView> {

  @override
  void initState() {
    //highlight-next-line
    ...

    //highlight-start
    // Subscribing 'RAISE_HAND' Topic
    widget.meeting.pubSub
      .subscribe("RAISE_HAND", messageHandler);
    //highlight-end
  }

  //highlight-start
  //Handler which will be called when new mesasge is
  //These is where we will show the message
  void messageHandler(PubSubMessage message) {
    if(context.mounted && widget.room.localParticipant.mode == Mode.SEND_AND_RECV){
      ScaffoldMessenger.of(context).showSnackBar(SnackBar(
        content: Text(
          "${message.senderName} raised hand",
          overflow: TextOverflow.fade,
        ),
      ));
    }
  }
  //highlight-end

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-next-line
        ...
      ]
    );
  }

  @override
  void dispose() {
    //highlight-start
    // Unsubscribe
    widget.room.pubSub.unsubscribe("RAISE_HAND", messageHandler);
    //highlight-end
    super.dispose();
  }

}
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [PubSub](/flutter/api/sdk-reference/pubsub-class/introduction)


---

# Introduction

Welcome to the Flutter Interactive Live Streaming (ILS). Build real-time, low-latency experiences where hosts and audiences connect, interact, and engage seamlessly using VideoSDK.

## Architecture Overview

**Architecture at a Glance** — Hosts join with `SEND_AND_RECV` permissions to broadcast and collaborate, while audiences connect with `RECV_ONLY` access to enjoy the stream without publishing their own media.

![Interactive Live Streaming architecture diagram](https://assets.videosdk.live/images/ils-architecture-live-streaming.png)

## Streaming Modes

**Interactive Live Streaming (ILS):** Low-latency, two-way sessions where hosts and promoted guests publish audio/video, manage roles, and drive rich audience participation.

**HTTP Live Streaming (HLS):** Broadcast delivery tuned for massive audiences with receiver-only playback and CDN scaling, perfect for town halls and one-to-many events.

- [Interactive Live Streaming Quick Start](/flutter/guide/video-and-audio-calling-api-sdk/quick-start-flutter-ils): Launch a Flutter ILS app from a single codebase with backstage, role, and engagement flows.
- [HTTP Live Streaming Quick Start](/flutter/guide/video-and-audio-calling-api-sdk/quick-start-ils): Follow the Flutter HLS steps to broadcast reliably to large, multi-platform audiences.


Use the guide below to explore the modular capabilities that help you design each part of this flow.

## Key Features

- [Cross-platform Staging](/flutter/guide/interactive-live-streaming/layout-managment/rendering-host-audience-views): Coordinate layouts and backstage flows that render seamlessly across mobile, web, and desktop targets.
- [Audience Management](/flutter/guide/interactive-live-streaming/audiance-managment/change-mode): Moderate large rooms, promote viewers, and balance speaker slots on any device.
- [Device & Screen Control](/flutter/guide/interactive-live-streaming/device-management/change-devices): Toggle cameras, microphones, and share screens with Flutter plugins across platforms.
- [Interactive Engagement](/flutter/guide/interactive-live-streaming/chat-during-livestream): Add chat, reactions, polls, and raise-hand to keep audiences leaning in.
- [Real-time Analytics](/flutter/guide/interactive-live-streaming/analytics/understanding-analytics-dashboard): Visualise quality and engagement trends with the analytics dashboard.
- [Recording & Highlights](/flutter/guide/interactive-live-streaming/recording/overview): Capture sessions, automate storage, and generate highlight reels for on-demand playback.
- [Geo & Network Policies](/flutter/guide/interactive-live-streaming/geo-fencing): Keep content compliant with geography and enterprise access requirements.
- [Relay & Multistream](/flutter/guide/interactive-live-streaming/relay-media): Simulcast or redistribute streams using relay media and HLS routes.


## Sample Projects

- [Flutter ILS Starter](https://github.com/videosdk-live/videosdk-ils-flutter-sdk-example): Spin up a Flutter host and audience experience with minimal setup.
- [Flutter HLS Broadcast](https://github.com/videosdk-live/videosdk-hls-flutter-sdk-example): Scale to tens of thousands of viewers with the HLS broadcast starter.


## Quick Start Paths

- [Install the SDK](/flutter/guide/interactive-live-streaming/flutter-sdk): Add the VideoSDK Flutter package and configure platform integrations.
- [Configure Tokens](/flutter/guide/interactive-live-streaming/authentication-and-tokens): Generate secure tokens on your backend before onboarding viewers.
- [Launch the ILS Sample](/flutter/guide/video-and-audio-calling-api-sdk/run-a-sample-ils-project): Clone the Flutter ILS sample to validate host and viewer journeys.
- [Broadcast with HLS](/flutter/guide/video-and-audio-calling-api-sdk/run-a-sample-hls-project): Test the Flutter HLS sample to ensure massive audience playback.
- [Review Best Practices](/flutter/guide/interactive-live-streaming/best-practices/user-experience): Fine-tune UX, performance, and scalability tailored to Flutter apps.
- [Supported Platforms](/flutter/guide/interactive-live-streaming/supported-browser-and-device-os): Validate device and browser coverage before nationwide launches.



---

# Known Issues - Flutter




---

# Pin/Unpin Participants - Flutter

In a live stream setup, you often want to control which participant is actively visible on screen — whether it’s the host, a special guest, or someone screen sharing. To manage this dynamically, the `Participant` class provides two key methods:

- `pin()` – Focus on a specific participant’s camera or screen share

- `unpin()` – Remove that focus and return to the default layout

This allows you to programmatically decide who gets the spotlight in your live stream layout.

### `pin()`

The pin() method makes it easy to bring a host camera or screen share front and center in the broadcast layout. Once pinned, you can write the layout logic to place this host in the primary frame, e.g. fullscreen or in a highlighted position.

### `unpin()`

When a host is no longer the focus (e.g. their segment is over), you can reset their pinned state using unpin(). This allows your live stream UI to revert to a default grid view or automatically promote the next speaker.

### Events associated with pin/unpin

Following callbacks are received when a host is pinned or unpinned in the livestream.

- This event will be emitted when any [participant](/flutter/api/sdk-reference/participant-class/introduction) pin state gets changed.
- It will pass `participantId`, `state`, and `pinnedBy` as `Map<String, dynamic>` as an event handler parameter.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class SpeakerScreen extends StatefulWidget {
  ...
}

class _SpeakerScreenState extends State<SpeakerScreen> {
  late Room room;

  Map<String, Participant> _attendees = {};

  @override
  void initState() {
    //highlight-next-line
    setupLiveStreamEventListners();
    ...
  }

 void setUpLiveStreamEventListners(){
    room.on(Events.pinStateChanged, (data) {
    // do something
    });
   }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-next-line
        ...
      ]
    );
  }

  void updateAttendees(){
    Map<String, Participant> attendees = {};
    //highlight-start
    //we will pin localparticiant if mode is SEND_AND_RECV
    if(room.localParticipant.mode == Mode.SIGNALLING_ONLY);{
      attendees.putIfAbsent(
          room.localParticipant.id, () => room.localParticipant);
      room.localParticipant.unpin();
    }else{
      room.localParticipant.pin();
    }
      //highlight-end
    room.participants.values.forEach((participant) {
      if (participant.mode == Mode.SIGNALLING_ONLY) {
        attendees.putIfAbsent(participant.id, () => participant);
        //highlight-next-line
        participant.unpin();
      }
    });
    setState(()=>_attendees = attendees);
  }

}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [pin](/flutter/api/sdk-reference/participant-class/methods#pin)
- [unpin](/flutter/api/sdk-reference/participant-class/methods#unpin)
- [participants](/flutter/api/sdk-reference/room-class/properties#participants)
- [pinStateChanged](/flutter/api/sdk-reference/room-class/events#pinstatechanged)


---

# Rendering Host and Audience Views - Flutter

In a live stream setup, only hosts (participants in `SEND_AND_RECV` mode) can broadcast their audio and video. Audience members (in `RECV_ONLY` mode) are passive viewers who do not share their audio/video.

To ensure optimal performance and a clean user experience, your app should:

- **Render audio and video elements only for hosts** (i.e., participants in `SEND_AND_RECV` mode).
- **Display the total audience count** to give context on viewership without rendering individual audience tiles.

## Filtering and Rendering Hosts
The steps involved in rendering the video of hosts are as follows.

1. [Filtering Hosts and Checking their Cam Status](#1-filtering-hosts-and-checking-their-micwebcam-status)
2. [Rendering Video Streams of Hosts](#2-rendering-video-streams-of-hosts)


### `1. Filtering Hosts and Checking their Mic and Cam Status `

In a live stream, only participants in `SEND_AND_RECV` mode (i.e., hosts) actively share their audio and video. To render their video streams, begin by accessing all participants using the `Room` class. Then, filter out only those in `SEND_AND_RECV` mode.

For each of these participants, use the `Participant` class, which provides real-time information like displayName, micOn, and webcamOn. Display their name along with the current status of their microphone and Camera. If the camera is off, show a simple placeholder with their name. If it's on, render their video feed. This ensures only hosts are visible to the audience, keeping the experience clean and intentional.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class LiveStreamGrid extends StatelessWidget {
  final Map

</center>

### `2. Rendering Video Streams of Hosts`

Once you've filtered for participants in `SEND_AND_RECV` mode (i.e., hosts), you can use the `Participant` class to access their real-time data, including their CamStream, CamOn, and whether they are the local participant.

```js
class ParticipantViewTile extends StatefulWidget {
  final Participant participant;
  final bool isLocal;

  const ParticipantViewTile({
    Key? key,
    required this.participant,
    this.isLocal = false,
  }) : super(key: key);

  @override
  State

</center>

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [Participant Class](/flutter/api/sdk-reference/participant-class/properties)




---

# Live Captioning for Livestreams - Flutter

Live captioning enhances your livestreams by converting hosts' speech into text in real-time, boosting accessibility and engagement. Using the `Room` class, you can enable or disable captions on the fly, and display captions dynamically in your UI for all viewers.

Video SDK offers flexible configuration and event-driven updates to help you integrate captions seamlessly into your broadcast layout.

### `startTranscription()`

The `startTranscription()` method, accessible from the `Room` class, is used to initiate live captions in a live stream. This method accepts the following two parameters:

- `1. webhookUrl (optional)`: This is the webhook URL where you can listen to events related to the recording, such as the start and stop of recording. It triggers when the recording is completed and stored on the server. You can learn more about webhooks [here](https://en.wikipedia.org/wiki/Webhook)

- `2. summary (optional)`:
  - `enabled`: Indicates whether realtime transcription summary generation is enabled. Summary will be available after realtime transcription stopped. Default: false.
  - `prompt`: provides guidelines or instructions for generating a custom summary based on the realtime transcription content.

### `stopTranscription()`

The `stopTranscription()` method, accessible from the `Room` class, is used to stop the live captions in a live stream.


### Events associated with live captioning

- All [participants-including all the hosts and audience members](/flutter/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a callback on the [`transcriptionStateChanged`](/flutter/api/sdk-reference/room-class/events#transcriptionstatechanged) event with the current state of the captioning.
- All [participants-including all the hosts and audience members](/flutter/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a callback on the [`transcriptionText`](/flutter/api/sdk-reference/room-class/events#transcriptiontext) event with the latest captions whenever a host speaks.

#### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
class LiveStreamView extends StatefulWidget {
  ...
}

class _LiveStreamViewState extends State<LiveStreamView> {
  // Room object
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    setupLivestreamEventListener();
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      ElevatedButton(
        onPressed: () {
          //highlight-start
          // Configuration for realtime transcription
          final summaryConfig = SummaryConfig(
              enabled: true, prompt: 'Initial prompt for summary');
          final transcriptionConfig = TranscriptionConfig(
            webhookUrl: "https://your-webhook-url.com",
            summaryConfig: summaryConfig,
          );
          // Start realtime transcription
          _room.startTranscription(transcriptionConfig: transcriptionConfig);
          //highlight-end
        },
        child: const Text("Start Realtime Transcription"),
      ),
      ElevatedButton(
        onPressed: () {
          //highlight-start
          // Stop realtime transcription
          _room.stopTranscription();
          //highlight-end
        },
        child: const Text("Stop Realtime Transcription"),
      ),
    ]);
  }

  void setupLivestreamEventListener() {
    //highlight-start
    // Listen for transcription state changed event
    _room.on(Events.transcriptionStateChanged, (Map<String, dynamic> data) {
      //Status can be :: TRANSCRIPTION_STARTING
      //Status can be :: TRANSCRIPTION_STARTED
      //Status can be :: TRANSCRIPTION_STOPPING
      //Status can be :: TRANSCRIPTION_STOPPED
      log("Livestream transcription status : ${data['status']}");
    });
    //highlight-end

    //highlight-start
    // Listen for transcription text event
    _room.on(Events.transcriptionText, (Map<String, dynamic> data) {
      log("${data['participantName']}: ${data['text']} ${data['timestamp']}");
    });
    //highlight-end
  }
}
```
## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startTranscription()](/flutter/api/sdk-reference/room-class/methods#starttranscription)
- [stopTranscription()](/flutter/api/sdk-reference/room-class/methods#stoptranscription)
- [Events.transcriptionStateChanged](/flutter/api/sdk-reference/room-class/events#transcriptionstatechanged)
- [Events.transcriptionText](/flutter/api/sdk-reference/room-class/events#transcriptiontext)

---

# Reactions during Live Stream - Flutter

To enhance interaction between viewers and speakers during a livestream, a creative approach is to display viewers' reactions to everyone. This can be achieved by creating a lively atmosphere with flying emojis, similar to the experience seen in livestreams on platforms like Instagram.

This guide explains how to implement this engaging feature using the VideoSDK PubSub mechanism.


### Step 1: Creating a button to send reaction

To implement this functionality, start by creating a button that sends reactions to all users. When this button is clicked, publish a message with the emoji name to all participants using the VideoSDK PubSub mechanism.


```js


import 'dart:math';
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ReactionSender extends StatelessWidget {
  final Room room;

  const ReactionSender({required this.room});

  void sendReaction(BuildContext context, String reaction) {
    // Show local emoji immediately
    showEmoji(context, reaction);

    // Send reaction to others
    room.pubSub.publish(
      "REACTION",
      reaction,
      const PubSubPublishOptions(persist: false),
    );
  }

  void showEmoji(BuildContext context, String reaction) {
    final overlay = Overlay.of(context);
    final emojiEntry = OverlayEntry(
      builder: (context) => FlyingEmojiWidget(emoji: reaction),
    );
    overlay.insert(emojiEntry);

    Future.delayed(const Duration(seconds: 3), () => emojiEntry.remove());
  }

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () => sendReaction(context, "😍"),
      child: const Text("Send Reaction"),
    );
  }
}
class FlyingEmojiWidget extends StatefulWidget {
  final String emoji;

  const FlyingEmojiWidget({required this.emoji});

  @override
  State<FlyingEmojiWidget> createState() => _FlyingEmojiWidgetState();
}

class _FlyingEmojiWidgetState extends State<FlyingEmojiWidget>
    with SingleTickerProviderStateMixin {
  late final AnimationController _controller;
  late final Animation<Offset> _animation;
  final Random random = Random();

  @override
  void initState() {
    super.initState();

    final dx = random.nextDouble() * 2 - 1; // random horizontal direction
    final startOffset = Offset(dx, 1.2); // start off bottom
    final endOffset = Offset(dx, -0.2);  // move to top

    _controller = AnimationController(
      vsync: this,
      duration: const Duration(milliseconds: 3000),
    );

    _animation = Tween<Offset>(
      begin: startOffset,
      end: endOffset,
    ).animate(CurvedAnimation(parent: _controller, curve: Curves.easeOut));

    _controller.forward();
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Positioned.fill(
      child: SlideTransition(
        position: _animation,
        child: Align(
          alignment: Alignment.center,
          child: Text(widget.emoji, style: const TextStyle(fontSize: 40)),
        ),
      ),
    );
  }
}
```
### Step 2: Displaying the Reactions to all the users

`FlyingEmojiWidget` will be utilized to display the reactions on the screen. Listen to the browser event sent on the button click to show the flying emoji and display all reactions sent by other participants

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ReactionListener extends StatefulWidget {
  final Room room;

  const ReactionListener({required this.room});

  @override
  State<ReactionListener> createState() => _ReactionListenerState();
}

class _ReactionListenerState extends State<ReactionListener> {
  @override
  void initState() {
    super.initState();
    widget.room.pubSub.subscribe("REACTION", handleReaction);
  }

  @override
  void dispose() {
    widget.room.pubSub.unsubscribe("REACTION", handleReaction);
    super.dispose();
  }

  void handleReaction(PubSubMessage message) {
    final reaction = message.message;
    showEmoji(context, reaction);
  }

  void showEmoji(BuildContext context, String emoji) {
    final overlay = Overlay.of(context);
    final emojiEntry = OverlayEntry(
      builder: (context) => FlyingEmojiWidget(emoji: emoji),
    );
    overlay.insert(emojiEntry);

    Future.delayed(const Duration(seconds: 3), () => emojiEntry.remove());
  }

  @override
  Widget build(BuildContext context) {
    return const SizedBox(); 
  }
}
```
## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [PubSub](/flutter/api/sdk-reference/pubsub-class/introduction)


---

Recording meetings is an essential feature that ensures all important discussions, decisions, and interactions are documented for future reference. VideoSDK offers three types of recordings: Meeting Recording, Participant Recording, and Participant Track Recording. Each type serves a specific purpose to cater to different recording needs during a meeting.

## Meeting Recording

Meeting Recording captures the entire meeting, including all participants, audio, video, and shared content. This comprehensive recording is ideal for reviewing the entire meeting, ensuring that nothing is missed. It provides a holistic view of the meeting, capturing every interaction and piece of information shared during the session.

![Meeting Recording](https://cdn.videosdk.live/website-resources/docs-resources/MeetingRecording.png)

## Participant Recording

Participant Recording focuses on individual participants, capturing both their audio and video into a single file. This type of recording is particularly useful for tracking the contributions of specific participants or for scenarios where detailed analysis of an individual’s participation is needed. When a participant mutes their audio or turns off their video, the recording continues but with silenced audio or a black screen, respectively. This ensures a continuous recording without interruptions, reflecting the participant's involvement throughout the meeting.

![Participant Recording](https://cdn.videosdk.live/website-resources/docs-resources/ParticipantRecording.png)

## Participant Track Recording

Participant Track Recording allows you to record specific tracks of a participant, either audio or video, based on user input. This targeted approach is perfect for capturing particular aspects of a participant’s contribution, such as only their audio or only their video. Multiple files are generated whenever there is a change in the track's status (e.g., starting after being muted ), ensuring focused documentation of each continuous segment. This method is especially useful in scenarios where detailed analysis of specific media (audio or video) is required.

![Participant Track Recording](https://cdn.videosdk.live/website-resources/docs-resources/TrackRecording.png)



---

https://sdk.videosdk.live/js-sdk/0.2.6/videosdk.jsVideoSDK offers a range of video streaming tools and solutions for content creators, publishers, and developers.

- A custom template is a specialized layout for a live stream that allows users to integrate real-time graphics into their broadcasts.

- With custom templates, users can enhance their video content by overlaying graphics, text, images, and animations onto their live streams. These elements can be customized to align with specific branding requirements.

- By leveraging custom templates, users can craft dynamic and engaging video experiences. Whether incorporating live scoreboards, social media feeds, or other personalized elements, users have the flexibility to create visually appealing streams that stand out and capture audience attention.

:::note

Custom templates can also be used with recordings and RTMP service provided by VideoSDK.

:::

### What you can do with Custom Template

By utilizing a custom template, you have the flexibility to create various modes for your live stream. Here are some popular modes that you can design:

- **`PK Host:`** The host can organize a player vs. player battle, as illustrated in the example of a gaming battle shown below.

![pk host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_pk_battle.png)

- **`Watermark:`** The host has the ability to add and update watermarks anywhere in the template; for instance, the image below features a VideoSDK watermark on the top right side of the screen.

![watermark host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_water_mark.png)

- **`News Mode:`** Additionally, the host can incorporate dynamic text in the lower third banner, as demonstrated by the sample text in the bottom left of the screen.

![news mode](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_news_live.png)

### Custom template with VideoSDK

In this section, we will discuss how Custom Templates work with VideoSDK.

- **`Host`**: The host initiates live streaming by providing the `templateURL`. The `templateURL` is the URL of the hosted template webpage. The host is also responsible for managing the template, including tasks such as altering text, logos, and switching template layouts.

- **`VideoSDK Template Engine`** : The VideoSDK Template Engine accepts and opens the templateURL in the browser, actively listening to all events initiated by the Host. It facilitates the customization of the template in accordance with the host's preferences.

- **`Viewer`**: Viewers can stream the content, experiencing the live stream with added real-time graphics. This feature contributes to a distinctive and engaging viewing experience.

![custom template](https://cdn.videosdk.live/website-resources/docs-resources/custom_template.png)

### Understanding Template URL

The template URL is a webpage that VideoSDK Template Engine will open while composing the live stream.

It will appear as shown below.

![template url](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_url.png)

The Template URL comprises of two essential parts:

- Your actual page URL, resembling something like `https://example.com/videosdk-template`.
- Query parameters, designed to enable the VideoSDK Template Engine to seamlessly join the meeting upon opening the URL. There are three key query parameters in total:
  - `token`: Your token, serving as the authentication key to join the meeting.
  - `meetingId`: The meeting Id of the meeting that the VideoSDK Template Engine will join.
  - `participantId`: The participant ID of the VideoSDK Template Engine. This should be included when joining the template engine in your template, ensuring that the template engine participant remains invisible to other participants. **This parameter is automatically added by the VideoSDK**.

:::info

Above mentioned query parameters are mandatory. Apart from these parameters, you can pass any other extra parameters which are required according to your use-case.

:::

### **Creating Template**

**`Step 1:`** Import VideoSDK using `<script>` tag or install it using the below-mentioned npm command.
Make sure you are in your app directory before you run this command.



**Tab:**

" label="<script>" default>

```html
<html>
  <head></head>
  <body>
// highlight-next-line
<script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
  </body>
</html>
```

---

**npm:**

```bash
npm install @videosdk.live/js-sdk
```

---

**yarn:**

```bash
yarn add @videosdk.live/js-sdk
```

:::note

You can use VideoSDK's React or JavaScript SDK to create custom template. Following is the example of building custom template with JavaScript SDK.

:::

###### Structure of the Project

```jsx title="Project Structure"
  root
   ├── index.html
   ├── index.js
```

**`Step 2:`** Craft a user interface (UI) tailored for your live stream presentation.

```html title="index.html"
<!DOCTYPE html>
<html>
  <head> </head>

  <body>
    <div id="textDiv">Starting live stream...</div>

    
    <div class="row" id="videoContainer"></div>

    <script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
    <script src="index.js"></script>
  </body>
</html>
```

**`Step 3:`** Next, fetch the query parameters, from the URL which will be later used to initialize the meeting and get the elements from DOM.

```js title=index.js
const url = window.location;
const urlParams = new URLSearchParams(url.search);

const meetingId = urlParams.get("meetingId");
const token = urlParams.get("token");
const participantId = urlParams.get("participantId");

const videoContainer = document.getElementById("videoContainer");
const textDiv = document.getElementById("textDiv");
```

**`Step 4:`** Subsequently, initialize the meeting with the parameters that were extracted from the URL. Ensure direct initialization so that the template engine seamlessly joins the meeting upon page load.

```js title=index.js
window.VideoSDK.config(token);

const meeting = window.VideoSDK.initMeeting({
  meetingId: meetingId, // required
  name: "recorder", // required
  micEnabled: false,
  webcamEnabled: false,
  participantId: participantId,
});

meeting.join();

meeting.on("meeting-joined", () => {
  textDiv.style.display = "none";
});
```

**`Step 5:`** Next step is to create the container that will render the meeting view on the `participant-joined` event.

```js title=index.js
//  participant joined
meeting.on("participant-joined", (participant) => {
  let videoElement = createVideoElement(
    participant.id,
    participant.displayName
  );
  let audioElement = createAudioElement(participant.id);

  participant.on("stream-enabled", (stream) => {
    setTrack(stream, audioElement, participant, false);
  });
  videoContainer.appendChild(videoElement);
  videoContainer.appendChild(audioElement);
});

// participants left
meeting.on("participant-left", (participant) => {
  let vElement = document.getElementById(`f-${participant.id}`);
  vElement.remove(vElement);

  let aElement = document.getElementById(`a-${participant.id}`);
  aElement.remove(aElement);
});

// creating video element
function createVideoElement(pId, name) {
  let videoFrame = document.createElement("div");
  videoFrame.setAttribute("id", `f-${pId}`);

  //create video
  let videoElement = document.createElement("video");
  videoElement.classList.add("video-frame");
  videoElement.setAttribute("id", `v-${pId}`);
  videoElement.setAttribute("playsinline", true);
  videoElement.setAttribute("width", "300");
  videoElement.muted = true;
  videoFrame.appendChild(videoElement);

  let displayName = document.createElement("div");
  displayName.innerHTML = `Name : ${name}`;
  videoFrame.appendChild(displayName);

  return videoFrame;
}

// creating audio element
function createAudioElement(pId) {
  let audioElement = document.createElement("audio");
  audioElement.setAttribute("autoPlay", "false");
  audioElement.setAttribute("playsInline", "true");
  audioElement.setAttribute("controls", "false");
  audioElement.setAttribute("id", `a-${pId}`);
  audioElement.style.display = "none";
  return audioElement;
}

// setting media track
function setTrack(stream, audioElement, participant, isLocal) {
  if (stream.kind == "video") {
    isWebCamOn = true;
    const mediaStream = new MediaStream();
    mediaStream.addTrack(stream.track);
    let videoElm = document.getElementById(`v-${participant.id}`);
    videoElm.srcObject = mediaStream;
    videoElm
      .play()
      .catch((error) =>
        console.error("videoElem.current.play() failed", error)
      );
  }
  if (stream.kind == "audio") {
    if (isLocal) {
      isMicOn = true;
    } else {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(stream.track);
      audioElement.srcObject = mediaStream;
      audioElement
        .play()
        .catch((error) => console.error("audioElem.play() failed", error));
    }
  }
}
```

**`Step 6:`** Now, listen to PubSub messages from the `CHANGE_BACKGROUND` topic, triggering a change in the meeting's background color accordingly.

:::note

The PubSub mechanism is utilized to communicate with the template. You can learn more about [PubSub from here](/javascript/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

:::

```js title=index.js
meeting.on("meeting-joined", () => {
  //  ...

  meeting.pubSub.subscribe("CHANGE_BACKGROUND", (data) => {
    let { message } = data;
    document.body.style.backgroundColor = message;
  });
});
```

**`Step 7:`** Once tested, you can deploy it using your backend or host it on services like [firebase](https://www.geeksforgeeks.org/how-to-deploy-react-project-on-firebase/) or vercel.

:::tip

You can checkout the github repository for sample custom template [created here](https://github.com/videosdk-live/videosdk-custom-recording-template-js-example).

:::

### Setup Livestream Using Custom Template

- To utilize Custom Templates with Livestream, you need to establish both the Host and Viewer setups. The Host initiates the livestream, while Viewers can watch the broadcast.

![template manager](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_manager.png)

- To understand custom templates, clone this example and run it on your system.

```bash
git clone https://github.com/videosdk-live/videosdk-custom-recording-template-js-example.git
```

- You can utilize this custom template in [Start Recording API](/api-reference/realtime-communication/start-recording), [Start HLS API](/api-reference/realtime-communication/start-hlsStream) and [Start Livestream API](/api-reference/realtime-communication/start-livestream). Here is the example of HLS.
- To utilize the custom template that has been deployed, invoke the [Start HLS API](https://docs.videosdk.live/api-reference/realtime-communication/start-hlsStream) instead of the `startHls` method from the `Meeting` class. The necessary code has already been incorporated in the cloned example above.

:::important

You can create your own custom template manager in JavaScript. In this example, we are using one for better understanding.

:::

```js
<button
  onClick={async () => {
    const url = `https://api.videosdk.live/v2/hls/start`;
    //Update your Custom Template URL here if you have deployed your own, if not deployed you can use this template from our URL.
    //highlight-next-line
    const templateUrl = `https://lab.videosdk.live/js-template-demo/?meetingId=${meetingId}&token=${authToken}`;
    const options = {
      method: "POST",
      headers: {
        Authorization: authToken,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        roomId: meetingId,
        templateUrl: templateUrl,
      }),
    };

    const result = await fetch(url, options)
      .then((response) => response.json()) // result will have playbackHlsUrl and livestreamUrl
      .catch((error) => console.error("error", error));
  }}
>
  Start HLS
</button>
```

- In this example, the host has two options on their side, enabling them to change the background and send messages to the viewers.

- Given below is a test run of the example.


<div style={{textAlign: 'center'}}>



</div>

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)
- [Start HLS API](/api-reference/realtime-communication/start-hlsStream)
- [Start Livestream API](/api-reference/realtime-communication/start-livestream)
- [recordingState](/react/api/sdk-reference/use-meeting/properties#recordingstate)
- [hlsState](/react/api/sdk-reference/use-meeting/properties#hlsstate)
- [livestreamState](/react/api/sdk-reference/use-meeting/properties#livestreamstate)
- [hlsUrls](/react/api/sdk-reference/use-meeting/properties#hlsurls)
- [onRecordingStateChanged](/react/api/sdk-reference/use-meeting/events#onrecordingstatechanged)
- [onHlsStateChanged](/react/api/sdk-reference/use-meeting/events#onhlsstatechanged)
- [onLivestreamStateChanged](/react/api/sdk-reference/use-meeting/events#onlivestreamstatechanged)



---

# Geo Tag Meeting Recordings - Flutter

To ensure compliance for BFSIs doing vKYC, it very important to include the co-ordinates(location) of the customer in the recordings. VideoSDK provides a very customizable solution to implement this feature. You will be using custom templates for this purpose.

We have created a ready to use template for this use case which can be found [here](https://github.com/videosdk-live/videosdk-rtc-react-prebuilt-ui/tree/template/geo-tag-watermark). To integrate this template with your recordings follow the below mentiond instructions.

### Host the template

1. Clone the template repository and switch to the branch `template/geo-tag-watermark`.

```bash
git clone https://github.com/videosdk-live/videosdk-rtc-react-prebuilt-ui.git
cd videosdk-rtc-react-prebuilt-ui
git checkout template/geo-tag-watermark
```

2. Install the dependencies and create a build of the project using below mentioned commands.

```bash
npm install
npm run build
```

3. Host the contents of the build folder on your server and check if the template is up and running.

:::note

If you want to create the complete template from scratch you can [follow this guide.](/flutter/guide/video-and-audio-calling-api-sdk/live-streaming/custom-template)

:::

### Using the template for recording

1. To use the template that we deployed earlier, we will be using the `templateUrl` feature in the `startRecording` API.
   To generate the template URL, you will have to append the `meetingId`, and `token` has to be added in the query parameters. Also if you are using the template provided above you need to added a few extra parameters mentioned below. Here is the code snippet to generate the URL.

```js
async function main() {
  let meetingId = "Your MeetingID";
  let token = "Your Token";
  const templateUrl = `https://${YOUR Template URL}/?meetingId=${meetingId}&token=${token}&name=recorder&isRecorder=true&joinWithoutUserInteraction=true`;

  console.log(templateUrl);
}

main();
```

2. Now that we have the template URL, we will use this URL to start the recording using the below provided API call.

```js
async function main() {
  let meetingId = "Your MeetingID";
  let token = "Your Token";
  const templateUrl = `https://${YOUR Template URL}/?meetingId=${meetingId}&token=${token}&name=recorder&isRecorder=true&joinWithoutUserInteraction=true`;

  console.log(templateUrl);

  //Using the previouly created template URL and starting the recording using the API.
  const options = {
    method: "POST",
    headers: {
      Authorization: "$YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      roomId: "Your MeetingId",
      templateUrl: templateUrl,
    }),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();
```

### Updating the Geo Tagging Coordinates

We will be using the PubSub feature of VideoSDK to update the data of latitude and longitude. For the predefined template provided by us we are using `GEO_TAG` as topic name. We will be publishing the `participantName`, `latitude` and `longitude` of the participant for whom we want to show in the recording.

:::note

You will have to fetch the longitude and latitude of the participant before sending it using the pubsub.

:::

Here is the code how you will have to publish the message:

```js
  ElevatedButton(
    onPressed:(){
      _room.pubSub.publish(
        "GEO_TAG",
        "GEO TAG DATA",
        const PubSubPublishOptions(persist: true),
        {
          "latitude": "LATITUDE OF PARTICIPANT",
          "longitude": "LONGITUDE OF PARTICIPANT",
          "participantName": "NAME OF PARTICIPANT",
        })
    },
    child: const Text("Send Message"),
  )
```

After implementing this, you should get the recording in the following format:

![Geo Tagging Recoridng](https://cdn.videosdk.live/website-resources/docs-resources/geo-tag-recording-template.png)

If you wish to change how UI looks on recording, you can change it by updating the layout in the template itself.

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)
- [Learn more about Custom Templates](/flutter/guide/video-and-audio-calling-api-sdk/live-streaming/custom-template)


---

You have the option to create presigned URL, allowing you to upload your recordings to AWS, Azure, or GCP securely.
presigned URL provide a secure and temporary way to upload objects to your cloud storage. Instead of sharing your entire credentials, you can create a special URL that allows uploading a specific file for a limited time.

:::important

While presigned URL offer a convenient way to upload files securely, each cloud provider (AWS, Azure, and GCP) might have different restrictions on how they work. It's advisable to refer the respective documentation for **[<u>AWS</u>](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)**, **[<u>Azure</u>](https://learn.microsoft.com/en-us/rest/api/storageservices/delegate-access-with-shared-access-signature)**, and **[<u>GCP</u>](https://cloud.google.com/cdn/docs/using-signed-urls)** to gain a clearer understanding of presigned URL.

:::

### Code Sample

This guide will walk you through the process of generating a presigned URL for uploading recordings to your cloud storage of choice. You can use this generated presigned URL in [Start Recording API](/api-reference/realtime-communication/start-recording#preSignedUrl).



**AWS:**

```js
const { S3Client, PutObjectCommand } = require("@aws-sdk/client-s3");
const { getSignedUrl } = require("@aws-sdk/s3-request-presigner");

const region = <YOUR S3 REGION>;
const bucket = <YOUR S3 BUCKET NAME>;
const key = <YOUR FILE NAME>; // test/abc.mp4
const accessKeyId = <YOUR S3 ACCESS KEY ID>;
const secretAccessKey = <YOUR S3 SECRET ACCESS KEY>;
const expiresIn = <URL EXPIRY IN SECONDS>; // this number should be higher than duraion of recording

const s3Client = new S3Client({
credentials: {
    accessKeyId: accessKeyId,
    secretAccessKey: secretAccessKey,
},
region: region,
});

const createPresignedUrlWithClient = async () => {
const command = new PutObjectCommand({ Bucket: bucket, Key: key });
const preSignedUrl = await getSignedUrl(s3Client, command, { expiresIn: expiresIn });
return preSignedUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await createPresignedUrlWithClient();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

---

**AZURE:**

```js
const { BlobServiceClient, BlobSASPermissions } = require("@azure/storage-blob");

const connectionString = <YOUR AZURE STORAGE CONNECTION STRING>;
const containerName = <YOUR AZURE CONTAINER NAME>;
const blobName = <YOUR AZURE BLOB NAME>;
const startsOn = <YOUR SASURL START TIME>; // (optional, defaults to now)
const expiresOn = <YOUR SASURL EXPIRY TIME>; // expiry time should be higher than duration of recording

const generateSASUrl = async () => {
let blobServiceClient = BlobServiceClient.fromConnectionString(connectionString);
let containerClient = blobServiceClient.getContainerClient(containerName);

await containerClient.createIfNotExists({
    access: "container",
});

const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const sasUrl = await blockBlobClient.generateSasUrl({
    startsOn: startsOn, // sasUrl start time
    expiresOn: expiresOn, // sasUrl expiration time
    permissions: BlobSASPermissions.parse("write"),
});
return sasUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await generateSASUrl();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

---

**GCP:**

```js
const { Storage } = require("@google-cloud/storage");

const projectId = <YOUR GCP PROJECT ID>;
const clientEmail = <YOUR GCP CLIENT EMAIL>;
const privateKey = <YOUR GCP PRIVATE KEY>;
const expires =<URL EXPIRY IN SECONDS>; // this number should be higher than duraion of recording
const bucketName = <YOUR GCP BUCKET NAME>;
const fileName = <YOUR FILE NAME>; // test/abc.mp4

const storage = new Storage({
projectId: projectId,
credentials: {
    client_email: clientEmail,
    private_key: privateKey,
},
});

const generateSignedUrl = async () => {
const options = {
    version: "v4",
    action: "write",
    expires: expires,
    contentType: "video/mp4",
};

const [signedUrl] = storage.bucket(bucketName).file(fileName).getSignedUrl(options);
return signedUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await generateSignedUrl();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)



---

VideoSDK offers individual participant recording, generating a single, continuous file for a participant.

This recording captures the participant's audio and video streams throughout the meeting, regardless of whether they are muted or have their camera turned off. During periods of audio muting or video disengagement, the respective tracks will be silent or display a black screen, respectively.

You can access the recorded files in the developer dashboard or opt to store them in your own cloud storage.

This guide provides an overview of the start and stop functionality for individual participant recording through APIs.


## Start Individual Participant Recording

To start a participant recording, you will have to call `/v2/recordings/participant/start` API with following body parameters.

- `roomId`: RoomId for which the participant recording is to be started
- `participantId`: participantId of the participant to be recorder.
- `fileFormat`: Currently only `webm` is supported as file format. We will add the support for other formats in future.
- `webhookUrl`: The webhook URL where you would like to get the status updates of the recording. To learn more about webhooks refer [here](#participant-track-recording-starting).
- `bucketDirPath`: If you are using your own storage, you can provide the directory path where you want to store the recording. To configure the storage please [refere this quide](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config).

The usual recording path would look like `${sessionId}/${participantId}/${filename}`.

```js
import 'package:http/http.dart' as http;
import 'dart:convert';

Future<void> startParticipantRecording() async {
  final String roomId = "<YOUR ROOM ID>";
  final String participantId = "<PARTICIPANT ID>";
  final String fileFormat = "<YOUR FILE FORMAT>"; // (Optional) default: webm
  final String bucketDirPath = "<YOUR CLOUD STORAGE BUCKET PATH>"; // (Optional) test/abc
  final String webhookUrl = "<YOUR WEBHOOK URL>"; // (Optional)

  final url = Uri.parse("https://api.videosdk.live/v2/recordings/participant/start");
  final headers = {
    "Authorization": "$YOUR_TOKEN",
    "Content-Type": "application/json",
  };
  final body = jsonEncode({
    "roomId": roomId,
    "participantId": participantId,
    "fileFormat": fileFormat,
    "bucketDirPath": bucketDirPath,
    "webhookUrl": webhookUrl,
  });

  final response = await http.post(url, headers: headers, body: body);

  if (response.statusCode == 200) {
    print('Participant Recording started successfully');
  } else {
    print('Failed to start participant recording');
  }
}

```

## Stop Individual Participant Recording

To stop a participant recording, you will have to call `/v2/recordings/participant/stop` API with following body parameters.

- `roomId`: RoomId for which the participant recording is to be stopped
- `participantId`: participantId for which the recording is to be stopped.

```js
import 'dart:convert';
import 'package:http/http.dart' as http;

Future<void> stopParticipantRecording(String roomId, String participantId) async {
  final url = Uri.parse('https://api.videosdk.live/v2/recordings/participant/stop');
  final headers = {
    'Authorization': '$YOUR_TOKEN',
    'Content-Type': 'application/json',
  };
  final body = json.encode({
    'roomId': roomId,
    'participantId': participantId,
  });

  final response = await http.post(url, headers: headers, body: body);

  if (response.statusCode == 200) {
    print('Participant Recording stopped successfully');
  } else {
    print('Failed to stop participant recording');
  }
}

```

## Webhook associated with Participant Recording

### participant-recording-starting

- A "Participant Recording Starting" webhook is triggered when the participant recording process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-started

- Participant Recording started webhook will be received when successfully participant recording is started in meeting

###### Example

```javascript
{
    "webhookType": "participant-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopping

- A "Participant Recording Stopping" webhook is triggered when the participant recording end process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopped

- Participant Recording stopped webhook will be received when participant recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "participant-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-recording-failed

- A "Participant Recording Failed" webhook is generated when the participant recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "participant-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
    },
}
```

---

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Participant Recording API](/api-reference/realtime-communication/start-participant-recording)
- [Stop Participant Recording API](/api-reference/realtime-communication/stop-participant-recording)



---

VideoSDK provides participant track recording, creating separate audio or video files for participant.

New files are generated when a participant starts their audio or video again after turning it off (e.g., unmuting the microphone or restarting the camera). This ensures that each file represents a continuous segment of audio or video content.

Once track recording is complete, all audio files for a participant are consolidated into a single directory, as are the video files.


## Start Participant Track Recording

To start a participant track recording, you will have to call `/v2/recordings/participant/track/start` API with following body parameters.

- `roomId`: RoomId for which the participant track recording is to be started
- `participantId`: participantId of the participant to be recorder.
- `kind`: The kind of tracks you want to record.
  - You can pass following values: _`audio`_ | _`video`_ | _`screen_audio`_ | _`screen_video`_
- `fileFormat`: Currently only `webm` is supported as file format. We will add the support for other formats in future.
- `webhookUrl`: The webhook URL where you would like to get the status updates of the recording. To learn more about webhooks refer [here](#participant-track-recording-starting).
- `bucketDirPath`: If you are using your own storage, you can provide the directory path where you want to store the recording. To configure the storage please [refere this quide](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config).

The usual recording path would look like `${sessionId}/${participantId}/${kind}/${filename}`.

```js
import 'package:http/http.dart' as http;
import 'dart:convert';

Future<void> startTrackRecording() async {
  final String roomId = "<YOUR ROOM ID>";
  final String participantId = "<PARTICIPANT ID>";
  final String kind = "<YOUR STREAM KIND>";
  final String fileFormat = "<YOUR FILE FORMAT>";
  final String bucketDirPath = "<YOUR CLOUD STORAGE BUCKET PATH>";
  final String webhookUrl = "<YOUR WEBHOOK URL>";

  final Map<String, dynamic> body = {
    "roomId": roomId,
    "participantId": participantId,
    "kind": kind,
    "fileFormat": fileFormat,
    "bucketDirPath": bucketDirPath,
    "webhookUrl": webhookUrl,
  };

  final response = await http.post(
    Uri.parse('https://api.videosdk.live/v2/recordings/participant/track/start'),
    headers: {
      "Authorization": "$YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: jsonEncode(body),
  );

  if (response.statusCode == 200) {
    print(jsonDecode(response.body));
  } else {
    print('Failed to start track recording');
  }
}

```

## Stop Participant Track Recording

To stop a participant track recording, you will have to call `/v2/recordings/participant/track/stop` API with following body parameters.

- `roomId`: RoomId for which the participant track recording is to be stopped
- `participantId`: participantId for which the recording is to be stopped.
- `kind`: The kind of track recording you want to stop for the given participant.
  - You can pass following values: _`audio`_ | _`video`_ | _`screen_audio`_ | _`screen_video`_

```js
import 'package:http/http.dart' as http;
import 'dart:convert';

Future<void> stopTrackRecording() async {
  final String roomId = "<YOUR ROOM ID>";
  final String participantId = "<PARTICIPANT ID>";
  final String kind = "<YOUR STREAM KIND>";

  final Map<String, dynamic> body = {
    "roomId": roomId,
    "participantId": participantId,
    "kind": kind,
  };

  final response = await http.post(
    Uri.parse('https://api.videosdk.live/v2/recordings/participant/track/stop'),
    headers: {
      "Authorization": "$YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: jsonEncode(body),
  );

  if (response.statusCode == 200) {
    print(jsonDecode(response.body));
  } else {
    print('Failed to stop track recording');
  }
}

```

## Webhook associated with Participant Track Recording

### participant-track-recording-starting

- A "Participant Track Recording Starting" webhook is triggered when the track recording process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-started

- Participant Track Recording started webhook will be received when successfully track recording is started in meeting

###### Example

```javascript
{
    "webhookType": "participant-track-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopping

- A "Participant Track Recording Stopping" webhook is triggered when the track recording end process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopped

- Participant Track Recording stopped webhook will be received when track recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-track-recording-failed

- A "Participant Track Recording Failed" webhook is generated when the track recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Track Recording API](/api-reference/realtime-communication/start-track-recording)
- [Stop Track Recording API](/api-reference/realtime-communication/stop-track-recording)



---

### Storage Configuration

While recording your Livestream, you have the flexibility to store them either on VideoSDK's storage or configure your own storage solution such as **`AWS S3 Storage, Azure Blob or GCP Cloud Storage`**. To set up your own storage, you can navigate to the [API section](https://app.videosdk.live/api-keys) in the VideoSDK Dashboard.

- This feature allows you to configure storage provider for your Livestream recordings.

- You can configure multiple storage provider with multiple API Keys.

- Currently, we support `AWS S3`, `Azure Blob` and `GCP Cloud Storage`. We will add support for other storage provider soon !!

## Prerequisites

- An active [VideoSDK Developer Account](https://app.videosdk.live)
- `Aws S3`, `Azure Blob Storage` or `GCP Cloud Storage` Credentials

## How to setup ?

### Step 1 : Select Api Key

![Dashboard](/img/tutorial/dashboard/api-key-dashboard.png)

- Go to [VideoSDK Dashboard](https://app.videosdk.live/api-keys).
- Select API Key for which, you want to set storage configuration.
- Then click on `Storage Config` Icon in Actions.

### Step 2 : Choose Cloud Storage Provider

![Dashboard](/img/tutorial/dashboard/storage-config.png)

- As you can see in the image, there are 3 Cloud Storage Provider (`Aws`, `Azure`, `GCP`).
- You can select a Cloud Storage Provider as per your requirements.

### Step 3 : Configure Bucket or Container

<h4> For Aws S3 Storage </h4>

![Aws S3](/img/tutorial/dashboard/s3.png)

- You will need AWS S3 Bucket. [Learn to create S3 Bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html).

- As you can see in the image, you will need enter `accessKeyId`, `secretAccessKey`, `region`, `bucket`, and `ACL` to setup for Aws S3 Storage.

- Click on `Save` button.

<hr />

<h4> For Azure Blob Storage: </h4>

![Azure Blob](/img/tutorial/dashboard/blob.png)

- You will need Azure Blob Container. [Learn to create Blob Container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal#create-a-container).

- As you can see in the image, you will need to enter `connectionString` and `containerName` to setup for Azure Blob.

- Click on `Save` button.

<hr />

<h4> For Google Cloud Storage: </h4>

<img src="/img/tutorial/dashboard/gcp.png" alt="GCP Cloud Storage" width="436" height="632"/>

1. You will need Google Cloud Storage Bucket. [Learn to create Google Cloud Storage Bucket](https://cloud.google.com/storage/docs/creating-buckets).

2. After creation, click on the <b> &#xFE19; </b>button in the upper right corner and select **`Project settings`**.

3. Under **`IAM and Admin`**, select **`Service Accounts`**. In the service account list, click on the <b> &#xFE19; </b> button for the account just added or created before, and select **`Manage keys`**.

4. Click **`ADD KEY > Create new key`**. Select **`JSON`** in the pop-up box and click **`CREATE`**. A json file is downloaded with the name format `projectId-xxxxxxxx.json`.

5. Open the downloaded json file, which looks like the following example:

```
{
  "type": "service_account",
  "project_id": "videosdk-12345",
  "private_key_id": "yourprivateidkeyyourprivateidkeyyourprivateidkey",
  "private_key": "-----BEGIN PRIVATE KEY-----\nThisisYourPrivateKeyThisisYourPrivateKeyThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\n-----END PRIVATE KEY-----\n",
  "client_email": "xxxx-xxxx@videosdk-12345.iam.gserviceaccount.com",
  "client_id": "123456789012345678901",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/videosdk%40videosdk-404307.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}
```

- As you can see in the image, you will need to enter `Project Id`, `Client Email`, `Bucket`, `Private Key` to setup for Google Cloud Storage Bucket. You can retrieve these details from the json file.

- Click on `Save` button.

### Step 4 : Test

- It's time to test !!
- [Create Room](https://docs.videosdk.live/api-reference/realtime-communication/create-room) with token generated with the API Key, you have configured for.
- Start Livestream with the roomId created and Start Recording !!
- Then, you can see that recording will be available in your Bucket or Container.

:::note

- Only a single Recording Storage Config can be possible for a particular Api Key at a time.
- In order to add new Recording Configuration, first you need to delete current configuration.

:::


---

# Recording in Live Stream - Flutter

This guide will provide an overview of how to implement start and stop LiveStream Recording.

### `startRecording()`

`startRecording()` can be used to start a recording of the livestream which can be accessed from the `Room` object. This method accepts four parameters:

- `1. webhookUrl (optional)`: This would the webhook URL where you would like to listen to event happening for the recording like starting and stopping of recording. It will be triggered when the recording is completed and stored into server. Read more about webhooks [here](https://en.wikipedia.org/wiki/Webhook)

- `2. awsDirPath (optional)`: This parameter accepts the path for the your S3 bucket where you want to store recordings to. To allow us to store recording in your S3 bucket, you will need to fill this form by providing the required values. ([VideoSDK Cloud (AWS S3, Azure Blob or GCP ) Integration](/flutter/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config))

- `3. config (optional)`: This parameter will define how the recording should be recorded.

- `4. transcription (optional)`: This parameter lets you start post transcription for the recording.

  ```js
  Map<String, dynamic> config = {
    // highlight-next-line
    // Layout Configuration
    layout: {
      type: "GRID", // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
      priority: "SPEAKER", // "PIN", Default : "SPEAKER"
      gridSize: 4, // MAX : 4
    },

    // highlight-next-line
    // Theme of recording
    theme: "DARK", //  "LIGHT" | "DEFAULT"

    // highlight-next-line
    // `mode` is used to either record video & audio both or only audio.
    mode: "video-and-audio", // "audio", Default : "video-and-audio"

    // highlight-next-line
    // Quality of recording and is only applicable to `video-and-audio` type mode.
    quality: "high", /* Default : "med"
   "low" (SD Recording) | "med" (HD Recording) | "high" (FHD Recording) */

    //highlight-start
    // This mode refers to orientation of recording.
    // landscape : Record the livestream in horizontally
    // portrait : Record the livestream in vertically (Best for mobile view)
    //highlight-end
    orientation: "landscape", // "portrait",  Default : "landscape"
  };

  // highlight-next-line
  // Post Transcription Configuration
  Map<String, dynamic> transcription = {
    "enabled": true, // Enables post transcription
    "summary": {
      "enabled": true,  // Enables summary generation
       // Guides summary generation
      "prompt":
          "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    }
  };

  room.startRecording(config: config, transcription: transcription);
  ```

### `stopRecording()`

- `stopRecording()` is used to stop the livestream recording which can be accessed from the `Room` object.

#### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class LiveStreamScreen extends StatefulWidget {
  ...
}

class _LiveStreamScreenState extends State<LiveStreamScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ElevatedButton(
          onPressed:(){
            Map<String, dynamic> config = {
              "layout": {
                "type": "GRID",
                "priority": "SPEAKER",
                "gridSize": 4,
              },
              "theme": "DARK",
              "mode": "video-and-audio",
              "quality": "high",
              "orientation": "portrait",
            };

            Map<String, dynamic> transcription = {
              "enabled": true,
              "summary": {
                "enabled": true,
                "prompt":
                    "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
              }
            };
            _room.startRecording(config: config, transcription: transcription);
          },
          child: const Text("Start Recording"),
        ),
        ElevatedButton(
          onPressed:(){
            _room.stopRecording();
          },
          child: const Text("Stop recording"),
        ),
    //highlight-end
      ]
    );
  }
}
```

:::important
To initiate automatic recording at the beginning of a `session`, simply provide the `autoStartConfig` feature `recording` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.
:::

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startRecording](/flutter/api/sdk-reference/room-class/methods#startrecording)
- [stopRecording](/flutter/api/sdk-reference/room-class/methods#stoprecording)
- [Events.recordingStateChanged](/flutter/api/sdk-reference/room-class/events#recordingstatechanged)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

# Webhooks and Events - Flutter

### Event associated with Recording

- **recordingStateChanged** - Whenever Livestream recording state changes, then `recordingStateChanged` event will trigger.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class LivestreamScreen extends StatefulWidget {
  ...
}

class _LivestreamScreenState extends State<LivestreamScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    ...

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourLivestreamWidget();
  }

  //highlight-start
  void setupRoomEventListener() {
    room.on(Events.recordingStateChanged, (String status) {
      //Status can be :: RECORDING_STARTING
      //Status can be :: RECORDING_STARTED
      //Status can be :: RECORDING_STOPPING
      //Status can be :: RECORDING_STOPPED
      log("Livestream Recording status : $status");
    });
  }
  //highlight-end
}
```

## Webhook associated with Recording

### recording-starting

- A "Recording Starting" webhook is triggered when the recording process for a Livestream is initiated.

###### Example

```javascript
{
    "webhookType": "recording-starting",
    "data": {
        "LivestreamId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-started

- Recording started webhook will be received when successfully recording is started in Livestream

###### Example

```javascript
{
    "webhookType": "recording-started",
    "data": {
        "LivestreamId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopping

- A "Recording Stopping" webhook is triggered when the recording end process for a Livestream is initiated.

###### Example

```javascript
{
    "webhookType": "recording-stopping",
    "data": {
        "LivestreamId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopped

- Recording stopped webhook will be received when recording is successfully stopped in Livestream.

###### Example

```javascript
{
    "webhookType": "recording-stopped",
    "data": {
        "LivestreamId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
        "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",

    },
}
```

---

### recording-failed

- A "Recording Failed" webhook is generated when the recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "recording-failed",
    "data": {
        "LivestreamId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```


---

# Relay Media(PK Host) - Flutter

## Overview

The Relay Media feature enables hosts to relay their media (audio, video, screen share) to one or multiple other live streams. This creates cross-stream interactions similar to "PK battles" or collaborative broadcasts.

This feature allows audiences in one live stream to view and hear hosts from another live stream without changing rooms, creating powerful interactive experiences.

## Key Concepts

- **Media Relay**: The process of transmitting a host's audio/video from one live stream to another
- **Source Meeting**: The original live stream where the host is broadcasting
- **Destination Meeting**: The target live stream(s) where the host's media will be relayed
- **Relay Kinds**: The types of media that can be relayed (video, audio, screen share, etc.)

## Sequence Diagram



## Implementation Guide

### 1. Requesting Media Relay

### `requestMediaRelay()`

**Parameters:**

- `destinationlivestreamId` (string): ID of the target liveStream
- `token` (string, optional): Authentication token for the destination liveStream
- `kinds` (array, optional): Array of media types to relay. Options:
  - `"video"`: Camera video
  - `"audio"`: Microphone audio
  - `"share"`: Screen share video
  - `"share_audio"`: Screen share audio


```javascript
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
class LiveStreamView extends StatelessWidget {
  final Room livestream;
  final String token;

  const LiveStreamView({
    Key? key,
    required this.livestream,
    required this.token,
  }) : super(key: key);

  void _handleRequestMediaRelay(BuildContext context) {
    livestream.requestMediaRelay(
      "LiveStream-Id", // Replace with your actual livestreamID or target stream ID
      token,
      ["video", "audio"], // Add other media types if needed
    );
    Navigator.pop(context); // Optional: navigate back after requesting
  }

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      child: const Text('Request Media Relay'),
      onPressed: () => _handleRequestMediaRelay(context),
    );
  }
}
```
### 2. Handling Relay Requests (Destination Meeting)

In the destination liveStream, hosts (participants with `SEND_AND_RECV` mode) will receive relay requests:

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
class LiveStreamView extends StatefulWidget {
  final Room livestream;

  const LiveStreamView({Key? key, required this.livestream}) : super(key: key);

  @override
  State<LiveStreamView> createState() => _LiveStreamViewState();
}

class _LiveStreamViewState extends State<LiveStreamView> {
  late Room _room;
  String? relaylivestreamId;
  String? relayPeerId;

  @override
  void initState() {
    super.initState();
    _room = widget.livestream;

    _room.on(Events.mediaRelayRequestReceived, (livestreamId, peerId, displayname, accept, reject) {
      print("Media relay received: $livestreamId");

      setState(() {
        relaylivestreamId = livestreamId;
        relayPeerId = peerId;
      });

      _showRelayRequestDialog(
        context,
        displayname,
        relaylivestreamId!,
        relayPeerId!,
        accept,
        reject
      );
    });
  }

 void _showRelayRequestDialog(
  BuildContext context,
  String displayName,
  String livestreamId,
  String peerId,
  VoidCallback accept,
  VoidCallback reject,
) {
  showDialog(
    context: context,
    builder: (BuildContext context) {
      return AlertDialog(
        title: const Text('Media Relay Request'),
        content: Text(
            '$displayName wants to relay media in livestream $livestreamId. Allow?'),
        actions: [
          TextButton(
            child: const Text('Allow'),
            onPressed: () {
              accept(); // Call the provided accept callback
              Navigator.of(context).pop();
            },
          ),
          TextButton(
            child: const Text('Deny'),
            onPressed: () {
              reject(); // Call the provided reject callback
              Navigator.of(context).pop();
            },
          ),
        ],
      );
    },
  );
}
  @override
  Widget build(BuildContext context) {
    return const SizedBox.shrink(); 
  }
}
```

### 3. Handling Request Responses (Source Meeting)

In the source liveStream, track the response to your relay requests:

```js 
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class LiveStreamView extends StatefulWidget {
  final Room livestream;

  const LiveStreamView({Key? key, required this.livestream}) : super(key: key);

  @override
  State<LiveStreamView> createState() => _LiveStreamViewState();
}

class _LiveStreamViewState extends State<LiveStreamView> {
  late Room _room;
  String relayStatusMessage = "";

  @override
  void initState() {
    super.initState();
    _room = widget.livestream;

    _room.on(Events.mediaRelayRequestResponse, (decisionBy, decision, livestreamId) {
      final participantId = decisionBy;
      final _decision = decision

      if (_decision == "accepted") {
        print("Relay request accepted by $participantId");
        setState(() {
          relayStatusMessage = "Relay accepted by $participantId";
        });
      } else {
        print("Relay request rejected by $participantId");
        setState(() {
          relayStatusMessage = "Relay rejected by $participantId";
        });
      }
    });
  }

  @override
  Widget build(BuildContext context) {
    return Center(
      child: Text(
        relayStatusMessage.isNotEmpty
            ? relayStatusMessage
            : "Waiting for relay response...",
        style: const TextStyle(fontSize: 16),
      ),
    );
  }
}

```
### 4. Tracking Active Relays

When a relay successfully starts:

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
class LiveStreamView extends StatefulWidget {
  final Room livestream;

  const LiveStreamView({Key? key, required this.livestream}) : super(key: key);

  @override
  State<LiveStreamView> createState() => _LiveStreamViewState();
}

class _LiveStreamViewState extends State<LiveStreamView> {
  late Room _room;
  String? activeRelayId;

  @override
  void initState() {
    super.initState();
    _room = widget.livestream;

    _room.on(Events.mediaRelayStarted, (livestreamId) {
      final String _liveStreamId = livestreamId; 
      print("Media relay started to $liveStreamId");

      setState(() {
        activeRelayId = liveStreamId;
      });
    });
  }

  @override
  Widget build(BuildContext context) {
    return Center(
      child: Text(
        activeRelayId != null
            ? "Media relay active to: $activeRelayId"
            : "No active relay.",
        style: const TextStyle(fontSize: 16),
      ),
    );
  }
}

```
### 5. Stopping Media Relay

To stop an ongoing relay:

### `stopMediaRelay()`

**Parameters:**

- `liveStreamId` (string): ID of the liveStream where the relay should stop

```javascript
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
class LiveStreamView extends StatelessWidget {
  final Room livestream;
  final String token;

  const LiveStreamView({
    Key? key,
    required this.livestream,
    required this.token,
  }) : super(key: key);

  void _handleStopMediaRelay(BuildContext context) {
    meeting.stopMediaRelay();
    Navigator.pop(context); // Optional: navigate back after requesting
  }

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      child: const Text('Stop Relay'),
      onPressed: () => _handleStopMediaRelay(context),
    );
  }
}

```
### 6. Handling Relay Stop Events

When a relay stops for any reason:

```js 
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
class LiveStreamView extends StatefulWidget {
  final Room livestream;
  final String token;

  const LiveStreamView({
    Key? key,
    required this.livestream,
    required this.token,
  }) : super(key: key);

  @override
  State<LiveStreamView> createState() => _LiveStreamViewState();
}

class _LiveStreamViewState extends State<LiveStreamView> {
  late Room _room;

  @override
  void initState() {
    super.initState();
    _room = widget.livestream;
    registerEvents();
  }

  void registerEvents() {
    _room.on(Events.mediaRelayStopped, (livestreamId, reason) {
      String _reason = reason;
      switch (_reason) {
        case "user_stopped":
          toastMsg("Media relay stopped");
          break;
        case "connection_lost":
          toastMsg("Media relay ended");
          break;
        default:
          toastMsg("Media relay stopped");
      }
    });
  }

  void _handleRequestMediaRelay(BuildContext context) {
    _room.stopMediaRelay("<Livestream-Id>");
    Navigator.pop(context);
  }

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      child: const Text('Request Media Relay'),
      onPressed: () => _handleRequestMediaRelay(context),
    );
  }
}

```

### 7. Handling Relay Errors

To handle errors that may occur during relay:

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
class LiveStreamView extends StatefulWidget {
  final Room livestream;
  final String token;

  const LiveStreamView({
    Key? key,
    required this.livestream,
    required this.token,
  }) : super(key: key);

  @override
  State<LiveStreamView> createState() => _LiveStreamViewState();
}

class _LiveStreamViewState extends State<LiveStreamView> {
  late Room _room;

  @override
  void initState() {
    super.initState();
    _room = widget.livestream;
    registerEvents();
  }

  void registerEvents() {
    _room.on(Events.mediaRelayError, (livestreamId, reason) {
      print("Media relay error $reason");
    });
  }

  void _handleRequestMediaRelay(BuildContext context) {
    _room.stopMediaRelay("<LivestreamId>");
    Navigator.pop(context);
  }

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      child: const Text('Request Media Relay'),
      onPressed: () => _handleRequestMediaRelay(context),
    );
  }
}

```
## Use Cases

1.  **Guest Appearances:** Allow popular hosts to make guest appearances in other streams without leaving their audience
2.  **Cross-Stream Competitions:** Create "battles" or competitions between hosts in different streams
3.  **Multi-Location Broadcasting:** Connect hosts from different physical locations into a shared experience
4.  **Expert Commentary:** Bring in subject matter experts to comment on events in another stream

## Troubleshooting

### Common Issues

1.  **Relay Request Not Received**

    - Verify both meetings are active
    - Check that destination liveStream ID is correct
    - Ensure the token has proper permissions

2.  **Media Not Visible After Acceptance**

    - Verify network connectivity
    - Check that appropriate media kinds were specified
    - Ensure the host has enabled their camera/microphone

3.  **Unexpected Relay Termination**

    - Check for network connectivity issues
    - Verify that both meetings remain active
    - Look for error events with specific reasons

## API Reference

- [requestMediaRelay](/flutter/api/sdk-reference/room-class/methods#requestmediarelay)
- [stopMediaRelay](/flutter/api/sdk-reference/room-class/methods#stopmediarelay)
- [mediaRelayReceived](/flutter/api/sdk-reference/room-class/events#mediarelayreceived)
- [mediaRelayResponse](/flutter/api/sdk-reference/room-class/events#mediarelayresponse)
- [mediaRelayStarted](/flutter/api/sdk-reference/room-class/events#mediarelaystarted)
- [mediaRelayStopped](/flutter/api/sdk-reference/room-class/events#mediarelaystopped)
- [mediaRelayError](/flutter/api/sdk-reference/room-class/events#mediarelayerror)


---

# Release Notes - Flutter




---

---
title: RTMP Livestream - Video SDK Docs
hide_title: false
hide_table_of_contents: false
description: RTMP Livestream features quick integrate in Javascript, React JS, Android, IOS, React Native, Flutter with Video SDK to add live video & audio conferencing to your applications.
sidebar_label: RTMP Livestream
pagination_label: RTMP Livestream
keywords:
  - Start Livestream meeting
  - Stop Livestream meeting
  - audio calling
  - video calling
  - real-time communication
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: rtmp-livestream
--- 

# RTMP Livestream - Flutter

RTMP is a widely used protocol for live streaming video content from VideoSDK to platforms like YouTube, Twitch, Facebook, and others.

To initiate live streaming from VideoSDK to platforms supporting RTMP ingestion, you simply need to provide the platform-specific stream key and stream URL. This enables VideoSDK to connect to the platform's RTMP server and transmit the live video stream.

Furthermore, VideoSDK offers flexibility in configuring livestream layouts. You can achieve this by either selecting different prebuilt layouts in the configuration or by providing your custom template for livestreaming, catering to your specific layout preferences.

This guide will provide an overview of how to implement starting and stopping RTMP livestreaming with VideoSDK.

### `startLivestream()`

`startLivestream()` can be used to start a RTMP livestream of the meeting which can be accessed from the `Room` object. This method accepts three parameters:

- `1. outputs`: This parameter accepts an array of objects which contains the RTMP `url` and `streamKey` of the platforms you want to start the livestream.

- `2. config (optional)`: This parameter will define how the livestream layout should look like.

- `3. transcription (optional)`: This parameter lets you start post transcription for the recording.

 ```js
  var outputs = [
    {
      url: "rtmp://a.rtmp.youtube.com/live2",
      streamKey: "<STREAM_KEY>",
    },
    {
      url: "rtmps://",
      streamKey: "<STREAM_KEY>",
    },
  ];
  Map<String, dynamic> config = {
    // highlight-next-line
    // Layout Configuration
    layout: {
      type: "GRID", // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
      priority: "SPEAKER", // "PIN", Default : "SPEAKER"
      gridSize: 4, // MAX : 4
    },

    // highlight-next-line
    // Theme of livestream
    theme: "DARK", //  "LIGHT" | "DEFAULT"
  };

  // highlight-next-line
  // Post Transcription Configuration
  Map<String, dynamic> transcription = {
    "enabled": true, // Enables post transcription
    "summary": {
      "enabled": true,  // Enables summary generation
       // Guides summary generation
      "prompt":
          "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    }
  };

  room.startLivestream(outputs, config: config, transcription: transcription);
  ```

### `stopLivestream()`

- `stopLivestream()` is used to stop the meeting livestream which can be accessed from the `Room` object.

#### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class LivestreamScreen extends StatefulWidget {
  ...
}

class _LivestreamScreenState extends State<LivestreamScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ElevatedButton(
          onPressed:(){
            var outputs = [
              {
                url: "rtmp://a.rtmp.youtube.com/live2",
                streamKey: "<STREAM_KEY>",
              },
              {
                url: "rtmps://",
                streamKey: "<STREAM_KEY>",
              },
            ];
            var liveStreamConfig =  {
              'layout': {
                'type': 'GRID',
                'priority': 'SPEAKER',
                'gridSize': 4,
              },
              'theme': "LIGHT",
            };
            room.startLivestream(outputs, config: livestreamConfig);
          },
          child: const Text("Start Livestream"),
        ),
        ElevatedButton(
          onPressed:(){
            _room.stopLivestream();
          },
          child: const Text("Stop Livestream"),
        ),
    //highlight-end
      ]
    );
  }
}
```

### Event associated with Livestream

- **livestreamStateChanged** - Whenever meeting livestream state changes, then `livestreamStateChanged` event will trigger.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class LivestreamScreen extends StatefulWidget {
  ...
}

class _LivestreamScreenState extends State<LivestreamScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    ...

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourLivestreamScreenWidget();
  }

  //highlight-start
  void setupRoomEventListener() {
    room.on(Events.livestreamStateChanged, (String status) {
      //Status can be :: LIVESTREAM_STARTING
      //Status can be :: LIVESTREAM_STARTED
      //Status can be :: LIVESTREAM_STOPPING
      //Status can be :: LIVESTREAM_STOPPED
      log("Meeting Livestream status : $status");
    });
  }
  //highlight-end
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startLivestream](/flutter/api/sdk-reference/room-class/methods#startlivestream)
- [stopLivestream](/flutter/api/sdk-reference/room-class/methods#stoplivestream)
- [Events.livestreamStateChanged](/flutter/api/sdk-reference/room-class/events#livestreamstatechanged)



---

# Sending Virtual Gifts - Flutter

Virtual gifting is a powerful monetization and engagement feature that allows viewers to support hosts or speakers during a livestream by sending them digital tokens or "gifts." These gifts can be visually animated and even linked to leaderboards or reward systems.

This guide explains how to implement a secure and real-time virtual gifting experience using your backend server in combination with VideoSDK PubSub.

### How It Works
1. User Action: A viewer taps on a gift button to send a virtual gift to the host.

2. Server Verification:
   - A request is made to your business backend to process the gift.
    - The server authenticates the user, checks their wallet balance, deducts the gift value, and returns a success response.

3. Event Broadcast: Upon success, the client publishes a PubSub message to inform everyone in the livestream (host + other viewers) that a gift has been sent. Clients can then visually show an animation or notification.

### Backend Responsibility

Your backend plays a central role in verifying, validating, and processing gift transactions. It should:
  - Authenticate the request (token/session)
  - Verify if the user has sufficient balance
  - Deduct the gift cost
  - Store the transaction in a database (optional but recommended)
  - Respond with success or failure

### Frontend Implementation

- Sending a Gift (Client to Backend + PubSub)

```js
import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
import 'dart:convert';
import 'package:videosdk/videosdk.dart';
class GiftSender extends StatelessWidget {
  final String senderId;
  final String hostId;
  final Room room;

  GiftSender({
    required this.senderId,
    required this.hostId,
    required this.room,
  });

  void sendGift(String giftType) async {
    try {
      final response = await http.post(
        Uri.parse("https://your-api.com/send-gift"),
        headers: {"Content-Type": "application/json"},
        body: jsonEncode({
          "senderId": senderId,
          "hostId": hostId,
          "giftType": giftType,
        }),
      );

      final responseData = jsonDecode(response.body);
      if (responseData['success'] == true) {
        room.pubSub.publish(
          "GIFT",
          jsonEncode({
            "giftType": giftType,
            "from": senderId,
            "to": hostId,
          }),
          const PubSubPublishOptions(persist: true),
        );
      } else {
        debugPrint("Gift could not be sent: ${responseData['message']}");
      }
    } catch (e) {
      debugPrint("Error sending gift: $e");
    }
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        ElevatedButton(
          onPressed: () => sendGift("rose"),
          child: const Text("🌹 Send Rose"),
        ),
        ElevatedButton(
          onPressed: () => sendGift("diamond"),
          child: const Text("💎 Send Diamond"),
        ),
      ],
    );
  }
}
```
- Displaying the Gift (All Clients)

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class GiftReceiver extends StatefulWidget {
  final Room room;

  const GiftReceiver({required this.room});

  @override
  State<GiftReceiver> createState() => _GiftReceiverState();
}

class _GiftReceiverState extends State<GiftReceiver> {
  final List<Map<String, dynamic>> _gifts = [];

  void handleGift(PubSubMessage pubsubMessage) {
    final message = pubsubMessage.message;
    setState(() {
      print("handle gitft : ${message}");
      _gifts.add({
        "id": DateTime.now().millisecondsSinceEpoch,
        "from": "123",
        "to": "456",
        "type": "diamond",
      });
    });
  }

  @override
  void initState() {
    super.initState();
    widget.room.pubSub.subscribe("GIFT", handleGift);
  }

  @override
  void dispose() {
    widget.room.pubSub.unsubscribe("GIFT", handleGift);
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: _gifts.map((gift) {
        return Padding(
          padding: const EdgeInsets.symmetric(vertical: 4.0),
          child: Text(
              "🎁 ${gift['from']} sent a ${gift['type']} to ${gift['to']}"),
        );
      }).toList(),
    );
  }
}

```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [PubSub](/flutter/api/sdk-reference/pubsub-class/introduction)

---

# Initialize Live Stream - Flutter

To configure livestreaming with VideoSDK you require two things, first the `token` which will be used for **Authentication** purpose and a `streamId` which will be used to specify where the hosts and audience will join.

### Generating Token

You can generate a `token` in two ways:

1. **`Temporary Token`** : You can visit [Dashboard's API Key section](https://app.videosdk.live/api-keys) and generate a temporary token from there.

2. **`Server`** : You can setup **JWT** in backend and make an API call to get the token from your server.

To learn more about **Authentication** and token in detail you can follow [this guide](/flutter/guide/video-and-audio-calling-api-sdk/authentication-and-tokens).


```js
// With Temporary Token
const getToken = async () => {
  // Update the token here from the VideoSDK dashboard
   //highlight-start
  let token = "YOUR_TOKEN";
   //highlight-end
};

// Server
const getToken = async () => {
   //highlight-start
  const response = await fetch(`http://localhost:3000/get-token`, {
    method: "GET",
    headers: {
      Accept: "application/json",
      "Content-Type": "application/json",
    },
  });
  const { token } = await response.json();
   //highlight-end
  return token;
};
```

### Generating Stream Id

With the token ready, you can now get the `streamId` from the [VideoSDK's rooms API](/api-reference/realtime-communication/create-room).

```js
// API call to create livestream
Future<String> createStreamId(String token) async {
  final http.Response httpResponse = await http.post(
    Uri.parse("https://api.videosdk.live/v2/rooms"),
    headers: {'Authorization': token},
  );

//Destructuring the roomId from the response and store it in stremId variable
  String streamId = json.decode(httpResponse.body)['roomId'];
  return streamId;
}
```

### Initialization of Live Stream

You can initialize the live stream using the `VideoSdk Class` from the Flutter SDK. The `VideoSdk Class` is responsible for initializing the live stream with the provided configuration, which includes the `token`, `livestreamId`, `participantId` and many more.

#### VideoSdk Class

VideoSDK Class is a core class of SDK that provides methods to create and configure `VideoSdk Room`.
You have to pass the initialization configuration for the live stream and the token in the `VideoSdk Class`.

```js 
VideoSDK.createRoom(
      roomId: "<streamId>",
      mode: "SEND_AND_RECV", // "SEND_AND_RECV" for hosts/co-hosts, "RECV_ONLY" for audience
      token: "Generated-Token",
      displayName: "<Participant Name>",
      micEnabled: true, //Ignore for audience
      camEnabled: true, //Ignore for audience
      participantId: "<Unique Participant ID>", // Optional
      multiStrem : true, // //Ignore for audience

    );
```

- **`roomId`** :

  - This is a unique identifier that allows participants to join a specific live stream.
  - It will be in the format of `xxx-yyy-zzz` and will be generated using the [VideoSDK's Room API](/api-reference/realtime-communication/create-room).

- **`mode`** :

  - This paramter defines the mode the participant will enter the live stream with.
  - `SEND_AND_RECV`: For hosts/co-hosts who can send and receive media.
  - `RECV_ONLY`: For audience members who can only receive media.​


- **`name`**:

  - This represents the name of the participant in the live streams.
  - It will accept `String` type value.

- **`micEnabled`**:
 - This is a `boolean` flag, indicating whether a participant's microphone will be automatically enabled when they join the live stream. This property will be completely ignored for Audience participants, as they are not allowed to publish their audio.

- **`wcamEnabled`**:
- This is a `boolean` flag, indicating whether a participant's camera will be automatically enabled when they join the live stream. This property will be completely ignored for Audience participants, as they are not allowed to publish their video. 

- **`metaData`**:
  - If you want to provide additional details about the participants joining the live stream, such as their profile image, you can pass that information in this parameter.
  - It has to be of `Object` type.
  - This is an `OPTIONAL` parameter.

- **`participantId`**:

  - This is a unique identifier for the participant's inside the live stream.

    - It can be used to specify the **unique identifier** which can be linked with **your own database** service.
    - It has to be of `String` type.
    - This is an `OPTIONAL` parameter. By default VideoSDK will generate unique id for each participant.

- **`multistream`**:

  - This is a `boolean` flag, indicating whether the host's media stream should send multiple resolution layers or a single resolution layer.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class LiveStreamScreen extends StatefulWidget {
  const LiveStreamScreen({super.key});

  @override
  State<LiveStreamScreen> createState() => _LiveStreamScreenState();
}

class _LiveStreamScreenState extends State<LiveStreamScreen> {
  late Room _room;

  @override
  void initState() {

//highlight-start
    String token = getToken();
    String liveStreamId = createStreamId();
//highlight-end

    //highlight-start
    //Creating a new Room based on the passed LivestreamId and token from the Joining Screen
    // create room
    _room = VideoSDK.createRoom(
      roomId: liveStreamId,
      mode: "SEND_AND_RECV", // "SEND_AND_RECV" for hosts/co-hosts, "RECV_ONLY" for audience
      token: token,
      displayName: "<Participant Name>",
      micEnabled: true, //Ignore for audience
      camEnabled: true, //Ignore for audience
      participantId: "<Unique Participant ID>", // Optional
      multiStream : true, // //Ignore for audience

    );
    //highlight-end
    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return YourLivestreamWidget();
  }
}

```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [createRoom](/flutter/api/sdk-reference/videosdk-class/methods#createroom)





---

---
title: Join/Leave Live Stream | Video SDK
hide_title: true
hide_table_of_contents: false
description: Easily integrate join and leave functionalities for interactive live streams using Video SDK’s FlutterSdk with event handling for participant management.
sidebar_label: Join/Leave Live Stream
pagination_label: Join/Leave Live Stream
keywords:
  - audio calling
  - video calling
  - real-time communication
  - collaboration
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: join-leave-livestream
--- 

# Join Live Stream - Flutter

Once, the live stream is configured, the next step is to join it. If you have not initialized the live stream yet, you can [follow the guide here.](/flutter/guide/interactive-live-streaming/setup-livestream/initialize-livestream)

### `join()`

- To join the live stream you can call the `join()` method which is the part of the `Room` class of Flutter SDK.
- This method can be called after the live stream is initialized from the `VideoSdk class`.

### Events associated with Join

Following callbacks are received when a participant is successfully joined.

- [Local Participant](/flutter/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a [`Events.roomJoined`](/flutter/api/sdk-reference/room-class/events#roomjoined) event, when successfully joined.
- [Remote Participant](/flutter/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a [`Events.participantJoined`](/flutter/api/sdk-reference/room-class/events#participantjoined) event with the newly joined `Participant` object from the event callback.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class LiveStreamScreen extends StatefulWidget {
  ...
}

class _LiveStreamScreenState extends State<LiveStreamScreen> {
  late Room _room;

  @override
  void initState() {
    //Creating a new Room based on the passed livestreamId and token from the Joining Screen
    // create room
    _room = VideoSDK.createRoom(
      roomId: widget.livestreamId,
      token: widget.token,
      displayName: "John Doe",
      micEnabled: true,
      camEnabled: true,
      defaultCameraIndex:
          1, // Index of MediaDevices will be used to set default camera
    );

    //highlight-start
    //Calling Join after the room object is created
    _room.join()
    //highlight-end

    //highlight-start
    setupLiveStreamEventListener();
    //highlight-end

    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return YourLiveStreamWidget();
  }


  void setupLiveStreamEventListener() {
    room.on(Events.roomJoined, (){
      // Room/Livestream joined Successfully
    });
    room.on(Events.participantJoined, (Participant participant){
      // New Participant joined the livestream
    });
  }

}

```

### `leave()`

- To leave the live stream you can call the `leave()` method which is the part of the `Room` class of Flutter SDK.

:::note
This method can be called only after the live stream is joined successfully.
:::


### Events associated with the leave() method


Following callbacks are received when a participant leaves the livestream.

- [Local Participant](/flutter/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a callback on [`Events.roomLeft`](/flutter/api/sdk-reference/room-class/events#roomleft).
- All [remote participants](/flutter/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a callback [`Events.participantLeft`](/flutter/api/sdk-reference/room-class/events#participantleft) with `participantId`.


```jsx
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class LiveStreamScreen extends StatefulWidget {
  ...
}

class _LiveStreamScreenState extends State<LiveStreamScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    setupLiveStreamEventListener();
   
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ElevatedButton(
          onPressed:(){
            _room.leave();
          },
          child: const Text("Leave Livestream"),
        ),
        ElevatedButton(
          onPressed:(){
            _room.end();
          },
          child: const Text("End Livestream"),
        ),
    //highlight-end
      ]
    );
  }
    void setupLiveStreamEventListener() {
    room.on(Events.roomLeft, (){
      // Room/Livestream left
    });
    room.on(Events.participantLeft, (String participantId , Map<String,dynamic> reason){
      // Participant left the Livestream
    });
  }
}
```

:::tip
You should call the `leave()` method on the unmount of your main livestream widget so that livestream is left once the widget is unmounted.
:::

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [join()](/flutter/api/sdk-reference/room-class/methods#join)
- [roomJoined](/flutter/api/sdk-reference/room-class/events#roomjoined)
- [participantJoined](/flutter/api/sdk-reference/room-class/events#participantjoined)
- [leave()](/flutter/api/sdk-reference/room-class/methods#leave)
- [roomLeft](/flutter/api/sdk-reference/room-class/events#roomleft)
- [participantLeft](/flutter/api/sdk-reference/room-class/events#participantleft)


---

# Waiting Screen - Flutter

To create a smoother and more polished entry experience for audience members, it's important not to immediately render the meeting room when they join. Instead, show a waiting screen until at least one host is present in the room.

### Why This Matters?

- Hosts are typically responsible for driving the Livestream, and their presence is essential before audience members should be able to view or interact in the room.

- Allowing audience members (in RECV_ONLY mode) to enter a livestream with no active hosts (in SEND_AND_RECV mode) can result in confusion and a poor user experience.

### Participant Modes

- Hosts must join the livestream with the SEND_AND_RECV mode.
- Audience members should join with the RECV_ONLY mode.

### Implementation Guide

You can achieve this behavior by using the participants list and onParticipantJoined event from the Room Class.

1. Check if a Host is Present On initial render, use the participants object to determine if there's already a host in the room:

```js 
import 'package:videosdk/videosdk.dart';
Room _room; 
final hasHost = _room.participants.values.any(
  (participant) => participant.mode == Mode.SEND_AND_RECV,
);
```

If hasHost is true, render the livestream view. Otherwise, show the waiting screen.

2. Listen for Host Join
   Always listen for the onParticipantJoined event in case a host joins after the audience participant:

```js
import 'package:videosdk/videosdk.dart';
Room _room; 

_room.on(Events.participantJoined, (Participant participant) {
//Adding only Conference participant to show in grid
if (participant.mode == Mode.SEND_AND_RECV) {
  setState(
    () => participants.putIfAbsent(participant.id, () => participant),
  );
 }
});
```

This ensures that as soon as a host joins, the waiting audience members are transitioned smoothly into the livestream view.

<div style={{ textAlign: 'center' }}>
    <img
        src="https://cdn.videosdk.live/docs/images/flutter/ils/waiting_screen_flutter.jpg"
        alt="Waiting Screen"
         style={{height: '450px'}}
    />
</div>



---

# Supported Browser and Device OS - Flutter




---

# Switch Live Stream - Flutter

## Overview

The **Switch Live Stream** feature enables users to **seamlessly transition** between live streams without needing to manually disconnect and reconnect. This drastically improves user experience by reducing latency and preserving media and socket connections.

### Previously

1.  Users had to **disconnect** from the current liveStream.
2.  Then **manually connect** to a new liveStream:
    - New socket connection created.
    - New media transports initialized.
    - Delays due to re-connection and media setup.

This led to:

- **Higher latency**
- **Socket transport downtime**
- **Poor experience** for users switching frequently between rooms

### New Behavior with `switchTo`

- Keeps the existing **socket connection** alive
- Reuses or reconfigures existing **media**
- Switches the server-side context to the **new liveStream**

### `switchTo()`

#### **Parameters**

- **liveStreamId** (`string`, required): ID of the new liveStream to join
- **token** (`string`, optional): VideoSDK token for authentication

```javascript
class LiveStreamView extends StatefulWidget {
  final Room livestream;
  final String token;

  const LiveStreamView({
    Key? key,
    required this.livestream,
    required this.token,
  }) : super(key: key);

  @override
  State<LiveStreamView> createState() => _LiveStreamViewState();
}

class _LiveStreamViewState extends State<LiveStreamView> {
  late Room _room;

  @override
  void initState() {
    super.initState();
    _room = widget.livestream;
    registerEvents();
  }

  void registerEvents() {
    _room.on(Events.mediaRelayError, (data) {
      print("Media relay error $data");
    });
  }

  void _handleSwitchMeeting(BuildContext context) {
    _room.switchTo("<Desired - livestream-id>", "token"); //token is optionl
    Navigator.pop(context);
  }

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      child: const Text('Switch livestream'),
      onPressed: () => _handleSwitchMeeting(context),
    );
  }
}
```

## Important Considerations

### Meeting Status

- **The destination liveStream must be active** before attempting to switch.
- If the destination liveStream is inactive or doesn't exist, the switch will fail.

### Token Management

- **Token Expiry**: Be careful with short-lived tokens when using the switch feature.
  - If you're using short-lived tokens for security reasons, always provide a new token in the `switchTo` method.
  - Tokens that expire during a liveStream can cause unexpected disconnections.
- **Best Practice**: For frequent switches, use tokens with reasonable expiry times or implement a token refresh mechanism.

## API Reference

- [switchTo](/flutter/api/sdk-reference/room-class/methods#switchto)

---

# Virtual Background - Flutter

Virtual backgrounds enhance your **live stream experience** by allowing you to replace your physical background with a digital image or apply a blur effect. This is ideal for creators and streamers who want to maintain privacy, reduce distractions, or add a personal touch to their broadcast. You can use a preloaded background image or supply your own via a CDN.

:::important

- Currently, this feature is only available on Google Chrome, Firefox and Brave browser.

:::

## Virtual Background using `VideoSDKMediaEffects` plugin

The `VideoSDKMediaEffects` plugin enables the integration of sophisticated virtual background effects within your video applications. By leveraging this plugin, users can replace their physical backgrounds with custom images or dynamic video backdrops, creating a more immersive and engaging experience. 

:::info

- The Virtual Background methods from the `VideoSDKMediaEffects` plugin are supported only on Android and iOS devices.
- The Virtual Background feature in VideoSDK can be utilized regardless of the livestream environment, including the pre-call screen.

:::

### Install the plugin 

- Install the `VideoSDKMediaEffects` plugin using the below-mentioned flutter command. Make sure you are in your flutter app directory before you run this command.

```js
$ flutter pub add videosdk_media_effects
```

### Apply Virtual Background

- The `applyVirtualBackground()` method from the `VideoSDKMediaEffects` plugin allows users to dynamically change the video background during a live session. By passing a URI of the desired background image, this method seamlessly integrates the virtual background into the video stream.

### Change Virtual Background

- The `changeVirtualBackground()` method from the `VideoSDKMediaEffects` plugin enables users to effortlessly switch their current virtual background to a new image. This functionality allows for dynamic customization and enhances the user's video experience by providing the ability to update their background on the fly. By passing a URI of the new background image, this method seamlessly integrates the new virtual background into the video stream.

### Remove Virtual Background

- The `removeVirtualBackground()` method from the `VideoSDKMediaEffects` plugin provides users with a convenient way to revert their video background to its original state, removing any previously applied virtual background. This functionality ensures flexibility for users to switch between virtual and real backgrounds as needed.

**Example Code:**


```js

import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
//Import the plugin
import 'package:videosdk_media_effects/videosdk_media_effects.dart';

class livestreamScreen extends StatefulWidget {
  //Existing configuration
}

class _livestreamScreenState extends State<livestreamScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    //Existing configuration
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        //To Apply Virtual Background
        ElevatedButton(
          onPressed:(){
            Uri backgroundImageURI = Uri.parse("https://cdn.videosdk.live/virtual-background/cloud.jpeg");
            VideosdkMediaEffects.applyVirtualBackground(backgroundSource: backgroundImageURI);
          },
          child: const Text("Apply Virtual Background"),
        ),
        //To Change Virtual Background 
        ElevatedButton(
          onPressed:(){
            Uri newBackgroundImageURI = Uri.parse("https://cdn.videosdk.live/virtual-background/san-fran.jpeg");
            VideosdkMediaEffects.changeVirtualBackground(backgroundSource: newBackgroundImageURI);
          },
          child: const Text("Change Virtual Background"),
        ),
        //To Remove Virtual Background
        ElevatedButton(
          onPressed:(){
            VideosdkMediaEffects.removeVirtualBackground();
          },
          child: const Text("Remove Virtual Background"),
        ),
    //highlight-end
      ]
    );
  }
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [applyVirtualBackground()](/flutter/api/sdk-reference/videosdkmediaeffects-plugin#applyvirtualbackground)
- [changeVirtualBackground()](/flutter/api/sdk-reference/videosdkmediaeffects-plugin#changevirtualbackground)
- [removeVirtualBackground()](/flutter/api/sdk-reference/videosdkmediaeffects-plugin#removevirtualbackground)



---



---

# Overview of SIP with VideoSDK - Flutter




SIP (Session Initiation Protocol) is extensively employed for setting up and controlling IP-based calls. It facilitates the initiation and termination of user sessions over IP networks, enabling SIP-based systems to connect and exchange voice communications over the internet.

With VideoSDK's SIP Connect feature, you can enable your users to join VideoSDK meetings via VOIP using third-party service providers. This allows for establishing a bridge between participants using our client SDKs and those joining via SIP, enhancing the accessibility and connectivity of your video meetings.

![SIP Architecture](https://cdn.videosdk.live/website-resources/docs-resources/sip-architechture.png)

### Getting SIP Credentials

To use SIP Connect, you will first need to generate the credentials for the SIP. Go to the [VideoSDK dashboard](https://app.videosdk.live) and under the [API Keys](https://app.videosdk.live/api-keys) sections, first enable the SIP for the desired API key after which you will be presented with the SIP `username` and `password` you can use to establish connection with our SIP servers.

![SIP Credentials](https://cdn.videosdk.live/website-resources/docs-resources/sip-get-credentials.gif)

### How to use SIP to join a particular meeting?

Once you have the credentials, you can use any of the softphones like Linphone, Zoiper etc. or use a third party service provider like twilio to connect with a VideoSDK meeting by initiating a SIP call to `sip:<meeting-id>@sip.videosdk.live`

For example if you want to connect to `abcd-abcd-abcd` meeting then the SIP address will look like `sip:abcd-abcd-abcd@sip.videosdk.live`

### Example of Twilio PSTN

To utilize third-party PSTN (Public Switched Telephone Network) providers like Twilio for making calls via SIP (Session Initiation Protocol), follow these steps:

1. Log in to your Twilio account and navigate to the Phone Numbers section.
2. Purchase a phone number and access its configuration settings.
3. Set up a Webhook handler that will initiate a call to the VideoSDK SIP endpoint whenever an incoming call is received on the selected phone number.

![SIP Configuration for Twilio](https://cdn.videosdk.live/website-resources/docs-resources/sip-twilio-config.png)

##### Example for creating Webhook using Express

```js
const express = require("express");
const VoiceResponse = require("twilio").twiml.VoiceResponse;
const urlencoded = require("body-parser").urlencoded;

const app = express();

// Parse incoming POST params with Express middleware
app.use(urlencoded({ extended: false }));

// Webhook route which will be called by twilio when a call is received
app.post("/incoming-call-handler", (request, response) => {
  console.log({ request });
  // Use the Twilio Node.js SDK to build an XML response
  const twiml = new VoiceResponse();

  const dial = twiml.dial();
  dial.sip(
    {
      username: "<User name generated for dashboard>",
      password: "<Password generated from dashboard>",
    },
    "sip:<meetingId>@sip.videosdk.live"
  );

  // Render the response as XML in reply to the webhook request
  response.type("text/xml");
  response.send(twiml.toString());
});

//Start the express app on port 8000
app.listen(8000, () => {
  console.log(`Server listening on port ${8000}.`);
});
```



---

# Build a SIP Integration: VideoSDK & Twilio for Inbound Outbound Calls! Step-by-Step


Imagine joining an online meeting using just your phone—no apps, no browsers, no internet. This powerful option allows participants to connect via traditional telephony, by creating a bridge between phone systems and modern video conferencing platforms. In this post, we’ll explore how to build a SIP integration using VideoSDK and Twilio for both inbound and outbound VoIP calls.



We’ll break down the flow of calls, set up the project, and show you how to bring this functionality to life using Next.js.

## What Is a SIP Integration?

SIP, or Session Initiation Protocol, enables voice and video communications over internet-based networks. With SIP integrations, traditional phone systems can connect to online platforms .

By integrating SIP with VideoSDK’s SIP address and Twilio, you can handle both inbound and outbound calls while linking them to video meetings. This integration is particularly helpful for situations where participants lack internet access, allowing them to simply dial in to join a meeting or receive phone calls initiated by meeting participants.

## Understanding Inbound and Outbound Call Flows

### Inbound Calls

![Inboud Call Flow](https://assets.videosdk.live/images/inbound.png)

Inbound calls are initiated by a user or customer dialing a phone number, such as a Twilio-provisioned number. Here’s how the process works:

1. **User Dialing**: A participant dials the Twilio number tied to the SIP integration.
2. **Call Routing**: Twilio receives the call and notifies your server with call details.
3. **Server Processing**: Your server processes the request and sends an invite SIP request to the VideoSDK SIP address.
4. **Connection Established**: Once validated, the caller is connected to the specific video meeting through VideoSDK.

For example, if a customer wants to join a video conference using their phone, they can call a designated number. Following this process, the integration connects them to the meeting.

### Outbound Calls

![Outbound Call Flow](https://assets.videosdk.live/images/outbound.png)

Outbound calls begin with a participant or agent in an online meeting initiating a call to a customer’s phone. The process involves the following steps:

1. **Call Request Initiated**: A participant requests your server to call a specific phone number.
2. **Server Action**: The server notifies Twilio to establish the call.
3. **User Accepts Call**: When the user accepts, the connection is forwarded to the video meeting through VideoSDK.

This two-way communication ensures smooth interaction between online participants and phone users.

## Step-by-Step Guide to Setting Up the Project

### Prepare the Project Files

1. Create a workspace for the SIP integration project (or open your existing project if you already have one).

```bash
mkdir videosdk-sip-integration && cd videosdk-sip-integration
```

1. Navigate to project directory

```javascript
cd videosdk-sip-integration
```

1. Install dependencies that are required for you application to work

```javascript
npm install
```

### Configure the Environment

1. **Set Up the `.env` File**: Copy the `.env.example` file in the repository and rename it to `.env`.
2. **Add VideoSDK Details**: Obtain the SIP username, password, and authentication token from the [VideoSDK dashboard](https://app.videosdk.live/).
   - Generate an authentication token under “API Keys.”
   - Get your SIP username and password from the “SIP Config” section.
   - Add these details to the `.env` file.
3. **Configure Twilio**: Sign in to your [Twilio console](https://console.twilio.com/).
   - Copy your Twilio phone number, Account SID, and Auth Token.
   - Paste these values into the `.env` file.

```javascript
TWILIO_ACCOUNT_SID=your-twilio-account-sid
TWILIO_AUTH_TOKEN=your-twilio-auth-token
VIDEOSDK_SIP_USERNAME=your-videosdk-sip-username
VIDEOSDK_SIP_PASSWORD=your-videosdk-sip-password
NEXT_PUBLIC_TWILIO_PHONE_NUMBER=your-twilio-phone-number
NEXT_APP_URL=http://localhost:3000 # Replace with your production URL
```

Your `.env` file should now contain all necessary credentials.

### Running the Application

Once the configurations are complete, start the project using the following command:

```bash
npm run dev
```

![demo home page](https://assets.videosdk.live/images/demo.png)

The application will run locally on port 3000.



## Setting Up Call Routing

### Inbound Call Setup

**Define the API URL**: In Twilio’s Active Numbers section, specify your API endpoint (e.g., `/api/webhook/inbound`). Twilio will send incoming call details to this URL.

If hosting locally, tools like `ngrok` or `pinggy` can expose your server to the internet for testing purposes. Replace the localhost URL with the public domain generated by these tools in the Twilio configuration.

![Twilio Dashboard](https://assets.videosdk.live/images/twilio-dashboard.png)

**Handle Calls with VideoSDK**: Once Twilio routes the call, your code forwards the meeting ID to VideoSDK’s SIP address. This connects the caller to the online meeting.

```javascript

// Environment variables
const accountSid = process.env.TWILIO_ACCOUNT_SID || "";
const authToken = process.env.TWILIO_AUTH_TOKEN || "";
const videosdkSipUsername = process.env.VIDEOSDK_SIP_USERNAME || "";
const videosdkSipPassword = process.env.VIDEOSDK_SIP_PASSWORD || "";

const client = twilio(accountSid, authToken);

export async function POST(request: Request): Promise<Response> {
  try {
    const url = new URL(request.url);
    const meetingId = url.searchParams.get("meetingId");

    const twiml = new twilio.twiml.VoiceResponse();
    twiml.say("Welcome to the Video sdk conference. Connecting you now.");
    twiml.dial().sip(
      {
        username: videosdkSipUsername,
        password: videosdkSipPassword,
      },
      `sip:${meetingId}@sip.videosdk.live`
    );

    return new Response(twiml.toString(), {
      headers: {
        "Content-Type": "text/xml",
      },
    });
  } catch (error) {
    console.error("Error processing Twilio webhook:", error);

    // Return TwiML error response
    const twiml = new twilio.twiml.VoiceResponse();
    twiml.say("Sorry, there was an error connecting your call.");

    return new Response(twiml.toString(), {
      headers: {
        "Content-Type": "text/xml",
      },
    });
  }
}
```

### Outbound Call Setup

For outbound calls, the meeting participant in the web app interacts with an API endpoint that sends a request to Twilio. Twilio establishes the call with the provided number, connecting the phone user back to the meeting through VideoSDK.

```javascript

// Environment variables
const accountSid = process.env.TWILIO_ACCOUNT_SID || "";
const authToken = process.env.TWILIO_AUTH_TOKEN || "";
const twilioPhoneNumber = process.env.NEXT_PUBLIC_TWILIO_PHONE_NUMBER || "";

const client = twilio(accountSid, authToken);

export const dynamic = "force-dynamic";

export async function POST(request: Request): Promise<Response> {
  try {
    const { phoneNumber, meetingId } = await request.json();

    if (!phoneNumber) {
      throw new Error("phone number is required!");
    }

    // Make the outbound call
    const call = await client.calls.create({
      to: phoneNumber,
      from: twilioPhoneNumber,
      url: `${process.env.NEXT_APP_URL}/api/webhook/inbound?meetingId=${meetingId}`,
      method: "POST",
    });

    return new Response(JSON.stringify({ success: true, callSid: call.sid }), {
      headers: {
        "Content-Type": "application/json",
      },
    });
  } catch (error) {
    console.error("Error making outbound call:", error);

    return new Response(
      JSON.stringify({
        success: false,
        error: "Failed to initiate call",
      }),
      {
        status: 500,
        headers: {
          "Content-Type": "application/json",
        },
      }
    );
  }
}
```

**Create an Outbound API**: Write an API function to trigger calls using Twilio’s client instancee.g., `/api/webhook/outbound`)

**Trigger Outbound Calls**: Use this API in your application to handle requests for dialing specific numbers.

When the call is accepted, the system routes it to the VideoSDK SIP address, establishing a connection to the meeting.

## Testing the Integration

To test the setup:

1. Make a call to the Twilio number for inbound calls.
   - Ensure the meeting ID and SIP configurations are correctly passed.
2. Initiate an outbound call from a meeting participant to a phone number.
   - Validate that the phone user is successfully connected to the meeting.

Both inbound and outbound calls should work smoothly, demonstrating the bridged connection between telephony and video conferencing.

## Conclusion

Integrating SIP functionality into your project using VideoSDK and Twilio unlocks new possibilities for communication. By enabling inbound and outbound VoIP calls, you can connect traditional phone systems with modern video conferencing platforms.

This guide covered the basics of setting up the integration, routing calls, and ensuring smooth connectivity. If you encounter any issues or need further help, join the VideoSDK Discord community.

Simplify your users’ communication experience—embrace the power of SIP integration.



---

# SIP Connect - Flutter





SIP (Session Initiation Protocol) is extensively employed for setting up and controlling IP-based calls. It facilitates the initiation and termination of user sessions over IP networks, enabling SIP-based systems to connect and exchange voice communications over the internet.

With VideoSDK's SIP Connect feature, you can enable your users to join VideoSDK meetings via VOIP using third-party service providers. This allows for establishing a bridge between participants using our client SDKs and those joining via SIP, enhancing the accessibility and connectivity of your video meetings.

![SIP Architecture](https://cdn.videosdk.live/website-resources/docs-resources/sip-architechture.png)

### Getting SIP Credentials

To use SIP Connect, you will first need to generate the credentials for the SIP. Go to the [VideoSDK dashboard](https://app.videosdk.live) and under the [API Keys](https://app.videosdk.live/api-keys) sections, first enable the SIP for the desired API key after which you will be presented with the SIP `username` and `password` you can use to establish connection with our SIP servers.

![SIP Credentials](https://cdn.videosdk.live/website-resources/docs-resources/sip-get-credentials.gif)

### How to use SIP to join a particular meeting?

Once you have the credentials, you can use any of the softphones like Linphone, Zoiper etc. or use a third party service provider like twilio to connect with a VideoSDK meeting by initiating a SIP call to `sip:<meeting-id>@sip.videosdk.live`

For example if you want to connect to `abcd-abcd-abcd` meeting then the SIP address will look like `sip:abcd-abcd-abcd@sip.videosdk.live`

### Example of Twilio PSTN

To utilize third-party PSTN (Public Switched Telephone Network) providers like Twilio for making calls via SIP (Session Initiation Protocol), follow these steps:

1. Log in to your Twilio account and navigate to the Phone Numbers section.
2. Purchase a phone number and access its configuration settings.
3. Set up a Webhook handler that will initiate a call to the VideoSDK SIP endpoint whenever an incoming call is received on the selected phone number.

![SIP Configuration for Twilio](https://cdn.videosdk.live/website-resources/docs-resources/sip-twilio-config.png)

##### Example for creating Webhook using Express

```js
const express = require("express");
const VoiceResponse = require("twilio").twiml.VoiceResponse;
const urlencoded = require("body-parser").urlencoded;

const app = express();

// Parse incoming POST params with Express middleware
app.use(urlencoded({ extended: false }));

// Webhook route which will be called by twilio when a call is received
app.post("/incoming-call-handler", (request, response) => {
  console.log({ request });
  // Use the Twilio Node.js SDK to build an XML response
  const twiml = new VoiceResponse();

  const dial = twiml.dial();
  dial.sip(
    {
      username: "<User name generated for dashboard>",
      password: "<Password generated from dashboard>",
    },
    "sip:<meetingId>@sip.videosdk.live"
  );

  // Render the response as XML in reply to the webhook request
  response.type("text/xml");
  response.send(twiml.toString());
});

//Start the express app on port 8000
app.listen(8000, () => {
  console.log(`Server listening on port ${8000}.`);
});
```



---

<h1> {props.title} </h1>{" "}

### Why we are using JWT based Token ?

Token based authentication allows users to verify their identity by providing generated API key and secret.

We use JWT token for the authentication purpose because Token-based authentication is **widely used** in modern web applications and APIs because it offers several benefits over traditional authentication. For example, it can **reduce the risk of the credentials being misused**, and it allows for **more fine-grained control** over access to resources. Additionally, tokens can be easily revoked or expired, making it easier to manage access rights.

### How to generate Token ?

To manage secured communication, every participant that connects to the meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key` which you can get from [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

#### 1. Generating token from Dashboard

If you are looking to do **testing or for development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for getting token includes generating it from your backend server which will help in **keeping your credentials safe**.
:::

#### 2. Generating token in your backend

- Your server will generate access token using your API key and secret.
  - While generating a token, you can provide **expiration time, permissions and roles** which are discussed later in this section.
- Your client obtains token from your backend server.
- For token validation, client will pass this token to VideoSDK server.
- VideoSDK server will only allow entry in the meeting if the token is valid.

![img2.png](../../static/img/authentication-and-token.png)




Follow our official example repositories to setup token API [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)

### Payload while generating token

```js
{
 apikey: API_KEY, //MANDATORY
 permissions: [`allow_join`], //`ask_join` || `allow_mod` //MANDATORY
 version: 2, //OPTIONAL
 roomId: ROOM_ID, //OPTIONAL,
 participantId: PARTICIPANT_ID, //OPTIONAL
 roles: ['crawler', 'rtc'], //OPTIONAL
}
```

- **`apikey`(Mandatory)**: This must be the API Key generated from the VideoSDK Dashboard. You can get it from [here](https://app.videosdk.live/api-keys).

- **`permissions`(Mandatory)**: By providing the permissions, you can control what a participant can do in the meeting and whether he can join the meeting directly.

  Available permissions are:

  - **`allow_join`**: The participant is **allowed to join** the meeting directly.
  - **`ask_join`**: The participant is required to **ask for permission to join** the meeting. The participant having the permission `allow_join` can accept or reject a participant whenever someone wants to join.
  - **`allow_mod`**: The participant is **allowed to toggle** webcam & mic of other participants.

- **`version`(optional)**: For accessing the [v2 API](/api-reference/realtime-communication/intro), you need to provide `2` as the version value.

  - For passing `roomId`, `participantId` or `roles` parameters in payload, it is essential to set the version value to `2`.

- **`roomId`(optional)**: To provide customised access control, you can make the token applicable to a particular room by including the `roomId` in the payload.

- **`participantId`(optional)**: You can include the `participantId` in the payload to limit the token's access to a particular participant.

- **`roles`(optional)**:

  - **`crawler`**: This role is only for accessing [v2 API](/api-reference/realtime-communication/intro), you can not use this token for running the `Meeting`/`Room`.
  - **`rtc`**: This role is only allowed for running the `Meeting` / `Room`, with this role you can not use [server-side APIs](/api-reference/realtime-communication/intro).

Then, you have to sign this payload with your **`SECRET KEY`** and `jwt` options using the **`HS256 algorithm`**.

### Expiration time

You can set any expiration time to the token. But in the **production environment**, it is recommended to generate a token with **short expiration time** because by any chance if someone gets hold of the token, it won't be valid for a longer period of time.

### What happens if token is expired?

If your token is expired, the user won't be able to join the meeting and all the API calls will give error with message `Token is invalid or expired`.

:::note
Token is validated only once while joining the meeting, so if a person joins the meeting and the token gets expired after that, there won't be any issue in the current meeting.
:::

## How to check validity of token?

1. After generating the token, visit [jwt.io](https://jwt.io) and paste your token in the given area.
2. You will be able to see the payload you passed while generating the token and also be able to see the expiration time and token creation time.

![img1.png](../../static/img/validate-token.png)

## API Settings & Controls

The VideoSDK Dashboard provides a powerful [API Settings](https://app.videosdk.live/api-keys) section where you can configure various services and controls for your meetings. These settings allow you to customize the behavior of different features directly from the dashboard without requiring code changes.

## Audio/Video Configurations

:::note
Runtime configuration from the dashboard has higher precedence than static SDK configurations.
If a value is modified in the dashboard, it will override any previously defined SDK settings for that session.

Example:
Code: Video = HD → Dashboard: Video = Full HD → Applied: Full HD
:::

### Maximum Send Bitrate Per Participant

Control the maximum total upload bandwidth for all media streams from a single participant.

![Maximum Send Bitrate](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.00.11%E2%80%AFPM.png)

**Available Options:**
- **Auto**: Removes the upload bitrate limit (recommended for best quality)
- **SD (800kbps)**: Standard definition bitrate
- **HD (1500kbps)**: High definition bitrate
- **Full HD (3000kbps)**: Full high definition bitrate

:::tip
Setting this to **Auto** provides the best video quality as it removes upload bitrate constraints, allowing adaptive streaming based on network conditions.
:::

## Recording & Streaming Configuration

:::note
Recording and HLS follow a precedence-based configuration model:

API/SDK configuration → Highest priority
Dashboard configuration → Used only when no API values are defined

Any parameters explicitly set via the API will not be overridden by dashboard changes.
:::

### Recording Configuration

Configure recording settings for your meetings including layout, quality, and auto-start options.

![Recording Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.01.00%E2%80%AFPM.png)

**Recording Controls:**
- **Enabled**: Toggle to enable/disable recording functionality
- **Enabled Modes**: Choose between Video & Audio or Audio Only recording
- **Start Recording Automatically**: Auto-start recording when meeting begins
- **Layout Style**: Select Grid layout for recording composition
- **Maximum Tiles In Grid**: Set the number of participants visible in grid (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme for recordings
- **Video Orientation**: Choose between Landscape or Portrait mode
- **Recording Quality**: Select quality level (e.g., HD Medium)
- **Recording Mode**: Choose between Video & Audio or Audio Only

### HLS Streaming Configuration

Configure HTTP Live Streaming (HLS) settings for broadcasting your meetings.

![HLS Streaming Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.02.18%E2%80%AFPM.png)

**HLS Streaming Controls:**
- **Enabled**: Toggle to enable/disable HLS streaming
- **Enabled Modes**: Choose between Video & Audio or Audio Only streaming
- **Auto Start HLS**: Automatically start HLS when meeting begins
- **Record HLS Stream**: Enable recording of the HLS stream
- **Layout Style**: Select Grid layout for stream composition
- **Maximum Tiles In Grid**: Set the number of participants visible (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme
- **HLS Orientation**: Choose between Landscape or Portrait mode
- **HLS Quality**: Select streaming quality (e.g., HD Medium)
- **HLS Streaming Mode**: Choose between Video & Audio or Audio Only

### Additional Service Controls

Enable or disable additional services for your API key.

![Service Controls](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.08%E2%80%AFPM.png)

**Available Services:**
- **RTMP Output**: Enable RTMP streaming to external platforms
- **SIP Integration**: Enable SIP (Session Initiation Protocol) integration for telephony
- **Realtime Translation**: Enable real-time language translation in meetings

### Transcription & Summary

Configure transcription and domain whitelisting for your API key.

![Transcription Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.50%E2%80%AFPM.png)

**Transcription Controls:**
- **Enabled**: Toggle to enable/disable transcription and summary features
- **Whitelist Domain**: Add domain restrictions for API key usage
  - Enter domain names in the format `https://domain.name`
  - Click "Add Domain" to whitelist specific domains
  - Only whitelisted domains can use this API key
  - When no domains are whitelisted, the API key can be used from any domain


---

# Monitoring Call Quality - Flutter

Monitoring the local participant’s call quality is essential to ensure a smooth and uninterrupted meeting experience. Changes in network conditions or device performance can directly affect audio and video quality. By subscribing to the **`qualityLimitation`** event accessible from the `Room` class, your app can detect these changes in real-time and provide immediate feedback to the participant.

## Why It Matters

Even brief network congestion, low bandwidth, or high CPU usage can impact the meeting experience. Monitoring these limitations allows your app to:

- Notify the local participant of potential issues affecting audio or video quality.
- Empower the participant to take action, like switching networks or closing other heavy applications.

## Example Usage

```js
import 'package:videosdk/videosdk.dart';

late Room _room;

@override
void initState() {
  super.initState();

  // Create room
  _room = VideoSDK.createRoom(
    roomId: widget.meetingId,
    token: widget.token,
    displayName: "John Doe",
    micEnabled: micEnabled,
    camEnabled: camEnabled,
    defaultCameraIndex: kIsWeb
        ? 0
        : 1, // Index of MediaDevices used to set default camera
  );

  setMeetingEventListener();

  // Join room
  _room.join();
}

// Listening to meeting events
void setMeetingEventListener() {
  _room.on(
    Events.qualityLimitation,
    (type, state, timestamp) {
      print(
        "Quality Limitation for $type in state $state at $timestamp",
      );
    },
  );
}

```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [qualityLimitation](/flutter/api/sdk-reference/room-class/events#qualitylimitation)


---

# Monitoring Remote Participants' Stream - Flutter

Monitoring the state of a remote participant’s stream helps ensure a consistent and high-quality meeting experience. The **`streamStateChanged`** event accessible from the `Stream` class provides real-time updates whenever the condition of a remote video or screenshare video stream changes — allowing your app to detect issues and respond accordingly.

By subscribing to this event, you can track when a stream becomes active, stuck, or experiences a freeze, and take corrective actions or inform users as needed.

:::note
This event is emitted exclusively for remote participants, specifically for their video and screen share video streams.
:::

## Why It Matters

Stream state monitoring is crucial for maintaining call reliability and diagnosing issues that affect the remote participant’s media. Using this event, you can:

- Detect when a remote participant’s video freezes or becomes stuck.
- Notify local participants about possible issues.
- Log state transitions for diagnostics or quality metrics.

## Example Usage

```js
import 'package:videosdk/videosdk.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;

  const ParticipantTile({
    super.key,
    required this.participant,
  });

  @override
  State<ParticipantTile> createState() => _ParticipantTileState();
}

class _ParticipantTileState extends State<ParticipantTile> {
  Stream? videoStream;

  @override
  void initState() {
    super.initState();

    // Initialize existing video stream (if already available)
    widget.participant.streams.forEach((key, Stream stream) {
      if (stream.kind == 'video') {
        _setVideoStream(stream);
      }
    });

    _initStreamListeners();
  }

  void _setVideoStream(Stream stream) {
    setState(() {
      videoStream = stream;
    });

    // Listen to stream state changes
    videoStream?.on(
      Events.streamStateChanged,
      (state, timestamp) {
        log("Stream state changed to $state at $timestamp");
      },
    );
  }

  void _initStreamListeners() {
    widget.participant.on(
      Events.streamEnabled,
      (Stream stream) {
        if (stream.kind == 'video') {
          _setVideoStream(stream);
          widget.participant.setQuality(quality);
        }
       
      },
    );
    
  }

  @override
  Widget build(BuildContext context) {
    return Container(
      // Your UI here
    );
  }
}

```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [streamStateChanged](/flutter/api/sdk-reference/stream-class/events#streamstatechanged)


---

# Chat using PubSub - Flutter

For the communication or any kind of messaging in between the participants, VideoSDK provides `pubSub` which use Publish-Subsciribe mechanism and can be used to develope wide varitey of functionalities. For example, participants could use it to send chat messages to each other, share files or other media, or even trigger actions like muting or unmuting audio or video.

Now we will see, how we can use PubSub to implement Chat functionality. If you are not familiar with the PubSub mechanism, you can [follow this guide](./pubsub).

## Implementing Chat

### `Group Chat`

1. First step in creating a group chat is choosing the topic which all the participants will publish and subscribe to send and receive the messages. We will be using `CHAT` as the topic for this one. So let us lets create a message input and send button to publish the messages using the `pubSub` from the `Room` object.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ChatView extends StatefulWidget {
  final Room room;
  ...
}

class _ChatViewState extends State<ChatView> {

  final msgTextController = TextEditingController();


  @override
  void initState() {
    //highlight-next-line
    ...

    //highlight-start
    // Subscribing 'CHAT' Topic
    widget.meeting.pubSub
      .subscribe("CHAT", messageHandler)
      .then((value) => setState((() => messages = value)));
    //highlight-end
  }

  //highlight-start
  //Handler which will be called when new mesasge is received
  void messageHandler(PubSubMessage message) {
    setState(() => messages!.messages.add(message));
  }
  //highlight-end

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        Row(
          children: [
            Expanded(
              child: TextField(
                style: TextStyle(
                  fontSize:16,
                  fontWeight: FontWeight.w500,
                ),
                controller: msgTextController,
                onChanged: (value) => setState(() {
                  msgTextController.text;
                }),
                decoration: const InputDecoration(
                  hintText: "Write your message",
                  border: InputBorder.none,
                ),
              ),
            ),
            ElevatedButton(
              onPressed:(){
                if(!msgTextController.text.trim().isEmpty){
                  widget.room.pubSub
                        .publish(
                          "CHAT",
                          msgTextController.text,
                          const PubSubPublishOptions(
                              persist: true),
                        )
                        .then(
                            (value) => msgTextController.clear())
                }
              },
              child: const Text("Send Message"),
            ),
          ],
        ),
    //highlight-end
      ]
    );
  }

}
```

2. Final step in the group chat would be to display the messages others send. For this will use the `messages` and display all the messages by subscribing to the topic `CHAT`.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ChatView extends StatefulWidget {
  final Room room;
  ...
}

class _ChatViewState extends State<ChatView> {

  // PubSubMessages
  PubSubMessages? messages;

  @override
  void initState() {
    //highlight-next-line
    ...

    //highlight-start
    // Subscribing 'CHAT' Topic
    widget.meeting.pubSub
      .subscribe("CHAT", messageHandler)
      .then((value) => setState((() => messages = value)));
    //highlight-end
  }

  //highlight-start
  //Handler which will be called when new mesasge is received
  void messageHandler(PubSubMessage message) {
    setState(() => messages!.messages.add(message));
  }
  //highlight-end

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        Expanded(
          child: messages == null
              ? const Center(child: CircularProgressIndicator())
              : SingleChildScrollView(
                  reverse: true,
                  child: Column(
                    children: messages!.messages
                        .map(
                          (message) => Text(
                            message.message
                          ),
                        )
                        .toList(),
                  ),
                ),
        ),

        ...
        //Send Message code Here
    //highlight-end
      ]
    );
  }

  @override
  void dispose() {
    //highlight-start
    // Unsubscribe
    widget.room.pubSub.unsubscribe("CHAT", messageHandler);
    //highlight-end
    super.dispose();
  }
}
```

### `Private Chat`

In the above example, if you want to convert into the private chat between two participants, then all you have to do is pass `sendOnly` parameter in `PubSubPublishOptions`.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ChatView extends StatefulWidget {
  final Room room;
  ...
}

class _ChatViewState extends State<ChatView> {

  //...

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        Row(
          children: [
            Expanded(
              child: TextField(
                style: TextStyle(
                  fontSize:16,
                  fontWeight: FontWeight.w500,
                ),
                controller: msgTextController,
                onChanged: (value) => setState(() {
                  msgTextController.text;
                }),
                decoration: const InputDecoration(
                  hintText: "Write your message",
                  border: InputBorder.none,
                ),
              ),
            ),
            ElevatedButton(
              onPressed:(){
                if(!msgTextController.text.trim().isEmpty){
                  //highlight-start
                  // Pass the participantId of the participant to whom you want to send the message.
                  widget.room.pubSub
                        .publish(
                          "CHAT",
                          msgTextController.text,
                          const PubSubPublishOptions(
                            persist: true, sendOnly: ["xyz"]),
                        )
                        .then(
                            (value) => msgTextController.clear())
                  //highlight-end
                }
              },
              child: const Text("Send Message"),
            ),
          ],
        ),
      ]
    );
  }

}
```

### Displaying Latest Message Notificaiton

You may want to show the notification to the user when new message arrives. So lets continue our example and add alert for the new images.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ChatView extends StatefulWidget {
  final Room room;
  ...
}

class _ChatViewState extends State<ChatView> {

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  //highlight-start
  //Handler which will be called when new mesasge is received
  void messageHandler(PubSubMessage message) {
    //Show snackbar on new message
    if(context.mounted){
      ScaffoldMessenger.of(context).showSnackBar(SnackBar(
        content: Text(
          message.message,
          overflow: TextOverflow.fade,
        ),
      ));
    }
    setState(() => messages!.messages.add(message));
  }
  //highlight-end

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ...
         //highlight-end
      ]
    );
  }

  @override
  void dispose() {
    //highlight-next-line
    ...
  }
}
```

## Downloading Chat Messages

All the messages from the PubSub which where published with `persist : true` and can be downloaded as an `.csv` file. This file will be available in the VideoSDK dashboard as well as throught the [Sessions API](/api-reference/realtime-communication/fetch-session-using-sessionid).

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub](/flutter/api/sdk-reference/pubsub-class/introduction)


---

# PubSub - Flutter

PubSub is a short acronym for Publish-Subscribe mechanism. This mechanism is used to send and recieve messages from a particular topic. As the name suggests, for someone to send a message, they have to specify the topic and the message which should be published and for someone to receive a message, they should be subscribed to that topic.

Here is a visual to better understand publish-subscribe mechanism.

![pubsub](/img/pubsub.png)

## PubSub

In order to use PubSub in meeting, VideoSDK provides a hook `usePubSub` which allows you to subscribe to any topic and publish to any topic allowing to pass on messages and instructions during the meeting easily.

### `publish()`

- This method is used for publishing message of specific topic.
- This method can be accessed from the `pubSub` from the `Room`.
- This method will accept following parameters as input:
  - `topic`: This will be the topic where the message will be published.
  - `message`: This will be the actual message to be published. It has to be in `String` format.
  - `options`: This is an object of `PubSubPublishOptions` which specifies the options for publish. `PubSubPublishOptions` has 2 properties. 
    - `persist` : `persist` offered the option of keeping the message around for the duration of the session. When `persist` is set to `true`, that message will be retained for upcoming participants and will be available in [VideoSDK Session Dashboard](https://app.videosdk.live/meetings/sessions) with `.CSV` format after completion of session.
    - `sendOnly`: If you want to send a message to specific participants, you can pass their respective `participantId` in form of `List<String>`. If you don't provide any IDs, the message will be sent to all participants by default. This is optional parameter.
  - `payload`: If you need to include additional information along with a message, you can pass here as `Map<String, dynamic>`. This is optional parameter.


```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        //These will publish "Hello World!" on the "CHAT" topic
        ElevatedButton(
          onPressed:(){
            _room.pubSub.publish("CHAT", "Hello World!")
          },
          child: const Text("Send Message"),
        ),
    //highlight-end
      ]
    );
  }
}
```

## Receiving the messages

- All the previous messages for the particular topic can be recieved by subscribing to the topic.
- To subscribe to a specific topic, use can use the `subscribe()` method which will return the `Future<PubSubMessages>` and accepts the `topic` to be subscribed and a `callback function` which will be called when ever any new message is received.

- `PubSubMessages` contains the `messages` as a list of `PubSubMessage` which will contain following properties:
  - `senderId`: This represents the `participantId` of the participant who send the message.
  - `senderName`: This represents the `displayName` of the participant who send the message.
  - `message`: This will be the acatual message that was send.
  - `timestamp`: This wil the timestamp for when the message was published.
  - `topic`: This will be the name of the topic message was published to.
  - `payload`: This will be the data that you have send with message.

## Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ChatView extends StatefulWidget {
  final Room room;
  ...
}

class _ChatViewState extends State<ChatView> {

  // PubSubMessages
  PubSubMessages? messages;

  @override
  void initState() {
    //highlight-next-line
    ...

    //highlight-start
    // Subscribing 'CHAT' Topic
    widget.meeting.pubSub
      .subscribe("CHAT", messageHandler)
      .then((value) => setState((() => messages = value)));
    //highlight-end
  }

  //highlight-start
  //Handler which will be called when new mesasge is received
  void messageHandler(PubSubMessage message) {
    setState(() => messages!.messages.add(message));
  }
  //highlight-end

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        Expanded(
          child: messages == null
              ? const Center(child: CircularProgressIndicator())
              : SingleChildScrollView(
                  reverse: true,
                  child: Column(
                    children: messages!.messages
                        .map(
                          (message) => Text(
                            message.message
                          ),
                        )
                        .toList(),
                  ),
                ),
        ),
    //highlight-end
      ]
    );
  }

  @override
  void dispose() {
    //highlight-start
    // Unsubscribe
    widget.room.pubSub.unsubscribe("CHAT", messageHandler);
    //highlight-end
    super.dispose();
  }
}
```

## Applications of PubSub

PubSub is a very powerful mechanism which can be used to do alot of things which can make your meeting experience much more interactive. Some of the most common usecase that we have come across for the PubSub during a meeting are listed below:

1. [`Chat`](./chat-using-pubsub): You can utilise this to develop various Chat features, such as Private Chat and Group Chat. You can follow our chat [integration guide here](./chat-using-pubsub).
2. `Raise Hand`: You can allow attendees to raise their hands at any time during the meeting, informing everyone else that someone has done so.
3. `Layout Switching`: You can change the meeting's layout for every participant at once during the meeting, such as from Grid layout to Spotlight or Grid Layout to Sidebar Layout, etc.
4. `Whiteboard`: You can develop an interactive whiteboard functionality that is completely functional.
5. `Poll`: You may make polls, let users respond to them, and display the results at the end of a poll.
6. `Question Answer Session`: You can also design interactive functionality that is question-and-answer based.

## Downloading PubSub Messages

All the messages from the PubSub which were published with `persist : true` and can be downloaded as an `.csv` file. This file will be available in the VideoSDK dashboard as well as throught the [Sessions API](/api-reference/realtime-communication/fetch-session-using-sessionid).

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub](/flutter/api/sdk-reference/pubsub-class/introduction)


---

# Realtime Store - Flutter

The **Realtime Store** allows you to store, update, retrieve, and observe custom key-value data within a meeting — in real time. It acts as a shared data layer across all connected participants, ensuring synchronized states throughout the session.

This is particularly useful for collaborative or stateful meeting experiences such as:

- Pinned messages and flags
- Moderation data (e.g., blocked users)
- Collaborative notes or polls

## `setValue()`

The `setValue()` method is used to store or update data in the RealtimeStore. If a key already exists, it will be overwritten with the new value. Passing `null` as the value deletes the key.

### Key Notes

- Supports **String** values only.
- Each key can store up to **1 KB** of data.
- A maximum of **100 keys** are allowed per session.
- Deletion is performed by setting the value to `null`.
- Throws an error if:
  - The key is missing or empty.
  - The request fails.
  - The session exceeds the 100-key limit.

### Parameters

- **`key`** (`String`)  
  The unique key to store the data under.

- **`value`** (`String?`)  
  The string value to be stored. Pass `null` to delete the key.


### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    _room = VideoSDK.createRoom(
      roomId: widget.meetingId,
      token: widget.token,
      displayName: "User1",
      micEnabled: true,
      camEnabled: true,
      defaultCameraIndex: 0,
      multiStream: true,
      mode: Mode.SEND_AND_RECV,
    );
    _room.join();
  }

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      //highlight-start
      ElevatedButton(
        String key = "BLOCK_CHAT";
        String value = "true";
        onPressed: () async {
            try {
              await _room.realtimeStore.setValue(key, value);
            } catch(e){
              print("Error:$e");
            }
        },
        child: const Text("Realtime Store Set Value"),
      ),
      //highlight-end
    ]);
  }
}

```

---

## `getValue()`

The `getValue()` method retrieves the current value associated with a given key.

### Key Notes

- Returns the current string value for the given key.
- Useful for fetching shared state when joining a meeting or reloading a view.
- Throws an error if the key is missing/empty or if the request fails.

### Parameters

- **`key`** (`String`)  
  The key whose value you want to retrieve.

### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    _room = VideoSDK.createRoom(
      roomId: widget.meetingId,
      token: widget.token,
      displayName: "User1",
      micEnabled: true,
      camEnabled: true,
      defaultCameraIndex: 0,
      multiStream: true,
      mode: Mode.SEND_AND_RECV,
    );
    _room.join();
  }

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      //highlight-start
       ElevatedButton(
        String key = "BLOCK_CHAT";
        String response= "";
        onPressed: () async {
          try { 
            response = await _room.realtimeStore.getValue(key);
          } catch(e){
            print("Error:$e");
          }
        },
        child: const Text("Realtime Store Get Value:$response"),
      ),
      //highlight-end
    ]);
  }
}
```
---

## `observe()`

The `observe()` method subscribes to real-time updates for a given key. When the key’s value changes, a delegate method on your listener is automatically triggered for all connected participants.

### Key Notes

- Returns an `observerId` which you can later use to stop observing.
- The callback receives the new value and information about who updated it.
- Ideal for syncing live data like timers, shared notes, or agendas.


### Parameters

- **`key`** (`String`)  
  The key to observe.

- **`callback`** (`function`)
  Function triggered on each update. Receives:

  - `value` (`String?`) → Updated value or `null` if deleted
  - `updatedBy` (`Participant?`) → Object of participant who made the update

### Example


```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    _room = VideoSDK.createRoom(
      roomId: widget.meetingId,
      token: widget.token,
      displayName: "User1",
      micEnabled: true,
      camEnabled: true,
      defaultCameraIndex: 0,
      multiStream: true,
      mode: Mode.SEND_AND_RECV,
    );
    _room.join();
  }

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      //highlight-start
       ElevatedButton(
        String key = "BLOCK_CHAT";
          onPressed: () async {
         try {
            observerId = await meeting.realtimeStore.observe(key,(value, updatedBy) {
              print("Updated by: ${updatedBy!.id}");
            },
        );
        } catch(e){
          print("Error:$e");
        }
       }
      child: const Text("Realtime Store Observe"),
      ),
      //highlight-end
    ]);
  } 
}
```

---

## `stopObserving()`

Stops receiving updates for a specific key and listener combination.

### Key Notes

- Should be called when the listener is no longer needed (e.g., component unmount).
### Parameters

- **`observerId`** (`String`)
  The observer ID returned from `observe()`.

### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    _room = VideoSDK.createRoom(
      roomId: widget.meetingId,
      token: widget.token,
      displayName: "User1",
      micEnabled: true,
      camEnabled: true,
      defaultCameraIndex: 0,
      multiStream: true,
      mode: Mode.SEND_AND_RECV,
    );
    _room.join();
  }

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      //highlight-start
       ElevatedButton(
         onPressed: () async {
          try{
          if (observerId != null) {
            await meeting.realtimeStore
                .stopObserving(observerId!);
            print(
                "Stopped observing with ID: $observerId");
            observerId = null; // Clear the observer ID
          } else {
            print("No active observer to stop");
          }
          } catch(e){
            print("Error:$e");
          }
          Navigator.pop(context);
        },        
      ),
      //highlight-end
    ]);
  }
}
```
---

### Error Handling & Constraints

| Property           | Description                                                                  |
| ------------------ |------------------------------------------------------------------------------|
| **Error Handling** | All errors will be handled in onError() callback. |
| **Payload Size**   | Maximum **1 KB per key**.                                                    |
| **Supported Type** | Only `String` values are supported. Use `null` to delete key.                |
| **Concurrency**    | The latest write overwrites previous values (last write wins)                |
| **Key Limit**      | A maximum of 100 keys are allowed in a single session.                       |


# API Reference

The API references for this page are provided below.


- [setValue()](/flutter/api/sdk-reference/realtimestore-class/methods#setvalue)
- [getValue()](/flutter/api/sdk-reference/realtimestore-class/methods#getvalue)
- [observe()](/flutter/api/sdk-reference/realtimestore-class/methods#observe)
- [stopObserving()](/flutter/api/sdk-reference/realtimestore-class/methods#stopobserving)


---

# Render Whiteboard - Flutter

This guide explains how to dynamically render a whiteboard in your flutter application.

## Install Dependencies

- The whiteboard is rendered using a `WebView` component. To handle this across platforms, we use the `flutter_inappwebview` package, which offers a unified WebView experience and supports all major Platforms — including Android, iOS, web, macOS, and Windows.

```js
$ flutter pub add flutter_inappwebview
```

## Render the Whiteboard

To render the whiteboard:

- Listen for the `whiteboardStarted` event from the room instance to obtain the whiteboard URL.
- Pass this URL to the `initialUrlRequest` parameter of the `InAppWebView` widget using the `WebUri` constructor.


```js
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
import 'package:flutter_inappwebview/flutter_inappwebview.dart';


class MeetingScreen extends StatefulWidget {
  @override
  State<StatefulWidget> createState() => _MeetingScreenState();
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;
  bool isWhiteboardOn = false;
  String? whiteboardUrl;

  @override
  void initState() {
    super.initState();
    //highlight-next-line
    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      //highlight-start
      ElevatedButton(
        child: Text(
          isWhiteboardOn ? 'Stop Whiteboard' : 'Start Whiteboard',
        ),
        onPressed: () {
          if (isWhiteboardOn) {
            _room.stopWhiteboard();
          } else {
            _room.startWhiteboard();
          }
        },
      ),
      //highlight-end

      if (isWhiteboardOn)
        //highlight-start
        SizedBox(
          height: 300,
          width: 350,
          child: InAppWebView(
            initialUrlRequest: URLRequest(url: WebUri(whiteboardUrl!)),
          ),
        ),
        //highlight-end
    ]);
  }

  void setupRoomEventListener() {
    //highlight-start
    _room.on(Events.whiteboardStarted, (url) {
      print("Whiteboard Started, url: $url");
      setState(() {
        whiteboardUrl = url;
        isWhiteboardOn = true;
      });
    });

    _room.on(Events.whiteboardStopped, () {
      print("Whiteboard stopped.");

      setState(() {
        isWhiteboardOn = false;
      });
    });
    //highlight-end
  }
}
```

---

---
title: Upload & Fetch Temporary File | Video SDK
hide_title: true
hide_table_of_contents: false
description: Upload & Fetch Temporary File.
sidebar_label: File Sharing
pagination_label: Upload-Fetch Temporary File
keywords:
  - upload temporary file
  - fetch temporary file
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: upload-fetch-temporary-file
--- 

# Upload and Retrieve the Temporary File - Flutter

This guide demonstrates how to upload and retrieve files from VideoSDK's temporary file storage system.

### `uploadBase64File()`

- By using the `uploadBase64File()` method of the [`Room`](/flutter/api/sdk-reference/room-class/introduction) class, you can upload your file to Videosdk's Temporary storage.

- The `uploadBase64File()` method only works with `base64`. Therefore, it is necessary to convert your file into `base64` format.

- You have to pass `base64Data`,`token`,`fileName` as parameter in `uploadBase64File()` function.

- The function will return the corresponding `fileUrl`, which you can then use to retrieve the file.

```js
void uploadFile() async {
    String base64Data = "<Your File's base64>"; //Convert your file to base64 and pass here
    String token = "<VIDEOSDK_TOKEN>";
    String fileName = "myImage.jpeg"; // Provide name with extension here
    String url = await room.uploadBase64File(
        base64Data: base64Data,
        token : token,
        fileName : fileName,
    )
    print("fileUrl $url");
}
```

### `fetchBase64File()`

- By using the `fetchBase64File()` method of the [`Room`](/flutter/api/sdk-reference/room-class/introduction) class, you can retrieve your file from Videosdk's Temporary storage.

- You have to pass the `fileUrl` which is returned by `uploadBase64File()` function, and the `token` as parameters to retrieve a file.

- This function will return the image in the form of `base64`.


```js
void fetchFile() async {
    String url = "<Your FileUrl>" //Provide fileUrl which is returned by uploadBase64File()
    String token = "<VIDEOSDK_TOKEN>"
    String base64 = room.fetchBase64File( 
        token: token,
        url: url,
    )
    print("base64 $base64");
}
```
:::note

The file stored in the system will be automatically deleted once the current room/meeting comes to an end.

:::

---

# Whiteboard - Flutter

The Whiteboard is an interactive, shared canvas that enables users to collaborate in real-time within your Flutter application. It allows multiple participants to draw, write, and add annotations simultaneously, making it ideal for meetings, presentations, brainstorming sessions, and other collaborative activities.

This documentation will guide you on how to start and stop the whiteboard, and handle the necessary events to ensure a smooth user experience.

## `startWhiteboard()`

- To start the whiteboard session, you can call the `startWhiteboard()` method of the `Room` class, which initializes the whiteboard and makes it available for user interaction.

### Events associated with startWhiteboard

- All participants will receive the `Events.whiteboardStarted` event when the whiteboard is successfully started. This event includes a URL that can be used to render the whiteboard for interaction within the app.
- It can be subscribed to, using the `Room` object.
- The whiteboard URL can be displayed using either a `WebView` component or an `iframe` element, depending on the platform, allowing participants to interact seamlessly within the app. For detailed instructions on rendering the whiteboard, refer to this [guide](/flutter/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/render-whiteboard).


```javascript
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      //highlight-start
      ElevatedButton(
        onPressed: () {
          _room.startWhiteboard();
        },
        child: const Text("Start Whiteboard"),
      ),
      //highlight-end
    ]);
  }

  void setupRoomEventListener() {
    //highlight-start
    _room.on(Events.whiteboardStarted, (url) {
      print("Whiteboard Started. Whiteboard url: $url");
    });
    //highlight-end
  }
}
```

## `stopWhiteboard()`

- To end the whiteboard session, you can call the `stopWhiteboard()` method of the `Room` class, which terminates the active whiteboard and cleans up any resources associated with it.

### Events associated with stopWhiteboard

- All participants will receive the `Events.whiteboardStopped` event when the whiteboard session is successfully terminated. This event signals that the whiteboard is no longer available for interaction within the app.
- It can be subscribed to, using the `Room` object.


```javascript
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      //highlight-start
      ElevatedButton(
        onPressed: () {
          _room.stopWhiteboard();
        },
        child: const Text("Stop Whiteboard"),
      ),
      //highlight-end
    ]);
  }

  void setupRoomEventListener() {
    //highlight-start
    _room.on(Events.whiteboardStopped, (url) {
      print("Whiteboard Stopped");
    });
    //highlight-end
  }
}
```

## API Reference

- [startWhiteboard()](/flutter/api/sdk-reference/room-class/methods#startwhiteboard)
- [stopWhiteboard()](/flutter/api/sdk-reference/room-class/methods#stopwhiteboard)
- [whiteboardStarted](/flutter/api/sdk-reference/room-class/events#whiteboardstarted)
- [whiteboardStopped](/flutter/api/sdk-reference/room-class/events#whiteboardstopped)


---

# Concept and Architecture - Flutter

Before diving into the concept, let's understand the VideoSDK, VideoSDK is a software development kit that offers tools and APIs for creating apps that are based on video and audio. It typically includes features such as video and audio calls, chat, cloud recording, simulcasting (RTMP), interactive live streaming (HLS), and many more across a wide range of platforms and devices.

## Concepts

![img.png](../../../../static/img/room-concept.png)

### `1. Meeting / Room`

- Meeting or Room objects in the VideoSDK provide a virtual place for participants to interact and engage in real-time voice, video, and screen-sharing sessions. The object is in charge of handling media streams and participant communication.

- Meeting or Room can be uniquely identified by `meetingId` or `roomId`.

### `2. Participant`

- Participant is a VideoSDK object that represents each user/client in the meeting or room and allows them to share audio/video assets.

- `2.1 Local Participant` :
  The local participant is the one that runs on the user's device. The local participant has control over their own media streams, including the ability to start and stop audio and video.

  - The local participant in a meeting/room can also connect with other participants by transmitting and receiving audio and video streams, exchanging chat messages, and more.

- `2.2 Remote Participant` :
  The remote participant receives audio and video streams from the local participant and other remote participants and also has the ability to exchange audio, video, and chat messages with the local participant.

- Each participant in VideoSDK can be uniquely identified by `participantId`.

### `3. MediaStream & Track`

- A mediastream is a collection of audio & video tracks that can be transmitted between participants in real-time.

- A track is a continuous flow of audio or video data and can be thought of as a stream of media frames.

- A mediastream can contain multiple tracks. One video track for the video feed from the camera and one audio track for the audio feed from the microphone. These tracks can be transmitted between participants in VideoSDK Meeting / Room.

### `4. Events / Notifications`

- Events / Notifications can be used to inform users about various activities happening in a Meeting / Room, including participant join/leave and new messages. They can also be used to alert users about any SDK-level errors that occur during a call.

---

### `5. Session`

- A Session is the instance of an ongoing meeting/room which has one or more participants in it. A single room or meeting can have multiple sessions.
- Each session can be uniquely identified by `sessionId`.

![img.png](../../../../static/img/meeting-session.jpg)

---

![img.png](../../../../static/img/recording-hls-rtmp.png)

### `6. Cloud Recording`

- Cloud recording in VideoSDK refers to the process of recording audio or video content and storing it on a remote server or VideoSDK server.

### `7. Simulcasting (RTMP)`

- RTMP is a popular protocol for live streaming video content from a VideoSDK to platforms such as YouTube, Twitch, Facebook, and others.
- By providing the platform-specific `stream key` and `stream URL`, the VideoSDK can connect to the platform's RTMP server and transmit the live video stream.

### `8. Http Live Streaming (HLS)`

- Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

- In an interactive live stream (HLS), viewers can take part in a variety of activities like live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

## Architecture

This diagram demonstrates end-to-end flow to implement video & audio calls, record calls, and go live on social media.

![Video-sdk-architecture!](/img/video-sdk-archietecture.svg)


---

# Mute All Participants - Flutter

If you are the host or moderator of a video conference, you may want to mute all the participants at once. This can be useful in various scenarios, such as when you want to deliver a presentation or when there is background noise that is causing distractions.

- To achieve this, you have to iterate over the list of participants from the `Room` object and call `muteMic` method on each `Participant` object.

```javascript
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        ElevatedButton(
          child: Text("Mute all participants"),
          onPressed: () => {
            _room.participants.values.forEach((participant) {
              participant.muteMic();
            });
        }),
      ]
    );
  }
}
```

:::note
Participant who will be muting other participants should have permission **`allow_mod`** passed in the token. To know more about permissions [**visit here**](/react-native/guide/video-and-audio-calling-api-sdk/authentication-and-token).
:::

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [muteMic()](/flutter/api/sdk-reference/participant-class/methods#mutemic)


---

# Toggle Remote Participant Media - Flutter

When hosting a meeting, it's important that the host of the meeting should be able to request someone's Mic or Camera to be turned on or should be able to turn them off.

:::note
Participant who will be controlling other participant's mic and camera should have permission **`allow_mod`** passed in the token. To know more about permissions [**visit here**](/flutter/guide/video-and-audio-calling-api-sdk/authentication-and-tokens).
:::

Before we discuss the methods and events associated with this functionality, here is how the flow would look like.

![img1](/img/toggle-remote-media.png)

## Methods

### `unmuteMic()`

- If you wish to turn **on** the microphone of a participant, you will be calling the `unmuteMic()` on the `Participant` object.

- When this method is called, the participant whose microphone is requested will receive the `Events.micRequested` event with the `participantId` of the participant who requested it and two callback functions `accept` and `reject` which should be called based on decision made by the user.

- **Example:** Meeting is running with **Participant A** and **Participant B**. Now **Participant A** wants to unmute Mic of **Participant B**, so **Participant A** will use `unmuteMic()` function to request **Participant B**, after that **Participant B** recieve the `Events.micRequested` event, from there user can either accept or reject the incoming request.

### `enableCam()`

- If you wish to turn **on** the camera of a participant, you will be calling the `enableCam()` from the `useParticipant` hook.

- When this method is called, the participant whose camera is requested will receive the `Events.cameraRequested` event with the `participantId` of the participant who requested it and two callback functions `accept` and `reject` which should be called based on decision made by the user.

- **Example:** Meeting is running with **Participant A** and **Participant B**. Now **Participant A** wants to Enable Cam of **Participant B**, so **Participant A** will use `enableCam()` function to request **Participant B**, after that **Participant B** recieve the `Events.cameraRequested` event, from there user can either accept or reject the incoming request.

### `muteMic()`

- If you wish to turn **off** the microphone of a participant, you will be calling the `muteMic()` on the `Participant` object.
- This will disable the microphone of the participant.

### `disableCam()`

- If you wish to turn **off** the camera of a participant, you will be calling the `disableCam()` on the `Participant` object.
- This will disable the camera of the participant.

#### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;
  const ParticipantTile({super.key, required this.participant});

  @override
  State

</div>

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [unmuteMic()](/flutter/api/sdk-reference/participant-class/methods#unmutemic)
- [muteMic()](/flutter/api/sdk-reference/participant-class/methods#mutemic)
- [enableCam()](/flutter/api/sdk-reference/participant-class/methods#enablecam)
- [disableCam()](/flutter/api/sdk-reference/participant-class/methods#disablecam)
- [Events.cameraRequested](/flutter/api/sdk-reference/room-class/events#camerarequested)
- [Events.micRequested](/flutter/api/sdk-reference/room-class/events#micrequested)


---

# Remove Participant - Flutter

This feature in a meeting allows the meeting host or organizer to remove a participant from the meeting. This can be helpful in situations where a participant is causing a disturbance, is behaving inappropriately, or is not following meeting guidelines.

VideoSDK provide three ways to remove participant from meeting.

1. [Using SDK](#1-using-sdk)
2. [Using VideoSDK Dashboard](#2-using-videosdk-dashboard)
3. [Using Rest API](#3-using-rest-api)

## 1. Using SDK

### `remove()`

Remove participant allows removing participant while session is on-going. This can be helpful when moderation in particular meeting is required.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;
  const ParticipantTile({super.key, required this.participant});

  @override
  State

</div>

## 3. Using Rest API

- You can also remove the particular participant from the meeting [using the REST API](/api-reference/realtime-communication/remove-participant).
- To use this method, you should have the `sessionId` of the meeting and `participantId` of the participant who is supposed to be removed.

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [remove()](/flutter/api/sdk-reference/participant-class/methods#remove)
- [Events.roomLeft](/flutter/api/sdk-reference/room-class/events#roomleft)
- [Events.participantLeft](/flutter/api/sdk-reference/room-class/events#participantleft)


---

# Share screen - Flutter iOS

iOS requires you to add an Broadcast Upload Extension to capture the screen to the device.

:::note

Flutter iOS screenshare is available from the SDK version 1.0.5 and above and the deployment target for iOS app should be **iOS 14 or newer**
:::

## Create Broadcast Upload Extension in iOS

### Step 1 : Open Target

Open your project with xcode, select **File > New > Target** in menu bar.

![IOS Screen Share](/img/ios-screenshare/step1-xcode.png)

### Step 2 : Select Target

Choose **Broadcast Upload Extension**, and click next.

![IOS Screen Share](/img/ios-screenshare/step2-xcode.png)

### Step 3 : Configure Broadcast Upload Extension

Enter extensions name in **Product Name** field, choose team from dropdown, Uncheck include UI extension field and click finish.

![IOS Screen Share](/img/ios-screenshare/step3-xcode.png)

### Step 4 : Activate Extension scheme

You will be prompted **Activate "Your-Extension-name" scheme?** pop-up, click activate.

![IOS Screen Share](/img/ios-screenshare/step4-xcode.png)

Now, broadcast folder will appear in xcode left side bar.

![IOS Screen Share](/img/ios-screenshare/step5-xcode.png)

### Step 5 : Add External file in Created Extension

Open [videosdk-rtc-flutter-sdk-example](https://github.com/videosdk-live/videosdk-rtc-flutter-sdk-example/tree/main/ios/FlutterBroadcast), Copy `SampleUploader.swift`, `SocketConnection.swift`, `DarwinNotificationCenter.swift`, and `Atomic.swift` files to your extension's folder and make sure they're added to the target.

### Step 6 : Update `SampleHandler.swift` file

Open [SampleHandler.swift](https://github.com/videosdk-live/videosdk-rtc-flutter-sdk-example/blob/main/ios/FlutterBroadcast/SampleHandler.swift) and Copy `SampleHandler.swift` file content and paste it to your extensions `SampleHandler.swift` file.

### Step 7 : Add Capability in App

In Xcode, go to **YourappName > Signing & Capabilities**. and click on **+Capability** to configure app group.

![IOS Screen Share](/img/ios-screenshare/step8-xcode.png)

Select **App Groups** from list

![IOS Screen Share](/img/ios-screenshare/step9-xcode.png)

After that, you have to select or add generated app group id which you have created before.

![IOS Screen Share](/img/ios-screenshare/step10-xcode.png)

### Step 8 : Add Capability in Extension

Go to **Your-Extension-Name > Signing & Capabilities** and configure **App Group** functionality which we had perform in previous steps. (Group id should be same for both targets)

![IOS Screen Share](/img/ios-screenshare/step11-xcode.png)

### Step 9 : Add App Group Id in Extension File

Go to extensions `SampleHandler.swift` file and paste your group Id in `appGroupIdentifier` constant.

![IOS Screen Share](/img/ios-screenshare/step12-xcode.png)

### Step 10 : Update App level info.plist file

1.  Add a new key **RTCScreenSharingExtension** in Info.plist with the extension's Bundle Identifier as the value.
2.  Add a new key **RTCAppGroupIdentifier** in Info.plist with the extension's App groups Id as the value.

**Note** : For extension's Bundle Identifier, go to **TARGETS > Your-Extension-Name > Signing & Capabilities** .

![IOS Screen Share](/img/ios-screenshare/step13-xcode.png)

:::note

You can also check out extension [example code](https://github.com/videosdk-live/videosdk-rtc-flutter-sdk-example/tree/main/ios/FlutterBroadcast) on github
:::

## Enable Screen Share

- In order to start screen-sharing just call `room.enableScreenShare()` method.

```js
ElevatedButton(
    child: Text("Start ScreenSharing"),
    onPressed: () {
        room.enableScreenShare();
    },
),
```

![IOS Screen Share](/img/ios-screenshare/step23-xcode.png)

After clicking **Start Broadcast** button, we wiil be able to get the screen stream in session.

## Disable Screen Share

By using `room.disableScreenShare()` function, a participant can stop publishing screen stream to other participants.

```js
ElevatedButton(
    child: Text("Stop ScreenSharing"),
    onPressed: () {
        room.disableScreenShare();
    },
),
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Camera Controls - Flutter

Whenever any participant wants to start/stop broadcasting their video to other participant in a room, they can simply do it with VideoSDK Room.

This guide will provide an overview of how to implement enable, disable and switch camera features in a room.

1. **Enable Camera** - By using `enableCam()` function, a participant can publish camera stream to other participants.
2. **Disable Camera** - By using `disableCam()` function, a participant can stop publishing camera stream to other participants.
3. **Switch Camera** - By using `changeCam()` function, a participant can stream from front / rear camera during the room.This function is only applicable for Mobile devices.

### Enable, Disable And Switch Camera

```js
ElevatedButton(
  onPressed: room.disableCam,
  child: Text("disable camera"),
),
ElevatedButton(
  onPressed: room.enableCam,
  child: Text("enable camera"),
),
ElevatedButton(
  onPressed:  () {
    room.changeCam("<device>")
  },
  child: Text("changeCam"),
),
```

### Events

**Events associated with `enableWebcam()`:**

- [`streamEnabled`](../../../api/sdk-reference/participant-class/events.md#streamenabled) event will be emitted with [`stream`](../../../api/sdk-reference/stream-class/introduction.md) object from the event callback, inside that [participant](../../../api/sdk-reference/participant-class/introduction.md) object.

**Events associated with `disableWebcam()`:**

- [`streamDisabled`](../../../api/sdk-reference/participant-class/events.md#streamdisabled) event will be emitted with [`stream`](../../../api/sdk-reference/stream-class/introduction.md) object from the event callback, inside that [participant](../../../api/sdk-reference/participant-class/introduction.md) object.

```js
participant.on(Events.streamEnabled, (Stream stream){
  if (stream.kind === "video") {
    //particiapnt turned on video
    //Render Participant video logic here
  }
});
participant.on(Events.streamDisabled, (Stream stream){
  if (stream.kind === "video") {
    //particiapnt turned off video
    //remove Participant video logic here
  }
});
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Custom Participant ID - Flutter

- Whenever any participant joins room, it is assigned a new unique participant id every time.

- To assign an unique participant id manually to local participant, specify participant id while creating Room using `createRoom()` method.

```js
createRoom(
    .
    .
    participantId: "abcd-efgh-ijkl", // custom participant id
),
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Custom Audio Track - Flutter

We have introduced the ability to pass a custom Audio track for the Audio of the participants. This feature can be used to add custom layers like background noise removal, echo cancellation, etc. on audio and send it to other participants.

## Creating a Custom Audio Track

- You can create a Audio Track using `createMicrophoneAudioTrack()` method of `VideoSDK` class.
- This method can be used to create audio track using different encoding parameters and noise cancellation configuration.

### Parameters

- **microphoneId**:

  - type: `String`
  - required: `false`
  - It will be the id of the mic from which the audio should be captured.

- **encoderConfig**:

  - type: `CustomTrackAudioConfig`
  - required: `false`
  - default: `speech_standard`
  - Allowed values : `speech_low_quality` | `speech_standard` | `music_standard` | `standard_stereo` | `high_quality` | `high_quality_stereo`
  - It will be the encoder configuration you want to use for Audio Track.

- **noiseConfig**

  - **echoCancellation**

    - type: `boolean`
    - required: `false`
    - If `true` echo cancellation will turned on else it would be turned off.

  - **autoGainControl**

    - type: `boolean`
    - required: `false`
    - If `true` auto gain will turned on else it would be turned off.

  - **noiseSuppression**
    - type: `boolean`
    - required: `false`
    - If `true` noise suppression will turned on else it would be turned off.

#### Returns

- `Future<CustomTrack?>`

### Example

```javascript
CustomTrack? audioTrack = await VideoSDK.createMicrophoneAudioTrack(
        encoderConfig: CustomAudioTrackConfig.high_quality);
```

## Using Custom Audio Track

### Custom Track while initializing the meeting

If you are passing `micEnabled: true` in the `createRoom` and want to use custom tracks from start of the meeting, you can pass custom track in the `createRoom` as shown below.

```javascript
CustomTrack? audioTrack = await VideoSDK.createMicrophoneAudioTrack(
        encoderConfig: CustomAudioTrackConfig.high_quality);

Room room = VideoSDK.createRoom(
      roomId: widget.meetingId,
      token: widget.token,
      displayName: widget.displayName,
      micEnabled: widget.micEnabled,
      camEnabled: widget.camEnabled,
      maxResolution: 'hd',
      defaultCameraIndex: 1,
      multiStream: false,

      // Pass the custom track here
      customMicrophoneAudioTrack: audioTrack, // custom audio track :: optional
      notification: const NotificationInfo(
        title: "Video SDK",
        message: "Video SDK is sharing screen in the meeting",
        icon: "notification_share", // drawable icon name
      ),
    );
```

### Custom Track with `unmuteMic()`

In order to switch tracks during the meeting, you have to pass the `CustomTrack` in the `room.unmuteMic()` method.

:::note

Make sure to call `muteMic()` before you create a new track as it may lead to unexpected behavior.

:::

```javascript
CustomTrack? audioTrack = await VideoSDK.createMicrophoneAudioTrack(
        encoderConfig: CustomAudioTrackConfig.high_quality);

room.unmuteMic(customTrack);
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Custom Video Track - Flutter

We have introduced the ability to pass a custom video track for the video of the participants. This feature can be used to add custom video encoder config, and background removal & video filter from external SDK(e.g., [Banuba](https://www.banuba.com/)) and send it to other participants.

## Creating a Custom Video Track

- You can create a Video Track using `createCameraVideoTrack()` method of `VideoSDK` class.
- This method can be used to create video track using different encoding parameters, camera facing mode, and optimization mode.

### Parameters

- **cameraId**:

  - type: `String`
  - required: `false`
  - It will be the id of the camera from which the video should be captured.

- **encoderConfig**:

  - type: `CustomVideoTrackConfig`
  - required: `false`
  - default: `h360p_w640p`
  - Allowed values : `h90p_w160p` | `h180p_w320p` | `h216p_w384p` | `h360p_w640p` | `h540p_w960p` | `h720p_w1280p` | `h1080p_w1920p` | `h1440p_w2560p` | `h2160p_w3840p` | `h120p_w160p` | `h180p_w240p` | `h240p_w320p` | `h360p_w480p` | `h480p_w640p` | `h540p_w720p` | `h720p_w960p` | `h1080p_w1440p` | `h1440p_w1920p`
  - It will be the encoderConfigs you can want to use for the Video Track.

:::note

Above mentioned encoder configurations are valid for both, landscape as well as portrait mode.

:::

- **facingMode**:

  - type: `FacingMode`
  - required: `false`
  - Allowed values : `FacingMode.front` | `FacingMode.environment`
  - It will specify whether to use front or back camera for the video track.

- **multiStream**

  - type: `boolean`
  - required: `false`
  - default: true
  - It will specify if the stream should send multiple resolution layers or single resolution layer.

  :::info

  - For meetings with fewer than or equal to four participants, setting `multiStream:false` is regarded as best practice.
  - This parameter is only available from `v1.0.9`.

  :::

#### Returns

- `Future<CustomTrack?>`

### Example

```javascript
CustomTrack? videoTrack = await VideoSDK.createCameraVideoTrack(
      encoderConfig: CustomVideoTrackConfig.h1440p_w1920p,
      multiStream: false,
      facingMode:"user",
    );
```

## Using Custom Video Track

### Custom Track while initializing the meeting

If you are passing `webcamEnabled: true` in the `createRoom` and want to use custom tracks from start of the meeting, you can pass custom track in the `createRoom` params as shown below.

```javascript
CustomTrack? videoTrack = await VideoSDK.createCameraVideoTrack(
      encoderConfig: CustomVideoTrackConfig.h1440p_w1920p,
      multiStream: false,
      facingMode:"user",
    );

Room room = VideoSDK.createRoom(
      roomId: widget.meetingId,
      token: widget.token,
      displayName: widget.displayName,
      micEnabled: widget.micEnabled,
      camEnabled: widget.camEnabled,
      maxResolution: 'hd',
      defaultCameraIndex: 1,
      multiStream: false,

      // Pass the custom track here
      customCameraVideoTrack: videoTrack, // custom video track :: optional
      notification: const NotificationInfo(
        title: "Video SDK",
        message: "Video SDK is sharing screen in the meeting",
        icon: "notification_share", // drawable icon name
      ),
    );
```

### Custom Track with `enableCam()`

In order to switch tracks during the meeting, you have to pass the `CustomTrack` in the `room.enableCam()` method.

:::note

Make sure to call `disableCam()` before you create a new track as it may lead to unexpected behavior.

:::

```javascript
CustomTrack? track = await VideoSDK.createCameraVideoTrack(
  facingMode: "environment",
  encoderConfig: CustomVideoTrackConfig.h1440p_w1920p,
  multiStream: true,
);
room.enableCam(track);
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Entry Request-Response - Flutter

- When anyone joins room, he/she will request for joining room and that request will get either accepted or denied by host.

## Entry Request

- When anyone asks for joining in your room, `Events.entryRequested` event is triggered with data having

  - `participantId` - This is the Id of participant, who have requested for joining room
  - `name` - This is the name of the participant.
  - `allow()` - Call this method if you want to allow that participant
  - `deny()` - Call this method if you want to deny that participant

```js
room.on(Events.entryRequested, (data) {
  var participantId = data['participantId'];
  var name = data["name"];
  var allow = data["allow"];
  var deny = data["deny"];

  showDialog(
    context: context,
    builder: (context) => AlertDialog(
      title: const Text("Join Request"),
      content: Text("Do you want to allow $name to join room?"),
      actions: [
        TextButton(
          child: const Text("Deny"),
          onPressed: () {
            deny();
            Navigator.of(context).pop();
          },
        ),
        TextButton(
          child: const Text("Allow"),
          onPressed: () {
            allow();
            Navigator.of(context).pop();
          },
        ),
      ],
    ),
  );
});
```

## Entry Respond

- If you have requested for joining room, `Events.entryResponded` is triggered when host accept or deny room.

  - `decision` - This will tell you, if you are allowed to join or not

```js
room.on(Events.entryResponded, (data) {
  var decision = data['decision'];
  if (id == room.localParticipant.id) {
    if (decision == 'allowed') {
      print("Allowed to join the room.");
    } else {
      print("Denied to join the room.");
    }
  }
});
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Error Event - Flutter

This event is helpful for development level troubleshooting while integrating SDK.

Whenever any invalid configuration provided or server/network errors arise, this event will trigger with a specific error code and message.

This event can ease your development process.

We have depicted a specific error name with code and message in the below table.

| Error Name                            | Code | Message                                                                                                                     |
| ------------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------- |
| **INVALID_API_KEY**                   | 4001 | `apikey` provided in the token is empty or invalid, please verify it on the dashboard.                                      |
| **INVALID_TOKEN**                     | 4002 | `token` is empty or invalid or might have expired.                                                                          |
| **INVALID_MEETING_ID**                | 4003 | `meetingId` is empty or invalid, please verify it or generate new meetingId using the API.                                  |
| **INVALID_PARTICIPANT_ID**            | 4004 | `participantId` is empty or invalid, it shouldn't contain any whitespaces.                                                  |
| **DUPLICATE_PARTICIPANT**             | 4005 | Leaving meeting, since this `participantId` joined from another device.                                                     |
| **ACCOUNT_DEACTIVATED**               | 4006 | It seems your account is deactivated by VideoSDK for some reason, you can reach out to us at `support@videosdk.live`.       |
| **ACCOUNT_DISCONTINUED**              | 4007 | _Server will respond you with specific message._                                                                            |
| **INVALID_PERMISSIONS**               | 4008 | `permissions` provided in the token are invalid, please don't use `allow_join` or `allow_mod` with `ask_join`.              |
| **MAX_PARTICIPANT_REACHED**           | 4009 | You have reached max participant limit in a meeting to increase contact at support@videosdk.live :)                          |
| **MAX_PARTICIPANT_REACHED**            | 4009 | You have reached max participant limit in a meeting.                                                                         |
| **MAX_SPEAKER_REACHED**               | 4010 | You have reached max speaker limit in a meeting.                                                                            |
| **START_RECORDING_FAILED**            | 4011 | Recording start request failed due to an unknown error.                                                                     |
| **STOP_RECORDING_FAILED**             | 4012 | Recording stop request failed due to an unknown error.                                                                      |
| **START_LIVESTREAM_FAILED**           | 4013 | Livestream start request failed due to an unknown error.                                                                    |
| **STOP_LIVESTREAM_FAILED**            | 4014 | Livestream stop request failed due to an unknown error.                                                                     |
| **INVALID_LIVESTREAM_CONFIG**         | 4015 | Livestream 'outputs' configuration provided was invalid.                                                                    |
| **START_HLS_FAILED**                  | 4016 | HLS start request failed due to an unknown error.                                                                           |
| **STOP_HLS_FAILED**                   | 4017 | HLS stop request failed due to an unknown error.                                                                            |
| **PREV_RECORDING_PROCESSING**         | 4018 | Previous recording session is being processed, please try again after few seconds!                                          |
| **PREV_RTMP_RECORDING_PROCESSING**    | 4019 | Previous RTMP recording session is being processed, please try again after few seconds!                                     |
| **PREV_HLS_STREAMING_PROCESSING**     | 4020 | Previous HLS streaming session is being processed, please try again after few seconds!                                      |
| **MAX_SPEAKER_LIMIT_REACHED_ON_ORGANIZATION**    | 4026 | You have reached max speaker limit on organization. To increase contact at support@videosdk.live".                                                               |
| **MAX_VIEWER_LIMIT_REACHED_ON_ORGANIZATION**    | 4027 | You have reached max viewer limit on organization. To increase contact at support@videosdk.live".                                                               |
| **MAX_RECORDING_LIMIT_REACHED_ON_ORGANIZATION**    | 4028 | You have reached max limit of recording on organization. To increase contact at support@videosdk.live.                                                               |
| **MAX_HLS_LIMIT_REACHED_ON_ORGANIZATION**    | 4029 | You have reached max limit of hls on organization. To increase contact at support@videosdk.live.                                                               |
| **MAX_LIVESTREAM_LIMIT_REACHED_ON_ORGANIZATION**    | 4030 | You have reached max limit of livestream on organization. To increase contact at support@videosdk.live.                                                               |
| **RECORDING_FAILED**                  | 5001 | Recording stopped due to an unknown error.                                                                                  |
| **LIVESTREAM_FAILED**                 | 5002 | Livestream stopped due to an unknown error.                                                                                 |
| **HLS_FAILED**                        | 5003 | HLS stopped due to an unknown error.                                                                                        |
| **RECORDING_DURATION_LIMIT_REACHED**  | 5004 | Recording has been automatically stopped by the system, due to max duration limit of 2 hours reached for a single Recording |
| **LIVESTREAM_DURATION_LIMIT_REACHED** | 5005 | Livestream has been automatically stopped by the system, due to max duration limit of 2 hours reached for a single RTMP     |
| **HLS_DURATION_LIMIT_REACHED**        | 5006 | Hls has been automatically stopped by the system, due to max duration limit of 2 hours reached for a single HLS             |
| **ERROR_STARTING_VIDEO**              | 3011 | Some error occured during starting the video                                                                                |
| **ERROR_STARTING_AUDIO**              | 3012 | Some error occured during starting the audio.                                                                               |
| **ERROR_STARTING_SCREENSHARE**        | 3013 | Some error occured during starting the screen share.                                                                        |

### Event Code

You can get all the error codes from `VideoSDKErrors` which is a `Map<int, Map<String, String>>` containing all the errors.

```js

//add listener for the error events.
_meeting.on(Events.error, (error) {
  log("VIDEOSDK ERROR :: " +
      error['code'].toString() +
      "  :: " +
      error['name'].toString() +
      " :: " +
      error['message'].toString());
});
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Go Live On Social Media - Flutter

This feature allows participant to broadcast room on various social media platforms such as Facebook or Youtube.
This guide will provide an overview of how participant can start and stop broadcasting room.

1. **Start LiveStream** - By using `startLivestream()` function, a participant can start broadcasting room on various platforms by provding url and stream keys as an argument.

### Parameters

- **outputs**

  - type: `Array`
  - required: `true`
  - It will the array of object containing the url and stream keys.

- **config**:
  - type: `Object`
    - **config**:
      - **layout**:
        - **type**: _"GRID"_ | _"SPOTLIGHT"_ | _"SIDEBAR"_
        - **priority**: _"SPEAKER"_ | _"PIN"_
        - **gridSize**: Number _\`max 4\`_
      - **theme**: _"DARK"_ | _"LIGHT"_ | _"DEFAULT"_
  - required: `false`
  - It will be config for the layout of the recording you can to use.

2. **Stop LiveStream** - By using `stopLivestream()` function, a participant can stop broadcasting on all platforms.

### Start And Stop Live Stream

```js
// Start Live Stream
room.startLivestream([
  {
    url: "rtmp://a.rtmp.youtube.com/live2",
    streamKey: "streamKey1",
  },
], config: {
  'layout': {
    'type': 'GRID',
    'priority': 'SPEAKER',
    'gridSize': 4,
  },
  'theme': "LIGHT",
});

// Stop Live Stream
room?.stopLivestream();
```

### Events

1. **livestreamStateChanged** - Whenever broadcasting of meeting started / stopped, `livestreamStateChanged` event will trigger.

```js
room.on(Events.liveStreamStateChanged, (String status) {

  //Status can have values:
  // LIVESTREAM_STARTING -- Live Stream is starting
  // LIVESTREAM_STARTED -- Live Stream has started
  // LIVESTREAM_STOPPING -- Live Stream is stopping
  // LIVESTREAM_STOPPED -- Live Stream has stopped

  toastMsg("Meeting live streaming status : $status");
});
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Leave or End Meeting - Flutter

Whenever participant wishes to end their communication in the meeting, they can simply leave the meeting.

This guide will provide an overview of how to implement leave or end feature in VideoSDK meetings.

1. **Leave** - By using `leave()` function, only a participant will leave/exit the meeting, the rest of the meeting will continue with other participants.
2. **End** - By using `end()` function, meeting will end for each and every participant. So, use this function according to your use cases.

### Leave And End Meeting

```js
// Leave the meeting
meeting.leave();

// end() method is coming soon in flutter.
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Leave or End Room - Flutter

Whenever participant wishes to end their communication in the room, they can simply leave the room.

This guide will provide an overview of how to implement leave or end feature in VideoSDK rooms.

1. **Leave** - By using `leave()` function, only a participant will leave/exit the room, the rest of the room will continue with other participants.
2. **End** - By using `end()` function, room will end for each and every participant. So, use this function according to your use cases.

### Leave And End Room

```js
// Leave the room
room.leave();

// End Room Session
room.end();
```

### Events

**Events associated with `leave()`:**

- Local participant will receive a [`roomLeft`](../../../api/sdk-reference/room-class/events.md#roomleft) event.
- All remote participants will receive a [`participantLeft`](../../../api/sdk-reference/room-class/events.md#participantleft) event with `participantId`.

**Event associated with `end()`:**

- All [participants](../../../api/sdk-reference/participant-class/introduction.md) and [localParticipant](../../../api/sdk-reference/participant-class/introduction.md), will be emitted with [`roomLeft`](../../../api/sdk-reference/room-class/events.md#roomleft) event.

```js
room.on(Events.roomLeft, () => {
  //room Left
});

room.on(Events.participantLeft, (participant, Map<String,dynamic> reason) => {
  //Participant Left the room
});
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Manage Participants - Flutter

## 1. Local Participant (self)

Local participant is used to consume your video & audio streams.
it contains information about local participant such as displayName, id, quality and streams Map.

You can access localParticipant from the [room object](./start-join-room#2-initialization).

### Participant object properties

| Property Name | Type          | Description                                         |
| ------------- | ------------- | --------------------------------------------------- |
| id            | string        | Unique id of the participant.                       |
| displayName   | string        | The name you define during the room initialization. |
| local         | boolean       | Indicates the participant is local or not.          |
| quality       | string        | Indicates the participant streams quality.          |
| Streams       | Map of Stream | Returns Video & Audio Streams.                      |

### Stream Object properties

| Property Name | Type   | Description        |
| ------------- | ------ | ------------------ |
| id            | string | Unique id          |
| codec         | string | Video/Audio codec. |
| kind          | string | Stream Kind.       |
| track         | string | MediaStreamTrack   |

## 2. Other Participants (Except You)

Other participants Map is used to get all the participants (except you) in the room at any given time.

Other participants Map contains same properties as [LocalParticipant](/flutter/guide/video-and-audio-calling-api-sdk/features/manage-participants#participant-object-properties).

### ParticipantTile

```js title=participant_tile.dart
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
import '../../utils/toast.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;
  final bool isLocalParticipant;
  const ParticipantTile({
    Key? key,
    required this.participant,
    this.isLocalParticipant = false,
    }): super(key: key);

  @override
  State<ParticipantTile> createState() => _ParticipantTileState();
}

class _ParticipantTileState extends State<ParticipantTile> {
  Stream? shareStream;
  Stream? videoStream;
  Stream? audioStream;
  String? quality;

  @override
  void initState() {
    _initStreamListeners();
    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return Container(
        margin: const EdgeInsets.all(4.0),
        decoration: BoxDecoration(
          color: Theme.of(context).backgroundColor.withOpacity(1),
          border: Border.all(color: Colors.white38),
        ),
        child: AspectRatio(
          aspectRatio: 1,
          child: Padding(
            padding: const EdgeInsets.all(4.0),
            child: Stack(
              children: [
                videoStream != null
                    ? RTCVideoView(
                        videoStream?.renderer as RTCVideoRenderer,
                        objectFit:
                            RTCVideoViewObjectFit.RTCVideoViewObjectFitCover,
                      )
                    : const Center(
                        child: Icon(
                          Icons.person,
                          size: 180.0,
                          color: Color.fromARGB(140, 255, 255, 255),
                        ),
                      ),
                Positioned(
                  bottom: 0,
                  left: 0,
                  child: FittedBox(
                    fit: BoxFit.scaleDown,
                    child: Container(
                      padding: const EdgeInsets.all(2.0),
                      decoration: BoxDecoration(
                        color: Theme.of(context).backgroundColor.withOpacity(0.2),
                        border: Border.all(color: Colors.white24),
                        borderRadius: BorderRadius.circular(4.0),
                      ),
                      child: Text(
                        widget.participant.displayName,
                        textAlign: TextAlign.center,
                        style: const TextStyle(
                          color: Colors.white,
                          fontSize: 10.0,
                        ),
                      ),
                    ),
                  ),
                ),
                Positioned(
                  top: 0,
                  left: 0,
                  child: InkWell(
                    child: Container(
                      padding: const EdgeInsets.all(4),
                      decoration: BoxDecoration(
                        shape: BoxShape.circle,
                        color: audioStream != null
                            ? Theme.of(context).backgroundColor
                            : Colors.red,
                      ),
                      child: Icon(
                        audioStream != null ? Icons.mic : Icons.mic_off,
                        size: 16,
                      ),
                    ),
                    onTap: widget.isLocalParticipant
                        ? null
                        : () => audioStream != null
                              ? widget.participant.unmuteMic()
                              : widget.participant.muteMic(),
                  ),
                ),
                Positioned(
                  top: 0,
                  right: 0,
                  child: InkWell(
                    child: Container(
                      padding: const EdgeInsets.all(4),
                      decoration: BoxDecoration(
                        shape: BoxShape.circle,
                        color: videoStream != null
                            ? Theme.of(context).backgroundColor
                            : Colors.red,
                      ),
                      child: Icon(
                        videoStream != null
                            ? Icons.videocam
                            : Icons.videocam_off,
                        size: 16,
                      ),
                    ),
                    onTap: widget.isLocalParticipant
                        ? null
                        : () => videoStream != null
                                  ? widget.participant.disableCam()
                                  : widget.participant.enableCam(),
                  ),
                ),
                if (!widget.isLocalParticipant)
                  Positioned(
                    bottom: 0,
                    right: 0,
                    child: InkWell(
                      child: Container(
                        padding: const EdgeInsets.all(4),
                        decoration: const BoxDecoration(
                          shape: BoxShape.circle,
                          color: Colors.red,
                        ),
                        child: const Icon(
                          Icons.logout,
                          size: 16,
                        ),
                      ),
                      onTap: () {
                        showDialog(
                            context: context,
                            builder: (context) => AlertDialog(
                                  title: const Text("Are you sure ?"),
                                  actions: [
                                    TextButton(
                                      child: const Text("Yes"),
                                      onPressed: () {
                                        widget.participant.remove();
                                        toastMsg("Participant removed");
                                        Navigator.of(context).pop();
                                      },
                                    ),
                                    TextButton(
                                      child: const Text("No"),
                                      onPressed: () => Navigator.of(context).pop(),
                                    )
                                  ],
                                ));
                      },
                    ),
                  ),
              ],
            ),
          ),
        ),
    );
  }

  _initStreamListeners() {
    widget.participant.on(Events.streamEnabled, (Stream _stream) {
      setState(() {
        if (_stream.kind == 'video') {
          videoStream = _stream;
        } else if (_stream.kind == 'audio') {
          audioStream = _stream;
        } else if (_stream.kind == 'share') {
          shareStream = _stream;
        }
      });
    });

    widget.participant.on(Events.streamDisabled, (Stream _stream) {
      setState(() {
        if (_stream.kind == 'video' && videoStream?.id == _stream.id) {
          videoStream = null;
        } else if (_stream.kind == 'audio' && audioStream?.id == _stream.id) {
          audioStream = null;
        } else if (_stream.kind == 'share' && shareStream?.id == _stream.id) {
          shareStream = null;
        }
      });
    });
  }
}
```

```js title=participant_grid_view.dart
import 'dart:developer';
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
import 'participant_tile.dart';

class ParticipantGridView extends StatefulWidget {
  final Room room;
  const ParticipantGridView({
    Key? key,
    required this.room,
  }) : super(key: key);

  @override
  State<ParticipantGridView> createState() => _ParticipantGridViewState();
}

class _ParticipantGridViewState extends State<ParticipantGridView> {
  String? activeSpeakerId;
  Participant? localParticipant;
  Map<String, Participant> participants = {};

  @override
  void initState() {
    // Initialize participants
    localParticipant = widget.room.localParticipant;
    participants = widget.room.participants;

    // Setting room event listeners
    setRoomListeners(widget.room);
    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return GridView.count(
      crossAxisCount: 2,
      children: [
        ParticipantTile(
          participant: localParticipant!,
          isLocalParticipant: true,
        ),
        ...participants.values
            .map((participant) => ParticipantTile(participant: participant))
            .toList()
      ],
    );
  }

  void setRoomListeners(Room _room_) {
    // Called when participant joined room
    _room.on(
      Events.participantJoined,
      (Participant participant) {
        final newParticipants = participants;
        newParticipants[participant.id] = participant;
        setState(() {
          participants = newParticipants;
        });
      },
    );

    // Called when participant left room
    _room.on(
      Events.participantLeft,
      (String participantId, Map<String, dynamic> reason) {
        final newParticipants = participants;

        newParticipants.remove(participantId);
        setState(() {
          participants = newParticipants;
        });
      },
    );

    // Called when speaker is changed
    _room.on(Events.speakerChanged, (_activeSpeakerId) {
      setState(() {
        activeSpeakerId = _activeSpeakerId;
      });
    });
  }
}
```

## 3. Participant Related Events

1. **participantJoined** - Whenever any new participant join the room, `participantJoined` event will trigger. For example, the room is running with **Alice** and **Bob**, then **Eve** join that room, after that `participantJoined` event trigger and return the [participant object](/flutter/guide/video-and-audio-calling-api-sdk/features/manage-participants#participant-object-properties).

2. **participantLeft** - Whenever any participant leave/exit the room, `participantLeft` event will trigger.For example, the room is running with **Alice** and **Bob**, then **Bob** leave that room, after that `participantLeft` event trigger and return the [participant object](/flutter/guide/video-and-audio-calling-api-sdk/features/manage-participants#participant-object-properties)

3. **speakerChanged** - Whenever any participant starts actively speaking in room, `speakerChanged` event will trigger and return the speaker `participantId`.

4. **presenterChanged** - Whenever any participant present/screenshare their screen/window in room, `presenterChanged` event will trigger and return the presenter `participantId`.

5. **streamEnabled** - Whenever any participant enabled mic/camera in room, `streamEnabled` event will trigger and return `Stream`.

6. **streamDisabled** - Whenever any participant disabled mic/camera in room, `streamDisabled` event will trigger and return `Stream`.

```js
// Adding event listner
room.on(Events.participantJoined, (Participant participant) {
  print("new participant => $participant");
  },
);

room.on(Events.participantLeft, (String participantId, Map<String, dynamic> reason) {
  print("new participant => $participantId");
  },
);

room.on(Events.presenterChanged, (activePresenterId) {
  print("presenter changed => $activePresenterId");
  },
);
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Mic Controls - Flutter

Whenever any participant wants to start / stop broadcasting their audio to other participant in room, they can simply do it with VideoSDK room.

This guide will provide an overview of how to use enable and disable Mic in a room.

1. **Enable Mic** - By using `unmuteMic()` function, a participant can publish audio to other participants.
2. **Disable Mic** - By using `muteMic()` function, a participant can stop publishing audio to other participants.
3. **Change Mic** - By using `changeMic()` function, a participant can change mic.

### Enable, Disable, Change Mic

```js
ElevatedButton(
  onPressed: room.unmuteMic,
  child: Text("unmuteMic"),
),
ElevatedButton(
  onPressed: room.muteMic,
  child: Text("muteMic"),
),

// changeMic() method is coming soon in flutter.
```

### Events

**Events associated with `unmuteMic()`:**

- [`streamEnabled`](../../../api/sdk-reference/participant-class/events.md#streamenabled) event will be emitted with [`stream`](../../../api/sdk-reference/stream-class/introduction.md) object from the event callback, inside that [participant](../../../api/sdk-reference/participant-class/introduction.md) object.

**Events associated with `muteMic()`:**

- [`streamDisabled`](../../../api/sdk-reference/participant-class/events.md#streamdisabled) event will be emitted with [`stream`](../../../api/sdk-reference/stream-class/introduction.md) object from the event callback, inside that [participant](../../../api/sdk-reference/participant-class/introduction.md) object.

```js
participant.on(Events.streamEnabled, (Stream stream){
  if (stream.kind === "audio") {
    //particiapnt turned on audio
  }
});
participant.on(Events.streamDisabled, (Stream stream){
  if (stream.kind === "audio") {
    //particiapnt turned off audio
  }
});
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Participant Video Stream - Flutter

- Using this feature, you can pause/resume participant's video stream.

## Pause video stream

- `pause()` method is used to pause videostream of a participant.

```js
ElevatedButton(
  child: Text("Pause Video"),
  onPressed: () {
    List<Stream> streams = participant.streams.where((e) => e.kind == 'video').toList();

    if(streams.length != 0){
      Stream videoStream = streams[0];
      videoStream.track.pause();
    }
  }
),
```

## Resume video stream

- `resume()` method is used to resume videostream of a participant.

```js
ElevatedButton(
  child: Text("Resume Video"),
  onPressed: () {
    List<Stream> streams = participant.streams.where((e) => e.kind == 'video').toList();

    if(streams.length != 0){
      Stream videoStream = streams[0];
      videoStream.track.resume();
    }
  }
),

```

## Events

**Event associated with `pause()`:**

- [`streamPaused`](../../../api/sdk-reference/participant-class/events.md#streampaused) event will be emitted with [`stream`](../../../api/sdk-reference/stream-class/introduction.md) object from the event callback, inside that [participant](../../../api/sdk-reference/participant-class/introduction.md) object.

**Event associated with `resume()`:**

- [`streamResumed`](../../../api/sdk-reference/participant-class/events.md#streamresumed) event will be emitted with [`stream`](../../../api/sdk-reference/stream-class/introduction.md) object from the event callback, inside that [participant](../../../api/sdk-reference/participant-class/introduction.md) object.

```js
participant.on(Events.streamPaused, (Stream stream){
  if (stream.kind === "video") {
    //particiapnt video stream paused
  }
});
participant.on(Events.streamResumed, (Stream stream){
  if (stream.kind === "video") {
    //particiapnt video stream resumed
  }
});
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# PubSub - Flutter

PubSub feature allows the participant to send and receive messages of the topics which he has subscribed.

## Methods

### publish()

This method is use for publishing message of specific topic.

#### Syntax

```js
  Future<void> publish(
    String topic,
    String message,
    [PubSubPublishOptions options]
  )
```

| Parameter Name | Type                 | Description                                                                                                                                       |
| -------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| topic          | String               | This should be the topic for which you are publishing a message.                                                                                  |
| message        | String               | This is the actual message, which will be published to participants, who had subscribed to a particular topic.                                    |
| options        | PubSubPublishOptions | This is an object of PubSubPublishOptions, which provides an option, such as `persist`, which persists message history for upcoming participants. |

#### Example

```js
  // publish()
  ElevatedButton(
    onPressed: () async {
      // Publish a message
      await room.pubSub.publish(
        "CHAT", // Topic
        "Hello from Flutter!", // Message Content
        const PubSubPublishOptions(
          "persist": true // Stores the message in server for future participants
        ),
      );

      print("Message published");
    },
    child: Text("Publish"),
  ),
```

<br />

### subscribe()

This method is used to subscribe for particular topic. This method returns a list of messages which were sent earlier.

#### Syntax

```js
  Future<PubSubMessages> subscribe(
    String topic,
    Function(PubSubMessage) messageHandler,
  )
```

| Parameter Name | Type   | Description                                                                 |
| -------------- | ------ | --------------------------------------------------------------------------- |
| topic          | String | This should be the topic to be subscribed.                                  |
| messageHandler | String | This is a handler function, which will be called when new message received. |

#### Example

```js
  // subscribe()
  ElevatedButton(
    onPressed: () async {
      // Subscribe 'CHAT' topic and get persisted messages
      var messages = await room.pubSub.subscribe("CHAT", messageHandler);

      // Printing message list
      print("Messages: ${messages.messages.map((msg) => msg.message).join(" ")}");
    },
    child: Text("Subscribe"),
  ),

  // Message Handler
  void messageHandler(msg){
    // Do something
    print("New message received: $msg");
  }
```

### unsubscribe()

This method is used to unsubscribe the message topic.

#### Syntax

```js
  Future<void> unsubscribe(
    String topic,
    Function(PubSubMessage) messageHandler,
  )
```

| Parameter Name | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| topic          | String | This should be the topic to be unsubscribed.                   |
| messageHandler | String | This is a handler function, which was passed in `subscribe()`. |

#### Example

```js
  // unsubscribe
  ElevatedButton(
    onPressed: () {
      // Unsubscribe 'CHAT' topic
      await room.pubSub.unSubscribe("CHAT", messageHandler);
    },
    child: Text("UnSubscribe"),
  ),
```

## Sample Code

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

// ChatScreen
class ChatScreen extends StatefulWidget {
  final Room room;
  const ChatScreen({required this.room});

  @override
  _ChatScreenState createState() => _ChatScreenState();
}

class _ChatScreenState extends State<ChatScreen> {
  @override
  void initState() {
    super.initState();

    widget.room.pubSub.subscribe("CHAT", messageHandler)
      .then((messages) =>
          print("Subscribed to chat: ${messages.messages.map((msg) => msg.message).join(" ")}"));
  }

  @override
  Widget build(BuildContext context) {
    final room = widget.room;
    return Scaffold(
      appBar: AppBar(title: const Text("PubSub Sample Code")),
      body: Center(
        child: ElevatedButton(
          child: const Text("Send Hello !"),
          // Publish Hello message
          onPressed: () => room.pubSub.publish(
            "CHAT",
            "Hello",
            const PubSubPublishOptions(persist: true),
          ),
        ),
      ),
    );
  }

  // Handle incoming messages
  void messageHandler(PubSubMessage message) {
    print("New message: ${message.message}");
  }

  @override
  void dispose() {
    // Unsubscribe
    widget.room.pubSub.unsubscribe("CHAT", messageHandler);
    super.dispose();
  }
}

```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Record Meeting - Flutter

Record meeting allows participants to record video & audio during the meeting. The recording files are available in developer dashboard.
Any participant can start / stop recording any time during the meeting.

This guide will provide an overview of how to implement start and stop Meeting Recording.

1. **Start Recording** - By using `startRecording()` function, a participant can start meeting recording.
2. **Stop Recording** - By using `stopRecording()` function, a participant can stop meeting recording.

### Start And Stop Recording

```js
// Start Recording
meeting.startRecording('<webhookUrl>');
// Stop Recording
meeting.stopRecording(),
```

### Events

1. **recordingStarted** - Whenever any participant start meeting recording, then `recordingStarted` event will trigger.

2. **recordingStopped** - Whenever any participant stop meeting recording, then `recordingStopped` event will trigger.

```js
meeting.on(Events.recordingStarted, () {
  print("meeting recording started");
});
//
meeting.on(Events.recordingStopped, () {
  print("meeting recording stopped");
});
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Record Room - Flutter

Record room allows participants to record video & audio during the room. The recording files are available in developer dashboard.
Any participant can start / stop recording any time during the room.

This guide will provide an overview of how to implement start and stop Room Recording.

1. **Start Recording** - By using `startRecording()` function, a participant can start room recording.

### Parameters

- **webhookUrl**:

  - type: `String`
  - required: `false`
  - It will be webhook url where you want to get teh status of the recording.

- **awsDirPath**:

  - type: `String`
  - required: `false`
  - It will be path for your AWS storage specifing where to store the recording file.

- **config**:

  - type: `Object`
    - **config**:
      - **layout**:
        - **type**: _"GRID"_ | _"SPOTLIGHT"_ | _"SIDEBAR"_
        - **priority**: _"SPEAKER"_ | _"PIN"_
        - **gridSize**: Number _\`max 4\`_
      - **theme**: _"DARK"_ | _"LIGHT"_ | _"DEFAULT"_
      - **mode**: _"video-and-audio"_ | _"audio"_
      - **quality**: _"low"_ | _"med"_ | _"high"_
      - **orientation**: _"landscape"_ | _"portrait"_
  - required: `false`
  - It will be config for the layout of the recording you can to use.

2. **Stop Recording** - By using `stopRecording()` function, a participant can stop room recording.

### Start And Stop Recording

```js
// Start Recording
room.startRecording(config: {
  'layout': {
    'type': 'GRID',
    'priority': 'SPEAKER',
    'gridSize': 4,
  },
  'theme': "LIGHT",
  "mode": "video-and-audio".
  'quality':'high'
});

// Stop Recording
room.stopRecording(),
```

### Events

- **recordingStateChanged** - Whenever meeting recording state changes, then `recordingStateChanged` event will trigger.

```js
room.on(Events.recordginStateChanged, (String status) {

  // Status can have values -
  // RECORDING_STARTING -- Recording is starting
  // RECORDING_STARTED -- Recording is started
  // RECORDING_STOPPING -- Recording is stopping
  // RECORDING_STOPPED -- Recording is stopped

  toastMsg("Meeting recording status : $status");
});
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Remove Participant - Flutter

- Whenever any participant (having privileges) wants to remove other participant in room, he/she can do it with this feature.

- `Participant` class provides the `remove()` method to remove participant from the room.

```js
ElevatedButton(
    child: Text("Remove Participant"),
    onPressed: () {
        participant.remove();
    },
),
```

:::note
To remove any participant, you must have appropriate permissions
:::


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Share Your Screen - Flutter

- Whenever any participant wants to share a complete screen of mobile, they can simply do it with VideoSDK Room.

- This guide will provide an overview of how to enable or disable Screen Share in a room.

## Enable Screen Share

- `Room` class provides the method to enable screen-sharing.

- In order to start screen-sharing just call `room.enableScreenShare()` method.

```js
ElevatedButton(
    child: Text("Start ScreenSharing"),
    onPressed: () {
        room.enableScreenShare();
    },
),
```

:::caution

For Flutter iOS Screen Share feature, you need to follow this guide [Flutter iOS Screen Share](../extras/flutter-ios-screen-share)
:::

### Customise notification

- When a presenter starts screen share, presenter will receive a notification with a pre-defined title and messages.

- You can Customise those title, message and icon as per your requirements using `NotificationInfo` class and passed to `createRoom()` method.

```js
VideoSDK.createRoom(
    .
    .
    notification: const NotificationInfo(
        title: "Video SDK",
        message: "Video SDK is sharing screen in the room",
        icon: "notification_share", // drawable icon name
    ),
),
```

## Disable Screen Share

By using `room.disableScreenShare()` function, a participant can stop publishing screen stream to other participants.

```js
ElevatedButton(
    child: Text("Stop ScreenSharing"),
    onPressed: () {
        room.disableScreenShare();
    },
),
```

## Display Screen Share Stream

#### Local Participant

When a Local participant share the screen, `streamEnabled` Event on the `Participant` is triggered with the `Stream` which can be added to a `RTCVideoView`.

```js
room.localParticipant.on(Events.streamEnabled, (Stream _stream) {
    if (_stream.kind == 'share') {
        screenShareStream = _stream;
      }
    });
```

#### Other Participants

When other participant(Except you) share their screen, `presenterChanged` Event on the `Participant` is triggered with the `participantId` of the screen share.

```js
room.on(Events.presenterChanged, (_activePresenterId) {
    Participant? activePresenterParticipant = room.participants[_activePresenterId];

    Stream? _stream = activePresenterParticipant?
                        .streams.values
                        .singleWhere((e) => e.kind == "share");

    remoteParticipantShareStream = _stream;
});
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Set Video Quality - Flutter

- Set Video Quality feature allows participants to set other participant's video quality during the room.

- `Participant` class provides the `setQuality()` method to set participant's video quality.

```js
ElevatedButton(
    child: Text("Set High Quality"),
    onPressed: () {
        // Set Video Quality

        // High Quality
        participant.setQuality('high');

        // Medium Quality
        participant.setQuality('med');

        // Low Quality
        participant.setQuality('low');

    },
),
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Set Viewport - Flutter

When you are working with Video Calling, video quality is the most important part of communication. When a participant is shown on the screen, consuming multiple high quality although not required, will result in more memory and CPU usage of the device, eventually degrading quality.

The way to optimize around these situation is to consume the video quality which is required to fit the view of a particular participant, resulting in better quality, less usage of network bandwidth and providing a better experience.

Viewport is the size of window or visible area in which video for the participant is shown. We can optimize the consuming video quality based on the viewport size of the participant. For example if the viewport size of a particular participant view is `480x360`, VideoSDK will download a `480x360` stream. If a participant on screen is present in bigger size, VideoSDK will provide a higher quality video for that particular participant only.


<div style={{textAlign: 'center'}}>



</div>

### setViewPort()

`setViewPort()` can be used to achieve the best optimization of the video. This method is called with the `width` and `height` of the participant view on the `Participant` object and VideoSDK will handle the rest.

##### Parameters

- `width`

  - type: `int`
  - Width of the participant view for which the quliaty of video is to be adjusted.

- `height`
  - type: `int`
  - Height of the participant view for which the quliaty of video is to be adjusted.

### Example

```js
class ParticipantTile extends StatefulWidget {
  final Participant participant;
  final bool isLocalParticipant;
  const ParticipantTile(
      {Key? key, required this.participant, this.isLocalParticipant = false})
      : super(key: key);

  @override
  State<ParticipantTile> createState() => _ParticipantTileState();
}

class _ParticipantTileState extends State<ParticipantTile> {
  //create a widgetKey which can be used to refer the Video container
  GlobalKey _widgetKey = GlobalKey();

  @override
  Widget build(BuildContext context) {
    return Container(
        key: _widgetKey, //assign key to reference this view
        child: <Your Widget Here for Displaying participant>
    );
  }

  //call this method whenever the widget height of width gets changed.
  //it can be during stream enabled, stream resume, etc
  onViewPortChange() {
    try {
      //get the renderbox
      final RenderBox renderBox =
          _widgetKey.currentContext?.findRenderObject() as RenderBox;
      _widgetKey.currentContext?.size;

      //Get Size of the renderbox
      final Size size = renderBox.size;

      //apply setViewPort on the participant with height and width of view
      widget.participant.setViewPort(size.width, size.height);
    } catch (exception) {
      log("Unable to set Viewport $exception");
    }
  }
}
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Speaker Indication - Flutter

Speaker indication feature in VideoSDK let you know, which participant in a room is active speaker.

Whenever any participant speaks in room, `speakerChanged` event will trigger.

For example, the room is running with **Alice** and **Bob**. Whenever any of them speaks, `speakerChanged` event will trigger and return the speaker `participantId`.

We can access `speakerChanged` event through [room object](./start-join-room#2-initialization).

### speakerChanged Event

```js
room.on(Events.speakerChanged, (activeSpeakerId) {
  print("participantId => $activeSpeakerId");
});
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Start or Join Meeting - Flutter

<div style={{display:'flex',flexDirection:'row',alignItems:'stretch',}}>
<div style={{}}>
<p>After the successful installation of VideoSDK, the next step is to integrate VideoSDK features with your webApp/MobileApp.</p>

<p>To Communicate with other participant's audio or video call, you will need to join the meeting.</p>

<p>This guide will provide an overview of how to configure, initialize and join a VideoSDK meeting.</p>

</div>
<div>
<img src="/img/gif/new-meeting.gif"/>
</div>

</div>

## 1. Configuration

To configure a meeting, you will need [generated token](/flutter/guide/video-and-audio-calling-api-sdk/server-setup) and [meetingId](/api-reference/realtime-communication/create-room), we had discussed in [Server Setup](/flutter/guide/video-and-audio-calling-api-sdk/server-setup).
This code snippet calls API from local server

**Scenario 1** - Suppose you **don't have** any meetingId, you can simply generate meetingId by invoking `create-meeting` API.

**Scenario 2** - Suppose you **have** meetingId, now you don't have to call `create-meeting` API to generate meetingId, instead you can call `validate-meeting` API to validate meetingId.

**Token generation API is necessary for both scenario.**

```js
import 'dart:convert';
import 'package:http/http.dart' as http; // For API Calling, you need to add third party package "http"
import 'package:videosdk/rtc.dart';

// States Defined in Stateful Component.
String? meetingId;
String? token;

void _getMeetingIdAndToken() async {
    final LOCAL_SERVER_URL = dotenv.env['LOCAL_SERVER_URL'];

    // Calling get-token API.
    final Uri tokenUrl = Uri.parse('$LOCAL_SERVER_URL/get-token');
    final http.Response tokenResponse = await http.get(tokenUrl);

    final dynamic _token = json.decode(tokenResponse.body)['token'];

    // Calling create-meeting API.
    final Uri meetingIdUrl =
        Uri.parse('$LOCAL_SERVER_URL/create-meeting/');

    final http.Response meetingIdResponse =
        await http.post(meetingIdUrl, body: {"token": _token});

    final _meetingId = json.decode(meetingIdResponse.body)['meetingId'];

    // Setting into states of stateful widget
    setState(() {
      token = _token;
      meetingId = _meetingId;
    });
  }

  // This API is for validate the meeting id
  // Not require to call this API after create meeting API

dynamic validateMeeting(token, meetingId) async {
    final String LOCAL_SERVER_URL = dotenv.env['LOCAL_SERVER_URL'];
    final Uri validateMeetingUrl =
        Uri.parse('$LOCAL_SERVER_URL/validate-meeting/$meetingId');
    final http.Response validateMeetingResponse =
        await http.post(validateMeetingUrl, body: {"token": token});
    final _meetingId = json.decode(validateMeetingResponse.body)['meetingId'];
    if (_meetingId != null) {
      return _meetingId;
    } else {
      return null;
    }
  }

```

## 2. Initialization

<div style={{display:'flex',flexDirection:'row',alignItems:'stretch',}}>
<div style={{}}>
<p>
After configuration, you will have to Initialize 
<p>
meeting by providing name, meetingId, micEnabled, webcamEnabled & maxResolution.
</p>
</p>

</div>
<div>
<img src="/img/gif/add-participant.gif"/>
</div>

</div>

```js
import 'package:flutter/material.dart';
import 'package:videosdk/rtc.dart';

class MyApp extends StatelessWidget {
    @override
    Widget build(BuildContext context) {
        return MeetingBuilder(
            meetingId: "
</div>

</div>

```js
// Join the meeting
meeting?.join();
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Start or Join Room - Flutter

<div style={{display:'flex',flexDirection:'row',alignItems:'stretch',}}>
<div style={{}}>
<p>After the successful installation of VideoSDK, the next step is to integrate VideoSDK features with your webApp/MobileApp.</p>

<p>To Communicate with other participant's audio or video call, you will need to join the room.</p>

<p>This guide will provide an overview of how to configure, initialize and join a VideoSDK room.</p>

</div>
<div>
<img src="/img/gif/new-meeting.gif"/>
</div>

</div>

## 1. Configuration

To configure a room, you will need [generated token](/flutter/guide/video-and-audio-calling-api-sdk/server-setup) and [roomId](/api-reference/realtime-communication/create-room), we had discussed in [Server Setup](/flutter/guide/video-and-audio-calling-api-sdk/server-setup).
This code snippet calls API from local server

**Scenario 1** - Suppose you **don't have** any roomId, you can simply generate roomId by invoking `create-room` API.

**Scenario 2** - Suppose you **have** roomId, now you don't have to call `create-room` API to generate roomId, instead you can call `validate-room` API to validate roomId.

**Token generation API is necessary for both scenario.**

```js
import 'dart:convert';
import 'package:http/http.dart' as http; // For API Calling, you need to add third party package "http"
import 'package:videosdk/videosdk.dart';

// States Defined in Stateful Component.
String? roomId;
String? token;

void _getRoomIdAndToken() async {
    final LOCAL_SERVER_URL = dotenv.env['LOCAL_SERVER_URL'];

    // Calling get-token API.
    final Uri tokenUrl = Uri.parse('$LOCAL_SERVER_URL/get-token');
    final http.Response tokenResponse = await http.get(tokenUrl);

    final dynamic _token = json.decode(tokenResponse.body)['token'];

    // Calling create-room API.
    final Uri roomIdUrl =
        Uri.parse('$LOCAL_SERVER_URL/create-room/');

    final http.Response roomIdResponse =
        await http.post(roomIdUrl, body: {"token": _token});

    final _roomId = json.decode(roomIdResponse.body)['roomId'];

    // Setting into states of stateful widget
    setState(() {
      token = _token;
      roomId = _roomId;
    });
  }

  // This API is for validate the room id
  // Not require to call this API after create room API

dynamic validateRoom(token, roomId) async {
    final String LOCAL_SERVER_URL = dotenv.env['LOCAL_SERVER_URL'];
    final Uri validateRoomUrl =
        Uri.parse('$LOCAL_SERVER_URL/validate-room/$roomId');
    final http.Response validateRoomResponse =
        await http.post(validateRoomUrl, body: {"token": token});
    final _roomId = json.decode(validateRoomResponse.body)['roomId'];
    if (_roomId != null) {
      return _roomId;
    } else {
      return null;
    }
  }

```

## 2. Initialization

<div style={{display:'flex',flexDirection:'row',alignItems:'stretch',}}>
<div style={{}}>
<p>
After configuration, you will have to Initialize 
<p>
room by providing name, roomId, micEnabled, camEnabled & maxResolution.
</p>
</p>

</div>
<div>
<img src="/img/gif/add-participant.gif"/>
</div>

</div>

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MyApp extends StatelessWidget {
  final Room = VideoSDK.createRoom(
    roomId: "
</div>

</div>

```js
// Join the room
room?.join();
```

## Events

Following events are emitted on the `room` when it is successfully joined.

- Local Participant will receive a [`roomJoined`](../../../api/sdk-reference/room-class/events.md#roomjoined) event when successfully joined.
- Remote Participant will receive a [`participantJoined`](../../../api/sdk-reference/room-class/events.md#participantjoined) event with the newly joined [`Participant`](../../../api/sdk-reference/participant-class/introduction.md) object from the event callback.

```js
room.on(Events.roomJoined, () => {
  print("Room Joined Successfully");
});

room.on(Events.participantJoined, (participant) => {
  print("New Participant Joined");
});
```


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Switch Audio Output (BETA) - Flutter

This feature will help yout to switch audio output device during the session.

## Get Connected Device List

This method will help you to list down all possible connected audio devices.

To get the list of all available audio output devices, use the `getAudioOutputDevices()`, which will return a list of `MediaDeviceInfo`.

`MediaDeviceInfo` will contain the `deviceId` and `label` of the particular audio output device.

```js

ElevatedButton(
  child: Text("Get Output Device"),
  onPressed: () => {
    List<MediaDeviceInfo> outputDevice = meeting.getAudioOutputDevices()
    log(outputDevice);
  }),
```

## Switch Audio to Another Device

This method will help you to switch specific audio output device.

```js
// Pass the MediaDeviceInfo object to which the audio is to be switched.
meeting.switchAudioOutput(mediaDeviceInfo);
```

:::note

`EARPIECE` is not supported whenever `WIRED_HEADSET` or `BLUETOOTH` device is connected
:::

To check the implementation of switch audio device in detail, check out the [Flutter Code Sample](https://github.com/videosdk-live/videosdk-rtc-flutter-sdk-example)


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Toggle Participant Media - Flutter

Control other participant's camera and mic.
For better idea, let's understand this with a real case scenario

**Scenario 1 (Online Class)** - In this scenario, the lecturer(Local Participant) will control the student's(Other Participant) camera and mic as per his/her needs.

**Scenario 2 (Online Events)** - In this scenario, the event hosts will control the audience camera and mic when someone wants to speak.

This guide will provide an overview of how to control other participant camera and mic in a room.

1. **Enable camera of Participant** - By using `enableCam()` function, a `cameraRequested` event will trigger on requested participant side.

   **Example** : Room is running with **User A** and **User B**. Now **User A** wants to Enable camera of **User B**, so **User A** will use `enableCam()` function to request **User B**, after that **User B** receive the `cameraRequested` event, from there user can either accept or reject the incoming request.

2. **Disable camera of Participant** - By using `disableCam()` function, camera of that participant will be turned off.

   **Example** : **User A** wants to Disable camera of **User B**, so **User A** will use `disableCam()` function to Disable it without any request.

3. **Unmute Mic of Participant** - By using `unmuteMic()` function, a `micRequested` event will trigger on requested participant side.

   **Example** : Room is running with **User A** and **User B**. Now **User A** wants to Enable Mic of **User B**, so **User A** will use `unmuteMic()` function to request **User B**, after that **User B** will receive the `micRequested` event, from there user can either accept or reject the incoming request.

4. **Mute Mic of Participant** - By using `muteMic()` function, Mic of that participant will disable.

   **Example** : **User A** wants to Disable Mic of **User B**, so **User A** will use `mute()` function to Disable it without any request.

:::note

To achieve this feature, you need to pass `allow_join` persmission while genearting token for room initialization. After that you will be able to access participant media methods.

[How to apply permission while generating token?](/flutter/guide/video-and-audio-calling-api-sdk/server-setup)

:::

### Request Media Methods

```js
const participants = room.participants;
const participant = participants.get("<participant-id>");

// This will emit an event called "cameraRequested" to that particular participant
participant.enableCam();

// This will directly disable camera of particular participant
participant.disableCam();

// This will emit an event called "micRequested" to that particular participant
participant.unmuteMic();

// This will directly disable mic of particular participant
participant.muteMic();
```

### Manage Requested Media Events

1. **cameraRequested** - This event will be emitted to the participant `B` when any other participant `A` requests to enable camera of that participant `B`. This event handler will receive following three arguments:

   - `accept()` - Callback function to accept the request.
   - `reject()` - Callback function to reject the request.

<div style={{height: "10px"}}></div>

2. **micRequested** - This event will be emitted to the participant `B` when any other participant `A` requests to enable mic of that participant `B`. This event handler will receieve following three arguments:

   - `accept()` - Callback function to accept the request.
   - `reject()` - Callback function to reject the request.

```js
// Handle camera Requested
widget.room.on(Events.cameraRequested, ({ accept, reject }) {
    // callback function to accept the request
    accept();

    // callback function to reject the request
    reject();
}, );

// Handle Mic Requested
widget.room.on(Events.micRequested, ({ accept, reject }) {
     // callback function to accept the request
    accept();

    // callback function to reject the request
    reject();
}, );
```


---

# Getting Started - Flutter SDK




---

# Cloud Proxy - Flutter


Our SDK features a Cloud Proxy that allows you to manage how your streaming content is routed through different network paths. This feature ensures compliance with various regional internet regulations by restricting traffic to specified proxy servers, based on your needs and the geographical location of users.

This capability is crucial for adhering to local data protection laws and optimizes the streaming experience by overcoming geographical network constraints. By directing user connections to appropriate regional servers, Cloud Proxy enhances overall service performance and reliability.

Cloud Proxy offers three straightforward operating modes to fit different business and firewall requirements:

- **UDP_OVER_TCP (Default)**: In this mode, the connection starts by attempting to establish a UDP connection for media transmission. If that fails, it will automatically shifts to a secure TCP connection, which is compatible with most firewalls.

- **Force UDP**: This mode uses only UDP to send media, ensuring high-quality streams. It's ideal for environments where media quality is critical and the firewall can be configured accordingly.

- **Force TCP**: Only uses TCP for secure media transmission, suitable for strict firewall settings that only permit TCP traffic over centain ports. This might require additional firewall configuration and could affect media quality under poor network conditions.




### In this sequence diagram:
- Client to Proxy Server: The client sends a request to the proxy server, which processes and forwards it based on predefined rules.
- Proxy Server to Destination Server: The proxy server sends the request to the destination server, receives the response, and relays it back to the client.

:::info

Cloud Proxy is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Implementation

```js
Room room = VideoSDK.createRoom(
  roomId: "<ROOM-ID>",
  token: "<TOKEN>",
  displayName: "<DISPLAY-NAME>",
  preferredProtocol: PreferredProtocol.UDP_ONLY,
  signalingBaseUrl: "proxy.yourwebsite.com"
);
```

### Parameters

- preferredProtocol:
  - UDP_OVER_TCP (default): Initially the server attempts to establish a connection using UDP, if that fails it automatically switches to TCP protocol.
  - UDP_ONLY: Force UDP protocol
  - TCP_ONLY: Force TCP protocol
- signalingBaseUrl: Proxy URL to origin signaling and media.

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [createRoom](/flutter/api/sdk-reference/videosdk-class/methods#createroom)


---

# Geo Fencing - Flutter


Our SDK includes a region geofencing feature to comply with local laws and regulations worldwide. It restricts connections to servers within specified regions, ensuring users connect only to designated areas, regardless of their location. 

This helps meet regional data protection requirements and enhances user experience by addressing geographical network limitations.




### In this sequence diagram:
- User 1 (India) tries to connect to a meeting. In a regular scenario, the meeting would connect to the India region, but due to the geofence configuration, the meeting will connect to North America.

## Considerations
- If the user’s location differs from the chosen region, the network quality between these locations may be poor, affecting audio and video quality.
- Avoid using geofencing unless your scenario requires regional compliance.

:::info

Geo Fencing is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Available Regions
- INDIA
- USA
- UAE
- EUROPE
- SINGAPORE
- AUSTRALIA

---

# Geo IP Restrictions  - Flutter


Our SDK features Geo IP Restriction to ensure adherence to location-based access controls. It determines the user's location using their IP address and allows or restricts content based on geographic rules. This is essential for businesses needing to comply with international content distribution laws or provide localized services.

By implementing Geo IP Restriction, you can control who accesses your services based on where they are, ensuring compliance with legal regulations and enhancing security. This feature also improves the user experience by ensuring content relevance and availability is tailored to the user's location.




### In this sequence diagram:
- User 1 (India) attempts to connect to a meeting that is geo-restricted to only allow connections from North America. The server denies the connection due to the geographic restrictions.
- User 2 (North America) successfully connects because their location complies with the geo-restricted rules set on the meeting.


## Considerations
- Avoid using geo ip restriction unless your scenario requires regional or VPN/Proxy restrictions.

:::info

Geo IP Restriction is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Available Regions
- INDIA
- USA
- UAE
- EUROPE
- SINGAPORE
- AUSTRALIA

---

# Error Events - Flutter 

VideoSDK provides the `error` event which informs you about any error happening during the meeting.

### Events.error

- This event is triggered whenever an invalid configuration is provided or server/network errors arise. In such cases, the event will trigger with a specific error code and message.
- It is particularly useful for development-level troubleshooting during SDK integration.
- It can be subscribed to using the `VideoSDK` and the `Room` object for errors from the respective methods.
- Both `VideoSDK` and `Room` objects emit different errors. Users need to set up listeners for errors from both objects to ensure comprehensive error handling and troubleshooting.

### Example

Here is an example demonstrating the usage of the event mentioned on this page.

```javascript
import 'dart:developer';

import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    //Existing configuration
    
    setupVideoSDKEventListener();
    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupVideoSDKEventListener() {
    VideoSDK.on(Events.error, (error) {
      log("VIDEOSDK ERROR :: ${error['code']}  :: ${error['name']} :: ${error['message']}");
    });
  }

  void setupRoomEventListener() {
    room.on(Events.error, (error) {
      log("VIDEOSDK ERROR :: ${error['code']}  :: ${error['name']} :: ${error['message']}");
    });
  }
  //highlight-end
}
```

### Error Codes

We have depicted a specific constant with code and message in the below table.



### 1. Errors associated with Organization 

This table lists errors that occur due to the configuration and limitations within your organization’s account. These include account status, participant limits, and add-on service availability.

| Type                                   | Code  | Message                                             |
|----------------------------------------|-------|-----------------------------------------------------|
| ACCOUNT_DEACTIVATED                   | 4006  | Your account has been deactivated. Please contact VideoSDK support. |
| ACCOUNT_DISCONTINUED                  | 4007  | Your account has been discontinued. Please reach out to support for more details. |
| MAX_PARTICIPANT_REACHED               | 4009  | You have reached the maximum participant limit for this meeting. |
| MAX_SPEAKER_REACHED                   | 4010  | The maximum number of speakers for this meeting has been reached. |
| MAX_SPEAKER_LIMIT_REACHED_ON_ORGANIZATION | 4026  | Your organization has reached the maximum number of speakers allowed. |
| MAX_VIEWER_LIMIT_REACHED_ON_ORGANIZATION | 4027  | Your organization has reached the maximum number of viewers allowed. |
| ADD_ON_SERVICES_DISABLED              | 4021  | Add-On services have been disabled. Please contact support to enable them. |
| MAX_RECORDING_LIMIT_REACHED_ON_ORGANIZATION              | 4028  | You have reached max limit of recording on organization. To increase contact at support@videosdk.live |
| MAX_HLS_LIMIT_REACHED_ON_ORGANIZATION  | 4029  | You have reached max limit of hls on organization. To increase contact at support@videosdk.live |
| MAX_LIVESTREAM_LIMIT_REACHED_ON_ORGANIZATION  | 4030  | You have reached max limit of livestream on organization. To increase contact at support@videosdk.live |

### 2. Errors associated with Token

Errors listed here are related to issues with the API key, authentication tokens, or permissions assigned to users. These errors can occur when tokens are missing, expired, or improperly configured.

| Type                                    | Code  | Message                                                |
|-----------------------------------------|-------|--------------------------------------------------------|
| INVALID_API_KEY                        | 4001  | The provided API key is either missing or invalid. |
| INVALID_TOKEN                          | 4002  | The provided token is empty, invalid, or has expired. |
| INVALID_PERMISSIONS                    | 4008  | The permissions in the token are incorrect. Please verify them. |
| UNAUTHORIZED_MEETING_ID                | 4022  | The provided token is not authorized for this meeting ID. |
| UNAUTHORIZED_PARTICIPANT_ID            | 4023  | The provided token is not authorized for this participant ID. |
| UNAUTHORIZED_ROLE                      | 4024  | The role specified in the token is not valid for joining this meeting. |
| UNAUTHORIZED_REQUEST                      | 4025 | Your request does not match the security configuration. |

### 3. Errors associated with Meeting and Participant

This table lists errors resulting from invalid or missing meeting or participant details, including cases where a participant attempts to join with a duplicate ID.

| Type                    | Code  | Message                                         |
|-------------------------|-------|-------------------------------------------------|
| INVALID_MEETING_ID      | 4003  | The meeting ID provided is either invalid or missing. |
| INVALID_PARTICIPANT_ID  | 4004  | The participant ID is either invalid or missing. |
| DUPLICATE_PARTICIPANT   | 4005  | This participant has joined from another device. |

### 4. Errors associated with Add-on Service

This section addresses errors that occur while using VideoSDK's add-on services such as recording, livestreaming, HLS streaming, and transcription.

### Recording-related errors

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_RECORDING_FAILED      | 4011  | Failed to start recording. Please try again.   |
| STOP_RECORDING_FAILED       | 4012  | Failed to stop recording. Please try again.    |
| RECORDING_FAILED            | 5001  | Recording was stopped due to an error.         |
| START_PARTICIPANT_RECORDING_FAILED | 4035 | Failed to start participant recording. Please check the request. |
| STOP_PARTICIPANT_RECORDING_FAILED  | 4036 | Failed to stop participant recording. |
| PARTICIPANT_RECORDING_FAILED       | 5012 | Participant recording has stopped due to an error. |
| START_TRACK_RECORDING_FAILED | 4037 | Failed to start track recording.                |
| STOP_TRACK_RECORDING_FAILED  | 4038 | Failed to stop track recording.                 |
| TRACK_RECORDING_FAILED  | 5013 | Track recording stopped due to an unknown error.                 |
| PREV_RECORDING_PROCESSING  | 4018 | Previous recording session is being processed, please try again after few seconds.                 |
| RECORDING_DURATION_LIMIT_REACHED | 5004 | Recording stopped due to maximum duration being reached. |

### Livestream-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| INVALID_LIVESTREAM_CONFIG           | 4015  | Livestream 'outputs' configuration provided was invalid            |
| START_LIVESTREAM_FAILED     | 4013  | Failed to start livestream. Please try again.  |
| STOP_LIVESTREAM_FAILED      | 4014  | Failed to stop livestream. Please try again.   |
| LIVESTREAM_FAILED           | 5002  | Livestream stopped due to an error.            |
| PREV_RTMP_RECORDING_PROCESSING | 4019 | Previous RTMP recording session is being processed, please try again after few seconds! |
| LIVESTREAM_DURATION_LIMIT_REACHED | 5005 | Livestream stopped due to maximum duration being reached. |

### HLS-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_HLS_FAILED            | 4016  | Failed to start HLS stream.                    |
| STOP_HLS_FAILED             | 4017  | Failed to stop HLS stream.                     |
| HLS_FAILED                  | 5003  | HLS streaming stopped due to an error.         |
| PREV_HLS_STREAMING_PROCESSING | 4020 | Previous HLS streaming session is still being processed. |
| HLS_DURATION_LIMIT_REACHED  | 5006  | HLS stream stopped due to maximum duration being reached. |

### Transcription-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_TRANSCRIPTION_FAILED  | 4031  | Failed to start transcription. Please try again. |
| STOP_TRANSCRIPTION_FAILED   | 4032  | Failed to stop transcription.                  |
| TRANSCRIPTION_FAILED        | 5007  | Transcription stopped due to an error.         |

### 5.Errors associated with Media

These errors involve media access, device availability, or permission-related issues affecting camera, microphone, and screen sharing.

### Device permission-related errors
| Type                                      | Code  | Message                                          |
|-------------------------------------------|-------|--------------------------------------------------|
| ERROR_CAMERA_ACCESS_UNAVAILABLE          | 3005  | Camera access unavailable: Please ensure your device is compatible and that you're on a secure website (https://).                |
| ERROR_MICROPHONE_ACCESS_UNAVAILABLE      | 3006  | Microphone access unavailable: Please ensure your device is compatible and that you're on a secure website (https://).             |
| ERROR_CAMERA_ACCESS_DENIED_OR_DISMISSED      | 3007  | Camera access was denied or dismissed. To proceed, kindly grant access manually through your device/browser settings.. |
| ERROR_MICROPHONE_ACCESS_DENIED_OR_DISMISSED      | 3008  | Microphone access was denied or dismissed. To proceed, kindly grant access through your device/browser settings. |
| ERROR_CAMERA_PERMISSION_DENIED_BY_OS     | 3009  | Camera permission denied by OS system settings. Please check the system settings and grant permission for this browser. |
| ERROR_MICROPHONE_PERMISSION_DENIED_BY_OS | 3010  | Microphone permission denied by OS system settings. Please check the system settings and grant permission for this browser. |
| ERROR_SCREENSHARE_PERMISSION_DENIED  | 3014  | Screen sharing permission was denied. To enable screen sharing, please try again and grant the necessary permissions. |

### Device-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| ERROR_CAMERA_IN_USE          | 3003  | The camera is being used by another application. Please close any programs utilizing the camera, such as video conferencing tools, screen recording software, or other browsers. Restart your browser and attempt again. |
| ERROR_MICROPHONE_IN_USE      | 3004  | The microphone is being used by another application. Please close any programs utilizing the microphone, such as video conferencing tools, screen recording software, or other browsers. Restart your browser and attempt again. |
| ERROR_STARTING_VIDEO      | 3011  | Something went wrong, and the webCam could not be enabled. Please try again. |
| ERROR_STARTING_AUDIO      | 3012  | Something went wrong, and the microphone could not be enabled. Please try again. |
| ERROR_STARTING_SCREENSHARE      | 3013  | Something went wrong, and the screenshare could not be enabled. Please try again. |
| ERROR_CAMERA_DEVICE_INCOMPATIBLE       | 3019  | Camera device cannot produce video: Unable to produce video stream. Please ensure your device is compatible. |
| ERROR_MICROPHONE_DEVICE_INCOMPATIBLE   | 3020  | Microphone device cannot produce audio: Unable to produce audio stream. Please ensure your device is compatible. |
| ERROR_SCREENSHARE_NOT_SUPPORTED  | 3015  | Screenshare not supported: Unable to generate a screenshare stream. Please ensure your device/browser is compatible. |

### 6.Errors associated with Track

These errors occur when there are issues with video or audio tracks, such as disconnections or invalid custom tracks.

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| ERROR_CREATING_VIDEO_TRACK      | 3017  | An error occurred while creating the video track. Please try again. |
| ERROR_CREATING_AUDIO_TRACK      | 3018  | An error occurred while creating the audio track. Please try again. |
| ERROR_CUSTOM_VIDEO_TRACK_DISPOSED      | 3001  | The provided custom video track has been disposed of, and is now in an ended state. Reverting to the default video track. |
| ERROR_CUSTOM_AUDIO_TRACK_DISPOSED      | 3002  | The provided custom audio track has been disposed of, and is now in an ended state. Reverting to the default audio track. |


### 7.Errors associated with Actions

Below error is triggered when an action is attempted before joining a meeting.

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| ERROR_ACTION_PERFORMED_BEFORE_MEETING_JOINED     | 3022  | Oops! Something went wrong. The room was in a connecting state, and during that time, an action encountered an issue. Please try again after joining a meeting. |
| ERROR_JOINING_MEETING     | 3023  | Something went wrong. The meeting could not be joined. Please try again. |
| ERROR_CHANGING_MODE     | 3021  | Something went wrong, and the mode could not be changed. Please try again. |
| ERROR_STARTING_FOREGROUND_SERVICE | 3016 | An error occurred while initializing the foreground service, preventing screenshare from being enabled. Please try again. |


### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [Room class Events.error](/flutter/api/sdk-reference/room-class/events#error)
- [VideoSDK class Events.error](/flutter/api/sdk-reference/videosdk-class/events#error)




---

# HLS Events - Flutter 

VideoSDK provides the `hlsStateChanged` event, which informs you about the current state of HLS for the meeting.

### Events.hlsStateChanged

- This event is triggered when the HLS status of the meeting changes.
- It can be subscribed to using the `Room` Object.

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

### Example

Here is an example demonstrating the usage of the event mentioned on this page.

```javascript
import 'dart:developer';
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    //Existing configuration

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {
    room.on(Events.hlsStateChanged, (Map<String, dynamic> data) {
      //Status can be :: HLS_STARTING
      //Status can be :: HLS_STARTED
      //Status can be :: HLS_PLAYABLE
      //Status can be :: HLS_STOPPING
      //Status can be :: HLS_STOPPED
      log("Meeting HLS status : ${data['status']}");
      if (data['status'] == "HLS_PLAYABLE") {
        log("PLAYBACKHLS URL --  ${data['playbackHlsUrl']}");
      }
    });
  }
  //highlight-end
}
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [Events.hlsStateChanged](/flutter/api/sdk-reference/room-class/events#hlsstatechanged)


---

# Media Events - Flutter 

VideoSDK offers various events that can be monitored to obtain information about the media status of participants in the meeting.

Here are the events specifically related to the stream:

### Events.streamEnabled

- This event is triggered whenever a participant's video, audio or screen share stream is enabled.
- It can be subscribed to using the `Participant` object.

### Events.streamDisabled

- This event is triggered whenever a participant's video, audio or screen share stream is disabled.
- It can be subscribed to using the `Participant` object.

### Events.streamPause

- This event is triggered whenever a participant's video, audio or screen share stream is paused.
- It can be subscribed to using the `Participant` object.

### Events.streamResumed

- This event is triggered whenever a participant's video, audio or screen share stream is resumed.
- It can be subscribed to using the `Participant` object.

### Example

Here is an example demonstrating the usage of all the events mentioned on this page.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;
  //Existing congiguration
}

class _ParticipantTileState extends State<ParticipantTile> {
  @override
  void initState() {
    //highlight-next-line
    //Existing congiguration

    setupParticipantEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourParticipantTileWidget();
  }

  //highlight-start
  void setupParticipantEventListener() {
    widget.participant.on(Events.streamEnabled, (Stream stream) {
      if (stream.kind == "video") {
        // Participant turned on video
      } else if (stream.kind == "audio") {
        // Participant turned on audio
      } else if (stream.kind == "share") {
        // Participant started screenshare
      }
    });

    widget.participant.on(Events.streamDisabled, (Stream stream) {
      if (stream.kind == "video") {
        // Participant turned off video
      } else if (stream.kind == "audio") {
        // Participant turned off audio
      } else if (stream.kind == "share") {
        // Participant stopped screenshare
      }
    });

    widget.participant.on(Events.streamPaused, (Stream stream) {
      if (stream.kind == "video") {
        // Participant video pause
      } else if (stream.kind == "audio") {
        // Participant audio pause
      } else if (stream.kind == "share") {
        // Participant screenshare paused
      }
    });

    widget.participant.on(Events.streamResumed, (Stream stream) {
      if (stream.kind == "video") {
        // Participant video resume
      } else if (stream.kind == "audio") {
        // Participant audio resume
      } else if (stream.kind == "share") {
        // Participant screenshare resumed
      }
    });
  }
  //highlight-end
}
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [Events.streamEnabled](/flutter/api/sdk-reference/participant-class/events#streamenabled)
- [Events.streamDisabled](/flutter/api/sdk-reference/participant-class/events#streamdisabled)
- [Events.streamPaused](/flutter/api/sdk-reference/participant-class/events#streampaused)
- [Events.streamResumed](/flutter/api/sdk-reference/participant-class/events#streamresumed)


---

# Network Events - Flutter

VideoSDK offers the `qualityLimitation` event, providing information about any quality limitations detected or resolved during the meeting.

### qualityLimitation

- This callback is triggered when a quality limitation is detected or resolved during the meeting.
- Limitations may occur due to congestion, bandwidth issues, or CPU constraints.
- Developers can use this event to gracefully adjust media settings (like reducing video resolution) and restore them once the limitation is resolved.
- It can be subscribed to using the `Room` class.

### Example

Here is an example demonstrating the usage of the event mentioned on this page.

```javascript
import 'package:videosdk/videosdk.dart';
Room room;
room.on(Events.qualityLimitation, (type, state, timestamp) {
  print("Quality Limitiation for $type on $state at $timestamp");
});
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [qualityLimitation](/flutter/api/sdk-reference/room-class/events#qualitylimitation)


---

# Participant Events - Flutter 

VideoSDK provides various events that can be utilized to gather information about the participants in the meeting.

Here are the events specifically related to the participant:

### Events.participantJoined

- This event is triggered when someone joins the meeting, returning the `Participant` object as parameter.
- It can be subscribed to using the `Room` object.

### Events.participantLeft

- This event is triggered when someone leaves the meeting, along with the participantId and Reason. You can refer to the reason details [here](/flutter/api/sdk-reference/room-class/events#participantleft).
- It can be subscribed to using the `Room` object.
- When `Events.participantLeft` is triggered, a reason object is also provided.
- The table below outlines the possible reason codes and their descriptions:

| Type                                   | Code  | Message                                             |
|----------------------------------------|-------|-----------------------------------------------------|
| WEBSOCKET_DISCONNECTED                 | 1001  | Socket disconnected. |
| REMOVE_PEER                  | 1002  | Participant was removed from the meeting. |
| REMOVE_PEER_VIEWER_MODE_CHANGED               | 1003  | Participant removed because viewer mode was changed. |
| REMOVE_PEER_MEDIA_RELAY_STOP  |  1004 | Your organization has reached the maximum number of speakers allowed. |
| SWITCH_ROOM | 1005  | Participant switched to a different room. |
| ROOM_CLOSE | 1006  | The meeting has been closed. |
| UNKNOWN              | 1007  | Participant disconnected due to an unknown reason. |
| REMOVE_ALL              | 1008  | Remove All from the meeting. |
| MEETING_END_API  | 1009  | Meeting Ended. |



### Events.cameraRequested

- This event is triggered for participant `B`, when another participant, `A` requests to enable their webcam.
- Upon accepting the request, participant `B`'s webcam will be enabled.
- It can be subscribed to using the `Room` object.

### Events.micRequested

- This event is triggered for participant `B`, when another participant, `A` requests to enable their mic.
- Upon accepting the request, participant `B`'s mic will be enabled.
- It can be subscribed to using the `Room` object.

### Example

Here is an example demonstrating the usage of all the events mentioned on this page.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    //Existing configuration

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {
    _room.on(Events.participantJoined, (Participant participant) {
      // New Participant joined the room
    });

    _room.on(Events.participantLeft, (String participantId , LeaveReason reason) {
      // Participant left the room
    });

    _room.on(Events.cameraRequested, (data) {
      String? participantId = data["participantId"];

      Function accept = data["accept"];
      Function reject = data["deny"];

      // participantId, will be the id of participant who requested to enable camera

      // if the request is accepted
      accept();

      // if the request is rejected
      reject();
    });

    _room.on(Events.micRequested, (data) {
      String participantId = data["participantId"];

      Function accept = data["accept"];
      Function reject = data["reject"];

      // participantId, will be the id of participant who requested to enable camera

      // if the request is accepted
      accept();

      // if the request is rejected
      reject();
    });
  }
  //highlight-end
}
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [Events.participantJoined](/flutter/api/sdk-reference/room-class/events#participantjoined)
- [Events.participantLeft](/flutter/api/sdk-reference/room-class/events#participantleft)
- [Events.cameraRequested](/flutter/api/sdk-reference/room-class/events#camerarequested)
- [Events.micRequested](/flutter/api/sdk-reference/room-class/events#micrequested)


---

# Recording Events - Flutter 

VideoSDK provides the `recordingStateChanged` event, which notifies you of the current state of recording for the meeting.

### Events.recordingStateChanged

- This event is triggered when the recording status of the meeting changes. 
- It can be subscribed to using the `Room` object.

### Example

Here is an example demonstrating the usage of the event mentioned on this page.

```javascript
import 'dart:developer';
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    //Existing configuration

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {
    room.on(Events.recordingStateChanged, (String status) {
      //Status can be :: RECORDING_STARTING
      //Status can be :: RECORDING_STARTED
      //Status can be :: RECORDING_STOPPING
      //Status can be :: RECORDING_STOPPED
      log("Meeting Recording status : $status");
    });
  }
  //highlight-end
}
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [Events.recordingStateChanged](/flutter/api/sdk-reference/room-class/events#recordingstatechanged)


---

# Room Connection Events - Flutter

VideoSDK provides `Events.roomStateChanged` event which will notify you of the current connection state of the room.

### Events.roomStateChanged

- This event is triggered whenever the room's state changes. 
- The current state of the room is passed as a callback parameter.
- All available states are `connecting`, `connected`, `disconnected`, `reconnecting`.
- It can be subscribed to using the `Room` object.

### Example

Here is the usage of the event mentioned in this page.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    //Existing configuration

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {
    room.on(Events.roomStateChanged, (RoomState state) {
        switch (state) {
          case RoomState.connecting:
            print('Meeting is Connecting');
            break;
          case RoomState.connected:
            print('Meeting is Connected');
            break;
          case RoomState.disconnected:
            print('Meeting connection disconnected abruptly');
            break;
          case RoomState.reconnecting:
            print('Meeting in reconnecting state');
          default:
            print('default');
        }
    });
  //highlight-end
}
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [Events.roomStateChanged](/flutter/api/sdk-reference/room-class/events#roomStateChanged)

---

# Room Events - Flutter 

VideoSDK provides several types of events that can be listened to in order to determine the current state of the room.

Here are the events specifically related to the room:

### Events.roomJoined

- This event is triggered when the room is successfully joined.
- It can be subscribed to using the `Room` object.

### Events.roomLeft

- This event is triggered when the room is left with a specified reason. You can refer to the reason details [here](/flutter/api/sdk-reference/room-class/events#roomleft).
- It can be subscribed to using the `Room` object. 



### Events.speakerChanged

- This event is triggered when there is a change in the active speaker during the meeting.
- It can be subscribed to using the `Room` object.

### Events.presenterChanged

- This event is triggered when there is a change in the presenter during the meeting.
- It can be subscribed to using the `Room` object.

### Example

Here is an example demonstrating the usage of all the events mentioned on this page.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    //Existing configuration

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {
    room.on(Events.roomJoined, () {
      //Room Joined successfully
    });

    room.on(Events.roomLeft, (LeaveReason reason) {
      //Room Left

      if(reason != null){
        print("Meeting Left reason: ${reason.message} and code: ${reason.code}");
      }
    });

    room.on(Events.speakerChanged, (String? activeSpeakerId) {
      //Room active speaker has changed
      //Participant ID of current active speaker is activeSpeakerId
    });

    room.on(Events.presenterChanged, (String? presenterId) {
      //Room screen presenter has changed
      //Participant ID of current presenter is presenterId
    });
  }
  //highlight-end
}
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [Events.roomJoined](/flutter/api/sdk-reference/room-class/events#roomjoined)
- [Events.roomLeft](/flutter/api/sdk-reference/room-class/events#roomleft)
- [Events.speakerChanged](/flutter/api/sdk-reference/room-class/events#speakerchanged)
- [Events.presenterChanged](/flutter/api/sdk-reference/room-class/events#presenterchanged)


---

# RTMP Events - Flutter 

VideoSDK provides the `livestreamStateChanged` event, which informs you about the current state of the livestream for the meeting.

### Events.livestreamStateChanged

- This event is triggered when the livestream status of the meeting changes.
- It can be subscribed to using the `Room` object.

### Example

Here is an example demonstrating the usage of the event mentioned on this page.

```javascript
import 'dart:developer';
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    //Existing configuration

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {
    room.on(Events.liveStreamStateChanged, (String status) {
      //Status can be :: LIVESTREAM_STARTING
      //Status can be :: LIVESTREAM_STARTED
      //Status can be :: LIVESTREAM_STOPPING
      //Status can be :: LIVESTREAM_STOPPED
      log("Meeting Livestream status : $status");
    });
  }
  //highlight-end
}
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [Events.liveStreamStateChanged](/flutter/api/sdk-reference/room-class/events#livestreamstatechanged)


---

# Stream Events - Flutter

### streamStateChanged

- This event is triggered when the state of a stream changes.
- The event callback will include the current state of the stream, which can be one of the following: `active`, `freeze-detected`, `freeze-resolved`, `stuck`.
- It can be subscribed to using the `Stream` class.

:::note
This event is emitted exclusively for remote participants, specifically for their video and screen share video streams.
:::

#### Parameters

- **`state`**: Specifies the current state of the stream.

    - **Type**: `String`
    - **Possible values**:
        - `"active"`: Stream is working normally.
        - `"stuck"`: Stream is not progressing as expected.
        - `"freeze-detected"`: Video freeze has been detected.
        - `"freeze-resolved"`: Video freeze has been resolved.
        - `"ended"`: Stream has ended.

- **`timestamp`**: The time (in milliseconds since epoch) when the state change occurred.
    - **Type**: `int`

### Example

Here is an example demonstrating the usage of the event mentioned on this page.

```javascript
import 'package:videosdk/videosdk.dart';
Stream videoStream; 

videoStream.on(Events.streamStateChanged, (state, timestamp){
    print("Stream State changed to state: $state at time:$timestanp");
});
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [streamStateChanged](/flutter/api/sdk-reference/stream-class/events#streamstatechanged)


---

<h1> {props.title} </h1>{" "}

Building applications with real-time voice, video, and interaction are just plain hard. It is complex and it takes a lot of time to build.

Video SDK provides developers with simple-to-use, highly customisable, and widely compatible APIs to embed real-time video, voice, and interaction functionalities into their applications without the need to develop the technology or the underlying infrastructure for real-time engagement themselves.



<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

## Steps


<div class="container guide-steps-block">
  <div class="row ">
    <div class="col col--6">
      
    </div>
     <div class="col col--6">
      
    </div>
  </div>
  <div class="row ">
   <div class="col col--6" >
      
    </div>
    <div class="col col--6">
      
    </div>
  </div>
  <div class="row ">
   <div class="col col--6" >
      
    </div>
    <div class="col col--6">
      
    </div>
  </div>
</div>

## Architecture

This diagram demonstrates end-to-end flow to implement video & audio calling, record calls and go-live on social media.

![Video-sdk-architecture!](/img/video-sdk-archietecture.svg)


---

# Active Speaker Indication - Flutter

Active Speaker indication feature in VideoSDK let you know, which participant in a meeting is active speaker. This feature can be particularly useful in larger meetings or webinars, where there may be many participants and it can be difficult to tell who is speaking.

Whenever any participant speaks in meeting, `speakerChanged` event will trigger with the participant id of the active speaker.

For example, the meeting is running with **Alice** and **Bob**. Whenever any of them speaks, `speakerChanged` event will trigger and return the speaker `participantId`.

### Event

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    ...

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {

    room.on(Events.speakerChanged, (String? activeSpeakerId) {
      //Room active speaker has changed
      //Participant ID of current active speaker is activeSpeakerId
    });
  }
  //highlight-end
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [speakerChanged](/flutter/api/sdk-reference/room-class/events#speakerchanged)


---

# Background Handling - Flutter

Due to platform-specific restrictions on **iOS** and **Android**, essential functionalities like microphone and camera access are limited when the app moves to **Background Mode**.

- **iOS** has strict resource management policies, preventing access to the camera in the background. However, it allows microphone access, which is crucial for maintaining media transmission.

- **Android 14 and above** restrict background microphone and camera access and enforce strict battery optimization policies. These policies can aggressively kill background processes.

To ensure seamless media transmission in **VideoSDK** when the app is in background, you must address these platform-specific limitations by:

- Enable the required background modes on **iOS**.
- Configure **permissions** and use **foreground services** on Android. 

Alternatively, if you prefer not to implement a foreground service, you can use [Picture-in-Picture (PiP)](../render-media/picture-in-picture-mode) mode on both **iOS** and **Android**. This allows the app to continue media playback in a small floating window, bypassing some of the background restrictions.

If these steps aren’t correctly implemented, the app will lose the ability to send or receive media when backgrounded, disrupting core communication features.

The sections below explain how to implement background support effectively on both platforms with **VideoSDK**.  

## iOS Background Handling

For **iOS** devices, you need to enable the necessary capabilities in **Xcode** to continue publishing and playing media while the app is in the background:

1. **Open your project in Xcode**.
2. Navigate to the **target settings**.
3. Select the **"Signing & Capabilities"** tab.
4. Click the **"+"** button to add capabilities.
5. Add **Background Modes**.

Under **Background Modes**, enable the following options:
- **Audio, AirPlay, and Picture in Picture**

This will allow your app to handle audio and video in the background, ensuring that essential media features like calls continue uninterrupted.

<center>
    <img src='https://cdn.videosdk.live/docs/images/react-native/screenshare/screen_share_backround_modes.png'/>
</center>

## Android Background Handling

On **Android**, background media capture is more restrictive. Challenges include:  

- Limited microphone/camera access when the app is backgrounded (usually ~60 seconds by default).  
- OEM-specific optimizations that aggressively kill background processes.  

To ensure reliable background capture and playback, use a **foreground service** with a persistent notification.



Update your `AndroidManifest.xml` to declare permissions and the foreground service:  

```xml title="AndroidManifest.xml"
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA"/>
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>


  <application>
    <service android:name=".MyForegroundService"
    android:foregroundServiceType="camera|microphone"
    android:stopWithTask="true" />
  </application>
</manifest>
```




Implement a foreground service that displays a persistent notification and keeps media capture active:

```js title="ForegroundService.kt"
package com.example.example

import android.app.*
import android.content.Intent
import android.os.Build
import android.os.IBinder
import android.util.Log
import androidx.core.app.NotificationCompat

class ForegroundService : Service() {
    
    companion object {
        const val NOTIFICATION_ID = 1001
        const val CHANNEL_ID = "AppChannelID"
        private const val TAG = "ForegroundService"
        
        // Actions
        const val ACTION_START = "com.example.example.START_FOREGROUND_SERVICE"
        const val ACTION_STOP = "com.example.example.STOP_FOREGROUND_SERVICE"
    }
    
    override fun onCreate() {
        super.onCreate()
        Log.d(TAG, "Service onCreate")
        createNotificationChannel()
    }
    
    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        Log.d(TAG, "Service onStartCommand")
        
        when (intent?.action) {
            ACTION_START -> {
                startForegroundService()
            }
            ACTION_STOP -> {
                stopForegroundService()
            }
            else -> {
                // Default action - start the service
                startForegroundService()
            }
        }
        
        return START_STICKY
    }
    
    override fun onBind(intent: Intent?): IBinder? {
        return null
    }
    
    override fun onDestroy() {
        super.onDestroy()
        Log.d(TAG, "Service onDestroy")
    }
    
    private fun startForegroundService() {
        Log.d(TAG, "Starting foreground service")
        
        try {
            val notification = createNotification()
            startForeground(NOTIFICATION_ID, notification)
            Log.d(TAG, "Foreground service started successfully")
        } catch (e: SecurityException) {
            Log.e(TAG, "Security exception while starting foreground service", e)
            // This usually means missing permissions
            throw e
        } catch (e: Exception) {
            Log.e(TAG, "Error starting foreground service", e)
            throw e
        }
    }
    
    private fun stopForegroundService() {
        Log.d(TAG, "Stopping foreground service")
        stopForeground(true)
        stopSelf()
    }
    
    private fun createNotification(): Notification {
        val notificationIntent = Intent(this, MainActivity::class.java)
        val pendingIntent = PendingIntent.getActivity(
            this,
            0,
            notificationIntent,
            PendingIntent.FLAG_IMMUTABLE
        )
        
        return NotificationCompat.Builder(this, CHANNEL_ID)
            .setContentTitle("Foreground Service")
            .setContentText("Camera and microphone are active")
            .setSmallIcon(R.mipmap.ic_launcher)
            .setContentIntent(pendingIntent)
            .setPriority(NotificationCompat.PRIORITY_LOW)
            .setOngoing(true)
            .build()
    }
    
    private fun createNotificationChannel() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            val channel = NotificationChannel(
                CHANNEL_ID,
                "Foreground Service",
                NotificationManager.IMPORTANCE_LOW
            ).apply {
                description = "Channel for foreground service notifications"
                setShowBadge(false)
                enableLights(false)
                enableVibration(false)
            }
            
            val notificationManager = getSystemService(NotificationManager::class.java)
            notificationManager?.createNotificationChannel(channel)
            Log.d(TAG, "Notification channel created")
        }
    }
}
```




Use a MethodChannel in MainActivity to start/stop the service from Dart:

```kotlin title="MainActivity.kt"
package com.example.example
import com.example.example.ForegroundService
import io.flutter.plugin.common.MethodChannel
import android.content.Intent
import io.flutter.embedding.android.FlutterActivity
import android.os.Bundle
import io.flutter.embedding.engine.FlutterEngine
import android.net.Uri

class MainActivity : FlutterActivity() {
private val CHANNEL = "com.example.example/channel"

    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
    super.configureFlutterEngine(flutterEngine)

        MethodChannel(flutterEngine.dartExecutor.binaryMessenger, CHANNEL).setMethodCallHandler { call, result ->
            when (call.method) {
                "startMicrophoneService" -> {
                    startService(Intent(this, ForegroundService::class.java).apply {
                        action = ForegroundService.ACTION_START
                    })
                    result.success(null)
                }
                "stopMicrophoneService" -> {
                    startService(Intent(this, ForegroundService::class.java).apply {
                        action = ForegroundService.ACTION_STOP
                    })
                    result.success(null)
                }
                else -> result.notImplemented()
            }
        }
    }
}
```





Finally, request permissions and start the service from React Native:

```js
class MeetingScreen extends StatefulWidget {
    @override State<MeetingScreen> createState() => _MeetingScreenState();
}

class _MeetingScreenState extends State<MeetingScreen> {
    static const platform = MethodChannel('com.example.example/channel');

    @override
    void initState() {

        Room room = VideoSDK.createRoom(
            roomId: widget.meetingId,
            token: widget.token,
            customCameraVideoTrack: widget.cameraTrack,
            customMicrophoneAudioTrack: widget.micTrack,
            displayName: widget.displayName,
            micEnabled: widget.micEnabled,
            camEnabled: widget.camEnabled,
            maxResolution: 'hd',
        );

        // Register meeting events
        registerMeetingEvents(room);

        // Join meeting
        room.join();
    }

    Future<void> _startMicrophoneService() async {
        try {
            await platform.invokeMethod('startMicrophoneService');
        } on PlatformException catch (e) {
            print("Failed to start service: '${e.message}'.");
        }
    }

    Future<void> _stopMicrophoneService() async {
        try {
            await platform.invokeMethod('stopMicrophoneService');
        } on PlatformException catch (e) {
            print("Failed to stop service: '${e.message}'.");
        }
    }

    void registerMeetingEvents(Room _meeting) {
        
        // Called when joined in meeting
        _meeting.on(Events.roomJoined, () {
            setState(() {
                meeting = _meeting;
                _joined = true;
            });
            if (!kIsWeb && Platform.isAndroid) {
                _startMicrophoneService();
            }
        });

        // Called when meeting is ended
        _meeting.on(Events.roomLeft, (String? errorMsg) {
            if(!kIsWeb && Platform.isAndroid){
                _stopMicrophoneService();
            }
        });
    }
}
```



---

# Change Audio Input Device - Flutter

During the meeting at any point a participant wishes to switch his/her input audio device, it can be done using the below mentioned methods.

:::important
This feature is only available on the **Web** and **Desktop**; if you want to use it on **Mobile**, please refer [this guide](./change-audio-output-device.md).
:::

### `getAudioDevices()`

- The `getAudioDevices()` method will help you to list down all possible connected audio input devices which will return a list of `AudioDeviceInfo` objects.

- The `AudioDeviceInfo` object will contain the `deviceId` , `kind` , `groupId` and `label` for the device.

### `changeMic()`

- After selecting the desired device, you can switch the audio input by passing the corresponding `AudioDeviceInfo` object as a parameter to the `changeMic()` method.

#### Example

```js
import 'dart:io';

import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  const MeetingScreen({Key? key}) : super(key: key);

  @override
  _MeetingScreenState createState() => _MeetingScreenState();
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;
  List<AudioDeviceInfo>? mics = [];

  @override
  void initState() {
    super.initState();
    fetchMics();
  }

  void fetchMics() async {
    List<AudioDeviceInfo>? audioDevices = await VideoSDK.getAudioDevices();
    if (kIsWeb || Platform.isMacOS || Platform.isWindows) {
      for (AudioDeviceInfo device in audioDevices!) {
        if (device.kind == 'audioinput') {
          mics?.add(device);
        }
      }
    }
    setState(() {});
  }

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      ElevatedButton(
          child: Text("Change Input Device"),
          onPressed: () => {
                showDialog(
                  context: context,
                  builder: (context) => AlertDialog(
                    title: const Text("Select Audio Device"),
                    content: Column(
                      mainAxisAlignment: MainAxisAlignment.center,
                      mainAxisSize: MainAxisSize.min,
                      children: <Widget>[
                        SingleChildScrollView(
                          reverse: true,
                          //highlight-start
                          child: mics != null && mics!.isNotEmpty
                              ? Column(
                                  children: mics!
                                      .map(
                                        (device) => ElevatedButton(
                                          child: Text(device.label),
                                          onPressed: () {
                                            _room.changeMic(device);
                                            Navigator.pop(context);
                                          },
                                        ),
                                      )
                                      .toList(),
                                )
                              : const Text("No Microphone Devices found."),
                          //highlight-end
                        )
                      ],
                    ),
                  ),
                )
              }),
    ]);
  }
}
``` 

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [getAudioDevices()](/flutter/api/sdk-reference/videosdk-class/methods#getaudiodevices)
- [changeMic()](/flutter/api/sdk-reference/room-class/methods#changemic)


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Change Audio Output Device - Flutter

During the meeting at any point a participant wishes to switch his/her output audio like from headphones to speaker, it can be done using the below mentioned methods.

### Getting Output Device

`getAudioOutputDevices()` method will help you to list down all possible connected audio devices which will return a list of `MediaDeviceInfo` objects.

`MediaDeviceInfo` will contain the `deviceId` and `label` for the device.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ElevatedButton(
          child: Text("Get Output Device"),
          onPressed: () => {
            List<MediaDeviceInfo> outputDevice = _room.getAudioOutputDevices()
            log(outputDevice);
        }),
    //highlight-end
      ]
    );
  }
}
```

### Switching Audio Device

You can switch the audio output device by using the `switchAudioOutput()` which will take the `MediaDeviceInfo` object as parameter to which you want to switch the audio output.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        ElevatedButton(
          child: Text("Change Output Device"),
          onPressed: () => {
            showDialog(
              context: context,
              builder: (context) => AlertDialog(
                title: const Text("Select Audio Device"),
                content: Column(
                  mainAxisAlignment: MainAxisAlignment.center,
                  mainAxisSize: MainAxisSize.min,
                  children: <Widget>[
                    SingleChildScrollView(
                      reverse: true,
                      //highlight-start
                      child: Column(
                        children: _room
                            .getAudioOutputDevices()
                            .map(
                              (device) => ElevatedButton(
                                child: Text(device.label),
                                onPressed: () => {
                                  _room.switchAudioDevice(device),
                                  Navigator.pop(context)
                                },
                              ),
                            )
                            .toList(),
                      ),
                      //highlight-end
                    )
                  ],
                ),
              ),
            );
        }),
      ]
    );
  }
}
```

:::note

`EARPIECE` is not supported whenever `WIRED_HEADSET` or `BLUETOOTH` device is connected.

:::

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [getAudioOutputDevice()](/flutter/api/sdk-reference/room-class/methods#getaudiooutputdevices)
- [switchAudioDevice()](/flutter/api/sdk-reference/room-class/methods#switchaudiodevice)


---

# Change Audio Output Device - Flutter

During the meeting at any point a participant wishes to switch his/her output audio like from headphones to speaker, it can be done using the below mentioned methods.

:::important
This feature works for input and output device on **Mobile** apps, and for output device on **Web** and **Desktop** apps.
:::


### `getAudioDevices()`

- The `getAudioDevices()` method will help you to list down all possible connected audio output devices which will return a list of `AudioDeviceInfo` objects.

- The `AudioDeviceInfo` object will contain the `deviceId` , `kind` , `groupId` and `label` for the device.

### `switchAudioDevice()`

- After selecting the desired device, you can switch the audio output by passing the corresponding `AudioDeviceInfo` object as a parameter to the `switchAudioDevice()` method.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  const MeetingScreen({Key? key}) : super(key: key);

  @override
  _MeetingScreenState createState() => _MeetingScreenState();
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;
  List<AudioDeviceInfo>? speakers = [];

  @override
  void initState() {
    super.initState();
    fetchSpeakers();
  }

  void fetchSpeakers() async {
    List<AudioDeviceInfo>? audioDevices = await VideoSDK.getAudioDevices();
      for (AudioDeviceInfo device in audioDevices!) {
        if (device.kind == 'audiooutput') {
          speakers?.add(device);
        }
      }
    setState(() {});
  }

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      ElevatedButton(
          child: const Text("Change Audio Device"),
          onPressed: () => {
                showDialog(
                  context: context,
                  builder: (context) => AlertDialog(
                    title: const Text("Select Audio Device"),
                    content: Column(
                      mainAxisAlignment: MainAxisAlignment.center,
                      mainAxisSize: MainAxisSize.min,
                      children: <Widget>[
                        SingleChildScrollView(
                          reverse: true,
                          child: speakers != null && speakers!.isNotEmpty
                              ? Column(
                                  children: speakers!
                                      .map(
                                        (device) => ElevatedButton(
                                          child: Text(device.label),
                                          onPressed: () {
                                            _room.switchAudioDevice(device);
                                            Navigator.pop(context);
                                          },
                                        ),
                                      )
                                      .toList(),
                                )
                              : const Text("No Speaker Devices found."),
                        )
                      ],
                    ),
                  ),
                )
              }),
    ]);
  }
}
```

:::note

For iOS devices:
- `EARPIECE` is not supported whenever `WIRED_HEADSET` or `BLUETOOTH` device is connected.
- `WIRED_HEADSET` and `BLUETOOTH` devices are not supported simultaneously. Priority is given to the most recently connected device.

:::

:::caution
On the web, the `microphone` will now be `muted` when the input audio device is `disconnected`. Users will need to `unmute` it to continue.
:::

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [getAudioDevices()](/flutter/api/sdk-reference/videosdk-class/methods#getaudiodevices)
- [switchAudioDevice()](/flutter/api/sdk-reference/room-class/methods#switchaudiodevice)


---

# Change Video Input Device - Flutter

During the meeting at any point a participant wishes to switch his/her input video device, it can be done using the below mentioned methods.

### `getVideoDevices()` 

- This method of the `VideoSDK` class will give you the list of all the available cameras which can be shown in a list.

- This method will return an array of `VideoDeviceInfo` which will contain the `deviceId` , `label` , `kind` and `groupId` of the camera input devices.

### `changeCam()`

- After selecting the desired device, you can switch the camera input by passing the corresponding `VideoDeviceInfo` object as a parameter to the `changeCam()` method.

#### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  const MeetingScreen({Key? key}) : super(key: key);

  @override
  _MeetingScreenState createState() => _MeetingScreenState();
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;
  List<VideoDeviceInfo>? cameras = [];

  @override
  void initState() {
    super.initState(); 
    fetchCameras();
  }

  void fetchCameras() async {
    cameras = await VideoSDK.getVideoDevices();
    setState(() {});  
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        ElevatedButton(
          child: const Text("Change Camera"),
          onPressed: () {
            showDialog(
              context: context,
              builder: (context) => AlertDialog(
                title: const Text("Select Camera Device"),
                content: Column(
                  mainAxisAlignment: MainAxisAlignment.center,
                  mainAxisSize: MainAxisSize.min,
                  children: <Widget>[
                    SingleChildScrollView(
                      reverse: true,
                      //highlight-start
                      child: cameras != null && cameras!.isNotEmpty
                          ? Column(
                              children: cameras!.map(
                                (device) => ElevatedButton(
                                  child: Text(device.label),
                                  onPressed: () {
                                    _room.changeCam(device);
                                    Navigator.pop(context);
                                  },
                                ),
                              ).toList(),
                            )
                          : const Text("No Camera Devices found."),
                      //highlight-end
                    ),
                  ],
                ),
              ),
            );
          },
        ),
      ],
    );
  }
}
``` 

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [getVideoDevices](/flutter/api/sdk-reference/videosdk-class/methods#getvideodevices)
- [changeCam()](/flutter/api/sdk-reference/room-class/methods#changecam)


---

---
title: Image Capturer | Video SDK
hide_title: true
hide_table_of_contents: false
description: Stream Image Capturer.
sidebar_label: Image Capturer
pagination_label: Image Capturer
keywords:
  - image capturer
  - stream image capturer
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: image-capturer
--- 

# Image Capturer - Flutter

This guide provides instructions on capturing images of participants from a video stream. 

This capability proves particularly valuable in Video KYC scenarios, enabling the capture of images where users can hold up their identity for verification.

### `captureImage()`

- By using the `captureImage()` method of the `Participant` class, you can capture image of a local participant from their video stream.
- You have the option to specify the desired height and width in the `captureImage()` method; however, these parameters are optional. If not provided, the VideoSDK will automatically use the dimensions of the local participant's webcamStream. 
- The `captureImage()` function returns the image in the form of a `base64` string.

```js
void imageCapture() async {
    // captureImage will return base64 string
    String? base64 = await room.localParticipant.captureImage(
        height: 400, 
        width: 400,
    );
    print("Base64 Image captured $base64Image");
}
```

### How to capture image of a remote participant ?

- Before proceeding, it's crucial to understand [VideoSDK's temporary file storage system](/flutter/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/upload-fetch-temporary-file) and the underlying [pubsub mechanism](/flutter/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

- Here's a break down of the steps, using the names Participant A and Participant B for clarity:

#### Step 1 : Initiate Image Capture Request

- In this step, you have to first send a request to Participant B, whose image you want to capture, using pubsub.
- In order to do that, you have to publish a message. Here, `IMAGE_CAPTURE` pubsub topic is used.
- Also, you will be using the `sendOnly` property of the `PubSubPublishOptions` class. Therefore, the request will be sent to that participant only.

```js
class MeetingScreen extends StatefulWidget {
    const MeetingScreen({Key? key}) : super(key: key);

    @override
    _MeetingScreenState createState() => _MeetingScreenState();
}

class _MeetingScreenState extends State<MeetingScreen> {
    late Room _room;

    // send Request to participant
    void sendRequest(String participantId) {
        // Pass the participantId of the participant whose image you want to capture
        // Here, it will be Participant B's id, 
        // as you want to capture the the image of Participant B
        if (participantId != meeting.localParticipant.id) {
            var publishOptions = PubSubPublishOptions(
                persist: false,
                sendOnly: [participantId],
            );
            // create pubsub topic to send Request
            _room.pubSub.publish(
                "IMAGE_CAPTURE",
                "Sending request to capture image",
                publishOptions,
            );
        }
    }

    @override
    Widget build(BuildContext context) {
        return Column(children: [
            ElevatedButton(
                onPressed: () { 
                    sendRequest("enter the participant ID to send image capture request");
                },
                child: Text("Capture Image"),
            ),
        ]);
    }
}
```

#### Step 2 : Capture and Upload File

- To capture an image from a remote participant [Participant B] . you need to subscribe to a topic called `IMAGE_CAPTURE`. When you receive an image capture request, you will capture the image using the `captureImage()` method of the `Participant` class.

```js
class MeetingScreen extends StatefulWidget {
    const MeetingScreen({Key? key}) : super(key: key);

    @override
    _MeetingScreenState createState() => _MeetingScreenState();
}

class _MeetingScreenState extends State<MeetingScreen> {
    late Room _room;

    void messageHandler(PubSubMessage message) {
        if (message.senderId != _room.localParticipant.id) {
            captureAndStoreImage(message.senderId);
        }
    }
    
    // capture and store image when message received
    void captureAndStoreImage(String senderId) async {

        // capture image
        String? base64Data = await _room.localParticipant.captureImage(
            height: 400,
            width: 400,
        );
        print("base64Data : $base64Data");
    }
    
    // subscribe to receive request
    void registerMeetingEvents(Room _room) {
        _room.on(
            Events.roomJoined,
            () async {
                _room.pubSub.subscribe("IMAGE_CAPTURE", messageHandler);
            },
        );
    }
}
```

- The captured image is then stored in VideoSDK's temporary file storage system using the `uploadBase64File()` function of the `Room` class. This operation returns a unique `fileUrl` of the stored image.


```js
void captureAndStoreImage(String senderId) async {
    // capture image
    String? base64Data = await meeting.localParticipant.captureImage(
        height: 400,
        width: 400,
    );

    String token = "<VIDEOSDK_TOKEN>";
    String fileName = "myCapture.jpeg"; // specify a name for image file with extension

    // upload image to videosdk storage system
    String? url = await meeting.uploadBase64File(
        base64Data: base64Data!,
        token: token,
        fileName: fileName,
    );
    print("Image URL: $url");
}
```

- Next, the `fileUrl` is sent back to the participant who initiated the request using the `IMAGE_TRANSFER` topic.

```js
void captureAndStoreImage(String senderId) async {

    String? base64Data = await meeting.localParticipant.captureImage(
        height: 400,
        width: 400,
    );

    String token = "<VIDEOSDK_TOKEN>";
    String fileName = "myCapture.jpeg";

    String? url = await meeting.uploadBase64File(
        base64Data: base64Data!,
        token: token,
        fileName: fileName,
    );

    // publish image Transfer
    PubSubPublishOptions options = PubSubPublishOptions(
        persist: false,
        sendOnly: [senderId],
    );
    
    meeting.pubSub.publish(
        "IMAGE_TRANSFER",
        url!,
        options,
    );
}
```

#### Step 3 : Fetch and Display Image

- To display a captured image, the `showCapturedImage()` method is used. Here's how it works:

- Within the `showCapturedImage()` method, subscribe to the `IMAGE_TRANSFER` topic to receive the `fileUrl` associated with the captured image.

- Once the `fileUrl` is obtained, use the `fetchBase64File()` method from the `Room` class to retrieve the file in `base64` format from VideoSDK's temporary storage.

```js
void showCapturedImage() async {
    PubSubMessages messages = await meeting.pubSub.subscribe(
        "IMAGE_TRANSFER",
        (PubSubMessage message) async {
            if (message.senderId != meeting.localParticipant.id) {
                String url = message.message;
                String token = "<VIDEOSDK_TOKEN>";

                String? base64 = await meeting.fetchBase64File(
                    url: url,   // pass fileUrl to fetch the file
                    token: token,
                );

                print("base64 $base64");  // here is your image in the form of base64
            }
        },
    );
}
```

- With the `base64` data in hand. we can convert it into `Uint8List` using Dart's `base64Decode()` method. This `Uint8List` can then be used to render the image on the screen using `Image.memory()` widget.

```js
class MeetingScreen extends StatefulWidget {
    const MeetingScreen({Key? key}) : super(key: key);

    @override
    _MeetingScreenState createState() => _MeetingScreenState();
}

class _MeetingScreenState extends State<MeetingScreen> {

    Uint8List? _capturedImage;
    
    void showCapturedImage() async {
        PubSubMessages messages = await meeting.pubSub.subscribe(
            "IMAGE_TRANSFER",
            (PubSubMessage message) async {
                if (message.senderId != meeting.localParticipant.id) {
                    String url = message.message;
                    String token = "<VIDEOSDK_TOKEN>";

                    String? base64 = await meeting.fetchBase64File(
                        url: url,   // pass fileUrl to fetch the file
                        token: token,
                    );
                    
                    // set state to set _capturedImage to the obtain base64 string
                    setState(() {
                        _capturedImage = base64Decode(base64!);
                    });
                }
            },
        );
    }

    @override
    Widget build(BuildContext context) {
        return Scaffold(
        appBar: AppBar(title: const Text("Captured Image")),
            body: Center(
                // Display the image
                child: _capturedImage != null
                    ? Image.memory(_capturedImage!)
                    : const Text("Waiting for image..."),
            ),
        );
    }
}
```

:::note

The file stored in the system will be automatically deleted once the current room/meeting comes to an end.

:::

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [captureImage()](/flutter/api/sdk-reference/participant-class/methods#captureimage)
- [pubSub()](/flutter/api/sdk-reference/pubsub-class/introduction)
- [uploadBase64File()](/flutter/api/sdk-reference/room-class/methods#uploadbase64file)
- [fetchBase64File()](/flutter/api/sdk-reference/room-class/methods#fetchbase64file)

---

# Mute / Unmute Mic - Flutter

Muting and Unmuting your microphone refers to turning your microphone off and on, respectively.

When you mute your microphone, you prevent any sound from your microphone from being transmitted to other meeting participants, while unmuting it allows others to hear you.

### `unmuteMic()`

- By using `unmuteMic()` function of `Room` object, local participant can publish audio to other participants.

  - You can call this method when the local participant is not broadcasting any audio to others.

- You can pass customised audio track in `unmuteMic()` by using [Custom Audio Track](/flutter/guide/video-and-audio-calling-api-sdk/render-media/optimize-audio-track).

- Audio stream of the participant can be accessed from the `streams` property of `Participant` object.

### `muteMic()`

- By using `muteMic()` function of `Room` object, local participant can stop publish audio to other participants.

- You can call this method when the local participant is broadcasting any audio to others.

#### Example

```jsx
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ElevatedButton(
          onPressed:(){
            _room.unmuteMic();
          },
          child: const Text("Unmute Mic"),
        ),
        ElevatedButton(
          onPressed:(){
            _room.muteMic();
          },
          child: const Text("Mute Mic"),
        ),
    //highlight-end
      ]
    );
  }
}
```

### Getting Participant Mic Status

- You can get the **local participant's** media status by going through the `stream` Map of the `Participant` object.
- If `stream` contains a value where `kind` is `audio` then the participant's microphone is active else it is disabled.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;
  const ParticipantTile({super.key, required this.participant});

  @override
  State<ParticipantTile> createState() => _ParticipantTileState();
}

class _ParticipantTileState extends State<ParticipantTile> {
  Stream? audioStream;

  @override
  void initState() {
    //highlight-start
    // initial video stream for the participant
    //Check if camera stream is already present
    widget.participant.streams.forEach((key, Stream stream) {
      setState(() {
        if (stream.kind == 'audio') {
          audioStream = stream;
        }
      });
    });
    //highlight-end

    _initStreamListeners();
    super.initState();
  }

  //highlight-start
  //Change state according to the events received
  _initStreamListeners() {
    widget.participant.on(Events.streamEnabled, (Stream stream) {
      if (stream.kind == 'audio') {
        setState(() => audioStream = stream);
      }
    });

    widget.participant.on(Events.streamDisabled, (Stream stream) {
      if (stream.kind == 'audio') {
        setState(() => audioStream = null);
      }
    });
  }
  //highlight-end

  @override
  Widget build(BuildContext context) {
    return Padding(
      padding: const EdgeInsets.all(8.0),
      child: Text("Current Mic status of ${widget.participant.displayName} is ${audioStream !=null ? "Active": "Disable"}")
    );
  }
}
```

### Events associated with unmuteMic

- Every Participant will receive a callback on [`Events.streamEnabled`](/flutter/api/sdk-reference/participant-class/events#streamenabled) of the [`Participant`](/flutter/api/sdk-reference/participant-class/introduction) object with `Stream` object.

### Events associated with muteMic

- Every Participant will receive a callback on [`Events.streamDisabled`](/flutter/api/sdk-reference/participant-class/events#streamdisabled) of the [`Participant`](/flutter/api/sdk-reference/participant-class/introduction) object with `Stream` object.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;
  ...
}

class _ParticipantTileState extends State<ParticipantTile> {

  @override
  void initState() {
    ...

    //highlight-next-line
    _initStreamListeners();
    super.initState();
  }

  //highlight-start
  //Change state according to the events received
  _initStreamListeners() {
    widget.participant.on(Events.streamEnabled, (Stream stream) {
      if (stream.kind == 'audio') {
        //Mic Turned On
      }
    });

    widget.participant.on(Events.streamDisabled, (Stream stream) {
      if (stream.kind == 'audio') {
        //Mic Turned Off
      }
    });
  }
  //highlight-end

  @override
  Widget build(BuildContext context) {
    return YourParticipantWidget();
  }
}
```

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [unmuteMic()](/flutter/api/sdk-reference/room-class/methods#unmutemic)
- [muteMic()](/flutter/api/sdk-reference/room-class/methods#mutemic)
- [Events.streamEnabled](/flutter/api/sdk-reference/participant-class/events#streamenabled)
- [Events.streamDisabled](/flutter/api/sdk-reference/participant-class/events#streamdisabled)


---

# On / Off Camera - Flutter

Any participant can turn on or off his camera in the meeting using below methods.

### `enableCam()`

- By using `enableCam()` function of `Room` object, local participant can publish video to other participants.

- You can call this method when the local participant is not broadcasting any video to others.

- You can pass customised video track in `enableCam()` by using [Custom Video Track](/flutter/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track).

- Video stream of the participant can be accessed from the `streams` property of `Participant` object.

### `disableCam()`

- By using `disableCam()` function of `Room` object, local participant can stop publish video to other participants.

- You can call this method when the local participant is broadcasting any video to others.

#### Example

```jsx
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ElevatedButton(
          onPressed:(){
            _room.enableCam();
          },
          child: const Text("Enable Camera"),
        ),
        ElevatedButton(
          onPressed:(){
            _room.disableCam();
          },
          child: const Text("Disable Camera"),
        ),
    //highlight-end
      ]
    );
  }
}
```

:::note
To learn, how to render video in the meeting, follow this detailed [guide](/flutter/guide/video-and-audio-calling-api-sdk/render-media/display-video#2-rendering-video).
:::

### Getting Participant Camera Status

- You can get the **local participant's** media status by going through the `stream` Map of the `Participant` object.
- If `stream` contains a value where `kind` is `video` then the participant's camera is active else it is disabled.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;
  const ParticipantTile({super.key, required this.participant});

  @override
  State<ParticipantTile> createState() => _ParticipantTileState();
}

class _ParticipantTileState extends State<ParticipantTile> {
  Stream? videoStream;

  @override
  void initState() {
    //highlight-start
    // initial video stream for the participant
    //Check if camera stream is already present
    widget.participant.streams.forEach((key, Stream stream) {
      setState(() {
        if (stream.kind == 'video') {
          videoStream = stream;
        }
      });
    });
    //highlight-end

    _initStreamListeners();
    super.initState();
  }

  //highlight-start
  //Change state according to the events received
  _initStreamListeners() {
    widget.participant.on(Events.streamEnabled, (Stream stream) {
      if (stream.kind == 'video') {
        setState(() => videoStream = stream);
      }
    });

    widget.participant.on(Events.streamDisabled, (Stream stream) {
      if (stream.kind == 'video') {
        setState(() => videoStream = null);
      }
    });
  }
  //highlight-end

  @override
  Widget build(BuildContext context) {
    return Padding(
      padding: const EdgeInsets.all(8.0),
      child: Text("Current Camera status of ${widget.participant.displayName} is ${videoStream !=null ? "Active": "Disable"}")
    );
  }
}
```

### Events associated with enableCam

- Every Participant will receive a callback on [`Events.streamEnabled`](/flutter/api/sdk-reference/participant-class/events#streamenabled) of the [`Participant`](/flutter/api/sdk-reference/participant-class/introduction) object with `Stream` object.

### Events associated with disableCam

- Every Participant will receive a callback on [`Events.streamDisabled`](/flutter/api/sdk-reference/participant-class/events#streamdisabled) of the [`Participant`](/flutter/api/sdk-reference/participant-class/introduction) object with `Stream` object.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;
  ...
}

class _ParticipantTileState extends State<ParticipantTile> {

  @override
  void initState() {
    ...

    //highlight-next-line
    _initStreamListeners();
    super.initState();
  }

  //highlight-start
  //Change state according to the events received
  _initStreamListeners() {
    widget.participant.on(Events.streamEnabled, (Stream stream) {
      if (stream.kind == 'video') {
        //Camera Turned On
      }
    });

    widget.participant.on(Events.streamDisabled, (Stream stream) {
      if (stream.kind == 'video') {
        //Camera Turned Off
      }
    });
  }
  //highlight-end

  @override
  Widget build(BuildContext context) {
    return YourParticipantWidget();
  }
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [enableCam()](/flutter/api/sdk-reference/room-class/methods#enablecam)
- [disableCam()](/flutter/api/sdk-reference/room-class/methods#disablecam)
- [Events.streamEnabled](/flutter/api/sdk-reference/participant-class/events#streamenabled)
- [Events.streamDisabled](/flutter/api/sdk-reference/participant-class/events#streamdisabled)


---

# Screen Share for Desktop apps - Flutter

Screen sharing in a meeting is the process of sharing your device screen with other participants in the meeting. It allows everyone in the meeting to see exactly what you are seeing on your screen, which can be helpful for presentations, demonstrations, or collaborations.

### `getScreenShareSources()`

- `getScreenShareSources()` method will help you to list down all available screens and opened windows.

- This method will return a list of `DesktopCapturerSource` objects which will contain the `name`, `thumbnail` and `type` for the source.

#### Example

```javascript
meeting.getScreenShareSources().then((value) => print("Sources : $value"));
```

### `enableScreenShare()`

- By using `enableScreenShare()` function of `Room` object, local participant can share his/her screen or window to other participants.

- `enableScreenShare()` will take the `DesktopCapturerSource` object as parameter to which you want to share the particular source(screen or window).

- Screen Share stream of the participant can be accessed from the `streams` property of `Participant` object.

### `disableScreenShare()`

- By using `disableScreenShare()` function of `Room` object, local participant can stop sharing his/her screen or window to other participants.

### Example

#### Step 1 : Create source selection dialogue

- Create dialog box for selecting a screen or window to share during a meeting. It retrieves the available sources using `getScreenShareSources()` method, allows the user to select a source, and provides buttons to share or cancel the selection.

```jsx title="screen_select_dialog.dart"
import 'package:flutter/material.dart';
import 'package:videosdk_webrtc/flutter_webrtc.dart';
import 'package:videosdk/videosdk.dart';
import 'tab_widget.dart';

// ignore: must_be_immutable
class ScreenSelectDialog extends Dialog {
  ScreenSelectDialog({Key? key, required this.room}) : super(key: key) {
    // get all available screen sources
    //highlight-next-line
    room.getScreenShareSources().then((value) => _setSources(value));
  }

  void _setSources(List

</center>

#### Step 2 : Pass selected source to `enableScreenShare()` method

- Show the screen sharing source selection dialogue that we created in step 1 and start screenShare by using the `_room.enableScreenShare()` method with the chosen source.

```jsx title="meeting_screen.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
import 'screen_select_dialog.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State

</div>

<br/>

:::note

If you do not pass a `DesktopCapturerSource` object to the `enableScreenShare()` method, by default SDK will choose your entire screen to share.

:::

### Rendering Screen Share Stream

1. To render the screenshare, you will need the `participantId` who is presenting the screen, which can be found from the `presenterId` property of `Room` object.

We will listen for the `Events.presenterChanged` on `Room` object to check if some other participant starts screen share, `Events.streamEnabled` and `Events.streamDisabled` on the `localParticipant`'s object to identify if the local participant is presenting or not.

```js title="meeting_screen.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
import './screen_share_view.dart';

class MeetingScreen extends StatefulWidget {
  final String meetingId;
  final String token;

  const MeetingScreen(
      {super.key, required this.meetingId, required this.token});

  @override
  State<MeetingScreen> createState() => _MeetingScreenState();
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;
  String? _presenterId;


  @override
  void initState() {
    // create room
    _room = VideoSDK.createRoom(
      roomId: widget.meetingId,
      token: widget.token,
      displayName: "John Doe",
      micEnabled: true,
      camEnabled: true,
      defaultCameraIndex:
          1, // Index of MediaDevices will be used to set default camera
    );

    setMeetingEventListener();

    // Join room
    _room.join();

    super.initState();
  }

  // listening to meeting events
  void setMeetingEventListener() {
    _room.on(Events.roomLeft, () {
      participants.clear();
      Navigator.popUntil(context, ModalRoute.withName('/'));
    });
    //highlight-start
    //Listening if remote participant starts presenting
    _room.on(Events.presenterChanged, (String? presenterId) {
      setState(() => {_presenterId = presenterId});
    });

    //Listening if local participant starts presenting
    _room.localParticipant.on(Events.streamEnabled, (Stream stream) {
      if (stream.kind == "share") {
        setState(() => {_presenterId = _room.localParticipant.id});
      }
    });

    _room.localParticipant.on(Events.streamDisabled, (Stream stream) {
      if (stream.kind == "share") {
        setState(() => {_presenterId = null});
      }
    });
    //highlight-end
  }

  // onbackButton pressed leave the room
  Future<bool> _onWillPop() async {
    _room.leave();
    return true;
  }

  @override
  Widget build(BuildContext context) {
    return WillPopScope(
      onWillPop: () => _onWillPop(),
      child: Scaffold(
        appBar: AppBar(
          title: const Text('VideoSDK QuickStart'),
        ),
        body: Padding(
          padding: const EdgeInsets.all(8.0),
          child: Column(
            children: [
              Text(widget.meetingId),
              //highlight-start
              //we will render the screenshare view if the presenterId is not null
              if (_presenterId != null)
                ScreenShareView(
                  participant: _presenterId == _room.localParticipant.id
                      ? _room.localParticipant
                      : _room.participants[_presenterId],
                ),
                //highlight-end
              ElevatedButton(
                  onPressed: () {
                    if (_presenterId != null) {
                      _room.disableScreenShare();
                    } else {
                      _room.enableScreenShare();
                    }
                  },
                  child: const Text('Toggle Screnshare')),
            ],
          ),
        ),
      ),
    );
  }
}

```

2. Now that we know if there is an active presenter, let us get the screen share stream from the `Participant` object and render it.

```js title="screen_share_view.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ScreenShareView extends StatelessWidget {
  final Participant? participant;

  ScreenShareView({super.key, required this.participant}) {
    //highlight-start
  //intialize the shareStream
    participant?.streams.forEach((key, value) {
      if (value.kind == "share") {
        shareStream = value;
      }
    });
    //highlight-end
  }
  Stream? shareStream;

  @override
  Widget build(BuildContext context) {
    return Container(
      color: Colors.grey.shade800,
      height: 300,
      width: 200,
      //highlight-start
      //show the screen share stream
      child: shareStream != null
          ? RTCVideoView(
              shareStream?.renderer as RTCVideoRenderer,
              objectFit: RTCVideoViewObjectFit.RTCVideoViewObjectFitCover,
            )
          : null,
          //highlight-end
    );
  }
}
```

### Events associated with enableScreenShare

- Every Participant will receive a callback on [`Events.streamEnabled`](/flutter/api/sdk-reference/participant-class/events#streamenabled) of the [`Participant`](/flutter/api/sdk-reference/participant-class/introduction) object with `Stream` object.

- Every Remote Participant will receive [`Events.presenterChanged`](/flutter/api/sdk-reference/room-class/events#presenterchanged) callback on the [`Room`](/flutter/api/sdk-reference/room-class/introduction) object with the participantId as `presenterId` who started the screen share.

### Events associated with disableScreenShare

- Every Participant will receive a callback on [`Events.streamDisabled`](/flutter/api/sdk-reference/participant-class/events#streamdisabled) of the [`Participant`](/flutter/api/sdk-reference/participant-class/introduction) object with `Stream` object.

- Every Remote Participant will receive [`Events.presenterChanged`](/flutter/api/sdk-reference/room-class/events#presenterchanged) callback on the [`Room`](/flutter/api/sdk-reference/room-class/introduction) object with the `presenterId` as `null`.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;
  ...
}

class _ParticipantTileState extends State<ParticipantTile> {

  @override
  void initState() {
    ...

    //highlight-next-line
    _initStreamListeners();
    super.initState();
  }

  //highlight-start
  //Change state according to the events received
  _initStreamListeners() {
    widget.participant.on(Events.streamEnabled, (Stream stream) {
      if (stream.kind == 'share') {
        //Screen share Turned On
      }
    });

    widget.participant.on(Events.streamDisabled, (Stream stream) {
      if (stream.kind == 'share') {
        //Screen Share Turned Off
      }
    });
  }
  //highlight-end

  @override
  Widget build(BuildContext context) {
    return YourParticipantWidget();
  }
}

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    ...

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {

    room.on(Events.presenterChanged, (String? presenterId) {
      //Room screen presenter has changed
      //Participant ID of current presenter is presenterId
    });
  }
  //highlight-end
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [enableScreenShare()](/flutter/api/sdk-reference/room-class/methods#enablescreenshare)
- [disableScreenShare()](/flutter/api/sdk-reference/room-class/methods#disablescreenshare)
- [Events.streamEnabled](/flutter/api/sdk-reference/participant-class/events#streamenabled)
- [Events.streamDisabled](/flutter/api/sdk-reference/participant-class/events#streamdisabled)


---

# Screen Share - Flutter

Screen sharing in a meeting is the process of sharing your device screen with other participants in the meeting. It allows everyone in the meeting to see exactly what you are seeing on your screen, which can be helpful for presentations, demonstrations, or collaborations.

### Screen Share feature Compatibility

| Android and iOS app                   | Web                                   | Desktop app                           | Safari browser         |
| ------------------------------------- | ------------------------------------- | ------------------------------------- | ---------------------- |
| <center> :white_check_mark: </center> | <center> :white_check_mark: </center> | <center> :white_check_mark: </center> | <center> :x: </center> |

### `enableScreenShare()`

- By using `enableScreenShare()` function of `Room` object, local participant can share his/her screen or window to other participants.

- Screen Share stream of the participant can be accessed from the `streams` property of `Participant` object.

- To enable Screenshare in Android devices, you need to provide the following permissions in `AndroidManifest.xml`.

### System Audio with Screen Share (Android Only)

- System Audio Sharing during screen sharing, allowing users to share both the screen and the audio from their device simultaneously.

- `Bool enableAudio`: In the `enableScreenShare()` method, the second parameter, `enableAudio`, is a flag that controls whether system audio is shared. Set it to `true` to include system audio with the screen share, or `false` to share only the screen without audio.

- Ensure that you request the necessary permissions (`android.permission.RECORD_AUDIO`) for screen sharing and system audio capture on the user's device. The required permissions may vary based on the Android version and device manufacturer.

- Devices running `Android 9` (`API Level 28`) or below will not support the System Audio sharing feature.

:::note
System audio will only be shared if the microphone is enabled. If the microphone is muted, the system audio will also be muted.
:::


```js title="AndroidManifest.xml"
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
//For Android devices versioned 14 and above.
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.CAPTURE_VIDEO_OUTPUT" />
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
```

### `disableScreenShare()`

- By using `disableScreenShare()` function of `Room` object, local participant can stop sharing his/her screen or window to other participants.

```jsx
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ElevatedButton(
          onPressed:(){
            if(!kIsWeb && Platform.isAndroid){
              _room.enableScreenShare(enableAudio: true); // Enable screen share with audio on Android
            }else{
              _room.enableScreenShare(); // Enable screen share without audio on other platforms
            }
          },
          child: const Text("Enable Screen Share"),
        ),
        ElevatedButton(
          onPressed:(){
            _room.disableScreenShare(); // Disable screen share
          },
          child: const Text("Disable Screen Share"),
        ),
    //highlight-end
      ]
    );
  }
}
```

:::important
To ensure that the microphone and camera work in the background, you must implement [background modes](./background-handling)
:::


### iOS Setup

:::note

For Flutter iOS Screen Share feature, you need to follow this guide [Flutter iOS Screen Share](/flutter/guide/video-and-audio-calling-api-sdk/extras/flutter-ios-screen-share)

:::


### Rendering Screen Share Stream

1. To render the screenshare, you will need the `participantId` who is presenting the screen, which can be found from the `presenterId` property of `Room` object.

We will listen for the `Events.presenterChanged` on `Room` object to check if some other participant starts screen share, `Events.streamEnabled` and `Events.streamDisabled` on the `localParticipant`'s object to identify if the local participant is presenting or not.

```js title="meeting_screen.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
import './screen_share_view.dart';

class MeetingScreen extends StatefulWidget {
  final String meetingId;
  final String token;

  const MeetingScreen(
      {super.key, required this.meetingId, required this.token});

  @override
  State<MeetingScreen> createState() => _MeetingScreenState();
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;
  String? _presenterId;


  @override
  void initState() {
    // create room
    _room = VideoSDK.createRoom(
      roomId: widget.meetingId,
      token: widget.token,
      displayName: "John Doe",
      micEnabled: true,
      camEnabled: true,
      defaultCameraIndex:
          1, // Index of MediaDevices will be used to set default camera
    );

    setMeetingEventListener();

    // Join room
    _room.join();

    super.initState();
  }

  // listening to meeting events
  void setMeetingEventListener() {
    _room.on(Events.roomLeft, () {
      participants.clear();
      Navigator.popUntil(context, ModalRoute.withName('/'));
    });
    //highlight-start
    //Listening if remote participant starts presenting
    _room.on(Events.presenterChanged, (String? presenterId) {
      setState(() => {_presenterId = presenterId});
    });

    //Listening if local participant starts presenting
    _room.localParticipant.on(Events.streamEnabled, (Stream stream) {
      if (stream.kind == "share") {
        setState(() => {_presenterId = _room.localParticipant.id});
      }
    });

    _room.localParticipant.on(Events.streamDisabled, (Stream stream) {
      if (stream.kind == "share") {
        setState(() => {_presenterId = null});
      }
    });
    //highlight-end
  }

  // onbackButton pressed leave the room
  Future<bool> _onWillPop() async {
    _room.leave();
    return true;
  }

  @override
  Widget build(BuildContext context) {
    return WillPopScope(
      onWillPop: () => _onWillPop(),
      child: Scaffold(
        appBar: AppBar(
          title: const Text('VideoSDK QuickStart'),
        ),
        body: Padding(
          padding: const EdgeInsets.all(8.0),
          child: Column(
            children: [
              Text(widget.meetingId),
              //highlight-start
              //we will render the screenshare view if the presenterId is not null
              if (_presenterId != null)
                ScreenShareView(
                  participant: _presenterId == _room.localParticipant.id
                      ? _room.localParticipant
                      : _room.participants[_presenterId],
                ),
                //highlight-end
              ElevatedButton(
                  onPressed: () {
                    if (_presenterId != null) {
                      _room.disableScreenShare();
                    } else {
                      if(!kIsWeb && Platform.isAndroid){
                        _room.enableScreenShare(enableAudio: true); // Enable screen share with audio on Android
                      }else{
                        _room.enableScreenShare(); // Enable screen share without audio on other platforms
                      }
                    }
                  },
                  child: const Text('Toggle Screnshare')),
            ],
          ),
        ),
      ),
    );
  }
}

```

2. Now that we know if there is an active presenter, let us get the screen share stream from the `Participant` object and render it.

```js title="screen_share_view.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ScreenShareView extends StatelessWidget {
  final Participant? participant;

  ScreenShareView({super.key, required this.participant}) {
    //highlight-start
  //intialize the shareStream
    participant?.streams.forEach((key, value) {
      if (value.kind == "share") {
        shareStream = value;
      }
    });
    //highlight-end
  }
  Stream? shareStream;

  @override
  Widget build(BuildContext context) {
    return Container(
      color: Colors.grey.shade800,
      height: 300,
      width: 200,
      //highlight-start
      //show the screen share stream
      child: shareStream != null
          ? RTCVideoView(
              shareStream?.renderer as RTCVideoRenderer,
              objectFit: RTCVideoViewObjectFit.RTCVideoViewObjectFitCover,
            )
          : null,
          //highlight-end
    );
  }
}
```

### Events associated with enableScreenShare

- Every Participant will receive a callback on [`Events.streamEnabled`](/flutter/api/sdk-reference/participant-class/events#streamenabled) of the [`Participant`](/flutter/api/sdk-reference/participant-class/introduction) object with `Stream` object.

- Every Remote Participant will receive [`Events.presenterChanged`](/flutter/api/sdk-reference/room-class/events#presenterchanged) callback on the [`Room`](/flutter/api/sdk-reference/room-class/introduction) object with the participantId as `presenterId` who started the screen share.

### Events associated with disableScreenShare

- Every Participant will receive a callback on [`Events.streamDisabled`](/flutter/api/sdk-reference/participant-class/events#streamdisabled) of the [`Participant`](/flutter/api/sdk-reference/participant-class/introduction) object with `Stream` object.

- Every Remote Participant will receive [`Events.presenterChanged`](/flutter/api/sdk-reference/room-class/events#presenterchanged) callback on the [`Room`](/flutter/api/sdk-reference/room-class/introduction) object with the `presenterId` as `null`.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;
  ...
}

class _ParticipantTileState extends State<ParticipantTile> {

  @override
  void initState() {
    ...

    //highlight-next-line
    _initStreamListeners();
    super.initState();
  }

  //highlight-start
  //Change state according to the events received
  _initStreamListeners() {
    widget.participant.on(Events.streamEnabled, (Stream stream) {
      if (stream.kind == 'share') {
        //Screen share Turned On
      }
    });

    widget.participant.on(Events.streamDisabled, (Stream stream) {
      if (stream.kind == 'share') {
        //Screen Share Turned Off
      }
    });
  }
  //highlight-end

  @override
  Widget build(BuildContext context) {
    return YourParticipantWidget();
  }
}

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    ...

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {

    room.on(Events.presenterChanged, (String? presenterId) {
      //Room screen presenter has changed
      //Participant ID of current presenter is presenterId
    });
  }
  //highlight-end
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [enableScreenShare()](/flutter/api/sdk-reference/room-class/methods#enablescreenshare)
- [disableScreenShare()](/flutter/api/sdk-reference/room-class/methods#disablescreenshare)
- [Events.streamEnabled](/flutter/api/sdk-reference/participant-class/events#streamenabled)
- [Events.streamDisabled](/flutter/api/sdk-reference/participant-class/events#streamdisabled)


---

# Known Issues - Flutter




---

https://sdk.videosdk.live/js-sdk/0.2.6/videosdk.jsVideoSDK offers a range of video streaming tools and solutions for content creators, publishers, and developers.

- A custom template is a specialized layout for a live stream that allows users to integrate real-time graphics into their broadcasts.

- With custom templates, users can enhance their video content by overlaying graphics, text, images, and animations onto their live streams. These elements can be customized to align with specific branding requirements.

- By leveraging custom templates, users can craft dynamic and engaging video experiences. Whether incorporating live scoreboards, social media feeds, or other personalized elements, users have the flexibility to create visually appealing streams that stand out and capture audience attention.

:::note

Custom templates can also be used with recordings and RTMP service provided by VideoSDK.

:::

### What you can do with Custom Template

By utilizing a custom template, you have the flexibility to create various modes for your live stream. Here are some popular modes that you can design:

- **`PK Host:`** The host can organize a player vs. player battle, as illustrated in the example of a gaming battle shown below.

![pk host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_pk_battle.png)

- **`Watermark:`** The host has the ability to add and update watermarks anywhere in the template; for instance, the image below features a VideoSDK watermark on the top right side of the screen.

![watermark host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_water_mark.png)

- **`News Mode:`** Additionally, the host can incorporate dynamic text in the lower third banner, as demonstrated by the sample text in the bottom left of the screen.

![news mode](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_news_live.png)

### Custom template with VideoSDK

In this section, we will discuss how Custom Templates work with VideoSDK.

- **`Host`**: The host initiates live streaming by providing the `templateURL`. The `templateURL` is the URL of the hosted template webpage. The host is also responsible for managing the template, including tasks such as altering text, logos, and switching template layouts.

- **`VideoSDK Template Engine`** : The VideoSDK Template Engine accepts and opens the templateURL in the browser, actively listening to all events initiated by the Host. It facilitates the customization of the template in accordance with the host's preferences.

- **`Viewer`**: Viewers can stream the content, experiencing the live stream with added real-time graphics. This feature contributes to a distinctive and engaging viewing experience.

![custom template](https://cdn.videosdk.live/website-resources/docs-resources/custom_template.png)

### Understanding Template URL

The template URL is a webpage that VideoSDK Template Engine will open while composing the live stream.

It will appear as shown below.

![template url](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_url.png)

The Template URL comprises of two essential parts:

- Your actual page URL, resembling something like `https://example.com/videosdk-template`.
- Query parameters, designed to enable the VideoSDK Template Engine to seamlessly join the meeting upon opening the URL. There are three key query parameters in total:
  - `token`: Your token, serving as the authentication key to join the meeting.
  - `meetingId`: The meeting Id of the meeting that the VideoSDK Template Engine will join.
  - `participantId`: The participant ID of the VideoSDK Template Engine. This should be included when joining the template engine in your template, ensuring that the template engine participant remains invisible to other participants. **This parameter is automatically added by the VideoSDK**.

:::info

Above mentioned query parameters are mandatory. Apart from these parameters, you can pass any other extra parameters which are required according to your use-case.

:::

### **Creating Template**

**`Step 1:`** Import VideoSDK using `<script>` tag or install it using the below-mentioned npm command.
Make sure you are in your app directory before you run this command.



**Tab:**

" label="<script>" default>

```html
<html>
  <head></head>
  <body>
// highlight-next-line
<script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
  </body>
</html>
```

---

**npm:**

```bash
npm install @videosdk.live/js-sdk
```

---

**yarn:**

```bash
yarn add @videosdk.live/js-sdk
```

:::note

You can use VideoSDK's React or JavaScript SDK to create custom template. Following is the example of building custom template with JavaScript SDK.

:::

###### Structure of the Project

```jsx title="Project Structure"
  root
   ├── index.html
   ├── index.js
```

**`Step 2:`** Craft a user interface (UI) tailored for your live stream presentation.

```html title="index.html"
<!DOCTYPE html>
<html>
  <head> </head>

  <body>
    <div id="textDiv">Starting live stream...</div>

    
    <div class="row" id="videoContainer"></div>

    <script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
    <script src="index.js"></script>
  </body>
</html>
```

**`Step 3:`** Next, fetch the query parameters, from the URL which will be later used to initialize the meeting and get the elements from DOM.

```js title=index.js
const url = window.location;
const urlParams = new URLSearchParams(url.search);

const meetingId = urlParams.get("meetingId");
const token = urlParams.get("token");
const participantId = urlParams.get("participantId");

const videoContainer = document.getElementById("videoContainer");
const textDiv = document.getElementById("textDiv");
```

**`Step 4:`** Subsequently, initialize the meeting with the parameters that were extracted from the URL. Ensure direct initialization so that the template engine seamlessly joins the meeting upon page load.

```js title=index.js
window.VideoSDK.config(token);

const meeting = window.VideoSDK.initMeeting({
  meetingId: meetingId, // required
  name: "recorder", // required
  micEnabled: false,
  webcamEnabled: false,
  participantId: participantId,
});

meeting.join();

meeting.on("meeting-joined", () => {
  textDiv.style.display = "none";
});
```

**`Step 5:`** Next step is to create the container that will render the meeting view on the `participant-joined` event.

```js title=index.js
//  participant joined
meeting.on("participant-joined", (participant) => {
  let videoElement = createVideoElement(
    participant.id,
    participant.displayName
  );
  let audioElement = createAudioElement(participant.id);

  participant.on("stream-enabled", (stream) => {
    setTrack(stream, audioElement, participant, false);
  });
  videoContainer.appendChild(videoElement);
  videoContainer.appendChild(audioElement);
});

// participants left
meeting.on("participant-left", (participant) => {
  let vElement = document.getElementById(`f-${participant.id}`);
  vElement.remove(vElement);

  let aElement = document.getElementById(`a-${participant.id}`);
  aElement.remove(aElement);
});

// creating video element
function createVideoElement(pId, name) {
  let videoFrame = document.createElement("div");
  videoFrame.setAttribute("id", `f-${pId}`);

  //create video
  let videoElement = document.createElement("video");
  videoElement.classList.add("video-frame");
  videoElement.setAttribute("id", `v-${pId}`);
  videoElement.setAttribute("playsinline", true);
  videoElement.setAttribute("width", "300");
  videoElement.muted = true;
  videoFrame.appendChild(videoElement);

  let displayName = document.createElement("div");
  displayName.innerHTML = `Name : ${name}`;
  videoFrame.appendChild(displayName);

  return videoFrame;
}

// creating audio element
function createAudioElement(pId) {
  let audioElement = document.createElement("audio");
  audioElement.setAttribute("autoPlay", "false");
  audioElement.setAttribute("playsInline", "true");
  audioElement.setAttribute("controls", "false");
  audioElement.setAttribute("id", `a-${pId}`);
  audioElement.style.display = "none";
  return audioElement;
}

// setting media track
function setTrack(stream, audioElement, participant, isLocal) {
  if (stream.kind == "video") {
    isWebCamOn = true;
    const mediaStream = new MediaStream();
    mediaStream.addTrack(stream.track);
    let videoElm = document.getElementById(`v-${participant.id}`);
    videoElm.srcObject = mediaStream;
    videoElm
      .play()
      .catch((error) =>
        console.error("videoElem.current.play() failed", error)
      );
  }
  if (stream.kind == "audio") {
    if (isLocal) {
      isMicOn = true;
    } else {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(stream.track);
      audioElement.srcObject = mediaStream;
      audioElement
        .play()
        .catch((error) => console.error("audioElem.play() failed", error));
    }
  }
}
```

**`Step 6:`** Now, listen to PubSub messages from the `CHANGE_BACKGROUND` topic, triggering a change in the meeting's background color accordingly.

:::note

The PubSub mechanism is utilized to communicate with the template. You can learn more about [PubSub from here](/javascript/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

:::

```js title=index.js
meeting.on("meeting-joined", () => {
  //  ...

  meeting.pubSub.subscribe("CHANGE_BACKGROUND", (data) => {
    let { message } = data;
    document.body.style.backgroundColor = message;
  });
});
```

**`Step 7:`** Once tested, you can deploy it using your backend or host it on services like [firebase](https://www.geeksforgeeks.org/how-to-deploy-react-project-on-firebase/) or vercel.

:::tip

You can checkout the github repository for sample custom template [created here](https://github.com/videosdk-live/videosdk-custom-recording-template-js-example).

:::

### Setup Livestream Using Custom Template

- To utilize Custom Templates with Livestream, you need to establish both the Host and Viewer setups. The Host initiates the livestream, while Viewers can watch the broadcast.

![template manager](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_manager.png)

- To understand custom templates, clone this example and run it on your system.

```bash
git clone https://github.com/videosdk-live/videosdk-custom-recording-template-js-example.git
```

- You can utilize this custom template in [Start Recording API](/api-reference/realtime-communication/start-recording), [Start HLS API](/api-reference/realtime-communication/start-hlsStream) and [Start Livestream API](/api-reference/realtime-communication/start-livestream). Here is the example of HLS.
- To utilize the custom template that has been deployed, invoke the [Start HLS API](https://docs.videosdk.live/api-reference/realtime-communication/start-hlsStream) instead of the `startHls` method from the `Meeting` class. The necessary code has already been incorporated in the cloned example above.

:::important

You can create your own custom template manager in JavaScript. In this example, we are using one for better understanding.

:::

```js
<button
  onClick={async () => {
    const url = `https://api.videosdk.live/v2/hls/start`;
    //Update your Custom Template URL here if you have deployed your own, if not deployed you can use this template from our URL.
    //highlight-next-line
    const templateUrl = `https://lab.videosdk.live/js-template-demo/?meetingId=${meetingId}&token=${authToken}`;
    const options = {
      method: "POST",
      headers: {
        Authorization: authToken,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        roomId: meetingId,
        templateUrl: templateUrl,
      }),
    };

    const result = await fetch(url, options)
      .then((response) => response.json()) // result will have playbackHlsUrl and livestreamUrl
      .catch((error) => console.error("error", error));
  }}
>
  Start HLS
</button>
```

- In this example, the host has two options on their side, enabling them to change the background and send messages to the viewers.

- Given below is a test run of the example.


<div style={{textAlign: 'center'}}>



</div>

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)
- [Start HLS API](/api-reference/realtime-communication/start-hlsStream)
- [Start Livestream API](/api-reference/realtime-communication/start-livestream)
- [recordingState](/react/api/sdk-reference/use-meeting/properties#recordingstate)
- [hlsState](/react/api/sdk-reference/use-meeting/properties#hlsstate)
- [livestreamState](/react/api/sdk-reference/use-meeting/properties#livestreamstate)
- [hlsUrls](/react/api/sdk-reference/use-meeting/properties#hlsurls)
- [onRecordingStateChanged](/react/api/sdk-reference/use-meeting/events#onrecordingstatechanged)
- [onHlsStateChanged](/react/api/sdk-reference/use-meeting/events#onhlsstatechanged)
- [onLivestreamStateChanged](/react/api/sdk-reference/use-meeting/events#onlivestreamstatechanged)



---

# Interactive Livestream (HLS) - Flutter

Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

In an interactive live stream (HLS), viewers can take part in a variety of activities like live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

<center>

![Screen Share with Audio](https://cdn.videosdk.live/website-resources/docs-resources/mobile_hls.png)

</center>

VideoSDK also allows you to configure the interactive livestream layouts in numerous ways like by simply setting different prebuilt layouts in the configuration or by providing your own custom template to do the livestream according to your layout choice.

This guide will provide an overview of how to implement start and stop Livestreaming.

### `startHls()`

`startHls()` can be used to start a interactive livestream of the meeting which can be accessed from the `Room` object. This method accepts two parameters:

- `1. config (optional)`: This parameter will define how the livestream layout should look like.

- `2. transcription (optional)`: This parameter lets you start post transcription for the Livestreaming.

  ```js
  Map<String, dynamic> config = {
    // highlight-next-line
    // Layout Configuration
    "layout": {
      "type": "GRID", // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
      "priority": "SPEAKER", // "PIN", Default : "SPEAKER"
      "gridSize": 4, // MAX : 4
    },

    // highlight-next-line
    // Theme of recording
    "theme": "DARK", //  "LIGHT" | "DEFAULT"

    // highlight-next-line
    // `mode` is used to either record video & audio both or only audio.
    "mode": "video-and-audio", // "audio", Default : "video-and-audio"

    // highlight-next-line
    // Quality of recording and is only applicable to `video-and-audio` type mode.
    "quality": "high", /* Default : "med"
   "low" (SD HLS) | "med" (HD HLS) | "high" (FHD HLS) */

    //highlight-start
    // This mode refers to orientation of recording.
    // landscape : Record the meeting in horizontally
    // portrait : Record the meeting in vertically (Best for mobile view)
    //highlight-end
    "orientation": "landscape", // "portrait",  Default : "landscape"
  };

  // highlight-next-line
  // Post Transcription Configuration
  Map<String, dynamic> transcription = {
    "enabled": true, // Enables post transcription
    "summary": {
      "enabled": true,  // Enables summary generation
       // Guides summary generation
      "prompt":
          "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    }
  };

  room.startHls(config: config, transcription: transcription);
  ```

### `stopHls()`

- `stopHls()` is used to stop the meeting livestream which can be accessed from the `Room` object.

#### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ElevatedButton(
          onPressed:(){
            Map<String, dynamic> config = {
              "layout": {
                "type": "GRID",
                "priority": "SPEAKER",
                "gridSize": 4,
              },
              "theme": "DARK",
              "mode": "video-and-audio",
              "quality": "high",
              "orientation": "portrait",
            };

            Map<String, dynamic> transcription = {
              "enabled": true,
              "summary": {
                "enabled": true,
                "prompt":
                    "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
              }
            };
            _room.startHls(config: config, transcription: transcription);
          },
          child: const Text("Start HLS"),
        ),
        ElevatedButton(
          onPressed:(){
            _room.stopHls();
          },
          child: const Text("Stop HLS"),
        ),
    //highlight-end
      ]
    );
  }
}
```

:::tip
If you want to learn more about the Interactive Livestream and how you can implement it in your own platform, you can checkout this [guide](/flutter/guide/interactive-live-streaming/integrate-hls/overview).
:::

### Event associated with HLS

- **hlsStateChanged** - Whenever meeting HLS state changes, then `hlsStateChanged` event will trigger.

- You can get the `playbackHlsUrl` and `livestreamUrl` of the HLS to play it on the Viewer side when the state changes to `HLS_PLAYABLE`
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    ...

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {
    room.on(Events.hlsStateChanged, (Map<String, dynamic> data) {
      //Status can be :: HLS_STARTING
      //Status can be :: HLS_STARTED
      //Status can be :: HLS_PLAYABLE
      //Status can be :: HLS_STOPPING
      //Status can be :: HLS_STOPPED
      log("Meeting HLS status : ${data['status']}");
      if (data['status'] == "HLS_PLAYABLE")
        log("PLAYBACKHLS URL -- " + data['playbackHlsUrl']);
    });
  }
  //highlight-end
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startHls](/flutter/api/sdk-reference/room-class/methods#starthls)
- [stopHls](/flutter/api/sdk-reference/room-class/methods#stophls)
- [Events.hlsStateChanged](/flutter/api/sdk-reference/room-class/events#hlsstatechanged)


---

# RTMP Livestream - Flutter

RTMP is a popular protocol for live streaming video content from a VideoSDK to platforms such as YouTube, Twitch, Facebook, and others.

By providing the platform-specific stream key and stream URL, the VideoSDK can connect to the platform's RTMP server and transmit the live video stream.

VideoSDK allows you to livestream your meeting to platform which support RTMP ingestion just by providing the platform-specific stream key and stream URL, we can connect to the platform's RTMP server and transmit the live video stream.

VideoSDK also allows you to configure the livestream layouts in numerous ways like by simply setting different prebuilt layouts in the configuration or by providing your own custom template to do the livestream according to your layout choice.

This guide will provide an overview of how to implement start and stop RTMP Livestreaming.

### `startLivestream()`

`startLivestream()` can be used to start a RTMP livestream of the meeting which can be accessed from the `Room` object. This method accepts three parameters:

- `1. outputs`: This parameter accepts an array of objects which contains the RTMP `url` and `streamKey` of the platforms you want to start the livestream.

- `2. config (optional)`: This parameter will define how the livestream layout should look like.

- `3. transcription (optional)`: This parameter lets you start post transcription for the recording.

  ```js
  var outputs = [
    {
      url: "rtmp://a.rtmp.youtube.com/live2",
      streamKey: "<STREAM_KEY>",
    },
    {
      url: "rtmps://",
      streamKey: "<STREAM_KEY>",
    },
  ];
  Map<String, dynamic> config = {
    // highlight-next-line
    // Layout Configuration
    layout: {
      type: "GRID", // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
      priority: "SPEAKER", // "PIN", Default : "SPEAKER"
      gridSize: 4, // MAX : 4
    },

    // highlight-next-line
    // Theme of livestream
    theme: "DARK", //  "LIGHT" | "DEFAULT"
  };

  // highlight-next-line
  // Post Transcription Configuration
  Map<String, dynamic> transcription = {
    "enabled": true, // Enables post transcription
    "summary": {
      "enabled": true,  // Enables summary generation
       // Guides summary generation
      "prompt":
          "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    }
  };

  room.startLivestream(outputs, config: config, transcription: transcription);
  ```

### `stopLivestream()`

- `stopLivestream()` is used to stop the meeting livestream which can be accessed from the `Room` object.

#### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ElevatedButton(
          onPressed:(){
            var outputs = [
              {
                url: "rtmp://a.rtmp.youtube.com/live2",
                streamKey: "<STREAM_KEY>",
              },
              {
                url: "rtmps://",
                streamKey: "<STREAM_KEY>",
              },
            ];
            var liveStreamConfig =  {
              'layout': {
                'type': 'GRID',
                'priority': 'SPEAKER',
                'gridSize': 4,
              },
              'theme': "LIGHT",
            };
            room.startLivestream(outputs, config: livestreamConfig);
          },
          child: const Text("Start Livestream"),
        ),
        ElevatedButton(
          onPressed:(){
            _room.stopLivestream();
          },
          child: const Text("Stop Livestream"),
        ),
    //highlight-end
      ]
    );
  }
}
```

### Event associated with Livestream

- **livestreamStateChanged** - Whenever meeting livestream state changes, then `livestreamStateChanged` event will trigger.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    ...

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {
    room.on(Events.livestreamStateChanged, (String status) {
      //Status can be :: LIVESTREAM_STARTING
      //Status can be :: LIVESTREAM_STARTED
      //Status can be :: LIVESTREAM_STOPPING
      //Status can be :: LIVESTREAM_STOPPED
      log("Meeting Livestream status : $status");
    });
  }
  //highlight-end
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startLivestream](/flutter/api/sdk-reference/room-class/methods#startlivestream)
- [stopLivestream](/flutter/api/sdk-reference/room-class/methods#stoplivestream)
- [Events.livestreamStateChanged](/flutter/api/sdk-reference/room-class/events#livestreamstatechanged)


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Migration Notes - Flutter

This page will guide you to migrate from previous version of Flutter SDK.

## Migration to v1.0.0 from v0.0.14

1. We have renamed `Meeting` class to `Room` class.

2. Import `package:videosdk/videosdk.dart` instead of `package:videosdk/rtc.dart`.

   For Example:

   ```js title=v0.0.14
   import "package:videosdk/rtc.dart";
   ```

   ```js title=v1.0.0
   import "package:videosdk/videosdk.dart";
   ```

3. Replace MeetingBuilder with [`VideoSDK.createRoom()`](../../api/sdk-reference/videosdk-class/methods#createroom) and [`join()`](../../api/sdk-reference/room-class/methods#join).

   For Example:

   ```js title=v0.0.14
   // MeetingBuilder
   MeetingBuilder(
      meetingId: '<MEETING_ID>',
      token: '<TOKEN>',
      displayName: '<DISPLAY_NAME>',
      micEnabled: true,
      webcamEnabled: true,
      maxResolution: 'hd',
      notification: const NotificationInfo(
         title: "Video SDK",
         message: "Video SDK is sharing screen in the meeting",
         icon: "notification_share",
      ),
      builder: (_meeting){
         // Do Something
      }
   ),

   ```

   ```js title=v1.0.0
   // Creating VideoSDK Room
   Room room = VideoSDK.createRoom(
      roomId: '<ROOM_ID>',
      token: '<TOKEN>',
      displayName: '<DISPLAY_NAME>',
      micEnabled: true,
      camEnabled: true,
      maxResolution: 'hd',
      notification: const NotificationInfo(
         title: "Video SDK",
         message: "Video SDK is sharing screen in the meeting",
         icon: "notification_share",
      ),
   );

   // Joining VideoSDK Room
   room.join();

   ```

4. Change event `Events.meetingJoined` to [`Events.roomJoined`](../../api/sdk-reference/room-class/events#roomjoined).

   For Example:

   ```js title=v0.0.14
   meeting.on(Events.meetingJoined, (){
      // Do Something
   })
   ```

   ```js title=v1.0.0
   room.on(Events.roomJoined, (){
      // Do Something
   })
   ```

5. Change event `Events.meetingLeft` to [`Events.roomLeft`](../../api/sdk-reference/room-class/events#roomleft).

   For Example:

   ```js title=v0.0.14
   meeting.on(Events.meetingLeft, (){
      // Do Something
   })
   ```

   ```js title=v1.0.0
   room.on(Events.roomLeft, (){
      // Do Something
   })
   ```

6. Change event `Events.webcamRequested` to [`Events.cameraRequested`](../../api/sdk-reference/room-class/events#camerarequested).

   For Example:

   ```js title=v0.0.14
   meeting.on(Events.webcamRequested, (){
      // Do Something
   })
   ```

   ```js title=v1.0.0
   room.on(Events.cameraRequested, (){
      // Do Something
   })
   ```

7. Change `enableMic()` method to [`unmuteMic()`](../../api/sdk-reference/participant-class/methods#unmutemic) method of [`Participant Class`](../../api/sdk-reference/participant-class/introduction).

   For Example:

   ```js title=v0.0.14
   participant.enableMic();
   ```

   ```js title=v1.0.0
   participant.unmuteMic();
   ```

8. Change `disableMic()` method to [`muteMic()`](../../api/sdk-reference/participant-class/methods#mutemic) method of [`Participant Class`](../../api/sdk-reference/participant-class/introduction).

   For Example:

   ```js title=v0.0.14
   participant.disableMic();
   ```

   ```js title=v1.0.0
   participant.muteMic();
   ```

9. Change `enableWebcam()` method to [`enableCam()`](../../api/sdk-reference/participant-class/methods#enablecam) method of [`Participant class`](../../api/sdk-reference/participant-class/introduction).

   For Example:

   ```js title=v0.0.14
   participant.enableWebcam();
   ```

   ```js title=v1.0.0
   participant.enableCam();
   ```

10. Change `disableWebcam()` method to [`disableCam()`](../../api/sdk-reference/participant-class/methods#disablecam) method of [`Participant class`](../../api/sdk-reference/participant-class/introduction).

For Example:

```js title=v0.0.14
participant.disableWebcam();
```

```js title=v1.0.0
participant.disableCam();
```

11. Change `enableWebcam()` method to [`enableCam()`](../../api/sdk-reference/room-class/methods#enablecam) method of [`Room class`](../../api/sdk-reference/room-class/introduction).

For Example:

```js title=v0.0.14
meeting.enableWebcam();
```

```js title=v1.0.0
room.enableCam();
```

12. Change `disableWebcam()` method to [`disableCam()`](../../api/sdk-reference/room-class/methods#disablecam) method of [`Room class`](../../api/sdk-reference/room-class/introduction).

For Example:

```js title=v0.0.14
meeting.disableWebcam();
```

```js title=v1.0.0
room.disableCam();
```

13. Change `getWebcams()` method to [`getCameras()`](../../api/sdk-reference/room-class/methods#getcameras) method of [`Room class`](../../api/sdk-reference/room-class/introduction).

For Example:

```js title=v0.0.14
meeting.getWebcams();
```

```js title=v1.0.0
room.getCameras();
```

14. Change `changeWebcam()` method to [`changeCam()`](../../api/sdk-reference/room-class/methods#changecam) method of [`Room class`](../../api/sdk-reference/room-class/introduction).

For Example:

```js title=v0.0.14
meeting.changeWebcam(deviceId);
```

```js title=v1.0.0
room.changeCam(deviceId);
```

15. Change `selectedWebcamId` property to [`selectedCamId`](../../api/sdk-reference/room-class/properties#selectedcamid) on [`Room class`](../../api/sdk-reference/room-class/introduction).

For Example:

```js title=v0.0.14
String webCamId = meeting.selectedWebcamId;
```

```js title=v1.0.0
String webCamId = meeting.selectedCamId;
```

---


---

# Quick Start in Flutter using BLoC


VideoSDK enables you to embed video calling functionality into your Flutter applications within minutes.

In this quick start, we’ll walk through integrating group video calling using Flutter Video SDK with BLoC for state management. You’ll learn how to architect your application using BLoCto manage state cleanly and efficiently.

This guide will get you up and running with VideoSDK’s video & audio calling along with BLoC state management in minutes.

## Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

- Video SDK Developer Account (Not having one, follow **[Video SDK Dashboard](https://app.videosdk.live/)**)
- Familiarity with Flutter and basic BLoC concepts.
- **[Flutter Video SDK](https://pub.dev/packages/videosdk)**
- Have Flutter installed on your device.

:::important

One should have a VideoSDK account to generate token.
Visit VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate token

:::

## Getting Started with the Code!

Follow the steps to create the environment necessary to add video calls into your app. Also you can find the code sample for [quickstart here](https://github.com/videosdk-live/quickstart/tree/main/flutter-rtc/quickstart_bloc).

### Create a new Flutter project.

Create a new Flutter App using the below command.

```bash
$ flutter create flutter_bloc_quickstart
```

### Install Required Dependencies

Navigate to your project directory and run the following commands to install the necessary dependencies:

```js
$ flutter pub add videosdk

//run this command to add http library to perform network call to generate roomId
$ flutter pub add http

// Add BLoC-related packages for state management
flutter pub add flutter_bloc
flutter pub add equatable
```

### Video SDK Compatibility

| Android and iOS                       | Web (Beta)                            | Desktop (Beta)                        | Safari                 |
| ------------------------------------- | ------------------------------------- | ------------------------------------- | ---------------------- |
| <center> :white_check_mark: </center> | <center> :white_check_mark: </center> | <center> :white_check_mark: </center> | <center> :x: </center> |


### Structure of the project

Your project structure should look like this.

```js title="Project Structure"
    root
    ├── android
    ├── ios
    ├── lib
         ├── bloc
         │     ├── meeting_cubit.dart
         │     └── meeting_state.dart
         ├── api_call.dart
         ├── join_screen.dart
         ├── main.dart
         ├── meeting_controls.dart
         ├── meeting_screen.dart
         └── participant_tile.dart
```

We are going to create flutter widgets (JoinScreen, MeetingScreen, MeetingControls, ParticipantTile, meeting_cubit, meeting_state).

### App Structure

App widget will contain `JoinScreen` and `MeetingScreen` widget. `MeetingScreen` will have `MeetingControls` and `ParticipantTile` widget. 

<div style={{textAlign: 'center'}}>

![VideoSDK Flutter Quick Start Architecture](https://cdn.videosdk.live/website-resources/docs-resources/flutter_quick_start_arch.png)

</div>

### Configure Project

#### For Android

- Update the `/android/app/src/main/AndroidManifest.xml` for the permissions we will be using to implement the audio and video features.

```js title="AndroidManifest.xml"
<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
<uses-permission android:name="android.permission.WAKE_LOCK" />
```
#### For iOS

- Add the following entries which allow your app to access the camera and microphone to your `/ios/Runner/Info.plist` file :

```xml
<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) Camera Usage!</string>
<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) Microphone Usage!</string>
```

- Uncomment the following line to define a global platform for your project in `/ios/Podfile` :

```js title="Podfile"
# platform :ios, '12.0'
```

#### For MacOS

- Add the following entries to your `/macos/Runner/Info.plist` file which allow your app to access the camera and microphone.

```xml
<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) Camera Usage!</string>
<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) Microphone Usage!</string>
```

- Add the following entries to your `/macos/Runner/DebugProfile.entitlements` file which allow your app to access the camera, microphone and open outgoing network connections.

```xml
<key>com.apple.security.network.client</key>
<true/>
<key>com.apple.security.device.camera</key>
<true/>
<key>com.apple.security.device.microphone</key>
<true/>
```

- Add the following entries to your `/macos/Runner/Release.entitlements` file which allow your app to access the camera, microphone and open outgoing network connections.

```xml
<key>com.apple.security.network.server</key>
<true/>
<key>com.apple.security.network.client</key>
<true/>
<key>com.apple.security.device.camera</key>
<true/>
<key>com.apple.security.device.microphone</key>
<true/>
```

### Step 1: Get started with api_call.dart

Before jumping to anything else, you will write a function to generate a unique meetingId. You will require auth token, you can generate it using either by using [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples) or generate it from the [Video SDK Dashboard](https://app.videosdk.live/api-keys) for development.

```js title="api_call.dart"
import 'dart:convert';
import 'package:http/http.dart' as http;

//Auth token we will use to generate a meeting and connect to it
//highlight-next-line
String token = "

## Run and Test

The app is all set to test. Make sure to update the `token` in `api_call.dart`

Your app should look like this after the implementation.

<div style={{textAlign: 'center'}}>



</div>

<br/>

:::caution
If you get `webrtc/webrtc.h file not found` error at a runtime in ios then check solution [here](https://docs.videosdk.live/flutter/guide/video-and-audio-calling-api-sdk/known-issues#issue--1).
:::

:::tip
You can checkout the complete [flutter bloc example here](https://github.com/videosdk-live/quickstart/tree/main/flutter-rtc/quickstart_bloc).
:::


---

# Quick Start for Interactive Live Streaming in Flutter


**VideoSDK** empowers you to seamlessly integrate **interactive live streaming** features into your React Native application in minutes. While built for LiveStream, the SDK is easily adaptable for live streaming with support for up to **100 hosts/co-hosts** and **2,000 viewers** in **real-time**. Perfect for social use cases, this guide will walk you through integrating live streaming into your app.

:::info
For standard live streaming with 6-7 second latency and playback support, follow this [documentation](./quick-start-ils.md).
:::

## Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

- Video SDK Developer Account (Not having one, follow **[Video SDK Dashboard](https://app.videosdk.live/)**)
- Basic understanding of Flutter
- **[Flutter VideoSDK](https://pub.dev/packages/videosdk)**
- Have Flutter installed on your system.

## Getting Started with the Code!

Follow the steps to create the environment necessary to add video calls into your app. Also you can find the code sample for [quickstart here](https://github.com/videosdk-live/quickstart/tree/main/interactive-live-streaming/flutter-ils).

## Create new Flutter app

Create a new Flutter App using the below command.

```bash
$ flutter create videosdk_flutter_quickstart_ils
```

## Install Video SDK

Install the VideoSDK using the below-mentioned npm command. Make sure you are in your flutter app directory before you run this command.

```bash
$ flutter pub add videosdk

//run this command to add http library to perform network call to generate roomId
$ flutter pub add http


```

## Structure of the project

Your project structure should look like this.

```jsx title="Project Structure"
  root
  ├── android
  ├── ios
  ├── lib
       ├── api_call.dart
       ├── ils_screen.dart
       ├── ils_view.dart
       ├── join_screen.dart
       ├── main.dart
       ├── liveStream_Controls.dart
       ├── participant_tile.dart
       ├── participant_grid.dart
```

We are going to create following flutter widgets JoinScreen, ILSScreen, liveStream_Controls, ParticipantTile, ILSView for the quickstart app which will cover both Host and Audience part of the app.

## App Structure

App widget will contain **JoinScreen** and **ILSScreen** screens. ILSScreen will render the **ILSView** which consist of views based on the participants mode. ILSView will have **liveStreamControls** and both view will use **ParticipantTile** which will be conditionally rendered based on the modes.

<center>
<img height="500" alt="ViewAudience" src="https://cdn.videosdk.live/website-resources/docs-resources/flutter_ils_qs_overview.png"/>
</center>

# Configure Project

## For Android

- Update the /android/app/src/main/AndroidManifest.xml for the permissions we will be using to implement the audio and video features.

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

Also you will need to set your build settings to Java 8 because the official WebRTC jar now uses static methods in EglBase interface. Just add this to your app-level /android/app/build.gradle.

```
android {
    //...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}
```

- If necessary, in the same build.gradle you will need to increase minSdkVersion of defaultConfig up to 23 (currently default Flutter generator set it to 16).
- If necessary, in the same build.gradle you will need to increase compileSdkVersion and targetSdkVersion up to 31 (currently default Flutter generator set it to 30).

## For iOS

- Add the following entries which allow your app to access the camera and microphone to your /ios/Runner/Info.plist file :

```xml title="info.plist"
<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) Camera Usage!</string>
<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) Microphone Usage!</string>
```

- Uncomment the following line to define a global platform for your project in /ios/Podfile :

```x title="Podfile"
# platform :ios, '12.0'
```

### Step 1: Get started with api_call.dart


Before jumping to anything else, you will write a function to generate a unique liveStreamId. You will require auth token, you can generate it using either by using [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples) or generate it from the [Video SDK Dashboard](https://app.videosdk.live/api-keys) for development.

- Use the **`Token`** (which you have generated from Video Sdk Dashboard) in the .env file along with that also add the **`API`** Key for creating a room.


```js title="api_call.dart"
import 'dart:convert';
import 'package:http/http.dart' as http;

//Auth token we will use to generate a liveStream and connect to it
String token = "
</div>


### Step 2: Initialize and Join the Livestream


Let's create join_screen.dart file in lib directory and create JoinScreen StatelessWidget.

The JoinScreen will consist of:

- **`Create livestream Button`**- This button will create a new livestream for Host and join it with mode CONFERENCE.
- **`livestream ID TextField`** - This text field will contain the livestream ID, you want to join.
- **`Join Livestream as Host Button`** - This button allows the user to join an existing Live Stream using the provided livestreamId with the `SEND_AND_RECV` mode, enabling full host privileges.
- **`Join livestream as Audience Button`** -Enables the user to join an existing Live Stream using the provided livestream with the `RECV_ONLY` mode, allowing view-only access.

```js title="join_screen.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
import 'api_call.dart';
import 'ils_screen.dart';

class JoinScreen extends StatelessWidget {
  final _livestreamIdController = TextEditingController();

  JoinScreen({super.key});

  //Creates new livestream Id and joins it in CONFERNCE mode.
  void onCreateButtonPressed(BuildContext context) async {
    // call api to create livestream and navigate to ILSScreen with livestreamId,token and mode
    await createLivestream().then((liveStreamId) {
      if (!context.mounted) return;
      Navigator.of(context).push(
        MaterialPageRoute(
          builder: (context) => ILSScreen(
            liveStreamId: liveStreamId,
            token: token,
            mode: Mode.SEND_AND_RECV,
          ),
        ),
      );
    });
  }

  //Join the provided livestream with given Mode and livestreamId
  void onJoinButtonPressed(BuildContext context, Mode mode) {
    // check livestream  id is not null or invaild
    // if livestream id is vaild then navigate to ILSScreen with livestreamId, token and mode
    String liveStreamId = _livestreamIdController.text;
    var re = RegExp("\\w{4}\\-\\w{4}\\-\\w{4}");
    if (liveStreamId.isNotEmpty && re.hasMatch(liveStreamId)) {
      _livestreamIdController.clear();
      Navigator.of(context).push(
        MaterialPageRoute(
          builder: (context) => ILSScreen(
            liveStreamId: liveStreamId,
            token: token,
            mode: mode,
          ),
        ),
      );
    } else {
      ScaffoldMessenger.of(context).showSnackBar(const SnackBar(
        content: Text("Please enter valid livestream id"),
      ));
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      backgroundColor: Colors.black,
      appBar: AppBar(
        title: const Text('VideoSDK ILS QuickStart'),
      ),
      body: Padding(
        padding: const EdgeInsets.all(12.0),
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            //Creating a new livestream
            ElevatedButton(
              onPressed: () => onCreateButtonPressed(context),
              child: const Text('Create LiveStream'),
            ),
            const SizedBox(height: 40),
            TextField(
              style: const TextStyle(color: Colors.white),
              decoration: const InputDecoration(
                hintText: 'Enter LiveStream Id',
                border: OutlineInputBorder(),
                hintStyle: TextStyle(color: Colors.white),
              ),
              controller: _livestreamIdController,
            ),
            //Joining the livestream as host
            ElevatedButton(
              onPressed: () => onJoinButtonPressed(context, Mode.SEND_AND_RECV),
              child: const Text('Join livestream as Host'),
            ),
            //Joining the livestream as Audience
            ElevatedButton(
              onPressed: () => onJoinButtonPressed(context, Mode.RECV_ONLY),
              child: const Text('Join livestream as Audience'),
            ),
          ],
        ),
      ),
    );
  }
}

```

Update the app entry to JoinScreen from the main.dart file.

```js title="main.dart"
import 'package:flutter/material.dart';
import 'join_screen.dart';

void main() async {
  // Run Flutter App
  WidgetsFlutterBinding.ensureInitialized();

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // Material App
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      title: 'VideoSDK Flutter ils Example',
      theme: ThemeData.dark().copyWith(
        appBarTheme: const AppBarTheme().copyWith(
          color: Colors.black,
        ),
        primaryColor: Colors.black,
        scaffoldBackgroundColor: Colors.black45,
      ),
      home: JoinScreen(),
    );
  }
}

```

**Output For JoinScreen**

<center>
<img height="500" alt="ViewAudience" src="https://cdn.videosdk.live/website-resources/docs-resources/flutter_ils_qs_join_screen.jpg"/>
</center>


### Step 3: Creating the ILSScreen


Let's create ils_screen.dart file and create ILSScreen StatefulWidget which will take the liveStreamId, token and mode of the participant in the constructor.

We will create a new room using the createRoom method and render the ILSView based on the passed participant mode.

```js title="ils_screen.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
import 'ils_view.dart';
import 'join_screen.dart';

class ILSScreen extends StatefulWidget {
  final String liveStreamId;
  final String token;
  final Mode mode;

  const ILSScreen(
      {super.key,
      required this.liveStreamId,
      required this.token,
      required this.mode});

  @override
  State
</center>

**Output of Audience View**
<center>
<img height="500" alt="ViewAudience" src="https://cdn.videosdk.live/website-resources/docs-resources/flutter_ils_qs_audience_view.jpg"/>
</center>


## Run and Test

Now to run and test, make sure that you have added the **Token** in .env file and also **API** key.

Your app should look like this after the implementation.

<div style={{textAlign: 'center'}}>



</div>

:::tip
You can checkout the complete [quick start example here](https://github.com/videosdk-live/quickstart/tree/main/interactive-live-streaming/flutter-ils).
:::


---

# Quick Start for Http Live Streaming(HLS) in Flutter




VideoSDK enables you to embed the livestreaming experience into your Flutter application in minutes.

In this quickstart, we are going to explore interactive livestreaming feature of Video SDK. We will go through step by step guide of integrating interactive livestreaming with Flutter Video SDK.

:::info

For low-latency interactive live streaming (under 100ms), follow this [documentation](./quick-start-flutter-ils.md).
:::

## Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

- Video SDK Developer Account (Not having one, follow **[Video SDK Dashboard](https://app.videosdk.live/)**)
- The basic understanding of Flutter.
- **[Flutter Video SDK](https://pub.dev/packages/videosdk)**
- Have Flutter installed on your device.

:::important

One should have a VideoSDK account to generate token.
Visit VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate token

:::

## Getting Started with the Code!

Follow the steps to create the environment necessary to add video calls into your app. Also you can find the code sample for [quickstart here](https://github.com/videosdk-live/quickstart/tree/main/flutter-hls).




### Create a new Flutter project.

Create a new Flutter App using the below command.

```bash
$ flutter create videosdk_flutter_quickstart_ils
```

### Install Video SDK

Install the VideoSDK using the below-mentioned flutter command. Make sure you are in your flutter app directory before you run this command.

```js
$ flutter pub add videosdk

//run this command to add http library to perform network call to generate roomId
$ flutter pub add http

//run this command to add flutter_vlc_player library to play HLS stream in your app
$ flutter pub add flutter_vlc_player
```

### Structure of the project

Your project structure should look like this.

```js title="Project Structure"
root
├── android
├── ios
├── lib
     ├── api_call.dart
     ├── ils_screen.dart
     ├── ils_speaker_view.dart
     ├── ils_viewer_view.dart
     ├── join_screen.dart
     ├── livestream_player.dart
     ├── main.dart
     ├── meeting_controls.dart
     ├── participant_tile.dart
```

We are going to create following flutter widgets JoinScreen, ILSScreen, ILSSpeakerView, MeetingControls, ParticipantTile, ILSViewerView, LivestreamPlayer for the quickstart app which will cover both speaker and viewer part of the app.

### App Structure

App widget will contain `JoinScreen` and `ILSScreen` screens. `ILSScreen` will render the `ILSSpeakerView` or `ILSViewerView` based on the participants mode. `ILSSpeakerView` will have `MeetingControls` and `ParticipantTile`

<div style={{textAlign: 'center'}}>

![VideoSDK Flutter ILS Quick Start Architecture](https://cdn.videosdk.live/website-resources/docs-resources/flutter_ils_arch.png)

</div>

### Configure Project

#### For Android

- Update the `/android/app/src/main/AndroidManifest.xml` for the permissions we will be using to implement the audio and video features.

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

- Also you will need to set your build settings to Java 8 because the official WebRTC jar now uses static methods in `EglBase` interface. Just add this to your app-level `/android/app/build.gradle`.

```js
android {
    //...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}
```

- If necessary, in the same `build.gradle` you will need to increase `minSdkVersion` of `defaultConfig` up to `23` (currently default Flutter generator set it to `16`).

- If necessary, in the same `build.gradle` you will need to increase `compileSdkVersion` and `targetSdkVersion` up to `31` (currently default Flutter generator set it to `30`).

#### For iOS

- Add the following entries which allow your app to access the camera and microphone to your `/ios/Runner/Info.plist` file :

```xml
<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) Camera Usage!</string>
<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) Microphone Usage!</string>
```

- Uncomment the following line to define a global platform for your project in `/ios/Podfile` :

```js title="Podfile"
# platform :ios, '11.0'
```

### Step 1: Get started with api_call.dart


Before jumping to anything else, you will write a function to generate a unique meetingId. You will require auth token, you can generate it using either by using [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples) or generate it from the [Video SDK Dashboard](https://app.videosdk.live/api-keys) for development.

```js title="api_call.dart"
import 'dart:convert';
import 'package:http/http.dart' as http;

//Auth token we will use to generate a meeting and connect to it
//highlight-next-line
String token = "


### Step 3: Creating the ILSScreen


Let's create `ils_screen.dart` file and create ILSScreen `StatefulWidget` which will take the `meetingId`, `token` and `mode` of the participant in the constructor.

We will create a new room using the `createRoom` method and render the `ILSSpeakerView` or `ILSViewerView` based on the passed participant `mode`.

```js title="ils_screen.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
import './ils_speaker_view.dart';
import './ils_viewer_view.dart';

class ILSScreen extends StatefulWidget {
  final String meetingId;
  final String token;
  final Mode mode;

  const ILSScreen(
      {super.key,
      required this.meetingId,
      required this.token,
      required this.mode});

  @override
  State


### Step 5: Implementing the Viewer View


Let's create `StatefulWidget` named `ILSViewerView` in the `ils_viewer_view.dart` file.

ILSViewerView will listen to the `hlsStateChanged` event and if the HLS is started, it will show the livestream using the `flutter_vlc_player` library.

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

```js title="ils_viewer_view.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
import './livestream_player.dart';

class ILSViewerView extends StatefulWidget {
  final Room room;
  const ILSViewerView({super.key, required this.room});

  @override
  State


## Run and Test

The app is all set to test. Make sure to update the `token` in `api_call.dart`

Your app should look like this after the implementation.

#### Speaker View Output

<div style={{textAlign: 'center'}}>



</div>

#### Viewer View Output

<div style={{textAlign: 'center'}}>



</div>

<br/>

:::caution
If you get `webrtc/webrtc.h file not found` error at a runtime in ios then check solution [here](https://docs.videosdk.live/flutter/guide/video-and-audio-calling-api-sdk/known-issues#issue--1).
:::

:::tip
You can checkout the complete [quick start example here](https://github.com/videosdk-live/quickstart/tree/main/flutter-hls).
:::


---

# Quick Start in Flutter using RiverPod


VideoSDK enables you to embed video calling functionality into your Flutter applications within minutes.

In this quick start guide, we’ll walk through integrating group video calling using Flutter Video SDK with Riverpod for state management. You’ll learn how to architect your application using Riverpod to manage state in a clean, modular, and efficient way.

This guide will get you up and running with VideoSDK’s video & audio calling using Riverpod state management in just a few minutes.

## Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

- Video SDK Developer Account (Not having one, follow **[Video SDK Dashboard](https://app.videosdk.live/)**)
- Familiarity with Flutter and basic Riverpod concepts.
- **[Flutter Video SDK](https://pub.dev/packages/videosdk)**
- Have Flutter installed on your device.

:::important

One should have a VideoSDK account to generate token.
Visit VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate token

:::

## Getting Started with the Code!

Follow the steps to create the environment necessary to add video calls into your app. Also you can find the code sample for [quickstart here](https://github.com/videosdk-live/quickstart/tree/main/flutter-rtc/quickstart_riverpod).

### Create a new Flutter project.

Create a new Flutter App using the below command.

```bash
$ flutter create flutter_riverpod_quickstart
```

### Install Required Dependencies

Navigate to your project directory and run the following commands to install the necessary dependencies:

```js
$ flutter pub add videosdk

//run this command to add http library to perform network call to generate roomId
$ flutter pub add http

// Add Riverpod (Flutter's state management library)
$ flutter pub add riverpod

// Add Riverpod annotations for code generation with @riverpod and @Riverpod
$ flutter pub add riverpod_annotation

// Add build_runner to generate code for Riverpod (and other code-gen tools)
$ flutter pub add --dev build_runner
$ flutter pub add --dev riverpod_generator
```

### Video SDK Compatibility

| Android and iOS                       | Web (Beta)                            | Desktop (Beta)                        | Safari                 |
| ------------------------------------- | ------------------------------------- | ------------------------------------- | ---------------------- |
| <center> :white_check_mark: </center> | <center> :white_check_mark: </center> | <center> :white_check_mark: </center> | <center> :x: </center> |


### Structure of the project

Your project structure should look like this.

```js title="Project Structure"
    root
    ├── android
    ├── ios
    ├── lib
         ├── riverpod
         │     ├── meeting_controller.dart
         │     └── meeting_state.dart
         ├── api_call.dart
         ├── join_screen.dart
         ├── main.dart
         ├── meeting_controls.dart
         ├── meeting_screen.dart
         └── participant_tile.dart
```
We are going to create flutter widgets (JoinScreen, MeetingScreen, MeetingControls, ParticipantTile, meeting_controller, meeting_state).

### App Structure

App widget will contain `JoinScreen` and `MeetingScreen` widget. `MeetingScreen` will have `MeetingControls` and `ParticipantTile` widget. 

<div style={{textAlign: 'center'}}>

![VideoSDK Flutter Quick Start Architecture](https://cdn.videosdk.live/website-resources/docs-resources/flutter_quick_start_arch.png)

</div>

### Configure Project

#### For Android

- Update the `/android/app/src/main/AndroidManifest.xml` for the permissions we will be using to implement the audio and video features.

```js title="AndroidManifest.xml"
<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
<uses-permission android:name="android.permission.WAKE_LOCK" />
```
#### For iOS

- Add the following entries which allow your app to access the camera and microphone to your `/ios/Runner/Info.plist` file :

```xml
<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) Camera Usage!</string>
<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) Microphone Usage!</string>
```

- Uncomment the following line to define a global platform for your project in `/ios/Podfile` :

```js title="Podfile"
# platform :ios, '12.0'
```

#### For MacOS

- Add the following entries to your `/macos/Runner/Info.plist` file which allow your app to access the camera and microphone.

```xml
<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) Camera Usage!</string>
<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) Microphone Usage!</string>
```

- Add the following entries to your `/macos/Runner/DebugProfile.entitlements` file which allow your app to access the camera, microphone and open outgoing network connections.

```xml
<key>com.apple.security.network.client</key>
<true/>
<key>com.apple.security.device.camera</key>
<true/>
<key>com.apple.security.device.microphone</key>
<true/>
```

- Add the following entries to your `/macos/Runner/Release.entitlements` file which allow your app to access the camera, microphone and open outgoing network connections.

```xml
<key>com.apple.security.network.server</key>
<true/>
<key>com.apple.security.network.client</key>
<true/>
<key>com.apple.security.device.camera</key>
<true/>
<key>com.apple.security.device.microphone</key>
<true/>
```

### Step 1: Get started with api_call.dart

Before jumping to anything else, you will write a function to generate a unique meetingId. You will require auth token, you can generate it using either by using [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples) or generate it from the [Video SDK Dashboard](https://app.videosdk.live/api-keys) for development.

```js title="api_call.dart"
import 'dart:convert';
import 'package:http/http.dart' as http;

//Auth token we will use to generate a meeting and connect to it
//highlight-next-line
String token = "

## Run and Test

The app is all set to test. Make sure to update the `token` in `api_call.dart`

Your app should look like this after the implementation.

<div style={{textAlign: 'center'}}>



</div>

<br/>

:::caution
If you get `webrtc/webrtc.h file not found` error at a runtime in ios then check solution [here](https://docs.videosdk.live/flutter/guide/video-and-audio-calling-api-sdk/known-issues#issue--1).
:::

:::tip
You can checkout the complete [flutter riverpod example here](https://github.com/videosdk-live/quickstart/tree/main/flutter-rtc/quickstart_riverpod).
:::


---

# Quick Start for Conference in Flutter



VideoSDK enables you to embed the video calling feature into your Flutter application in minutes.

In this quickstart, we are going to explore group calling feature of Video SDK. We will go through step by step guide of integrating video calling with Flutter Video SDK.

This guide will get you running with the VideoSDK video & audio calling in minutes.

## Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

- Video SDK Developer Account (Not having one, follow **[Video SDK Dashboard](https://app.videosdk.live/)**)
- The basic understanding of Flutter.
- **[Flutter Video SDK](https://pub.dev/packages/videosdk)**
- Have Flutter installed on your device.

:::important

One should have a VideoSDK account to generate token.
Visit VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate token

:::

## Getting Started with the Code!

Follow the steps to create the environment necessary to add video calls into your app. Also you can find the code sample for [quickstart here](https://github.com/videosdk-live/quickstart/tree/main/flutter-rtc/quickstart).

### Create a new Flutter project.

Create a new Flutter App using the below command.

```bash
$ flutter create videosdk_flutter_quickstart
```

### Install Video SDK

Install the VideoSDK using the below-mentioned flutter command. Make sure you are in your flutter app directory before you run this command.

```js
$ flutter pub add videosdk

//run this command to add http library to perform network call to generate roomId
$ flutter pub add http
```

### Video SDK Compatibility

| Android and iOS                       | Web (Beta)                            | Desktop (Beta)                        | Safari                 |
| ------------------------------------- | ------------------------------------- | ------------------------------------- | ---------------------- |
| <center> :white_check_mark: </center> | <center> :white_check_mark: </center> | <center> :white_check_mark: </center> | <center> :x: </center> |

### Structure of the project

Your project structure should look like this.

```js title="Project Structure"
    root
    ├── android
    ├── ios
    ├── lib
         ├── api_call.dart
         ├── join_screen.dart
         ├── main.dart
         ├── meeting_controls.dart
         ├── meeting_screen.dart
         ├── participant_tile.dart
```

We are going to create flutter widgets (JoinScreen, MeetingScreen, MeetingControls, ParticipantTile).

### App Structure

App widget will contain `JoinScreen` and `MeetingScreen` widget. `MeetingScreen` will have `MeetingControls` and `ParticipantTile` widget.

<div style={{textAlign: 'center'}}>

![VideoSDK Flutter Quick Start Architecture](https://cdn.videosdk.live/website-resources/docs-resources/flutter_quick_start_arch.png)

</div>

### Configure Project

#### For Android

- Update the `/android/app/src/main/AndroidManifest.xml` for the permissions we will be using to implement the audio and video features.

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

- Also you will need to set your build settings to Java 8 because the official WebRTC jar now uses static methods in `EglBase` interface. Just add this to your app-level `/android/app/build.gradle`.

```js
android {
    //...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}
```

- If necessary, in the same `build.gradle` you will need to increase `minSdkVersion` of `defaultConfig` up to `23` (currently default Flutter generator set it to `16`).

- If necessary, in the same `build.gradle` you will need to increase `compileSdkVersion` and `targetSdkVersion` up to `31` (currently default Flutter generator set it to `30`).

#### For iOS

- Add the following entries which allow your app to access the camera and microphone to your `/ios/Runner/Info.plist` file :

```xml
<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) Camera Usage!</string>
<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) Microphone Usage!</string>
```

- Uncomment the following line to define a global platform for your project in `/ios/Podfile` :

```js title="Podfile"
# platform :ios, '12.0'
```

#### For MacOS

- Add the following entries to your `/macos/Runner/Info.plist` file which allow your app to access the camera and microphone.

```xml
<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) Camera Usage!</string>
<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) Microphone Usage!</string>
```

- Add the following entries to your `/macos/Runner/DebugProfile.entitlements` file which allow your app to access the camera, microphone and open outgoing network connections.

```xml
<key>com.apple.security.network.client</key>
<true/>
<key>com.apple.security.device.camera</key>
<true/>
<key>com.apple.security.device.microphone</key>
<true/>
```

- Add the following entries to your `/macos/Runner/Release.entitlements` file which allow your app to access the camera, microphone and open outgoing network connections.

```xml
<key>com.apple.security.network.server</key>
<true/>
<key>com.apple.security.network.client</key>
<true/>
<key>com.apple.security.device.camera</key>
<true/>
<key>com.apple.security.device.microphone</key>
<true/>
```

### Step 1: Get started with api_call.dart


Before jumping to anything else, you will write a function to generate a unique meetingId. You will require auth token, you can generate it using either by using [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples) or generate it from the [Video SDK Dashboard](https://app.videosdk.live/api-keys) for development.

```js title="api_call.dart"
import 'dart:convert';
import 'package:http/http.dart' as http;

//Auth token we will use to generate a meeting and connect to it
//highlight-next-line
String token = "


### Step 3: Creating the MeetingControls


Let's create `meeting_controls.dart` file and create MeetingControls `StatelessWidget`.

The MeetingControls will consist of:

- **Leave Button** - This button will leave the meeting.
- **Toggle Mic Button** - This button will unmute or mute mic.
- **Toggle Camera Button** - This button will enable or disable camera.

MeetingControls will accept 3 functions in constructor

- **onLeaveButtonPressed** - invoked when Leave button pressed
- **onToggleMicButtonPressed** - invoked when Toggle Mic button pressed
- **onToggleCameraButtonPressed** - invoked when Toggle Camera button pressed

```js title="meeting_controls.dart"
import 'package:flutter/material.dart';

class MeetingControls extends StatelessWidget {
  final void Function() onToggleMicButtonPressed;
  final void Function() onToggleCameraButtonPressed;
  final void Function() onLeaveButtonPressed;

  const MeetingControls(
      {super.key,
      required this.onToggleMicButtonPressed,
      required this.onToggleCameraButtonPressed,
      required this.onLeaveButtonPressed});

  @override
  Widget build(BuildContext context) {
    return Row(
      mainAxisAlignment: MainAxisAlignment.spaceEvenly,
      children: [
        ElevatedButton(
            onPressed: onLeaveButtonPressed, child: const Text('Leave')),
        ElevatedButton(
            onPressed: onToggleMicButtonPressed, child: const Text('Toggle Mic')),
        ElevatedButton(
            onPressed: onToggleCameraButtonPressed,
            child: const Text('Toggle WebCam')),
      ],
    );
  }
}
```


### Step 4: Creating ParticipantTile


Let's create `participant_tile.dart` file and create ParticipantTile `StatefulWidget`.

The ParticipantTile will consist of:

- **RTCVideoView** - This will show participant's video stream.

ParticipantTile will accept `Participant` in constructor

- **participant** - participant of the meeting.

```js title="participant_tile.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;
  const ParticipantTile({super.key, required this.participant});

  @override
  State


## Run and Test

The app is all set to test. Make sure to update the `token` in `api_call.dart`

Your app should look like this after the implementation.


<div style={{textAlign: 'center'}}>



</div>

<br/>

:::caution
If you get `webrtc/webrtc.h file not found` error at a runtime in ios then check solution [here](https://docs.videosdk.live/flutter/guide/video-and-audio-calling-api-sdk/known-issues#issue--1).
:::

:::tip
You can checkout the complete [quick start example here](https://github.com/videosdk-live/quickstart/tree/main/flutter-rtc/quickstart).
:::


---

## Understanding Usage Quota Limits - Flutter

In this documentation, you will find detailed information about the quotas associated with each plan, including usage limits for various features and functionalities. Understanding these quotas will help you optimize your usage, selecting the best pricing plan and make the most of your VideoSDK experience.

## How VideoSDK limits concurrent usage quota

VideoSDK's approach to limiting usage focuses on concurrent usage rather than overall usage. Concurrent usage refers to the number of participants or requests that can be hosted or processed simultaneously. 

For example, if there's a limit of 50 concurrent participants per organization, users can run multiple calls (sessions) simultaneously, with a maximum of 50 participants across all sessions combined.

## How to view my current plan’s quota limits?

To view the current quota limits on your organization, simply navigate to the [VideoSDK Dashboard](https://app.videosdk.live/), go to your Profile section, and click on the Billing tab.

## Free Plan

Since, we’ve designed Free Plan for developers who are just exploring, we’ve kept the limits that would get you started without a hitch.

Organisations on Free Plan have the following limits on concurrent usage:

| Feature | Concurrent Limit |
| --- | --- |
| Participants in Video Calls | 50 concurrent participants |
| Viewers in Live Streams | 100 concurrent viewers |
| Recording Request | 1 concurrent request at a time |
| HLS Encoding Request | 1 concurrent request at a time |
| RTMP-Out Request | 1 concurrent request at a time |

 
### How to increase my limits?

To increase your limits, simply upgrade your plan by providing billing details and credit card information.

## Pay-as-you-Go Plan

We've increased participant limits for this paid plan. This way, it won't significantly impact users heavily involved in production or integration.

Organisations on Pay-as-you-Go have the following limits on concurrent usage:

| Feature | Concurrent Limit |
| --- | --- |
| Participants in Video Calls | 100 concurrent participants |
| Viewers in Live Streams | 500 concurrent viewers |
| Recording Request | 5 concurrent request at a time |
| HLS Encoding Request | 5 concurrent request at a time |
| RTMP-Out Request | 5 concurrent request at a time |

### How to increase my limits?

To increase your limits further more, simply get in touch with us. [Contact us](https://www.videosdk.live/contact) directly or reach out via email at [support@videosdk.live](mailto:support@videosdk.live), and we'll handle the rest gladly.

## Enterprise Plan

For Enterprise users, all limits are tailored to the specific needs. Customised limits ensure optimal performance for your unique requirements.

To get started as an Enterprise user, simply get in touch with us, explain your requirements and use case, and we’ll customise the quota and limits according to your needs.

## Examples to understand concurrent limits

**Example #1**

Let's say you're using video callings (RTC) in your organization on the Free Plan. In this scenario, you can concurrently host up to 50 participants. However, the number of calls (sessions) you initiate is unrestricted.

To simplify, you can run multiple sessions simultaneously, but concurrently, you can only accommodate a maximum of 50 participants across all sessions. If a 51st participant attempts to join, they won't be able to access the session until you upgrade your plan to increase your participant limits.

**Example #2**

Let’s say you're using live streaming in your organization on the Free Plan. In this setup, you can concurrently host up to 100 viewers joining the sessions. While you have the flexibility to host multiple live streaming sessions, the number of viewers joining session concurrently is restricted.

**Example #3**

Lets say you’re using video callings (RTC) in your organization on the Pay-as-you-Go Plan and you're hosting 5 concurrent calls (sessions), all of which are being recorded. Now, when you initiate the 6th call (session) and request recording, VideoSDK will not process your recording request. Instead, it will throw an error because you've reached your recording request limit.

If you have any questions regarding quota limits and pricing plan, post in our [Discord community](https://discord.com/invite/Qfm8j4YAUJ), [contact us](https://www.videosdk.live/contact) directly, or reach out to us on [support@videosdk.live](mailto:support@videosdk.live).

---

Recording meetings is an essential feature that ensures all important discussions, decisions, and interactions are documented for future reference. VideoSDK offers three types of recordings: Meeting Recording, Participant Recording, and Participant Track Recording. Each type serves a specific purpose to cater to different recording needs during a meeting.

## Meeting Recording

Meeting Recording captures the entire meeting, including all participants, audio, video, and shared content. This comprehensive recording is ideal for reviewing the entire meeting, ensuring that nothing is missed. It provides a holistic view of the meeting, capturing every interaction and piece of information shared during the session.

![Meeting Recording](https://cdn.videosdk.live/website-resources/docs-resources/MeetingRecording.png)

## Participant Recording

Participant Recording focuses on individual participants, capturing both their audio and video into a single file. This type of recording is particularly useful for tracking the contributions of specific participants or for scenarios where detailed analysis of an individual’s participation is needed. When a participant mutes their audio or turns off their video, the recording continues but with silenced audio or a black screen, respectively. This ensures a continuous recording without interruptions, reflecting the participant's involvement throughout the meeting.

![Participant Recording](https://cdn.videosdk.live/website-resources/docs-resources/ParticipantRecording.png)

## Participant Track Recording

Participant Track Recording allows you to record specific tracks of a participant, either audio or video, based on user input. This targeted approach is perfect for capturing particular aspects of a participant’s contribution, such as only their audio or only their video. Multiple files are generated whenever there is a change in the track's status (e.g., starting after being muted ), ensuring focused documentation of each continuous segment. This method is especially useful in scenarios where detailed analysis of specific media (audio or video) is required.

![Participant Track Recording](https://cdn.videosdk.live/website-resources/docs-resources/TrackRecording.png)



---

https://sdk.videosdk.live/js-sdk/0.2.6/videosdk.jsVideoSDK offers a range of video streaming tools and solutions for content creators, publishers, and developers.

- A custom template is a specialized layout for a live stream that allows users to integrate real-time graphics into their broadcasts.

- With custom templates, users can enhance their video content by overlaying graphics, text, images, and animations onto their live streams. These elements can be customized to align with specific branding requirements.

- By leveraging custom templates, users can craft dynamic and engaging video experiences. Whether incorporating live scoreboards, social media feeds, or other personalized elements, users have the flexibility to create visually appealing streams that stand out and capture audience attention.

:::note

Custom templates can also be used with recordings and RTMP service provided by VideoSDK.

:::

### What you can do with Custom Template

By utilizing a custom template, you have the flexibility to create various modes for your live stream. Here are some popular modes that you can design:

- **`PK Host:`** The host can organize a player vs. player battle, as illustrated in the example of a gaming battle shown below.

![pk host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_pk_battle.png)

- **`Watermark:`** The host has the ability to add and update watermarks anywhere in the template; for instance, the image below features a VideoSDK watermark on the top right side of the screen.

![watermark host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_water_mark.png)

- **`News Mode:`** Additionally, the host can incorporate dynamic text in the lower third banner, as demonstrated by the sample text in the bottom left of the screen.

![news mode](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_news_live.png)

### Custom template with VideoSDK

In this section, we will discuss how Custom Templates work with VideoSDK.

- **`Host`**: The host initiates live streaming by providing the `templateURL`. The `templateURL` is the URL of the hosted template webpage. The host is also responsible for managing the template, including tasks such as altering text, logos, and switching template layouts.

- **`VideoSDK Template Engine`** : The VideoSDK Template Engine accepts and opens the templateURL in the browser, actively listening to all events initiated by the Host. It facilitates the customization of the template in accordance with the host's preferences.

- **`Viewer`**: Viewers can stream the content, experiencing the live stream with added real-time graphics. This feature contributes to a distinctive and engaging viewing experience.

![custom template](https://cdn.videosdk.live/website-resources/docs-resources/custom_template.png)

### Understanding Template URL

The template URL is a webpage that VideoSDK Template Engine will open while composing the live stream.

It will appear as shown below.

![template url](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_url.png)

The Template URL comprises of two essential parts:

- Your actual page URL, resembling something like `https://example.com/videosdk-template`.
- Query parameters, designed to enable the VideoSDK Template Engine to seamlessly join the meeting upon opening the URL. There are three key query parameters in total:
  - `token`: Your token, serving as the authentication key to join the meeting.
  - `meetingId`: The meeting Id of the meeting that the VideoSDK Template Engine will join.
  - `participantId`: The participant ID of the VideoSDK Template Engine. This should be included when joining the template engine in your template, ensuring that the template engine participant remains invisible to other participants. **This parameter is automatically added by the VideoSDK**.

:::info

Above mentioned query parameters are mandatory. Apart from these parameters, you can pass any other extra parameters which are required according to your use-case.

:::

### **Creating Template**

**`Step 1:`** Import VideoSDK using `<script>` tag or install it using the below-mentioned npm command.
Make sure you are in your app directory before you run this command.



**Tab:**

" label="<script>" default>

```html
<html>
  <head></head>
  <body>
// highlight-next-line
<script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
  </body>
</html>
```

---

**npm:**

```bash
npm install @videosdk.live/js-sdk
```

---

**yarn:**

```bash
yarn add @videosdk.live/js-sdk
```

:::note

You can use VideoSDK's React or JavaScript SDK to create custom template. Following is the example of building custom template with JavaScript SDK.

:::

###### Structure of the Project

```jsx title="Project Structure"
  root
   ├── index.html
   ├── index.js
```

**`Step 2:`** Craft a user interface (UI) tailored for your live stream presentation.

```html title="index.html"
<!DOCTYPE html>
<html>
  <head> </head>

  <body>
    <div id="textDiv">Starting live stream...</div>

    
    <div class="row" id="videoContainer"></div>

    <script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
    <script src="index.js"></script>
  </body>
</html>
```

**`Step 3:`** Next, fetch the query parameters, from the URL which will be later used to initialize the meeting and get the elements from DOM.

```js title=index.js
const url = window.location;
const urlParams = new URLSearchParams(url.search);

const meetingId = urlParams.get("meetingId");
const token = urlParams.get("token");
const participantId = urlParams.get("participantId");

const videoContainer = document.getElementById("videoContainer");
const textDiv = document.getElementById("textDiv");
```

**`Step 4:`** Subsequently, initialize the meeting with the parameters that were extracted from the URL. Ensure direct initialization so that the template engine seamlessly joins the meeting upon page load.

```js title=index.js
window.VideoSDK.config(token);

const meeting = window.VideoSDK.initMeeting({
  meetingId: meetingId, // required
  name: "recorder", // required
  micEnabled: false,
  webcamEnabled: false,
  participantId: participantId,
});

meeting.join();

meeting.on("meeting-joined", () => {
  textDiv.style.display = "none";
});
```

**`Step 5:`** Next step is to create the container that will render the meeting view on the `participant-joined` event.

```js title=index.js
//  participant joined
meeting.on("participant-joined", (participant) => {
  let videoElement = createVideoElement(
    participant.id,
    participant.displayName
  );
  let audioElement = createAudioElement(participant.id);

  participant.on("stream-enabled", (stream) => {
    setTrack(stream, audioElement, participant, false);
  });
  videoContainer.appendChild(videoElement);
  videoContainer.appendChild(audioElement);
});

// participants left
meeting.on("participant-left", (participant) => {
  let vElement = document.getElementById(`f-${participant.id}`);
  vElement.remove(vElement);

  let aElement = document.getElementById(`a-${participant.id}`);
  aElement.remove(aElement);
});

// creating video element
function createVideoElement(pId, name) {
  let videoFrame = document.createElement("div");
  videoFrame.setAttribute("id", `f-${pId}`);

  //create video
  let videoElement = document.createElement("video");
  videoElement.classList.add("video-frame");
  videoElement.setAttribute("id", `v-${pId}`);
  videoElement.setAttribute("playsinline", true);
  videoElement.setAttribute("width", "300");
  videoElement.muted = true;
  videoFrame.appendChild(videoElement);

  let displayName = document.createElement("div");
  displayName.innerHTML = `Name : ${name}`;
  videoFrame.appendChild(displayName);

  return videoFrame;
}

// creating audio element
function createAudioElement(pId) {
  let audioElement = document.createElement("audio");
  audioElement.setAttribute("autoPlay", "false");
  audioElement.setAttribute("playsInline", "true");
  audioElement.setAttribute("controls", "false");
  audioElement.setAttribute("id", `a-${pId}`);
  audioElement.style.display = "none";
  return audioElement;
}

// setting media track
function setTrack(stream, audioElement, participant, isLocal) {
  if (stream.kind == "video") {
    isWebCamOn = true;
    const mediaStream = new MediaStream();
    mediaStream.addTrack(stream.track);
    let videoElm = document.getElementById(`v-${participant.id}`);
    videoElm.srcObject = mediaStream;
    videoElm
      .play()
      .catch((error) =>
        console.error("videoElem.current.play() failed", error)
      );
  }
  if (stream.kind == "audio") {
    if (isLocal) {
      isMicOn = true;
    } else {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(stream.track);
      audioElement.srcObject = mediaStream;
      audioElement
        .play()
        .catch((error) => console.error("audioElem.play() failed", error));
    }
  }
}
```

**`Step 6:`** Now, listen to PubSub messages from the `CHANGE_BACKGROUND` topic, triggering a change in the meeting's background color accordingly.

:::note

The PubSub mechanism is utilized to communicate with the template. You can learn more about [PubSub from here](/javascript/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

:::

```js title=index.js
meeting.on("meeting-joined", () => {
  //  ...

  meeting.pubSub.subscribe("CHANGE_BACKGROUND", (data) => {
    let { message } = data;
    document.body.style.backgroundColor = message;
  });
});
```

**`Step 7:`** Once tested, you can deploy it using your backend or host it on services like [firebase](https://www.geeksforgeeks.org/how-to-deploy-react-project-on-firebase/) or vercel.

:::tip

You can checkout the github repository for sample custom template [created here](https://github.com/videosdk-live/videosdk-custom-recording-template-js-example).

:::

### Setup Livestream Using Custom Template

- To utilize Custom Templates with Livestream, you need to establish both the Host and Viewer setups. The Host initiates the livestream, while Viewers can watch the broadcast.

![template manager](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_manager.png)

- To understand custom templates, clone this example and run it on your system.

```bash
git clone https://github.com/videosdk-live/videosdk-custom-recording-template-js-example.git
```

- You can utilize this custom template in [Start Recording API](/api-reference/realtime-communication/start-recording), [Start HLS API](/api-reference/realtime-communication/start-hlsStream) and [Start Livestream API](/api-reference/realtime-communication/start-livestream). Here is the example of HLS.
- To utilize the custom template that has been deployed, invoke the [Start HLS API](https://docs.videosdk.live/api-reference/realtime-communication/start-hlsStream) instead of the `startHls` method from the `Meeting` class. The necessary code has already been incorporated in the cloned example above.

:::important

You can create your own custom template manager in JavaScript. In this example, we are using one for better understanding.

:::

```js
<button
  onClick={async () => {
    const url = `https://api.videosdk.live/v2/hls/start`;
    //Update your Custom Template URL here if you have deployed your own, if not deployed you can use this template from our URL.
    //highlight-next-line
    const templateUrl = `https://lab.videosdk.live/js-template-demo/?meetingId=${meetingId}&token=${authToken}`;
    const options = {
      method: "POST",
      headers: {
        Authorization: authToken,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        roomId: meetingId,
        templateUrl: templateUrl,
      }),
    };

    const result = await fetch(url, options)
      .then((response) => response.json()) // result will have playbackHlsUrl and livestreamUrl
      .catch((error) => console.error("error", error));
  }}
>
  Start HLS
</button>
```

- In this example, the host has two options on their side, enabling them to change the background and send messages to the viewers.

- Given below is a test run of the example.


<div style={{textAlign: 'center'}}>



</div>

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)
- [Start HLS API](/api-reference/realtime-communication/start-hlsStream)
- [Start Livestream API](/api-reference/realtime-communication/start-livestream)
- [recordingState](/react/api/sdk-reference/use-meeting/properties#recordingstate)
- [hlsState](/react/api/sdk-reference/use-meeting/properties#hlsstate)
- [livestreamState](/react/api/sdk-reference/use-meeting/properties#livestreamstate)
- [hlsUrls](/react/api/sdk-reference/use-meeting/properties#hlsurls)
- [onRecordingStateChanged](/react/api/sdk-reference/use-meeting/events#onrecordingstatechanged)
- [onHlsStateChanged](/react/api/sdk-reference/use-meeting/events#onhlsstatechanged)
- [onLivestreamStateChanged](/react/api/sdk-reference/use-meeting/events#onlivestreamstatechanged)



---

# Geo Tag Meeting Recordings - Flutter

To ensure compliance for BFSIs doing vKYC, it very important to include the co-ordinates(location) of the customer in the recordings. VideoSDK provides a very customizable solution to implement this feature. You will be using custom templates for this purpose.

We have created a ready to use template for this use case which can be found [here](https://github.com/videosdk-live/videosdk-rtc-react-prebuilt-ui/tree/template/geo-tag-watermark). To integrate this template with your recordings follow the below mentiond instructions.

### Host the template

1. Clone the template repository and switch to the branch `template/geo-tag-watermark`.

```bash
git clone https://github.com/videosdk-live/videosdk-rtc-react-prebuilt-ui.git
cd videosdk-rtc-react-prebuilt-ui
git checkout template/geo-tag-watermark
```

2. Install the dependencies and create a build of the project using below mentioned commands.

```bash
npm install
npm run build
```

3. Host the contents of the build folder on your server and check if the template is up and running.

:::note

If you want to create the complete template from scratch you can [follow this guide.](./custom-template.md)

:::

### Using the template for recording

1. To use the template that we deployed earlier, we will be using the `templateUrl` feature in the `startRecording` API.
   To generate the template URL, you will have to append the `meetingId`, and `token` has to be added in the query parameters. Also if you are using the template provided above you need to added a few extra parameters mentioned below. Here is the code snippet to generate the URL.

```js
async function main() {
  let meetingId = "Your MeetingID";
  let token = "Your Token";
  const templateUrl = `https://${YOUR Template URL}/?meetingId=${meetingId}&token=${token}&name=recorder&isRecorder=true&joinWithoutUserInteraction=true`;

  console.log(templateUrl);
}

main();
```

2. Now that we have the template URL, we will use this URL to start the recording using the below provided API call.

```js
async function main() {
  let meetingId = "Your MeetingID";
  let token = "Your Token";
  const templateUrl = `https://${YOUR Template URL}/?meetingId=${meetingId}&token=${token}&name=recorder&isRecorder=true&joinWithoutUserInteraction=true`;

  console.log(templateUrl);

  //Using the previouly created template URL and starting the recording using the API.
  const options = {
    method: "POST",
    headers: {
      Authorization: "$YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      roomId: "Your MeetingId",
      templateUrl: templateUrl,
    }),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();
```

### Updating the Geo Tagging Coordinates

We will be using the PubSub feature of VideoSDK to update the data of latitude and longitude. For the predefined template provided by us we are using `GEO_TAG` as topic name. We will be publishing the `participantName`, `latitude` and `longitude` of the participant for whom we want to show in the recording.

:::note

You will have to fetch the longitude and latitude of the participant before sending it using the pubsub.

:::

Here is the code how you will have to publish the message:

```js
  ElevatedButton(
    onPressed:(){
      _room.pubSub.publish(
        "GEO_TAG",
        "GEO TAG DATA",
        const PubSubPublishOptions(persist: true),
        {
          "latitude": "LATITUDE OF PARTICIPANT",
          "longitude": "LONGITUDE OF PARTICIPANT",
          "participantName": "NAME OF PARTICIPANT",
        })
    },
    child: const Text("Send Message"),
  )
```

After implementing this, you should get the recording in the following format:

![Geo Tagging Recoridng](https://cdn.videosdk.live/website-resources/docs-resources/geo-tag-recording-template.png)

If you wish to change how UI looks on recording, you can change it by updating the layout in the template itself.

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)
- [Learn more about Custom Templates](./custom-template.md)


---

You have the option to create presigned URL, allowing you to upload your recordings to AWS, Azure, or GCP securely.
presigned URL provide a secure and temporary way to upload objects to your cloud storage. Instead of sharing your entire credentials, you can create a special URL that allows uploading a specific file for a limited time.

:::important

While presigned URL offer a convenient way to upload files securely, each cloud provider (AWS, Azure, and GCP) might have different restrictions on how they work. It's advisable to refer the respective documentation for **[<u>AWS</u>](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)**, **[<u>Azure</u>](https://learn.microsoft.com/en-us/rest/api/storageservices/delegate-access-with-shared-access-signature)**, and **[<u>GCP</u>](https://cloud.google.com/cdn/docs/using-signed-urls)** to gain a clearer understanding of presigned URL.

:::

### Code Sample

This guide will walk you through the process of generating a presigned URL for uploading recordings to your cloud storage of choice. You can use this generated presigned URL in [Start Recording API](/api-reference/realtime-communication/start-recording#preSignedUrl).



**AWS:**

```js
const { S3Client, PutObjectCommand } = require("@aws-sdk/client-s3");
const { getSignedUrl } = require("@aws-sdk/s3-request-presigner");

const region = <YOUR S3 REGION>;
const bucket = <YOUR S3 BUCKET NAME>;
const key = <YOUR FILE NAME>; // test/abc.mp4
const accessKeyId = <YOUR S3 ACCESS KEY ID>;
const secretAccessKey = <YOUR S3 SECRET ACCESS KEY>;
const expiresIn = <URL EXPIRY IN SECONDS>; // this number should be higher than duraion of recording

const s3Client = new S3Client({
credentials: {
    accessKeyId: accessKeyId,
    secretAccessKey: secretAccessKey,
},
region: region,
});

const createPresignedUrlWithClient = async () => {
const command = new PutObjectCommand({ Bucket: bucket, Key: key });
const preSignedUrl = await getSignedUrl(s3Client, command, { expiresIn: expiresIn });
return preSignedUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await createPresignedUrlWithClient();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

---

**AZURE:**

```js
const { BlobServiceClient, BlobSASPermissions } = require("@azure/storage-blob");

const connectionString = <YOUR AZURE STORAGE CONNECTION STRING>;
const containerName = <YOUR AZURE CONTAINER NAME>;
const blobName = <YOUR AZURE BLOB NAME>;
const startsOn = <YOUR SASURL START TIME>; // (optional, defaults to now)
const expiresOn = <YOUR SASURL EXPIRY TIME>; // expiry time should be higher than duration of recording

const generateSASUrl = async () => {
let blobServiceClient = BlobServiceClient.fromConnectionString(connectionString);
let containerClient = blobServiceClient.getContainerClient(containerName);

await containerClient.createIfNotExists({
    access: "container",
});

const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const sasUrl = await blockBlobClient.generateSasUrl({
    startsOn: startsOn, // sasUrl start time
    expiresOn: expiresOn, // sasUrl expiration time
    permissions: BlobSASPermissions.parse("write"),
});
return sasUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await generateSASUrl();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

---

**GCP:**

```js
const { Storage } = require("@google-cloud/storage");

const projectId = <YOUR GCP PROJECT ID>;
const clientEmail = <YOUR GCP CLIENT EMAIL>;
const privateKey = <YOUR GCP PRIVATE KEY>;
const expires =<URL EXPIRY IN SECONDS>; // this number should be higher than duraion of recording
const bucketName = <YOUR GCP BUCKET NAME>;
const fileName = <YOUR FILE NAME>; // test/abc.mp4

const storage = new Storage({
projectId: projectId,
credentials: {
    client_email: clientEmail,
    private_key: privateKey,
},
});

const generateSignedUrl = async () => {
const options = {
    version: "v4",
    action: "write",
    expires: expires,
    contentType: "video/mp4",
};

const [signedUrl] = storage.bucket(bucketName).file(fileName).getSignedUrl(options);
return signedUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await generateSignedUrl();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)



---

# Start and Stop - Flutter

This guide will provide an overview of how to implement start and stop Meeting Recording.

### `startRecording()`

`startRecording()` can be used to start a recording of the meeting which can be accessed from the `Room` object. This method accepts four parameters:

- `1. webhookUrl (optional)`: This would the webhook URL where you would like to listen to event happening for the recording like starting and stopping of recording. It will be triggered when the recording is completed and stored into server. Read more about webhooks [here](https://en.wikipedia.org/wiki/Webhook)

- `2. awsDirPath (optional)`: This parameter accepts the path for the your S3 bucket where you want to store recordings to. To allow us to store recording in your S3 bucket, you will need to fill this form by providing the required values. ([VideoSDK Cloud (AWS S3, Azure Blob or GCP ) Integration](/flutter/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config))

- `3. config (optional)`: This parameter will define how the recording should be recorded.

- `4. transcription (optional)`: This parameter lets you start post transcription for the recording.

  ```js
  Map<String, dynamic> config = {
    // highlight-next-line
    // Layout Configuration
    layout: {
      type: "GRID", // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
      priority: "SPEAKER", // "PIN", Default : "SPEAKER"
      gridSize: 4, // MAX : 4
    },

    // highlight-next-line
    // Theme of recording
    theme: "DARK", //  "LIGHT" | "DEFAULT"

    // highlight-next-line
    // `mode` is used to either record video & audio both or only audio.
    mode: "video-and-audio", // "audio", Default : "video-and-audio"

    // highlight-next-line
    // Quality of recording and is only applicable to `video-and-audio` type mode.
    quality: "high", /* Default : "med"
   "low" (SD Recording) | "med" (HD Recording) | "high" (FHD Recording) */

    //highlight-start
    // This mode refers to orientation of recording.
    // landscape : Record the meeting in horizontally
    // portrait : Record the meeting in vertically (Best for mobile view)
    //highlight-end
    orientation: "landscape", // "portrait",  Default : "landscape"
  };

  // highlight-next-line
  // Post Transcription Configuration
  Map<String, dynamic> transcription = {
    "enabled": true, // Enables post transcription
    "summary": {
      "enabled": true,  // Enables summary generation
       // Guides summary generation
      "prompt":
          "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    }
  };

  room.startRecording(config: config, transcription: transcription);
  ```

### `stopRecording()`

- `stopRecording()` is used to stop the meeting recording which can be accessed from the `Room` object.

#### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ElevatedButton(
          onPressed:(){
            Map<String, dynamic> config = {
              "layout": {
                "type": "GRID",
                "priority": "SPEAKER",
                "gridSize": 4,
              },
              "theme": "DARK",
              "mode": "video-and-audio",
              "quality": "high",
              "orientation": "portrait",
            };

            Map<String, dynamic> transcription = {
              "enabled": true,
              "summary": {
                "enabled": true,
                "prompt":
                    "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
              }
            };
            _room.startRecording(config: config, transcription: transcription);
          },
          child: const Text("Start Recording"),
        ),
        ElevatedButton(
          onPressed:(){
            _room.stopRecording();
          },
          child: const Text("Stop recording"),
        ),
    //highlight-end
      ]
    );
  }
}
```

:::important
To initiate automatic recording at the beginning of a `session`, simply provide the `autoStartConfig` feature `recording` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.
:::

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startRecording](/flutter/api/sdk-reference/room-class/methods#startrecording)
- [stopRecording](/flutter/api/sdk-reference/room-class/methods#stoprecording)
- [Events.recordingStateChanged](/flutter/api/sdk-reference/room-class/events#recordingstatechanged)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

VideoSDK offers individual participant recording, generating a single, continuous file for a participant.

This recording captures the participant's audio and video streams throughout the meeting, regardless of whether they are muted or have their camera turned off. During periods of audio muting or video disengagement, the respective tracks will be silent or display a black screen, respectively.

You can access the recorded files in the developer dashboard or opt to store them in your own cloud storage.

This guide provides an overview of the start and stop functionality for individual participant recording through APIs.


## Start Individual Participant Recording

To start a participant recording, you will have to call `/v2/recordings/participant/start` API with following body parameters.

- `roomId`: RoomId for which the participant recording is to be started
- `participantId`: participantId of the participant to be recorder.
- `fileFormat`: Currently only `webm` is supported as file format. We will add the support for other formats in future.
- `webhookUrl`: The webhook URL where you would like to get the status updates of the recording. To learn more about webhooks refer [here](#participant-track-recording-starting).
- `bucketDirPath`: If you are using your own storage, you can provide the directory path where you want to store the recording. To configure the storage please [refere this quide](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config).

The usual recording path would look like `${sessionId}/${participantId}/${filename}`.

```dart
import 'package:http/http.dart' as http;
import 'dart:convert';

Future<void> startParticipantRecording() async {
  final String roomId = "<YOUR ROOM ID>";
  final String participantId = "<PARTICIPANT ID>";
  final String fileFormat = "<YOUR FILE FORMAT>"; // (Optional) default: webm
  final String bucketDirPath = "<YOUR CLOUD STORAGE BUCKET PATH>"; // (Optional) test/abc
  final String webhookUrl = "<YOUR WEBHOOK URL>"; // (Optional)

  final url = Uri.parse("https://api.videosdk.live/v2/recordings/participant/start");
  final headers = {
    "Authorization": "$YOUR_TOKEN",
    "Content-Type": "application/json",
  };
  final body = jsonEncode({
    "roomId": roomId,
    "participantId": participantId,
    "fileFormat": fileFormat,
    "bucketDirPath": bucketDirPath,
    "webhookUrl": webhookUrl,
  });

  final response = await http.post(url, headers: headers, body: body);

  if (response.statusCode == 200) {
    print('Participant Recording started successfully');
  } else {
    print('Failed to start participant recording');
  }
}

```

## Stop Individual Participant Recording

To stop a participant recording, you will have to call `/v2/recordings/participant/stop` API with following body parameters.

- `roomId`: RoomId for which the participant recording is to be stopped
- `participantId`: participantId for which the recording is to be stopped.

```dart
import 'dart:convert';
import 'package:http/http.dart' as http;

Future<void> stopParticipantRecording(String roomId, String participantId) async {
  final url = Uri.parse('https://api.videosdk.live/v2/recordings/participant/stop');
  final headers = {
    'Authorization': '$YOUR_TOKEN',
    'Content-Type': 'application/json',
  };
  final body = json.encode({
    'roomId': roomId,
    'participantId': participantId,
  });

  final response = await http.post(url, headers: headers, body: body);

  if (response.statusCode == 200) {
    print('Participant Recording stopped successfully');
  } else {
    print('Failed to stop participant recording');
  }
}

```

## Webhook associated with Participant Recording

### participant-recording-starting

- A "Participant Recording Starting" webhook is triggered when the participant recording process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-started

- Participant Recording started webhook will be received when successfully participant recording is started in meeting

###### Example

```javascript
{
    "webhookType": "participant-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopping

- A "Participant Recording Stopping" webhook is triggered when the participant recording end process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopped

- Participant Recording stopped webhook will be received when participant recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "participant-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-recording-failed

- A "Participant Recording Failed" webhook is generated when the participant recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "participant-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
    },
}
```

---

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Participant Recording API](/api-reference/realtime-communication/start-participant-recording)
- [Stop Participant Recording API](/api-reference/realtime-communication/stop-participant-recording)



---

VideoSDK provides participant track recording, creating separate audio or video files for participant.

New files are generated when a participant starts their audio or video again after turning it off (e.g., unmuting the microphone or restarting the camera). This ensures that each file represents a continuous segment of audio or video content.

Once track recording is complete, all audio files for a participant are consolidated into a single directory, as are the video files.


## Start Participant Track Recording

To start a participant track recording, you will have to call `/v2/recordings/participant/track/start` API with following body parameters.

- `roomId`: RoomId for which the participant track recording is to be started
- `participantId`: participantId of the participant to be recorder.
- `kind`: The kind of tracks you want to record.
  - You can pass following values: _`audio`_ | _`video`_ | _`screen_audio`_ | _`screen_video`_
- `fileFormat`: Currently only `webm` is supported as file format. We will add the support for other formats in future.
- `webhookUrl`: The webhook URL where you would like to get the status updates of the recording. To learn more about webhooks refer [here](#participant-track-recording-starting).
- `bucketDirPath`: If you are using your own storage, you can provide the directory path where you want to store the recording. To configure the storage please [refere this quide](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config).

The usual recording path would look like `${sessionId}/${participantId}/${kind}/${filename}`.

```dart
import 'package:http/http.dart' as http;
import 'dart:convert';

Future<void> startTrackRecording() async {
  final String roomId = "<YOUR ROOM ID>";
  final String participantId = "<PARTICIPANT ID>";
  final String kind = "<YOUR STREAM KIND>";
  final String fileFormat = "<YOUR FILE FORMAT>";
  final String bucketDirPath = "<YOUR CLOUD STORAGE BUCKET PATH>";
  final String webhookUrl = "<YOUR WEBHOOK URL>";

  final Map<String, dynamic> body = {
    "roomId": roomId,
    "participantId": participantId,
    "kind": kind,
    "fileFormat": fileFormat,
    "bucketDirPath": bucketDirPath,
    "webhookUrl": webhookUrl,
  };

  final response = await http.post(
    Uri.parse('https://api.videosdk.live/v2/recordings/participant/track/start'),
    headers: {
      "Authorization": "$YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: jsonEncode(body),
  );

  if (response.statusCode == 200) {
    print(jsonDecode(response.body));
  } else {
    print('Failed to start track recording');
  }
}

```

## Stop Participant Track Recording

To stop a participant track recording, you will have to call `/v2/recordings/participant/track/stop` API with following body parameters.

- `roomId`: RoomId for which the participant track recording is to be stopped
- `participantId`: participantId for which the recording is to be stopped.
- `kind`: The kind of track recording you want to stop for the given participant.
  - You can pass following values: _`audio`_ | _`video`_ | _`screen_audio`_ | _`screen_video`_

```dart
import 'package:http/http.dart' as http;
import 'dart:convert';

Future<void> stopTrackRecording() async {
  final String roomId = "<YOUR ROOM ID>";
  final String participantId = "<PARTICIPANT ID>";
  final String kind = "<YOUR STREAM KIND>";

  final Map<String, dynamic> body = {
    "roomId": roomId,
    "participantId": participantId,
    "kind": kind,
  };

  final response = await http.post(
    Uri.parse('https://api.videosdk.live/v2/recordings/participant/track/stop'),
    headers: {
      "Authorization": "$YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: jsonEncode(body),
  );

  if (response.statusCode == 200) {
    print(jsonDecode(response.body));
  } else {
    print('Failed to stop track recording');
  }
}

```

## Webhook associated with Participant Track Recording

### participant-track-recording-starting

- A "Participant Track Recording Starting" webhook is triggered when the track recording process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-started

- Participant Track Recording started webhook will be received when successfully track recording is started in meeting

###### Example

```javascript
{
    "webhookType": "participant-track-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopping

- A "Participant Track Recording Stopping" webhook is triggered when the track recording end process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopped

- Participant Track Recording stopped webhook will be received when track recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-track-recording-failed

- A "Participant Track Recording Failed" webhook is generated when the track recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Track Recording API](/api-reference/realtime-communication/start-track-recording)
- [Stop Track Recording API](/api-reference/realtime-communication/stop-track-recording)



---

### Storage Configuration

While recording your meetings, you have the flexibility to store them either on VideoSDK's storage or configure your own storage solution such as **`AWS S3 Storage, Azure Blob or GCP Cloud Storage`**. To set up your own storage, you can navigate to the [API section](https://app.videosdk.live/api-keys) in the VideoSDK Dashboard.

- This feature allows you to configure storage provider for your meeting recordings.

- You can configure multiple storage provider with multiple API Keys.

- Currently, we support `AWS S3`, `Azure Blob` and `GCP Cloud Storage`. We will add support for other storage provider soon !!

## Prerequisites

- An active [VideoSDK Developer Account](https://app.videosdk.live)
- `Aws S3`, `Azure Blob Storage` or `GCP Cloud Storage` Credentials

## How to setup ?

### Step 1 : Select Api Key

![Dashboard](/img/tutorial/dashboard/api-key-dashboard.png)

- Go to [VideoSDK Dashboard](https://app.videosdk.live/api-keys).
- Select API Key for which, you want to set storage configuration.
- Then click on `Storage Config` Icon in Actions.

### Step 2 : Choose Cloud Storage Provider

![Dashboard](/img/tutorial/dashboard/storage-config.png)

- As you can see in the image, there are 3 Cloud Storage Provider (`Aws`, `Azure`, `GCP`).
- You can select a Cloud Storage Provider as per your requirements.

### Step 3 : Configure Bucket or Container

<h4> For Aws S3 Storage </h4>

![Aws S3](/img/tutorial/dashboard/s3.png)

- You will need AWS S3 Bucket. [Learn to create S3 Bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html).

- As you can see in the image, you will need enter `accessKeyId`, `secretAccessKey`, `region`, `bucket`, and `ACL` to setup for Aws S3 Storage.

- Click on `Save` button.

<hr />

<h4> For Azure Blob Storage: </h4>

![Azure Blob](/img/tutorial/dashboard/blob.png)

- You will need Azure Blob Container. [Learn to create Blob Container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal#create-a-container).

- As you can see in the image, you will need to enter `connectionString` and `containerName` to setup for Azure Blob.

- Click on `Save` button.

<hr />

<h4> For Google Cloud Storage: </h4>

<img src="/img/tutorial/dashboard/gcp.png" alt="GCP Cloud Storage" width="436" height="632"/>

1. You will need Google Cloud Storage Bucket. [Learn to create Google Cloud Storage Bucket](https://cloud.google.com/storage/docs/creating-buckets).

2. After creation, click on the <b> &#xFE19; </b>button in the upper right corner and select **`Project settings`**.

3. Under **`IAM and Admin`**, select **`Service Accounts`**. In the service account list, click on the <b> &#xFE19; </b> button for the account just added or created before, and select **`Manage keys`**.

4. Click **`ADD KEY > Create new key`**. Select **`JSON`** in the pop-up box and click **`CREATE`**. A json file is downloaded with the name format `projectId-xxxxxxxx.json`.

5. Open the downloaded json file, which looks like the following example:

```
{
  "type": "service_account",
  "project_id": "videosdk-12345",
  "private_key_id": "yourprivateidkeyyourprivateidkeyyourprivateidkey",
  "private_key": "-----BEGIN PRIVATE KEY-----\nThisisYourPrivateKeyThisisYourPrivateKeyThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\n-----END PRIVATE KEY-----\n",
  "client_email": "xxxx-xxxx@videosdk-12345.iam.gserviceaccount.com",
  "client_id": "123456789012345678901",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/videosdk%40videosdk-404307.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}
```

- As you can see in the image, you will need to enter `Project Id`, `Client Email`, `Bucket`, `Private Key` to setup for Google Cloud Storage Bucket. You can retrieve these details from the json file.

- Click on `Save` button.

### Step 4 : Test

- It's time to test !!
- [Create Room](https://docs.videosdk.live/api-reference/realtime-communication/create-room) with token generated with the API Key, you have configured for.
- Start meeting with the roomId created and Start Recording !!
- Then, you can see that recording will be available in your Bucket or Container.

:::note

- Only a single Recording Storage Config can be possible for a particular Api Key at a time.
- In order to add new Recording Configuration, first you need to delete current configuration.

:::


---

# Webhooks and Events - Flutter

### Event associated with Recording

- **recordingStateChanged** - Whenever meeting recording state changes, then `recordingStateChanged` event will trigger.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    ...

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {
    room.on(Events.recordingStateChanged, (String status) {
      //Status can be :: RECORDING_STARTING
      //Status can be :: RECORDING_STARTED
      //Status can be :: RECORDING_STOPPING
      //Status can be :: RECORDING_STOPPED
      log("Meeting Recording status : $status");
    });
  }
  //highlight-end
}
```

## Webhook associated with Recording

### recording-starting

- A "Recording Starting" webhook is triggered when the recording process for a meeting is initiated.

###### Example

```javascript
{
    "webhookType": "recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-started

- Recording started webhook will be received when successfully recording is started in meeting

###### Example

```javascript
{
    "webhookType": "recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopping

- A "Recording Stopping" webhook is triggered when the recording end process for a meeting is initiated.

###### Example

```javascript
{
    "webhookType": "recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopped

- Recording stopped webhook will be received when recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
        "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",

    },
}
```

---

### recording-failed

- A "Recording Failed" webhook is generated when the recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```


---

# Interactive Livestream (HLS) - Flutter

Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

In an interactive live stream (HLS), viewers can take part in a variety of activities like live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

<center>

![Screen Share with Audio](https://cdn.videosdk.live/website-resources/docs-resources/mobile_hls.png)

</center>

VideoSDK also allows you to configure the interactive livestream layouts in numerous ways like by simply setting different prebuilt layouts in the configuration or by providing your own custom template to do the livestream according to your layout choice.

This guide will provide an overview of how to implement start and stop Livestreaming.

### `startHls()`

`startHls()` can be used to start a interactive livestream of the meeting which can be accessed from the `Room` object. This method accepts two parameters:

- `1. config (optional)`: This parameter will define how the livestream layout should look like.

- `2. transcription (optional)`: This parameter lets you start post transcription for the Livestreaming.

  ```js
  Map<String, dynamic> config = {
    // highlight-next-line
    // Layout Configuration
    "layout": {
      "type": "GRID", // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
      "priority": "SPEAKER", // "PIN", Default : "SPEAKER"
      "gridSize": 4, // MAX : 4
    },

    // highlight-next-line
    // Theme of recording
    "theme": "DARK", //  "LIGHT" | "DEFAULT"

    // highlight-next-line
    // `mode` is used to either record video & audio both or only audio.
    "mode": "video-and-audio", // "audio", Default : "video-and-audio"

    // highlight-next-line
    // Quality of recording and is only applicable to `video-and-audio` type mode.
    "quality": "high", /* Default : "med"
   "low" (SD HLS) | "med" (HD HLS) | "high" (FHD HLS) */

    //highlight-start
    // This mode refers to orientation of recording.
    // landscape : Record the meeting in horizontally
    // portrait : Record the meeting in vertically (Best for mobile view)
    //highlight-end
    "orientation": "landscape", // "portrait",  Default : "landscape"
  };

  // highlight-next-line
  // Post Transcription Configuration
  Map<String, dynamic> transcription = {
    "enabled": true, // Enables post transcription
    "summary": {
      "enabled": true,  // Enables summary generation
       // Guides summary generation
      "prompt":
          "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    }
  };

  room.startHls(config: config, transcription: transcription);
  ```

### `stopHls()`

- `stopHls()` is used to stop the meeting livestream which can be accessed from the `Room` object.

#### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ElevatedButton(
          onPressed:(){
            Map<String, dynamic> config = {
              "layout": {
                "type": "GRID",
                "priority": "SPEAKER",
                "gridSize": 4,
              },
              "theme": "DARK",
              "mode": "video-and-audio",
              "quality": "high",
              "orientation": "portrait",
            };

            Map<String, dynamic> transcription = {
              "enabled": true,
              "summary": {
                "enabled": true,
                "prompt":
                    "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
              }
            };
            _room.startHls(config: config, transcription: transcription);
          },
          child: const Text("Start HLS"),
        ),
        ElevatedButton(
          onPressed:(){
            _room.stopHls();
          },
          child: const Text("Stop HLS"),
        ),
    //highlight-end
      ]
    );
  }
}
```

:::tip
If you want to learn more about the Interactive Livestream and how you can implement it in your own platform, you can checkout this [guide](/flutter/guide/interactive-live-streaming/integrate-hls/overview).
:::

### Event associated with HLS

- **hlsStateChanged** - Whenever meeting HLS state changes, then `hlsStateChanged` event will trigger.

- You can get the `playbackHlsUrl` and `livestreamUrl` of the HLS to play it on the Viewer side when the state changes to `HLS_PLAYABLE`
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    ...

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {
    room.on(Events.hlsStateChanged, (Map<String, dynamic> data) {
      //Status can be :: HLS_STARTING
      //Status can be :: HLS_STARTED
      //Status can be :: HLS_PLAYABLE
      //Status can be :: HLS_STOPPING
      //Status can be :: HLS_STOPPED
      log("Meeting HLS status : ${data['status']}");
      if (data['status'] == "HLS_PLAYABLE")
        log("PLAYBACKHLS URL -- " + data['playbackHlsUrl']);
    });
  }
  //highlight-end
}
```

### Custom Template

With VideoSDK, you can also use your own custom designed layout template to livestream the meetings. In order to use the custom template, you need to create a template for which you can [follow this guide](/react/guide/interactive-live-streaming/custom-template). Once you have setup the template, you can use the [REST API to start](/api-reference/realtime-communication/start-livestream) the livestream with the `templateURL` parameter.

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startHls](/flutter/api/sdk-reference/room-class/methods#starthls)
- [stopHls](/flutter/api/sdk-reference/room-class/methods#stophls)
- [Events.hlsStateChanged](/flutter/api/sdk-reference/room-class/events#hlsstatechanged)


---

# Record Meeting - Flutter

VideoSDK allows you to record video & audio during the meeting. The recording files are available in developer dashboard or you can also choose to store them in your own cloud storage.

VideoSDK also allows you to configure the recording layouts in numerous ways like by simply setting different prebuilt layouts in the configuration or by providing your own custom template to do the recording according to your layout choice.

This guide will provide an overview of how to implement start and stop Meeting Recording.

:::important

To initiate automatic recording at the beginning of a `session`, simply provide the `autoStartConfig` feature `recording` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.

:::

### `startRecording()`

`startRecording()` can be used to start a recording of the meeting which can be accessed from the `Room` object. This method accepts four parameters:

- `1. webhookUrl (optional)`: This would the webhook URL where you would like to listen to event happening for the recording like starting and stopping of recording. It will be triggered when the recording is completed and stored into server. Read more about webhooks [here](https://en.wikipedia.org/wiki/Webhook)

- `2. awsDirPath (optional)`: This parameter accepts the path for the your S3 bucket where you want to store recordings to. To allow us to store recording in your S3 bucket, you will need to fill this form by providing the required values. ([VideoSDK Cloud (AWS S3, Azure Blob or GCP ) Integration](/flutter/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config))

- `3. config (optional)`: This parameter will define how the recording should be recorded.

- `4. transcription (optional)`: This parameter lets you start post transcription for the recording.

  ```js
  Map<String, dynamic> config = {
    // highlight-next-line
    // Layout Configuration
    layout: {
      type: "GRID", // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
      priority: "SPEAKER", // "PIN", Default : "SPEAKER"
      gridSize: 4, // MAX : 4
    },

    // highlight-next-line
    // Theme of recording
    theme: "DARK", //  "LIGHT" | "DEFAULT"

    // highlight-next-line
    // `mode` is used to either record video & audio both or only audio.
    mode: "video-and-audio", // "audio", Default : "video-and-audio"

    // highlight-next-line
    // Quality of recording and is only applicable to `video-and-audio` type mode.
    quality: "high", /* Default : "med"
   "low" (SD Recording) | "med" (HD Recording) | "high" (FHD Recording) */

    //highlight-start
    // This mode refers to orientation of recording.
    // landscape : Record the meeting in horizontally
    // portrait : Record the meeting in vertically (Best for mobile view)
    //highlight-end
    orientation: "landscape", // "portrait",  Default : "landscape"
  };

  // highlight-next-line
  // Post Transcription Configuration
  Map<String, dynamic> transcription = {
    "enabled": true, // Enables post transcription
    "summary": {
      "enabled": true,  // Enables summary generation
       // Guides summary generation
      "prompt":
          "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    }
  };

  room.startRecording(config: config, transcription: transcription);
  ```

### `stopRecording()`

- `stopRecording()` is used to stop the meeting recording which can be accessed from the `Room` object.

#### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ElevatedButton(
          onPressed:(){
            Map<String, dynamic> config = {
              "layout": {
                "type": "GRID",
                "priority": "SPEAKER",
                "gridSize": 4,
              },
              "theme": "DARK",
              "mode": "video-and-audio",
              "quality": "high",
              "orientation": "portrait",
            };

            Map<String, dynamic> transcription = {
              "enabled": true,
              "summary": {
                "enabled": true,
                "prompt":
                    "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
              }
            };
            _room.startRecording(config: config, transcription: transcription);
          },
          child: const Text("Start Recording"),
        ),
        ElevatedButton(
          onPressed:(){
            _room.stopRecording();
          },
          child: const Text("Stop recording"),
        ),
    //highlight-end
      ]
    );
  }
}
```

### Event associated with Recording

- **recordingStateChanged** - Whenever meeting recording state changes, then `recordingStateChanged` event will trigger.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    ...

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {
    room.on(Events.recordingStateChanged, (String status) {
      //Status can be :: RECORDING_STARTING
      //Status can be :: RECORDING_STARTED
      //Status can be :: RECORDING_STOPPING
      //Status can be :: RECORDING_STOPPED
      log("Meeting Recording status : $status");
    });
  }
  //highlight-end
}
```

### Storage Configuration

While recording your meetings, you can choose to store them on the VideoSDK's storage or you can also configure your own **`AWS S3 Storage, Azure Blob or GCP Cloud Storage`** to store the meeting recordings directly on your storage.

You can configure your own **`AWS S3 Storage, Azure Blob or GCP Cloud Storage`** from the [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).

You can also go through this [guide to setup](/docs/tutorials/user-dashboard/recording-storage-config) the storage or watch this [video to configure](https://www.loom.com/share/23a2617f824a4a5da004d14d1a541a9d) your storage.

### Custom Template

With VideoSDK, you can also use your own custom designed layout template to record the meetings. In order to use the custom template, you need to create a template for which you can [follow this guide](/react/guide/interactive-live-streaming/custom-template). Once you have setup the template, you can use the [REST API to start](/api-reference/realtime-communication/start-recording) the recording with the `templateURL` parameter.

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startRecording](/flutter/api/sdk-reference/room-class/methods#startrecording)
- [stopRecording](/flutter/api/sdk-reference/room-class/methods#stoprecording)
- [Events.recordingStateChanged](/flutter/api/sdk-reference/room-class/events#recordingstatechanged)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

# RTMP Livestream - Flutter

RTMP is a popular protocol for live streaming video content from a VideoSDK to platforms such as YouTube, Twitch, Facebook, and others.

By providing the platform-specific stream key and stream URL, the VideoSDK can connect to the platform's RTMP server and transmit the live video stream.

VideoSDK allows you to livestream your meeting to platform which support RTMP ingestion just by providing the platform-specific stream key and stream URL, we can connect to the platform's RTMP server and transmit the live video stream.

VideoSDK also allows you to configure the livestream layouts in numerous ways like by simply setting different prebuilt layouts in the configuration or by providing your own custom template to do the livestream according to your layout choice.

This guide will provide an overview of how to implement start and stop RTMP Livestreaming.

### `startLivestream()`

`startLivestream()` can be used to start a RTMP livestream of the meeting which can be accessed from the `Room` object. This method accepts two parameters:

- `1. outputs`: This parameter accepts an array of objects which contains the RTMP `url` and `streamKey` of the platforms you want to start the livestream.

- `2. config (optional)`: This parameter will define how the livestream layout should look like.

  ```js
  var outputs = [
    {
      url: "rtmp://a.rtmp.youtube.com/live2",
      streamKey: "<STREAM_KEY>",
    },
    {
      url: "rtmps://",
      streamKey: "<STREAM_KEY>",
    },
  ];
  Map<String, dynamic> config = {
    // highlight-next-line
    // Layout Configuration
    layout: {
      type: "GRID", // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
      priority: "SPEAKER", // "PIN", Default : "SPEAKER"
      gridSize: 4, // MAX : 4
    },

    // highlight-next-line
    // Theme of livestream
    theme: "DARK", //  "LIGHT" | "DEFAULT"
  };

  room.startLivestream(outputs,config:config);
  ```

### `stopLivestream()`

- `stopLivestream()` is used to stop the meeting livestream which can be accessed from the `Room` object.

#### Example

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ElevatedButton(
          onPressed:(){
            var outputs = [
              {
                url: "rtmp://a.rtmp.youtube.com/live2",
                streamKey: "<STREAM_KEY>",
              },
              {
                url: "rtmps://",
                streamKey: "<STREAM_KEY>",
              },
            ];
            var liveStreamConfig =  {
              'layout': {
                'type': 'GRID',
                'priority': 'SPEAKER',
                'gridSize': 4,
              },
              'theme': "LIGHT",
            };
            room.startLivestream(outputs, config: livestreamConfig);
          },
          child: const Text("Start Livestream"),
        ),
        ElevatedButton(
          onPressed:(){
            _room.stopLivestream();
          },
          child: const Text("Stop Livestream"),
        ),
    //highlight-end
      ]
    );
  }
}
```

### Event associated with Livestream

- **livestreamStateChanged** - Whenever meeting livestream state changes, then `livestreamStateChanged` event will trigger.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room room;

  @override
  void initState() {
    //highlight-next-line
    ...

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {
    room.on(Events.livestreamStateChanged, (String status) {
      //Status can be :: LIVESTREAM_STARTING
      //Status can be :: LIVESTREAM_STARTED
      //Status can be :: LIVESTREAM_STOPPING
      //Status can be :: LIVESTREAM_STOPPED
      log("Meeting Livestream status : $status");
    });
  }
  //highlight-end
}
```

### Custom Template

With VideoSDK, you can also use your own custom designed layout template to livestream the meetings. In order to use the custom template, you need to create a template for which you can [follow this guide](/react/guide/interactive-live-streaming/custom-template). Once you have setup the template, you can use the [REST API to start](/api-reference/realtime-communication/start-livestream) the livestream with the `templateURL` parameter.

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startLivestream](/flutter/api/sdk-reference/room-class/methods#startlivestream)
- [stopLivestream](/flutter/api/sdk-reference/room-class/methods#stoplivestream)
- [Events.livestreamStateChanged](/flutter/api/sdk-reference/room-class/events#livestreamstatechanged)


---

# Release Notes - Flutter




---

# Display Video - Flutter

In this guide, we will take a look at how to render the participant's audio and video on the screen.

## Rendering Participant

The two steps are involve to achieve this process.

1. [Get Mic and Webcam Status](#1-get-mic-and-webcam-status)
2. [Rendering Video](#2-rendering-video)

### `1. Get Mic and Webcam Status`

We must determine whether the participant's audio or video is on or off before rendering him or her. Hence, if the webcam is not turned on, we will begin by rendering the participant's frames with their name in them; otherwise, we will render the video.

**`Step 1:`** Let's get every `participants` from `Room` by listenting to the `participantJoined` as well as `participantLeft` event.

```js title="meeting_screen.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
import './participant_tile.dart';

class MeetingScreen extends StatefulWidget {
  final String meetingId;
  final String token;

  const MeetingScreen(
      {super.key, required this.meetingId, required this.token});

  @override
  State

</center>

### `2. Rendering Video`

The status of the `webcam` and `mic` is now displayed. If the webcam is turned `on`, we will use the `videoStream` we declared earlier and display the participant's video.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;
  //highlight-next-line
  ...
}

class _ParticipantTileState extends State

</center>

#### `2.1 Mirror Local Video View`

If you wish to show the mirror view of the local participant, you can pass boolean value to `mirror` property of RTCView.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;
  //highlight-next-line
  ...
}

class _ParticipantTileState extends State<ParticipantTile> {
  Stream? videoStream;
  Stream? audioStream;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  _initStreamListeners() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Container(
      color: Colors.black54,
      child: Stack(
        children: [
          if (videoStream != null)
            RTCVideoView(
              videoStream?.renderer as RTCVideoRenderer,
              objectFit: RTCVideoViewObjectFit.RTCVideoViewObjectFitCover,
              //highlight-next-line
              mirror: true,
            ),
        ],
      ),
    );
  }
}
```

##### Sample of mirror view video

![mirror view](https://cdn.videosdk.live/website-resources/docs-resources/mirror_view_mobile.jpg)

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [Participant](/flutter/api/sdk-reference/participant-class/introduction)
- [streamEnabled](/flutter/api/sdk-reference/participant-class/events#streamenabled)
- [streamDisabled](/flutter/api/sdk-reference/participant-class/events#streamdisabled)


---

# Layout and Grid Management - Flutter

In this guide, we will take a look at how to efficiently manage the participants in different types of layout.

## Grid Layout

The most usual way to showing participants within a grid. There are multiple things you should keep in mind when showing participants in the grid.

This includes the number of participants being shown on the screens, number of participants in the background(in the meeting but not on the grid), quality which is being consumed for each and every participant in the grid.

### Quality of Participant's Video

When there are large number of participants present on the screen, it is best to consume them in lower resolutions. For this we recommend you to call the `setQuality` method on the participants present in the grid with dynamic values based on the number of participants on the screen.

Here is the recommended video quality:

1. Participants less than 3: `setQuality("high")`
2. Participants between 3 to 4: `setQuality("med")`
3. Participants greater than 4: `setQuality("low")`

<center>
<img src='https://cdn.videosdk.live/website-resources/docs-resources/grid_quality_mobile.png' />
</center>

### Grid with Screen Share

When you are rendering a small grid along with the screen share of the presenter or you are showing a simple sidebar video of the participants while the screenshare is on, it is recommended to do `setQuality("low")` for the participants who are present in the sidebar.

## Grid with Pagination

If you are having large video calls where there are multiple speakers with video turned on, it is best to implement a pagination type setup where only a few (4-6) participants are shown on the grid and rest can be seen by changing the page.

To best utilize the resourses, you should pause the streams of the participants who are not present in the grid and resume them when the come in to the grid, you can resume their streams.

<center>
<img src='https://cdn.videosdk.live/website-resources/docs-resources/grid_pagination.png' />
</center>

###### Example to pause and resume streams

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class ParticipantTile extends StatefulWidget {
  final Participant participant;
  //highlight-next-line
  ...
}

class _ParticipantTileState extends State<ParticipantTile> {

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        //highlight-start
        ElevatedButton(
          onPressed:(){
            widget.participant.streams.forEach((stream){
              if(stream.kind == "video"){
                _stream.pause();
              }
            });
          },
          child: const Text("Pause Stream"),
        ),
        ElevatedButton(
          onPressed:(){
            widget.participant.streams.forEach((stream){
              if(stream.kind == "video"){
                _stream.resume();
              }
            });
          },
          child: const Text("Resume Stream"),
        ),
        //highlight-end
      ],
    );
  }
}
```

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [setQuality](/flutter/api/sdk-reference/participant-class/methods#setquality)


---

# Optimize Audio Track - Flutter

While optimizing for the best listening experience, it is necessary to fine-tune the audio track that is being used during the calls.

For the best fine-tuning experience, we have introduced the ability to pass a custom audio track for the participant's media before and during the meeting.

## Custom Audio Track

This feature can be used to add custom layers like background noise removal, echo cancellation, etc. on audio and send it to other participants.

### `How to Create Custom Audio Track ?`

- You can create a Audio Track using `createMicrophoneAudioTrack()` method of `VideoSDK`.

- This method can be used to create audio track using different encoding parameters and noise cancellation configuration.

#### Example

```javascript
import 'package:videosdk/videosdk.dart';

CustomTrack? customTrack = await VideoSDK.createMicrophoneAudioTrack({
  // highlight-next-line
  // It will be the id of the mic from which the voice should be captured.
  microphoneId : 'mic-id' // OPTIONAL

  // highlight-next-line
  // This will accept the voice profile you want to capture.
  encoderConfig: CustomAudioTrackConfig.speech_standard, // `high_quality` | `music_standard`,  Default : `speech_standard`

  noiseConfig: {
  // highlight-start
  // It is used to improve the quality of audio by removing background noise
  // that can interfere with the clarity of speech.
  // highlight-end
    "noiseSuppression": true,

  // highlight-next-line
  // It is used to remove unwanted echoes from voice.
    "echoCancellation": true,

 // highlight-next-line
  // It is used to maintain a consistent level of loudness or amplitude in a voice.
    "autoGainControl": true,
  },
});
```

- `speech_standard` : This config is optimised for normal voice communication.

- `high_quality` : This config is used for getting RAW audio, where you can apply your `noiseConfig`.

- `music_standard` : This config is optimised for communication, where sharing of musical notes such as songs or instrumental sounds, is important.

### `How to Setup Custom Audio Track ?`

The custom track can be set up both before and after the initialization of the meeting.

1. [Setting up a Custom Track during the initialization of a meeting](#1-setting-up-a-custom-track-during-the-initialization-of-a-meeting)
2. [Setting up a Custom Track with methods](#2-setting-up-a-custom-track-with-methods)

##### 1. Setting up a Custom Track during the initialization of a meeting

If you are passing `micEnabled: true` in the `createRoom` and want to use custom tracks from start of the meeting, you can pass custom track in the `customMicrophoneAudioTrack` as shown below.

:::caution
Custom Track will not apply on `micEnabled: false` configuration.
:::

##### Example

```javascript
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  final String meetingId;
  final String token;

  const MeetingScreen(
      {super.key, required this.meetingId, required this.token});

  @override
  State<MeetingScreen> createState() => _MeetingScreenState();
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    initRoom();
    super.initState();
  }

  void initRoom() {
    //highlight-start
    //Creating Custom Audio Track
    CustomTrack? audioTrack = await VideoSDK.createMicrophoneAudioTrack(
        encoderConfig: CustomAudioTrackConfig.speech_standard);

    //Creating a new Room with custom audio track
    // create room
    _room = VideoSDK.createRoom(
      roomId: widget.meetingId,
      token: widget.token,
      displayName: "John Doe",
      micEnabled: true,
      camEnabled: true,
      defaultCameraIndex:
          1, // Index of MediaDevices will be used to set default camera
      customMicrophoneAudioTrack: audioTrack, // custom audio track :: optional
    );
    //highlight-end
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }
}
```

#### 2. Setting up a Custom Track with methods

In order to switch tracks during the meeting, you have to pass the `CustomTrack` in the **`unmuteMic()`** method of `Room`.

:::tip
Make sure to call `muteMic()` before you create a new track as it may lead to unexpected behavior.
:::

##### Example

```javascript
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  final String meetingId;
  final String token;

  const MeetingScreen(
      {super.key, required this.meetingId, required this.token});

  @override
  State<MeetingScreen> createState() => _MeetingScreenState();
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    initRoom();
    super.initState();
  }

  void initRoom() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      childern: [
        ElevatedButton(
          onPressed: ()async{
            //highlight-start
            //Creating Custom Audio Track
            CustomTrack? audioTrack = await VideoSDK.createMicrophoneAudioTrack(
                encoderConfig: CustomAudioTrackConfig.speech_standard);

            _room.unmuteMic(audioTrack);
            //highlight-end
          },
          child: const Text("Unmute with Custom Track"),
        ),
      ]
    )
  }
}
```

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [Custom Audio Track](/flutter/api/sdk-reference/custom-tracks#custom-audio-track---flutter)


---

# Optimize Video Tracks - Flutter

While optimizing for the best viewing experience, it is necessary to fine-tune the video tracks that are being used during the calls.

For the best fine-tuning experience, we have introduced the ability to pass a custom video track for the participant's media before and during the meeting.

## Custom Video Track

This feature can be used to add custom video encoder configurations and background removal & video filter from external libraries and send it to other participants.

### `How to Create a Custom Video Track ?`

- You can create a Video Track using `createCameraVideoTrack()` method of `VideoSDK` class.

- This method can be used to create video track by specifying parameters like video resolution, camera facing mode, and the quality controls (`bitrateMode` and `maxLayer`).


- The video resolutions listed below are `common encoder` configuration options supported across `All Platforms`.

| Encoder Config | Resolution | Frame Rate | Optimized (kbps) | Balanced (kbps) | High Quality (kbps) |
| -------------- | :--------: | :--------: | :--------------: | :-------------: | :-----------------: |
| h144p_w192p | 192x144 | 15 fps | 60 | 100 | 150 |
| h240p_w320p | 320x240 | 15 fps | 120 | 200 | 350 |
| h480p_w640p | 640x480 | 25 fps | 300 | 500 | 750 |
| h720p_w960p | 960x720 | 30 fps | 800 | 1200 | 1600 |
| h1080p_w1440p | 1440x1080 | 30 fps | 1600 | 2200 | 2700 |
| h360p_w640p | 640x360 | 20 fps | 200 | 400 | 600 |
| h720p_w1280p | 1280x720 | 30 fps | 1000 | 1500 | 2000 |
| h1080p_w1440p | 1280x720 | 30 fps | 1600 | 2300 | 2700 |

<br/>

- The video resolutions listed below are additional encoder configuration options available specifically for `Web applications`. 

| Encoder Config | Resolution | Frame Rate | Optimized (kbps) | Balanced (kbps) | High Quality (kbps) |
| -------------- | :--------: | :--------: | :----------: | :----------: | :----------: |
| h120p_w160p | 160x120 | 15 fps | 60 | 100 | 150 |
| h180p_w240p | 240x180 | 15 fps | 100 | 150 | 250 |
| h360p_w480p | 480x360 | 20 fps | 200 | 400 | 600 |
| h540p_w720p | 720×540 | 30 fps | 350 | 650 | 800 |
| h1440p_w1920p | 1920×1440 | 30 fps | 3500 | 4000 | 4500 |
| h180p_w320p | 320x180 | 15 fps | 100 | 150 | 250 |
| h216p_w384p | 384x216 | 15 fps | 120 | 200 | 350 |
| h540p_w960p | 960x540 | 25 fps | 400 | 600 | 800 |
| h1440p_w2560p | 2560x1440 | 30 fps | 5000 | 5500 | 6000 |
| h2160p_w3840p | 3840x2160 | 30 fps | 8000 | 8500 | 9000 |

:::important
The below encoder configurations can also be used in mobile applications (Android and iOS). However, the actual video resolution may differ from the requested value due to device and hardware limitations. To obtain the exact resolution being used, refer to the supported video tracks available on the mobile application.
:::

:::note
Above mentioned encoder configurations are valid for both, landscape as well as portrait mode.
:::

#### Example

```javascript
import 'package:videosdk/videosdk.dart';

CustomTrack? customTrack = await VideoSDK.createCameraVideoTrack({
  // highlight-next-line
  // It will be the id of the camera from which the video should be captured.
  cameraId:"camera-id", // OPTIONAL

  // highlight-next-line
  // This will accept the resolution (height x width) of video you want to capture.
  encoderConfig: "h720p_w960p", // "h480p_w640p" | "h360p_w640p" ... // Default : "h720p_w1280p"

  // highlight-next-line
  // For Mobile browser It will specify whether to use front or back camera for the video track.
  facingMode: "FacingMode.environment", // "FacingMode.front"

  // highlight-next-line
  // We will discuss this parameter in next step.
  multiStream:true // false,  Default : true

    // highlight-next-line
  // Optional: This controls the video quality and bandwidth usage.
  bitrateMode: BitrateMode.HIGH_QUALITY, // "HIGH_QUALITY" | "BALANCED" , Default : BALANCED

  // highlight-next-line
  // Optional: This specifies the maximum number of simulcast layers (maxLayer) to publish.
  maxLayer: 2 // 3 , Default: 3

});
```

:::caution
The capabilities of the device have a significant impact on how custom track configurations behave. Assuming a case where you set encoder configuration to 1080p but the webcam only supports 720p, then encoder configuration will automatically switch to the highest resolution that the device can handle, which is 720p.
:::

##### What is `multiStream`?

- It will specify if the stream should send multiple resolution layers or single resolution layer.

**`multiStream : true`** By default, VideoSDK sends multiple resolution video streams to the server (whether you are using custom video track or not), For instance, user device capability is 720p, so VideoSDK sends 720p along with 360p and 90p streams. This allows VideoSDK to deliver the appropriate stream to each participant based on their network bandwidth.

<center>

![Multi Stream False](https://cdn.videosdk.live/website-resources/docs-resources/multistream_true.png)

</center>

**`multiStream : false`** If you want to restrict the VideoSDK to send only one stream to maintain quality, you can set `multiStream` to `false`.

<center>

![Multi Stream False](/img/multistream_false.png)

</center>

:::important
MultiStream functionality is not supported in the Firefox browser. VideoSDK will only send one stream for Firefox browsers.
:::

:::danger
`setQuality` would not have any effect if multiStream is set to `false`.
:::

##### What is `BitrateMode`?
`BitrateMode` is the key setting for video quality. It lets you decide whether to prioritize sharp details, save internet data, or find a good balance between the two.

You can choose from three distinct modes:
- `bandwidth_optimized`: Prioritizes lower bandwidth usage over video quality. Ideal for users with poor or unstable network conditions.
- `balanced`: The default setting. It provides a smart compromise between clear video and efficient bandwidth consumption, suitable for most use cases.
- `high_quality`: Prioritizes video quality over bandwidth usage. Use this when high-fidelity video is essential and viewers are expected to have strong network connections.

##### What is `maxLayer`?
`maxLayer` is an advanced parameter that gives you direct control over simulcast, which is the process of sending multiple versions (or "layers") of the same video stream at different resolutions and qualities simultaneously.

- `maxLayer : 3` **(Default)**: Publishes all available layers (e.g., high, medium, and low quality). This provides the maximum adaptability for viewers on diverse and unpredictable networks.
- `maxLayer : 2`: Intelligently publishes only the highest and lowest quality layers, skipping any in the middle. This is useful for providing a high-quality option and a low-bandwidth fallback without the overhead of a third stream.

  - If a device is capable of producing a `h720p_w960p` stream, setting `maxLayer : 2` will result in two streams being sent: the highest quality (`h720p_w960p`) and the lowest quality (e.g. `h240p_w320p`), ensuring a fallback for poor connections.

:::info
To use the `maxLayer` parameter, `multiStream` must be set to `true`. The `multiStream` flag enables simulcasting (sending multiple quality streams), while `maxLayer` specifies how many streams to send.
:::


### `How to Setup a Custom Video Track ?`

The custom track can be set up both before and after the initialization of the meeting.

1. [Setting up a Custom Track during the initialization of a meeting](#1-setting-up-a-custom-track-during-the-initialization-of-a-meeting)
2. [Setting up a Custom Track with methods](#2-setting-up-a-custom-track-with-methods)

##### 1. Setting up a Custom Track during the initialization of a meeting

If you are passing `webcamEnabled: true` in the `createRoom` and want to use custom tracks from start of the meeting, you can pass custom track in the `customCameraVideoTrack` as shown below.

:::caution
Custom Track will not apply on `webcamEnabled: false` configuration.
:::

##### Example

```javascript
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  final String meetingId;
  final String token;

  const MeetingScreen(
      {super.key, required this.meetingId, required this.token});

  @override
  State
</center>

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [Custom Video Track](/flutter/api/sdk-reference/custom-tracks#custom-video-track---flutter)


---

# Picture-in-Picture Mode

### Overview

Picture-in-Picture (PiP) mode enhances the video conferencing experience by allowing users to multitask while keeping a small, floating video window on their screen. This guide walks you through implementing PiP mode in Flutter using VideoSDK, covering both Android and iOS platforms—without relying on third-party dependencies.

To enable PiP mode, native methods are used on both Android and iOS through the method channel. On Android, PiP mode is activated with the `enterPictureInPictureMode()` method. On iOS, the process involves capturing RTC frames natively, rendering them into a custom view with `AVPlayer`, and then utilizing that view to enable PiP functionality.

<center>
    <img src='https://cdn.videosdk.live/website-resources/docs-resources/pip_flutter_ios.jpg'/>
</center>

:::note
You can check out the complete implementation in the [Github repository](https://github.com/videosdk-live/videosdk-flutter-pip-mode-example)
:::

### Prerequisites

- Familiarity with method channels in Flutter.
- To implement PiP (Picture-in-Picture) mode, clone the [Quick Start Repository](https://github.com/videosdk-live/quickstart/tree/main/flutter-rtc) and follow the implementation steps.

## Architecture Diagram
<center>
    <img src='https://cdn.videosdk.live/website-resources/docs-resources/flutter_pip_architecture.jpg'/>
</center>

## Android Implementation

**Step 1 : Configuring `AndroidManifest.xml`**

To enable Picture-in-Picture (PiP) mode in your Flutter application, update the `AndroidManifest.xml` file with the necessary permissions and activity configurations:


```js title="AndroidManifest.xml"
<uses-permission android:name="android.permission.WAKE_LOCK" />  
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/>  
<uses-permission android:name="android.permission.PICTURE_IN_PICTURE"/>  

<activity  
    android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout"  
    android:supportsPictureInPicture="true">  
</activity>  
```


**Step 2: Implementing PiP Mode**

The native Android implementation utilizes the [Picture-in-Picture (PiP)](https://developer.android.com/develop/ui/views/picture-in-picture) API to manage PiP mode effectively. The following methods play a crucial role in this implementation:


1. `onPictureInPictureRequested` (System-defined)

- Invoked when the system detects a request to enter PiP mode.

2. `startPiPMode` (Custom implementation)

- Manually initiates PiP mode with a 16:9 aspect ratio.
- It invokes `enterPictureInPictureMode()` Method 
- This method attempts to put the activity into Picture-in-Picture mode, allowing it to continue displaying content in a small, resizable window when the user navigates away from the app.


```kotlin title="MainActivity.kt"
package com.example.quick_start  

import android.app.PictureInPictureParams  
import android.os.Build  
import android.os.Bundle  
import android.util.Log  
import android.util.Rational  
import io.flutter.embedding.android.FlutterActivity  
import io.flutter.embedding.engine.FlutterEngine  
import io.flutter.plugin.common.MethodChannel  

class MainActivity : FlutterActivity() {  

    companion object {  
        var instance: MainActivity? = null  
    }  

    // MethodChannel for Flutter-native communication  
    private val Channel = "pip_channel"  

    // Flag to track if the user is on the meeting screen  
    private var isInMeetingScreen: Boolean = false  

    override fun onCreate(savedInstanceState: Bundle?) {  
        super.onCreate(savedInstanceState)  
        instance = this  
    }  

    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {  
        super.configureFlutterEngine(flutterEngine)  

        // Establish a MethodChannel for interaction with Flutter  
        MethodChannel(flutterEngine.dartExecutor.binaryMessenger, Channel)  
            .setMethodCallHandler { call, result ->  
                when (call.method) {  
                    "enterPiPMode" -> {  
                        // Enter PiP mode upon request from Flutter  
                        startPiPMode()  
                        result.success(null)  
                    }  
                    "setMeetingScreen" -> {  
                        // Update the meeting screen flag based on Flutter’s input  
                        isInMeetingScreen = call.arguments as Boolean  
                        result.success(null)  
                    }  
                    else -> result.notImplemented()  
                }  
            }  
    }  

    // Sends a message from Android to Flutter via MethodChannel  
    private fun sendMessageToFlutter(message: String) {  
        // Notify Flutter when PiP mode is activated  
        MethodChannel(flutterEngine!!.dartExecutor.binaryMessenger, Channel)  
            .invokeMethod("sendMessage", hashMapOf("message" to message))  
    }  

    // Handles system-triggered PiP requests  
    override fun onPictureInPictureRequested(): Boolean {  
        Log.d("MainActivity", "onPictureInPictureRequested: $isInMeetingScreen")  

        // If the user is on the meeting screen, activate PiP mode and notify Flutter  
        return if (isInMeetingScreen) {  
            startPiPMode()  
            sendMessageToFlutter("Done")  
            true  
        } else {  
            super.onPictureInPictureRequested()  
        }  
    }  

    // Initiates PiP mode  
    private fun startPiPMode() {  
        Log.d("MainActivity", "startPiPService")  

        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {  
            // Ensure PiP mode is supported (Android 8.0+)  
            val paramsBuilder = PictureInPictureParams.Builder()  
                .setAspectRatio(Rational(16, 9)) // Define the PiP window aspect ratio  
            this.enterPictureInPictureMode(paramsBuilder.build()) // Activate PiP mode  
        }  
    }  
} 

```

## iOS Implementation ##

**Step 1 : Enable Xcode Capabilities**

Enable the necessary capabilities in Xcode:
1. Open your project in Xcode.
2. Navigate to your target settings.
3. Select the "Signing & Capabilities" tab.
4. Click the "+" button to add capabilities.
5. Add **Background Modes**.

Under **Background Modes**, enable the following options:
- Audio, AirPlay, and Picture in Picture
- Voice over IP

<center>
    <img src='https://cdn.videosdk.live/website-resources/docs-resources/pip_flutter_ios_modes.png'/>
</center>


**Step 2: Handling Local and Remote participant Frames in iOS**

**Local participant Frames Handling**

For local participant frames, we utilize the `VideoProcessor` class in VideoSDK. 


:::info 
For a detailed setup guide on proceesor refer to [*this documentation*](https://docs.videosdk.live/flutter/guide/video-and-audio-calling-api-sdk/video-processor/ios-setup).
:::

- Below is the Swift implementation to process and render local frames:

```swift 
public class FrameProcessor: VideoProcessor {
    
  // Override the onFrameReceived function to access VideoFrames
  public override func onFrameReceived(_ frame: RTCVideoFrame) -> RTCVideoFrame? {
    // Access the frame data
    return frame
  }
}
```

**Handling Remote participant Streams**

- To handle remote participants video streams, we extract the WebRTC stream and pass it to the PiP manager.

```swift
public class FrameProcessor: VideoProcessor {

  // for the remote stream for specific remote id 
  static func updateRemote(remoteId: String) {
    remoteTrack = FlutterWebRTCPlugin.sharedSingleton()?.remoteTrack(forId: remoteId)
  }
}
```

**Step 3: Converting RTC Frames for PiP Mode**

To display Video in PiP mode, we need to convert `RTCVideoFrame` into a format compatible with AVKit.

1. Extract the frame buffer (`RTCCVPixelBuffer`).
2. Convert it to a `CVPixelBuffer`.
3. Create a `CMSampleBuffer` for AVFoundation compatibility.
4. Render the sample buffer using `AVSampleBufferDisplayLayer`.
5. Manage PiP mode using `AVPictureInPictureController`.

**Step 4 : Integrating PiP Mode**

To enable PiP mode using AVKit:

1. Create a PiPManager class for managing PiP state.
2. Use `AVPictureInPictureController` to toggle PiP mode.
3. Assign the **AVSampleBufferDisplayLayer** to PiP.
4. Enable user interactions with PiP mode.

- For a full implementation, refer to the [frame.swift](https://github.com/videosdk-live/videosdk-flutter-pip-mode-example/blob/main/ios/Runner/Frame.swift)

**Step 5 : Implementing PiP Method Channel in `AppDelegate.swift`**

The method channel in `AppDelegate.swift` is responsible for connecting Flutter and iOS for PiP mode control.


```swift title="AppDelegate.swift"
import UIKit
import Flutter
import videosdk

@main
@objc class AppDelegate: FlutterAppDelegate {
    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        GeneratedPluginRegistrant.register(with: self)

        // Video SDK setup
        let bgProcessor = FrameProcessor()
        let videoSDK = VideoSDK.getInstance
        videoSDK.registerVideoProcessor(videoProcessorName: "processor", videoProcessor: bgProcessor)

        guard let controller = window?.rootViewController as? FlutterViewController else {
            return super.application(application, didFinishLaunchingWithOptions: launchOptions)
        }

        // PiP Channel Setup
        let pipChannel = FlutterMethodChannel(
            name: "pip_channel",
            binaryMessenger: controller.binaryMessenger
        )

        pipChannel.setMethodCallHandler { (call, result) in
            switch call.method {
            case "setupPiP":
                PiPManager.setupPiP()
                result(nil)

            case "remoteStream":
                guard let args = call.arguments as? [String: Any],
                      let remoteId = args["remoteId"] as? String else {
                    result(FlutterError(code: "INVALID_ARGUMENTS", message: "Missing remoteId", details: nil))
                    return
                }
                FrameProcessor.updateRemote(remoteId: remoteId)
                result(nil)

            case "startPiP":
                PiPManager.startPIP()
                result(nil)

            case "stopPiP":
                PiPManager.stopPIP()
                result(nil)

            case "dispose":
                PiPManager.dispose()
                result(nil)

            default:
                result(FlutterMethodNotImplemented)
            }
        }

        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }
}  
```


## Flutter Side Implementation ##


**Step 1: Adding a PiP Mode Button in `meeting_controls.dart`**

- Modify the meeting controls UI to include a PiP mode button:

```js  title="meeting_controls.dart"
import 'package:flutter/material.dart';

class MeetingControls extends StatelessWidget {
  // ...
  final void Function() pipButtonPressed;

  const MeetingControls({
    super.key,
    // ...
    required this.pipButtonPressed,
  });

  @override
  Widget build(BuildContext context) {
    return Row(
      mainAxisAlignment: MainAxisAlignment.spaceEvenly,
      children: [
        // ...
        ElevatedButton(
            onPressed: pipButtonPressed,
            child: const Text('PiP Mode'),
        ),
      ],
    );
  }
}
```

**Step 2: Creating a Custom PiP View `pip_view.dart`**

- Since Android natively converts the entire page into PiP mode, we need to create a custom PiP View in Flutter.

```js title="pip_view.dart"
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
import './participant_tile.dart';

class PiPView extends StatefulWidget {
  final Room room;

  const PiPView({super.key, required this.room});

  @override
  State
</div>

<div style={{ marginTop: '30px' }}>
    :::tip  
    Stuck anywhere? Check out this [here](https://github.com/videosdk-live/videosdk-flutter-pip-mode-example.git) on GitHub  
    :::
</div>


---

# Understanding Analytics Dashboard - Flutter

Welcome to the world of actionable insights and empowered decision-making. VideoSDK's session analytics dashboard is your gateway to understanding, optimizing, and elevating every aspect of your sessions.

## Accessing Analytics Made Easy

Navigating through session data is a breeze with VideoSDK. Simply head to your session page at https://app.videosdk.live/meetings/sessions, where a treasure trove of session information awaits.

### How to Access Analytics?

Open Session Analytics effortlessly by following these steps:

1. **Click on Meeting-ID:**
    - Directly access analytics by clicking on the meeting-ID within the session table.
2. **Hover and Click View Analytics:**
    - Hover over a specific meeting row to reveal the **View Analytics** button in the Actions Column.
    - Click on **View Analytics** to open the Session Overview sidebar, unlocking a wealth of insights.

![Access Analytics](https://cdn.videosdk.live/website-resources/docs-resources/access_analytics.png)

---

There are three tabs available within the session analytics view:

## **1. Session Overview**

This tab provides an overview of the session, including its duration and participant details. You can explore individual participant statistics to understand their session performance better.

## **2. Errors**

In this tab, you can find information about any errors encountered during the session. It helps you identify and address issues like network problems or technical glitches promptly.

:::note

Session errors are visible with JS SDK v0.0.82 or higher, React SDK v0.1.85 or higher, and React Native v0.1.6 or newer versions.

:::

## **3. Session Stats**

Explore data and metrics sent and received by participants to measure performance of the session in this tab. It offers insights into data exchange among participants, including metrics on jitter, RTT, and packet loss, resolutions, and fps aiding in assessing communication efficiency.

Let's dive deeper into each of these tabs to gain a better understanding of session analytics.

# Session Overview

The session overview page is your compass in the sea of data. Here's what you'll uncover:

- **Meeting ID:** Unique identifier for the meeting in the format of `abcd-efgh-ijkl`.
- **Session ID:** Unique identifier for each session, uniquely identified by its `sessionId`.
- **Session Status:** Indicates if the session is ongoing or ended.
- **Session Initiating Time:** Time taken by the first participant to establish the connection.
- **Start and End Time:** Marks the start and end of the session.
- **Total Unique Participants Joined:** Total number of unique participants in the session.
- **Total Session Duration:** Overall duration of the session from start to end.
- **Total Participant Minutes:** A sum of all participant duration.
- **Recording, HLS, RTMP:** Additional services used in the session.

### Participant Table List

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for each participant.
- **Join Time:** Time taken by the participant to establish connection.
- **Duration:** Total time spent by this participant in the session.

### Efficient Session Management with Actions

Enhance your session management with streamlined actions:

- **Kick Out Participants:** Effortlessly remove/kickout participants from ongoing sessions.
- **Detailed Participant Analytics:**
- Hover over a specific participant row to reveal the `View Stats` button at the end of the row.
- Click on `View Stats` to open the Participant Overview sidebar.
    
    
![View Stats](https://cdn.videosdk.live/website-resources/docs-resources/view_stats.png)

## Explore Participant Insights

Discover valuable participant data that provides a clear view of engagement and experience:

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for better interaction.
- **Joined At:** Indicates the precise moment when participant connects to the session.
- **Left At:** Indicates the precise moment when participant left the session.
- **Total Duration:** Total duration of participant within that session.
- **Joining Time:** Time taken by the this participant to establish the connection.
- **Location:** Approx. geographic location from where the participant joined.
- **Platform:** Specifies whether participants are using a desktop or mobile device.
- **Device Info:** Offers details regarding the participant's device.
- **OS:** Provides information about the participant's OS.
- **Browser:** Provides specifics about the participant's browser
- **SDK Version:** Indicates the version of the SDK used by participants.

### Understanding Participant Call Health

We've developed call health to offer a rapid assessment of participant performance during calls. This feature highlights the performance of audio, video, and screen sharing audio-video separately. We've utilized color theory, with green indicating good performance, orange for moderate, and red for poor performance, to enhance clarity. For detailed insights, simply hover over the bars

![Participant Call Health](https://cdn.videosdk.live/website-resources/docs-resources/participant_call_health.png)

## Participant Session Stats

Dive into Participant Session Stats for valuable insights into your session experience! With just a click on `View Session Stats` at the bottom of the page, unlock a treasure trove of data crucial for understanding audio and video experiences.

Within this section, you can observe quality metrics for the selected participant, comparing them to others. Additionally, the `Sessions Stats` covers quality stats comparison for every participant. Keep reading to explore more about Session Stats.

**Visualizing Session Performance from Both Sides**

This section provides a two-sided view of your session's metrics.

- **Left Side: Sender Participant Graph** This section displays graphs representing the metrics sent by the sender participant.. Here, you can see how the various factors impacted the data you transmitted.
- **Right Side: Receiver Participant Graph** On the right side, you'll find a dropdown menu where you can select a specific participant. Choosing a receiver will display graphs showcasing the metrics **received by that participant**. This allows you to compare the sending experience (left side) with the receiving experience (right side) for different participants.

![VideoSDK Jitter Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_jitter_graph.png)

**See How Your Session Performed**

These metrics give you a clear picture of your session's quality. Understanding them helps you spot any issues and keep things running smoothly. Let's dive into what each metric means!

**Jitter:** Imagine your internet connection like a bumpy road. Jitter is how much those bumps cause your signal to bounce around. Less jitter means a smoother ride for your data (audio and video, threshold ≤ 30ms).

**RTT (Latency):** This is how long it takes for data to travel between you and the server you're connected to. Think of it like the time it takes for a message to get delivered – a lower RTT means a faster delivery (affects both audio and video, threshold ≤ 300ms).

**Bitrate:** This measures the amount of data flowing through your connection per second. Imagine it like the width of a water pipe – a higher bitrate allows for more data to flow, which can be good for high-quality audio/video or fast downloads.

**Packet Loss:** Think of data traveling in tiny packets. Packet loss is when some of those packets get dropped along the way. More packet loss means information might be missing, affecting things like audio/video quality or lag in games (threshold ≤ 5%).

**Resolution:** This refers to the sharpness and detail of an image or video. Think of it like the number of pixels on your screen – a higher resolution means a crisper picture (**Video Only**).

**FPS (Frames Per Second):** This measures how many images (frames) are displayed on your screen every second. Imagine it like a flipbook – a higher FPS creates a smoother and more fluid animation or video experience (**Video Only**).

![VideoSDK FPS Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_fps_graph.png)

![VideoSDK Resolution Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_resolution_graph.png)

---

# **Analyse Session Stats**

Similar to `Participant Session Stats`, this tab covers quality statistics sent by individual participants. You can select any participant to compare effectively with others.

Choose a sender participant from the dropdown menu on the left and select a recipient on the right to compare data over different time frames. This allows you to identify and explore issues within specific durations.

This tab covers the same metrics as covered in the `participant session stats`: Jitter, RTT (Latency), Bitrate, Packet-loss, Resolution (Video only), and FPS (Video only).

![VideoSDK Session Stats](https://cdn.videosdk.live/website-resources/docs-resources/session_stats.png)


---

# Understanding Call Quality - Flutter

When developing a video call app, customer satisfaction heavily depends on your app's video and audio quality and its fluctuation.

## Call Quality

If we look at the video quality from the user's perspective, a good video quality can be defined as smooth and clear video, along with a crystal clear audio. If the same is viewed from the developer's perspective, a good video quality can be determined as a high resolution, high frame rate video with minimal latency along with a high bitrate audio with minimal audio loss.

## Factors affecting Quality

When it comes to measuring the video and audio quality of a call, there are multiple variables to consider, and the most common factors which affect the video and audio quality are:

### `1. Network Bandwidth`

- Network bandwidth is a measurement of a user's network capability to how large data can be received and send.
- If the bandwidth is low at participant side, he/she is likely to get pixelated or frozen video along with robotic voice or minor breaking in the audio.
- Frequent change in the network providers can also result in high fluctuation of the internet bandwidth, which can also result in poor quality video.

### `2. Latency`

- Latency basically means the time it takes for data to transfer from one machine to another.
- If the meeting is hosted in `Ohio` region, and users are joining from `Singapore` region, so this will create long delay for data to transfer from one machine to another, thus you should pick a server according to your user base.
- In VideoSDK you can set the server during creation of Meeting/Room.

### `3. CPU Usage`

- CPU Usage is an also quite determining factor as all the audio and video streams which are going out and coming in will have to encoded or decoded which will require a significant amount of computation.
- The high the resolution and frame rate of the videos, the larger would be the computation required, which can be a reason for the bottleneck of delivering a good quality video.
- If the CPU is being consumed heavily, it can also result in a choppy or robotic audio.

### `4. Camera and Mic Quality`

- The camera and microphone should capture good quality of streams so that remote user doesn't get low quality stream even if he/she has good network bandwidth

## Identifying the Quality Issues

In order to identify quality issues, VideoSDK collects multiple audio and video related metrics which can help in pinpointing the quality issues. Let's have a look at those metrics and understand what the indicates.

### `1. Resolutions and Framerates`

- Resolution and frame rate are key metrics for video quality in a video call app. Resolution refers to the number of pixels in a video image, while frame rate refers to the number of frames displayed per second.

- Higher resolutions and frame rates can provide better video quality, but they also require more bandwidth and processing power. It's important to optimize this metrics for the devices and network conditions of your users.

- For example, if most of your users are on mobile devices, a lower resolution and frame rate may be more appropriate to ensure smooth playback and minimize bandwidth usage.

- If most of your users are on mobile and desktop devices, having higher resolution for desktop and mid-resolutions for mobile devices can help in improving the performance and quality as we will be saving the bandwidth on the mobile end.

### `2. Bitrate`

- Bitrate is the number of bits per second send or received during the transmission of audio or video streams. Bitrate can be a key parameter to determine the quality of the audio or video streams, as it should be fine-tuned for each resolution to achieve the best match of performance and bandwidth utilization.

- If the users are having excellent network conditions, higher bitrate can result in much better video quality but on the other hand, having very high bitrates on the mobile devices can result in heating issues due to high computation required to encode and decode the videos.

##### Example

We joined using the same phone **(iPhone 14)**, but the resolution and bitrate were different, first participant having resolution **`1280x720`** with bitrate **`1442 kbps`** and second participant having resolution **`960x540`** with bitrate **`642 kbps`**, so as we can see both participants' video appeared to be of equal quality even though resolution and bitrate are different.

![resolution-and-bitrate](/img/resolution-and-bitrate.png)

### `3. Packet Loss`

- Packet loss is a metric that indicates how many data packets are lost during transmission from the sender to the receiver. Packet loss can occur due to network congestion, hardware or software issues, or network latency. Higher packet loss can result in poor video and audio quality, as the missing packets can cause gaps or distortions in the media stream.


<div style={{textAlign: 'center'}}>



</div>

### `4. Jitter`

- The audio and video packets are sent out at random intervals over a specified time frame as they are being sent between the server and client. Nevertheless, jitter is produced when there is a variation in transmitting or receiving this data packets as a result of a faulty network connection.

- When data packets delay while being transmitted to the participant, usually because the network is busy. They'll display as pixelated video on a video call or sound choppy, distorted, or robotic on a voice call as they arrive. They'll arrive at random intervals, creating jitter.

### `5. Round Trip Time (Latency)`

- Round trip time is the amount of time required to transmit the data packets to send or receive from the server. If the servers are located very far from the user's location, they can observe a high latency (delay).

- With VideoSDK, this factor is taken care of as we automatically choose the nearest available server for participants. But if you are geofencing to a certain region, you should make sure that you choose the server which will be nearest to your users.

<center>

![resolution-and-bitrate](/img/rtt.png)

</center>

## Checking Realtime Statistics

VideoSDK provides methods to check the realtime statistics of the audio and video of all the participants.


### `getVideoStats()`

- The `getVideoStats()` method returns an object containing the different quality parameters for video stream, which can be accessed through the `Participant` Class.

- This object will contain values for the specific participant's video stream, including resolution, frame rate, bitrate, jitter, round trip time, and packet loss.

<div style={{textAlign: 'center'}}>



</div>

### `getAudioStats()`

- The `getAudioStats()` method returns an object containing the different quality parameters for audio stream, which can be accessed through the `Participant` Class.

- This object will contain values for the specific participant's audio stream, including bitrate, jitter, round trip time and packet loss.

### `getShareStats()`

- The `getShareStats()` method returns an object containing the different quality parameters for screen share stream, which can be accessed through the `Participant` class.

- This objects will contain values for the specific participant's screen share stream, including resolution, frame rate, bitrate, jitter, round trip time, and packet loss.


## Quality analysis Graphs

For all sessions conducted using VideoSDK, you can access quality analysis graphs from the [VideoSDK Dashboard](https://app.videosdk.live/meetings/sessions). These graphs help you visualize real-time data and identify spikes in certain parameters during calls, aiding in understanding the reasons for quality issues.

![quality analysis](/img/quality-analysis.png)

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [getVideoStats()](/flutter/api/sdk-reference/participant-class/methods#getvideostats)
- [getAudioStats()](/flutter/api/sdk-reference/participant-class/methods#getaudiostats)
- [getShareStats()](/flutter/api/sdk-reference/participant-class/methods#getsharestats)


---

# Virtual Background  - Flutter

Virtual backgrounds let you replace your real background during video calls or meetings with a digital image or video. This can be useful for:

- Privacy: Hide your messy room or anything you don't want others to see.

- Focus: Minimize distractions and keep the focus on the conversation.

- Fun: Liven up the call with a cool background theme.

    

<center>
<img src='https://cdn.videosdk.live/website-resources/docs-resources/virtual-background-ios.jpg' style={{height: '400px'}}/>
</center>

## Virtual Background using `VideoSDKMediaEffects` plugin

The `VideoSDKMediaEffects` plugin enables the integration of sophisticated virtual background effects within your video applications. By leveraging this plugin, users can replace their physical backgrounds with custom images or dynamic video backdrops, creating a more immersive and engaging experience. 

:::info

- The Virtual Background methods from the `VideoSDKMediaEffects` plugin are supported only on Android and iOS devices.
- The Virtual Background feature in VideoSDK can be utilized regardless of the meeting environment, including the pre-call screen.

:::

### Install the plugin 

- Install the `VideoSDKMediaEffects` plugin using the below-mentioned flutter command. Make sure you are in your flutter app directory before you run this command.

```js
$ flutter pub add videosdk_media_effects
```

### Apply Virtual Background

- The `applyVirtualBackground()` method from the `VideoSDKMediaEffects` plugin allows users to dynamically change the video background during a live session. By passing a URI of the desired background image, this method seamlessly integrates the virtual background into the video stream.

### Change Virtual Background

- The `changeVirtualBackground()` method from the `VideoSDKMediaEffects` plugin enables users to effortlessly switch their current virtual background to a new image. This functionality allows for dynamic customization and enhances the user's video experience by providing the ability to update their background on the fly. By passing a URI of the new background image, this method seamlessly integrates the new virtual background into the video stream.

### Remove Virtual Background

- The `removeVirtualBackground()` method from the `VideoSDKMediaEffects` plugin provides users with a convenient way to revert their video background to its original state, removing any previously applied virtual background. This functionality ensures flexibility for users to switch between virtual and real backgrounds as needed.

**Example Code:**


```js

import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
//Import the plugin
import 'package:videosdk_media_effects/videosdk_media_effects.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    //Existing configuration
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        //To Apply Virtual Background
        ElevatedButton(
          onPressed:(){
            Uri backgroundImageURI = Uri.parse("https://cdn.videosdk.live/virtual-background/cloud.jpeg");
            VideosdkMediaEffects.applyVirtualBackground(backgroundSource: backgroundImageURI);
          },
          child: const Text("Apply Virtual Background"),
        ),
        //To Change Virtual Background 
        ElevatedButton(
          onPressed:(){
            Uri newBackgroundImageURI = Uri.parse("https://cdn.videosdk.live/virtual-background/san-fran.jpeg");
            VideosdkMediaEffects.changeVirtualBackground(backgroundSource: newBackgroundImageURI);
          },
          child: const Text("Change Virtual Background"),
        ),
        //To Remove Virtual Background
        ElevatedButton(
          onPressed:(){
            VideosdkMediaEffects.removeVirtualBackground();
          },
          child: const Text("Remove Virtual Background"),
        ),
    //highlight-end
      ]
    );
  }
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [applyVirtualBackground()](/flutter/api/sdk-reference/videosdkmediaeffects-plugin#applyvirtualbackground)
- [changeVirtualBackground()](/flutter/api/sdk-reference/videosdkmediaeffects-plugin#changevirtualbackground)
- [removeVirtualBackground()](/flutter/api/sdk-reference/videosdkmediaeffects-plugin#removevirtualbackground)



---

# Run Audio & Video Call Project - Flutter

Video SDK provides open-source sample project [videosdk-rtc-flutter-sdk-example](https://github.com/videosdk-live/videosdk-rtc-flutter-sdk-example) on Github. This document introduces how to run this project.

## Prerequisites

- If your target platform is iOS, your development environment must meet the following requirements:
  - Flutter 2.0 or later
  - Dart 2.12.0 or later
  - macOS
  - Xcode (Latest version recommended)
- If your target platform is Android, your development environment must meet the following requirements:
  - Flutter 2.0 or later
  - Dart 2.12.0 or later
  - macOS or Windows
  - Android Studio (Latest version recommended)
- If your target platform is iOS, you need a real iOS device.
- If your target platform is Android, you need an Android simulator or a real Android device.
- Valid Video SDK [Account](https://app.videosdk.live/)


### Generate Token

To manage secured communication, every participant that connects to a meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key`, which you can obtain from the [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

**For development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for obtaining a token involves generating it from your backend server which will help in **keeping your credentials safe**.
:::


## Run the Sample Project

### Step 1: Clone the sample project

Clone the repository to your local environment.

```js
$ git clone https://github.com/videosdk-live/videosdk-rtc-flutter-sdk-example.git
```


### Step 2: Copy the .env.example file to .env file.

Open your favorite code editor and copy `.env.example` to `.env` file.

```js
$ cp .env.example .env
```


### Step 3: Modify .env file

Paste earlier generated temporary token here.

```js title=".env"
AUTH_TOKEN = "TEMPORARY-TOKEN";
```


### Step 4: Install the dependencies

Install all the dependencies to run the project.

```js
flutter pub get
```


### Step 5: Run the Sample App

Bingo, it's time to push the launch button.

```js
flutter run
```



---

# Run a Sample HLS Project - Flutter

Video SDK provides open-source sample project [videosdk-hls-flutter-sdk-example](https://github.com/videosdk-live/videosdk-hls-flutter-sdk-example) on Github. This document introduces how to run this project.

## Prerequisites

- If your target platform is iOS, your development environment must meet the following requirements:
  - Flutter 2.0 or later
  - Dart 2.12.0 or later
  - macOS
  - Xcode (Latest version recommended)
- If your target platform is Android, your development environment must meet the following requirements:
  - Flutter 2.0 or later
  - Dart 2.12.0 or later
  - macOS or Windows
  - Android Studio (Latest version recommended)
- If your target platform is iOS, you need a real iOS device.
- If your target platform is Android, you need an Android simulator or a real Android device.
- Valid Video SDK [Account](https://app.videosdk.live/)


### Generate Token

To manage secured communication, every participant that connects to a meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key`, which you can obtain from the [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

**For development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for obtaining a token involves generating it from your backend server which will help in **keeping your credentials safe**.
:::


## Run the Sample Project

### Step 1: Clone the sample project

Clone the repository to your local environment.

```js
$ git clone https://github.com/videosdk-live/videosdk-hls-flutter-sdk-example.git
```


### Step 2: Copy the .env.example file to .env file.

Open your favorite code editor and copy `.env.example` to `.env` file.

```bash
$ cp .env.example .env
```


### Step 3: Modify .env file

Paste earlier generated temporary token here.

```js title=".env"
AUTH_TOKEN = "TEMPORARY-TOKEN";
```


### Step 4: Install the dependencies

Install all the dependencies to run the project.

```js
flutter pub get
```


### Step 5: Run the Sample App

Bingo, it's time to push the launch button.

```js
flutter run
```



---

# Run Interactive Live Streaming Project - Flutter

Video SDK provides open-source sample project [videosdk-ils-flutter-sdk-example](https://github.com/videosdk-live/videosdk-ils-flutter-sdk-example) on Github. This document introduces how to run this project.

## Prerequisites

- If your target platform is iOS, your development environment must meet the following requirements:
  - Flutter 2.0 or later
  - Dart 2.12.0 or later
  - macOS
  - Xcode (Latest version recommended)
- If your target platform is Android, your development environment must meet the following requirements:
  - Flutter 2.0 or later
  - Dart 2.12.0 or later
  - macOS or Windows
  - Android Studio (Latest version recommended)
- If your target platform is iOS, you need a real iOS device.
- If your target platform is Android, you need an Android simulator or a real Android device.
- Valid Video SDK [Account](https://app.videosdk.live/)


### Generate Token

To manage secured communication, every participant that connects to a meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key`, which you can obtain from the [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

**For development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for obtaining a token involves generating it from your backend server which will help in **keeping your credentials safe**.
:::


## Run the Sample Project

### Step 1: Clone the sample project

Clone the repository to your local environment.

```js
$ git clone https://github.com/videosdk-live/videosdk-ils-flutter-sdk-example
```

After that change directory to the project folder:

```js
cd VideoSDK-ILS-Flutter-Example
```


### Step 2: Install the dependencies

Install all the Flutter dependencies

```js
flutter clean

flutter pub get
```


### Step 3: Modify .env

Open your favorite code editor and add VideoSDK `token` in it.

```js title=".env"
AUTH_TOKEN = "TEMPORARY-TOKEN";
```


### Step 4: Run the Sample App

Run the Flutter app with

```js
flutter run
```



---

# Scalability Guide for Large Participant Meetings

## Overview

This guide explains how to optimize performance when hosting video meetings with 10+ participants by using a key feature:

**Adaptive Subscriptions**: Intelligently prioritizes audio/video streams based on who's speaking

These features help solve common challenges in large meetings, such as excessive bandwidth consumption and poor quality for users with network constraints.

## Common Challenges in Large Meetings

### 1. Ineffective Stream Prioritization

**Problem**: All streams receive equal treatment regardless of importance.

**Impact**:

- Users with limited bandwidth experience poor quality
- Audio quality suffers when competing with video for resources
- Important speakers may not be clearly heard or seen

## Solution Features

### Adaptive Subscriptions

This feature optimizes bandwidth by prioritizing active speakers and managing stream quality.

**Key Benefits**:

- Identifies and prioritizes dominant speakers
- Intelligently manages bandwidth constraints
- Ensures clear audio even under network limitations
- Gives highest priority to pinned participants

**How It Works**:  
The system analyzes speaking patterns to detect active participants and adjusts stream priorities accordingly. For bandwidth-constrained users, it strategically pauses or lowers the quality of non-essential video streams. Pinned participants always receive the highest priority in stream allocation.

_Visual Illustration:_

<div style={{textAlign: 'center'}}>

<img src="https://cdn.videosdk.live/website-resources/docs-resources/adaptive_subscriptions_priority.png" alt="Viewport illustration" height="500px"/>
</div>

If a user experiences bandwidth constraints, Adaptive Subscriptions will pause the video streams in the following priority order:

1. Muted Participants
2. Least Dominant Speakers
3. Dominant Speakers

> If you want to achieve pin/unpin functionality, you can refer to [this documentation](https://docs.videosdk.live/flutter/api/sdk-reference/participant-class/methods#pin)

## Implementation Guide

### Prerequisites

- SDK Version: 3.3.0 or later

### Enabling Adaptive Subscriptionss(BETA)

You can toggle this feature using these methods:

```js title="main.dart"
// Enable adaptive subscriptions
room.enableAdaptiveSubscription();

// Disable adaptive subscriptions
room.disableAdaptiveSubscriptions();
```

**Recommended Implementation**:

```js title="main.dart"
@override
void initState() {
  super.initState();
  // Create instance of Room (Meeting)
  initMeeting();
  WidgetsBinding.instance.addObserver(this);
}

initMeeting() async {
  // createRoom called 
  Room room = VideoSDK.createRoom(
    roomId: widget.meetingId,
    token: widget.token,
    displayName: widget.displayName,
    micEnabled: widget.micEnabled,
    camEnabled: widget.camEnabled,
    multiStream: true,
  );
  // register events
  registerMeetingEvents(room);
}

void registerMeetingEvents(Room _meeting) {
  // Called when joined in meeting
  _meeting.on(
    Events.roomJoined,
    () async {
      _meeting.enableAdaptiveSubscription();
    },
  );
}   
```

### Stream Pause/Resume Events

When a video stream is paused or resumed, the system triggers events with specific reasons:

```js title="participant_tile.dart"
participant.on(Events.streamPaused, (kind, reason) {
  // when stream will get paused this event will be received
});
participant.on(Events.streamResumed, (kind, reason) {
  // when stream will get resumed this event will be received
});
```

**Pause Reasons**:

- `muted`: Participant has turned off their audio
- `leastDominance`: Participant hasn't spoken much in the meeting

**Resume Reasons**:

- `adaptiveSubscriptionsDisabled`: Feature was disabled
- `networkStable`: Network conditions have improved

> **Developer Tip**: When a stream is paused (e.g., due to network issues), always keep users in the loop by displaying a helpful UI indicator. For instance, render a message such as:
> "Paused: Waiting for stable connection..."

## Best Practices

- Enable adaptive subscriptions at the start of every meeting
- Design your UI to display indicators when a stream is paused
- Pin important participants to ensure they receive the highest streaming priority




---

# End-to-End Encryption (E2EE) - Flutter

## Overview

End-to-end encryption (E2EE) ensures that your media content remains private and secure by encrypting it on the sender's device and decrypting it only on the receiver's device. This prevents intermediaries, including VideoSDK servers, from accessing or modifying the content.

E2EE is particularly important for applications in security-critical domains such as telehealth, finance, and legal services.


## E2EE Modes
VideoSDK offers two modes of End-to-End Encryption (E2EE) for securing media streams during sessions:
  1. **Shared Key** (Meeting-Level): A single encryption key is used across the entire session, encrypting and decrypting media tracks for all participants.
  2. **Per-Participant Keys**: Individual participants have unique encryption keys, providing enhanced security by ensuring each participant's media streams are encrypted separately.

## How E2EE Works
- E2EE is applied at the session level, where in Shared Key mode, a single key encrypts and decrypts all media tracks for every participant, while in Per-Participant Keys mode, each participant is assigned a unique key to encrypt their individual media streams separately.
- Participants without the key cannot access the media.
- The entire encryption process is handled client-side. VideoSDK does not access or store any encryption keys.

## Key Management & Distribution

You are **fully responsible** for generating, managing, and securely distributing encryption keys to all participants. VideoSDK **never stores, accesses, or transfers** your encryption keys.

- Common Key Distribution Approaches:
  - Generate the key **on your server** when creating a meeting.
  - Send the key securely along with the **meeting access token**.
  - Use **HTTPS-secured API calls** to fetch the key on the client.

:::important

⚠️ Ensure that all participants have access to the correct encryption key before joining the room.

:::

## SDK Version Compatibility

The table below lists the minimum SDK versions that support E2EE.

| Flutter | iOS | React Native | React   | Android | JavaScript |
|---------|--------|---------------|-------|----------|-------------|
| 2.1.0   | 2.2.2 | 0.2.1 | 0.3.5 | 0.5.0 | 0.2.6 |
---

## Enabling E2EE in VideoSDK Flutter

VideoSDK provides two ways to enable End-to-End Encryption (E2EE):
1. **Shared Key**: A single encryption key shared by all participants.
2. **Per-Participant Key**: Unique encryption keys assigned to individual participants.


#### 1. Enabling E2EE using a Shared Key

When using a shared key, all participants utilize the same encryption key, set via the `setSharedKey()` method.

```js
@override  
void initState() {  
  super.initState();  

  // Set up the encryption key  
  keySetup();

  // Initialize the meeting instance  
  Room room = VideoSDK.createRoom(
    roomId: meetingId,
    token: token,
    displayName: displayName,
  );
}  

Future<void> keySetup() async {  
  try {  
    var baseKeyProvider =  BaseKeyProvider();  

    // Set a single shared encryption key for all participants
    await baseKeyProvider.setSharedKey('<Your Encryption Key>');

    // Set the key provider for E2EE
    VideoSDK.setKeyProvider(baseKeyProvider);  
  } catch (e) {  
    print("Error setting encryption key: ${e.toString()}");  
  }  
}  
```

:::warning

Make sure to set the encryption key using `setSharedKey()` before assigning the key provider with `setKeyProvider()`, otherwise it will throw an Exception.

:::


#### 2. Enabling E2EE using Per-Participant Keys

Per-Participant Keys enhance security by assigning a distinct encryption key to each participant, ensuring that access is uniquely controlled on a per-user basis.

##### Step 1. Initialize the BaseKeyProvider and Set Up Encryption Keys

- To enable encryption, you must set the **localParticipantId** along with its corresponding key using the `setKey()` method of the `BaseKeyProvider` class.
- Store each participant's ID and key securely on your server for decryption purposes.

:::important
You must use a single, shared `BaseKeyProvider` instance for both encryption (local participant) and decryption (remote participants).
:::


```js
class MeetingScreen extends StatefulWidget {
  const MeetingScreen({super.key});

  @override
  State<MeetingScreen> createState() => _MeetingScreenState();
}

class _MeetingScreenState extends State<MeetingScreen> {

  // Declare globally
  BaseKeyProvider baseKeyProvider = BaseKeyProvider();
  
  @override
  void initState() {
    super.initState();

    String localParticipantId = "YOUR_LOCAL_PARTICIPANT_ID";

    // Set up the encryption key 
    keySetup(localParticipantId , "SECRET_KEY");
    
    // Initialize the meeting instance  
    Room room = VideoSDK.createRoom(
      roomId: meetingId,
      token: token,
      displayName: displayName,
      participantId: localParticipantId,
    );
  }

  Future<void> keySetup(String participantId , String key) async {
    try {
      // Per-Participant E2EE: Set key for local participant
             // highlight-next-line
      await baseKeyProvider.setKey(participantId, key); // Your Encryption Key 
      VideoSDK.setKeyProvider(baseKeyProvider);
    } catch (e) {
      log("Error in setting the keys: ${e.toString()}");
    }
  }
}
```

:::warning

Make sure to set the encryption key using `setKey()` before assigning the key provider with `setKeyProvider()`, otherwise it will throw an Exception.

:::


##### Step 2. Decrypting Participant Streams using Per-Participant Keys

- When a participant joins, retrieve the corresponding encryption key (previously stored on your server) using the participant’s ID to decrypt their media streams.
- Use the same `BaseKeyProvider` instance to set the key for that remote participant to decrypt their media stream.

```js
class MeetingScreen extends StatefulWidget {
  const MeetingScreen({super.key});

  @override
  State<MeetingScreen> createState() => _MeetingScreenState();
}

class _MeetingScreenState extends State<MeetingScreen> {

  @override
  void initState() {
    super.initState();

    // Create instance of Room (Meeting)
    Room room = VideoSDK.createRoom(
      roomId: meetingId,
      token: token,
      displayName: displayName,
      participantId: participantId,
    );

    // Regiser Meeting event
    registerMeetingEvents(room);
  }
  
  void registerMeetingEvents(Room room) {

    room.on(Events.participantJoined, (Participant participant) {
      try {
        // Retrieve key from your server using participant.id
        String key = "SECRET_KEY";

        // Set the retrieved key to decrypt incoming participant streams
        // highlight-next-line
        baseKeyProvider.setKey(participant.id,key);
      } catch (e) {
        log("Error in setting the keys: ${e.toString()}");
      }
    });
  }
}
```

:::important

- Ensure all encryption keys are securely stored and retrieved from your server.
- Proper key management is essential for effective encryption and decryption, especially when using Per-Participant Keys.

:::

#### Additional Configuration Options

You can customize the encryption behavior by passing parameters while creating the BaseKeyProvider instance:

| Parameter                     | Type       | Description |
|--------------------------------|-----------|-------------|
| `discardFrameWhenCryptorNotReady` | `bool`  | If `true`, frames will be discarded when the cryptor is not ready, ensuring no unencrypted content is sent. |

## E2EE in Flutter Web

For Flutter Web, a dedicated worker file is required to handle cryptographic operations. Run the following command in your project root:

```bash
dart run videosdk:install_worker
```

This will install the required worker file inside your web directory.

## Event for the e2ee state

To monitor encryption state changes for each participant's media stream:

```js
widget.participant.on(Events.e2eeStateChanged, (
  E2EEState state,
  Stream stream,
) {
  print("$state is for the ${stream.kind}");
});
```

The possible values for `state` are:

| State |  Description |
|-------|--------------|
| EncryptionSuccess | Media encryption is successfully applied.|
| DecryptionSuccess | Incoming media is successfully decrypted.|
| EncryptionFailed | Encryption encountered an error. |
| DecryptionFailed | Decryption encountered an error. |
| InternalError | Internal processing error occurred. |

## To check whether E2EE is enabled

You can check whether E2EE is enabled by using `e2eeEnabled` property of `Room` class.

```dart
bool isE2EEEnabled = _room.e2eeEnabled;
print("Is E2EE Enabled: $isE2EEEnabled");
```

## Limitations

E2EE only applies to media. It does not apply to:

- Chat messages or metadata
- API calls and signaling data

These communications are still protected by TLS but are not encrypted end-to-end.

:::info

Recording and transcription features are not supported when End-to-End Encryption (E2EE) is enabled.

:::


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>
<h1> {props.title} </h1>{" "}

### Why we are using JWT based Token ?

Token based authentication allows users to verify their identity by providing generated API key and secret.

We use JWT token for the authentication purpose because Token-based authentication is **widely used** in modern web applications and APIs because it offers several benefits over traditional authentication. For example, it can **reduce the risk of the credentials being misused**, and it allows for **more fine-grained control** over access to resources. Additionally, tokens can be easily revoked or expired, making it easier to manage access rights.

### How to generate Token ?

To manage secured communication, every participant that connects to the meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key` which you can get from [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

#### 1. Generating token from Dashboard

If you are looking to do **testing or for development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for getting token includes generating it from your backend server which will help in **keeping your credentials safe**.
:::

#### 2. Generating token in your backend

- Your server will generate access token using your API key and secret.
  - While generating a token, you can provide **expiration time, permissions and roles** which are discussed later in this section.
- Your client obtains token from your backend server.
- For token validation, client will pass this token to VideoSDK server.
- VideoSDK server will only allow entry in the meeting if the token is valid.

![img2.png](../../static/img/authentication-and-token.png)




Follow our official example repositories to setup token API [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)

### Payload while generating token

```js
{
 apikey: API_KEY, //MANDATORY
 permissions: [`allow_join`], //`ask_join` || `allow_mod` //MANDATORY
 version: 2, //OPTIONAL
 roomId: ROOM_ID, //OPTIONAL,
 participantId: PARTICIPANT_ID, //OPTIONAL
 roles: ['crawler', 'rtc'], //OPTIONAL
}
```

- **`apikey`(Mandatory)**: This must be the API Key generated from the VideoSDK Dashboard. You can get it from [here](https://app.videosdk.live/api-keys).

- **`permissions`(Mandatory)**: By providing the permissions, you can control what a participant can do in the meeting and whether he can join the meeting directly.

  Available permissions are:

  - **`allow_join`**: The participant is **allowed to join** the meeting directly.
  - **`ask_join`**: The participant is required to **ask for permission to join** the meeting. The participant having the permission `allow_join` can accept or reject a participant whenever someone wants to join.
  - **`allow_mod`**: The participant is **allowed to toggle** webcam & mic of other participants.

- **`version`(optional)**: For accessing the [v2 API](/api-reference/realtime-communication/intro), you need to provide `2` as the version value.

  - For passing `roomId`, `participantId` or `roles` parameters in payload, it is essential to set the version value to `2`.

- **`roomId`(optional)**: To provide customised access control, you can make the token applicable to a particular room by including the `roomId` in the payload.

- **`participantId`(optional)**: You can include the `participantId` in the payload to limit the token's access to a particular participant.

- **`roles`(optional)**:

  - **`crawler`**: This role is only for accessing [v2 API](/api-reference/realtime-communication/intro), you can not use this token for running the `Meeting`/`Room`.
  - **`rtc`**: This role is only allowed for running the `Meeting` / `Room`, with this role you can not use [server-side APIs](/api-reference/realtime-communication/intro).

Then, you have to sign this payload with your **`SECRET KEY`** and `jwt` options using the **`HS256 algorithm`**.

### Expiration time

You can set any expiration time to the token. But in the **production environment**, it is recommended to generate a token with **short expiration time** because by any chance if someone gets hold of the token, it won't be valid for a longer period of time.

### What happens if token is expired?

If your token is expired, the user won't be able to join the meeting and all the API calls will give error with message `Token is invalid or expired`.

:::note
Token is validated only once while joining the meeting, so if a person joins the meeting and the token gets expired after that, there won't be any issue in the current meeting.
:::

## How to check validity of token?

1. After generating the token, visit [jwt.io](https://jwt.io) and paste your token in the given area.
2. You will be able to see the payload you passed while generating the token and also be able to see the expiration time and token creation time.

![img1.png](../../static/img/validate-token.png)

## API Settings & Controls

The VideoSDK Dashboard provides a powerful [API Settings](https://app.videosdk.live/api-keys) section where you can configure various services and controls for your meetings. These settings allow you to customize the behavior of different features directly from the dashboard without requiring code changes.

## Audio/Video Configurations

:::note
Runtime configuration from the dashboard has higher precedence than static SDK configurations.
If a value is modified in the dashboard, it will override any previously defined SDK settings for that session.

Example:
Code: Video = HD → Dashboard: Video = Full HD → Applied: Full HD
:::

### Maximum Send Bitrate Per Participant

Control the maximum total upload bandwidth for all media streams from a single participant.

![Maximum Send Bitrate](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.00.11%E2%80%AFPM.png)

**Available Options:**
- **Auto**: Removes the upload bitrate limit (recommended for best quality)
- **SD (800kbps)**: Standard definition bitrate
- **HD (1500kbps)**: High definition bitrate
- **Full HD (3000kbps)**: Full high definition bitrate

:::tip
Setting this to **Auto** provides the best video quality as it removes upload bitrate constraints, allowing adaptive streaming based on network conditions.
:::

## Recording & Streaming Configuration

:::note
Recording and HLS follow a precedence-based configuration model:

API/SDK configuration → Highest priority
Dashboard configuration → Used only when no API values are defined

Any parameters explicitly set via the API will not be overridden by dashboard changes.
:::

### Recording Configuration

Configure recording settings for your meetings including layout, quality, and auto-start options.

![Recording Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.01.00%E2%80%AFPM.png)

**Recording Controls:**
- **Enabled**: Toggle to enable/disable recording functionality
- **Enabled Modes**: Choose between Video & Audio or Audio Only recording
- **Start Recording Automatically**: Auto-start recording when meeting begins
- **Layout Style**: Select Grid layout for recording composition
- **Maximum Tiles In Grid**: Set the number of participants visible in grid (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme for recordings
- **Video Orientation**: Choose between Landscape or Portrait mode
- **Recording Quality**: Select quality level (e.g., HD Medium)
- **Recording Mode**: Choose between Video & Audio or Audio Only

### HLS Streaming Configuration

Configure HTTP Live Streaming (HLS) settings for broadcasting your meetings.

![HLS Streaming Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.02.18%E2%80%AFPM.png)

**HLS Streaming Controls:**
- **Enabled**: Toggle to enable/disable HLS streaming
- **Enabled Modes**: Choose between Video & Audio or Audio Only streaming
- **Auto Start HLS**: Automatically start HLS when meeting begins
- **Record HLS Stream**: Enable recording of the HLS stream
- **Layout Style**: Select Grid layout for stream composition
- **Maximum Tiles In Grid**: Set the number of participants visible (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme
- **HLS Orientation**: Choose between Landscape or Portrait mode
- **HLS Quality**: Select streaming quality (e.g., HD Medium)
- **HLS Streaming Mode**: Choose between Video & Audio or Audio Only

### Additional Service Controls

Enable or disable additional services for your API key.

![Service Controls](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.08%E2%80%AFPM.png)

**Available Services:**
- **RTMP Output**: Enable RTMP streaming to external platforms
- **SIP Integration**: Enable SIP (Session Initiation Protocol) integration for telephony
- **Realtime Translation**: Enable real-time language translation in meetings

### Transcription & Summary

Configure transcription and domain whitelisting for your API key.

![Transcription Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.50%E2%80%AFPM.png)

**Transcription Controls:**
- **Enabled**: Toggle to enable/disable transcription and summary features
- **Whitelist Domain**: Add domain restrictions for API key usage
  - Enter domain names in the format `https://domain.name`
  - Click "Add Domain" to whitelist specific domains
  - Only whitelisted domains can use this API key
  - When no domains are whitelisted, the API key can be used from any domain


---

# Initialise Meeting - Flutter

To configure a VideoSDK meeting you require two things, first the `token` which will be used for **Authentication** purpose and a `meetingId` which will be used to specify where a participant will join. Let's see each of the steps closely.

### Generating Token

You can generate a `token` in two ways:

1. **`Temporary Token`** : You can visit [Dashboard's API Key section](https://app.videosdk.live/api-keys) and generate the temporary token from there.

2. **`Server`** : You can setup **JWT** in backend and make an API call to get the token from your server.

To learn more about **Authentication** and token in detail you can follow [this guide](../authentication-and-tokens).

```js
// With Temporary Token
Future<String> getToken() async {
  // Update the token here from the VideoSDK dashboard
  // highlight-next-line
  let token = "YOUR_TOKEN";
  return token;
};

// Server
// API call to create meeting
Future<String> getToken(String token) async {
  final http.Response httpResponse = await http.post(
    //highlight-start
    //Using the VideoSDK API Endpoint
    Uri.parse('http://localhost:8080/get-token'),
    //highlight-end
  );

  //Destructuring the roomId from the response
  return json.decode(httpResponse.body)['token'];
}
```

### Generating Meeting Id

With the token ready, we can get the `meetingId` from the [VideoSDK's rooms API](/api-reference/realtime-communication/create-room).

```js
// API call to create meeting
Future<String> createMeeting(String token) async {
  final http.Response httpResponse = await http.post(
    //highlight-start
    //Using the VideoSDK API Endpoint
    Uri.parse('https://api.videosdk.live/v2/rooms'),
    //Passing the token in headers
    headers: {'Authorization': token},
    //highlight-end
  );

  //Destructuring the roomId from the response
  return json.decode(httpResponse.body)['roomId'];
}
```

### Initialization of Meeting

We can initialize a new meeting using the `createRoom` method of the `VideoSDK` class. `createRoom` method returns a `Room` object, which will be configured using the provided `token`, `meetingId`, `participantId` and other parameters.

#### createRoom()

Let's take a deeper look at the available configuration options first.

```js
Room room = VideoSDK.createRoom(
  roomId: "Meeting-d",
  token: "Token",
  displayName: "<Name-of-participant>",
  micEnabled: "<Flag-to-enable-mic>",,
  camEnabled: "<Flag-to-enable-webcam>",
  participantId: "Id-of-participant", // optional, default: SDK will generate
);
```

- **`roomId`** :

  - roomId is unique identifiers that allow participants to join a specific meeting or room.
  - It will be in the format of `xxx-yyy-zzz` and will be generated using the [VideoSDK's Room API](/api-reference/realtime-communication/create-room).

- **`displayName`**:

  - This will represent the name of the participant in the meeting.
  - It will accept `String`type value.

- **`micEnabled`**:

  - This is a `boolean` flag, indicating whether a participant's microphone will be automatically enabled when they join a meeting.

- **`camEnabled`**:

  - This is a `boolean` flag, indicating whether a participant's webcam will be automatically enabled when they join a meeting.

- **`participantId`**:

  - This will be the unique identifier for the participant inside the meeting.

    - It can be used to specify the **unique identifier** which can be linked with **your own database** service.
    - It has to be of `String` type.
    - This is an `OPTIONAL` parameter. By default VideoSDK will generate unique id for each participant.

:::caution
You must ensure that the `participantId` is not repeated in the same meeting or room, It will enable VideoSDK to eliminate any participant respect to that `participantId`.
:::

To know more about other properties, you can follow [our API Reference](../../../api/sdk-reference/videosdk-class/methods).

With all the configuration options explained, here is how you will be using the `VideoSdk Class`.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  final String meetingId;
  final String token;

  const MeetingScreen(
      {super.key, required this.meetingId, required this.token});

  @override
  State<MeetingScreen> createState() => _MeetingScreenState();
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-start
    //Creating a new Room based on the passed meetingId and token from the Joining Screen
    // create room
    _room = VideoSDK.createRoom(
      roomId: widget.meetingId,
      token: widget.token,
      displayName: "John Doe",
      micEnabled: true,
      camEnabled: true,
      defaultCameraIndex:
          1, // Index of MediaDevices will be used to set default camera
    );
    //highlight-end
    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }
}

```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [createRoom](/flutter/api/sdk-reference/videosdk-class/methods#createroom)


---

# Join Meeting - Flutter

### Overview

Before joining the meeting, it has to be initialized. If you have not initialized a meeting/room yet, you can [follow the guide here.](./initialise-meeting)

### `join()`

- To join the meeting you can call the `join()` on the created `Room` object.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //Creating a new Room based on the passed meetingId and token from the Joining Screen
    // create room
    _room = VideoSDK.createRoom(
      roomId: widget.meetingId,
      token: widget.token,
      displayName: "John Doe",
      micEnabled: true,
      camEnabled: true,
      defaultCameraIndex:
          1, // Index of MediaDevices will be used to set default camera
    );

    //highlight-start
    //Calling Join after the room object is created
    _room.join()
    //highlight-end

    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }
}

```

### Events associated with Join

Following callbacks are received when a participant is successfully joined.

- [Local Participant](../concept-and-architecture#2-participant) will receive a [`Events.roomJoined`](/flutter/api/sdk-reference/room-class/events#roomjoined) event, when successfully joined.
- [Remote Participant](../concept-and-architecture#2-participant) will receive a [`Events.participantJoined`](/flutter/api/sdk-reference/room-class/events#participantjoined) event with the newly joined `Participant` object from the event callback.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {
    room.on(Events.roomJoined, (){
      // Room/Meeting joined Successfully
    });
    room.on(Events.participantJoined, (Participant participant){
      // New Participant joined the meeting
    });
  }
  //highlight-end
}
```

#### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [join()](/react/api/sdk-reference/use-meeting/methods#join)
- [roomJoined](/flutter/api/sdk-reference/room-class/events#roomjoined)
- [participantJoined](/flutter/api/sdk-reference/room-class/events#participantjoined)


---

# Leave or End Meeting - Flutter

Participant can choose to leave the meeting without removing all the other participants. This is typically done by `Leave Meeting`.

Alternatively, if the participant is the host or the last person remaining in the session, they can choose `End Meeting` by removing all other participants, which will end the session for everyone.

### `leave()`

To leave the meeting without removing all the participant you need to call `leave()` on the `Room` object.

### `end()`

To leave the meeting by removing all the participant you need to call `end()` on the `Room` object.

#### Example

```jsx
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        ElevatedButton(
          onPressed:(){
            _room.leave();
          },
          child: const Text("Leave Meeting"),
        ),
        ElevatedButton(
          onPressed:(){
            _room.end();
          },
          child: const Text("End Meeting"),
        ),
    //highlight-end
      ]
    );
  }
}
```

:::tip
You should call the `leave()` method on the unmount of your main meeting widget so that meeting is left once the widget is unmounted.
:::

### Events associated with Leave

Following callbacks are received when a participant leaves the meeting.

- [Local Participant](../concept-and-architecture#2-participant) will receive a callback on [`Events.roomLeft`](/flutter/api/sdk-reference/room-class/events#roomleft).
- All [remote participants](../concept-and-architecture#2-participant) will receive a callback [`Events.participantLeft`](/flutter/api/sdk-reference/room-class/events#participantleft), along with the `participantId` of the participant who left.

### Events associated with End

Following callbacks are received when a participant ends the meeting.

- All [remote participants](../concept-and-architecture#2-participant) and local participant will receive a callback on [`Events.roomLeft`](/flutter/api/sdk-reference/room-class/events#participantleft).

```jsx
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...

    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }

  //highlight-start
  void setupRoomEventListener() {
    room.on(Events.roomLeft, (){
      // Room/Meeting left
    });
    room.on(Events.participantLeft, (String participantId , Map<String,dynamic> reason){
      // Participant left the meeting
    });
  }
  //highlight-end
}
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [leave()](/flutter/api/sdk-reference/room-class/methods#leave)
- [end()](/flutter/api/sdk-reference/room-class/methods#end)
- [roomLeft](/flutter/api/sdk-reference/room-class/events#roomleft)
- [participantLeft](/flutter/api/sdk-reference/room-class/events#participantleft)


---

# Precall Setup - Flutter

Picture this: before diving into the depths of a video call, imagine giving your setup a quick check-up, like a tech-savvy doctor ensuring all systems are a go. That's essentially what a precall experience does- it’s like your extensive debug session before the main code execution—a crucial step in ensuring your app's performance is top-notch.

## **Step-by-Step Guide: Integrating Precall Feature**

### **Step 1: Check Permissions**

- Begin by ensuring that your application has the necessary permissions to access user devices such as cameras, microphones, and speakers.
- Utilize the `checkPermissions()` method of the `VideoSDK` class to verify if permissions are granted.
- To enable checking of microphone and camera permissions on iOS devices, add the following to your `Podfile`:

```js
post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
    //Add this into your podfile
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
        'PERMISSION_CAMERA=1',
        'PERMISSION_MICROPHONE=1',
      ]
    end
  end
end
```

```js
import 'package:videosdk/videosdk.dart';

void checkMediaPermissions() async {
  try {
  //By default both audio and video permissions will be checked.
  Map

</center>

### **Step 2: Request Permissions (if necessary)**

- If permissions are not granted, use the `requestPermission()` method of the `VideoSDK` class to prompt users to grant access to their devices.
- To enable requesting of microphone and camera permissions on iOS devices, add the following to your `Podfile`:

```js
post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
    //Add this into your podfile
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
        'PERMISSION_CAMERA=1',
        'PERMISSION_MICROPHONE=1',
      ]
    end
  end
end
```

:::note

In case permissions are blocked by the user, the permission request dialogue cannot be re-rendered programmatically. In such cases, consider providing guidance to users on manually adjusting their permissions.

:::

```js
void requestMediaPermissions() async {
  try {
      //By default both audio and video permissions will be requested.
      Map

</center>

### **Step 3: Render Device List**

- Once you have the necessary permissions, Fetch and render list of available video and audio devices using the `getVideoDevices()` and `getAudioDevices()` methods of the `VideoSDK` class respectively.
- Enable users to select their preferred devices from these lists.

:::note

For iOS devices:

- `EARPIECE` is not supported whenever `WIRED_HEADSET` or `BLUETOOTH` device is connected.
- `WIRED_HEADSET` and `BLUETOOTH` devices are not supported simultaneously. Priority is given to the most recently connected device.

:::

```js

List

</center>

### **Step 4: Handle Device Changes**

- Implement the `deviceChanged` callback of the `VideoSDK` class to dynamically re-render device lists whenever new devices are attached or removed from the system.
- Ensure that users can seamlessly interact with newly connected devices without disruptions.

:::info

- The `deviceChanged` event is not supported in macOS applications.

:::

```js
VideoSDK.on(
  Events.deviceChanged,
  (devices) {
    print("device changed ${devices}");
  },
);
```

### **Step 5: Ensuring the selected devices are used in the Meeting**

- Ensure that all relevant states, such as microphone and camera status (on/off), and selected devices, are passed into the meeting from the precall screen.
- This can be accomplished by passing these crucial states and media streams onto the VideoSDK and Room Methods.
- For the video device, create a custom track with the selected CameraID and pass it to the `createRoom` method.
- For audio devices in web and desktop applications:
  - Use the `switchAudioDevice` method to select the desired audio output device.
  - Use the `changeMic `method to select the desired audio input device once the room is joined.
- For audio devices in mobile applications, use the `switchAudioDevice` method to select both the input and output audio devices.
- By ensuring this integration, users can seamlessly transition from the precall setup to the actual meeting while preserving their preferred settings.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  final String meetingId;
  final String token;

  const MeetingScreen(
      {super.key, required this.meetingId, required this.token});

  @override
  State<MeetingScreen> createState() => _MeetingScreenState();
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //Create a custom track with the selectedVideoDevice Id
    CustomTrack? cameraTrack = await VideoSDK.createCameraVideoTrack(
      cameraId: selectedVideoDevice?.deviceId);
    // create room
    _room = VideoSDK.createRoom(
      roomId: widget.meetingId,
      token: widget.token,
      displayName: "John Doe",
      micEnabled: true,
      camEnabled: true,
      customCameraVideoTrack: cameraTrack, //For Video Devices
    );
    registerMeetingEvents(room);
    super.initState();
  }

  //For Audio Devices
void registerMeetingEvents(Room _meeting) {
    // Called when joined in meeting
  _meeting.on(
    Events.roomJoined,
    () {
      //When meeting is joined, call the switchAudioDevice method to switch Audio Output.
      _meeting.switchAudioDevice(widget.selectedAudioOutputDevice!);

      //When meeting is joined, call the changeMic method to switch Audio Input.(Onlyrequired for web and desktop applications)
        if (kIsWeb || Platform.isWindows || Platform.isMacOS) {
          _meeting.changeMic(widget.selectedAudioInputDevice!);
        }
    },
  );
}

  @override
  Widget build(BuildContext context) {
    return YourMeetingWidget();
  }
}
```

By following these step-by-step instructions, you can seamlessly integrate a precall feature into your application, empowering users to optimize their audio and video setup for a superior communication experience.

:::note

You can explore the complete implementation of the Precall feature in the official Flutter SDK example [available here.](https://github.com/videosdk-live/videosdk-rtc-flutter-sdk-example)

:::

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [getVideoDevices](/flutter/api/sdk-reference/videosdk-class/methods#getvideodevices)
- [getAudioDevices](/flutter/api/sdk-reference/videosdk-class/methods#getaudiodevices)
- [deviceChanged](/flutter/api/sdk-reference/videosdk-class/events#devicechanged)
- [checkPermissions](/flutter/api/sdk-reference/videosdk-class/methods#checkpermissions)
- [requestPermissions](/flutter/api/sdk-reference/videosdk-class/methods#requestpermissions)


---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

### Generate Token

To manage secured communication, every participant that connects to a meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key`, which you can obtain from the [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

**For development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for obtaining a token involves generating it from your backend server which will help in **keeping your credentials safe**.
:::



---

SIP Connect allows you to connect any SIP-compatible device or softphone to a VideoSDK room. This guide explains how to configure SIP for your VideoSDK account and connect a SIP user to an existing meeting.

## Architecture

The following diagram illustrates how SIP Connect works. A SIP user connects to the VideoSDK SIP Gateway, which then bridges the call to the VideoSDK Room.

![VideoSDK Telephony Workflow](https://strapi.videosdk.live/uploads/SIP_CONNECT_c81702f580.png)

## Steps

In this guide, we are using Twilio as the SIP provider, but you can choose from other providers like Plivo, Exotel, Telnyx, Ozontel, etc. The configuration process is similar across most providers.

### 1. Create VideoSDK Meeting


:::note
Ensure you have a VideoSDK meeting setup. If you don't have one, follow the <a href={props.quickStartLink}>Quick Start Guide</a> to create a basic video calling app.
:::

You can connect a SIP user to any active VideoSDK meeting. If you already have a meeting ID, you can proceed to the next step.



### 2. Create Inbound Gateway


An **Inbound Gateway** is required to receive calls from a SIP provider (like Twilio, Vonage, Telnyx) and route them to VideoSDK.

**twilio:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/inbound-gateways).
2. Navigate to **Telephony > Inbound Gateways**.
3. Click **Add Inbound Gateway**.
4. Enter a name and the phone number you purchased from your SIP provider.
5. Select the Geo Region option and choose where inbound SIP traffic should be routed (currently supported: India, US).
6. Click **Create**.
7. Copy the **Inbound Gateway SIP URI**
- Default: `sip:orgId.sip.videosdk.live`
- Regional (to restrict calls to a specific region): `sip:orgId.<region>.sip.videosdk.live`
8. Configure this URI as the **Origination SIP URI** in your SIP provider's dashboard (e.g., Twilio, Vonage, Telnyx).

<div style={{textAlign: 'center'}}>
  
</div>

---

**vonage:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/inbound-gateways).
2. Navigate to **Telephony > Inbound Gateways**.
3. Click **Add Inbound Gateway**.
4. Enter a name and the phone number you purchased from Vonage.
5. Select the Geo Region option and choose where inbound SIP traffic should be routed (currently supported: India, US).
6. Click **Create**.
7. Copy the **Inbound Gateway SIP URI**
- Default: `sip:orgId.sip.videosdk.live`
- Regional (to restrict calls to a specific region): `sip:orgId.<region>.sip.videosdk.live`
8. In your **Vonage Console**, go to your SIP Trunk settings.
9. Under **Inbound Calls**, select your region.
10. In the **URI** section, paste the Inbound Gateway SIP URI you copied.
11. Link the phone number you purchased to this trunk.

<div style={{textAlign: 'center'}}>
  
</div>

---

**telnyx:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/inbound-gateways).
2. Navigate to **Telephony > Inbound Gateways**.
3. Click **Add Inbound Gateway**.
4. Enter a name and the phone number you purchased from Telnyx.
5. Select the Geo Region option and choose where inbound SIP traffic should be routed (currently supported: India, US).
6. Click **Create**.
7. Copy the **Inbound Gateway SIP URI**
- Default: `sip:orgId.sip.videosdk.live`
- Regional (to restrict calls to a specific region): `sip:orgId.<region>.sip.videosdk.live`
8. In your **Telnyx Console**, go to **Connections** and create a new SIP Connection.
9. Set the type as **FQDN**.
10. Under **FQDN**, add the VideoSDK Inbound Gateway SIP URI you copied.
11. Assign the phone number you purchased to this connection.

<div style={{textAlign: 'center'}}>
  
</div>

---

**api:**

You can create an inbound gateway programmatically using the API.

```bash title="cURL"
curl --request POST \
  --url https://api.videosdk.live/v2/sip/inbound-gateways \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
"name": "My Inbound Gateway",
"numbers": ["+1234567890"]
  }'
```

> **API Reference**: [Create Inbound Gateway](/api-reference/realtime-communication/sip/inbound-gateway/create-inbound-gateway)



### 3. Create Outbound Gateway


An **Outbound Gateway** is used if you want to dial out to a SIP user from a VideoSDK meeting.

**twilio:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/outbound-gateways).
2. Navigate to **Telephony > Outbound Gateways**.
3. Click **Add Outbound Gateway**.
4. Enter a name.
5. Enter the **Termination SIP URI** provided by your SIP provider.
6. Enter the **Username** and **Password** for your SIP provider.
7. Set the Geo Region to route outbound calls through a specific region (currently supported: India, US).
8. Click **Create**.

<div style={{textAlign: 'center'}}>
  
</div>

---

**vonage:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/outbound-gateways).
2. Navigate to **Telephony > Outbound Gateways**.
3. Click **Add Outbound Gateway**.
4. Enter a name.
5. Enter the **Domain** you set up in your Vonage SIP Trunk settings.
6. Enter the **Username** and **Password** you configured in Vonage under **Outbound Calls**.
7. Set the Geo Region to route outbound calls through a specific region (currently supported: India, US).
8. Click **Create**.
9. **Note:** For outbound gateway numbers, do not use the `+` sign—just use the country code and number.

<div style={{textAlign: 'center'}}>
  
</div>

---

**telnyx:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/outbound-gateways).
2. Navigate to **Telephony > Outbound Gateways**.
3. Click **Add Outbound Gateway**.
4. Enter a name.
5. Enter the **SIP Domain** you configured in your Telnyx SIP Connection.
6. Enter the **Username** and **Password** you set up in Telnyx under **Outbound Authentication**.
7. Set the Geo Region to route outbound calls through a specific region (currently supported: India, US).
8. Click **Create**.

<div style={{textAlign: 'center'}}>
  
</div>

---

**api:**

To route outbound calls through a specific region, set the `geoRegion` property in the API request. By default, the SIP server region is automatically selected based on the location nearest to the dialed number (currently supported: India, US).

```bash title="cURL"
curl --request POST \
  --url https://api.videosdk.live/v2/sip/outbound-gateways \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
"name": "My Outbound Gateway",
"numbers": ["+1234567890"],
"address": "sip.provider.com",
"geoRegion" : "us002",
"auth": {
  "username": "sip_username",
  "password": "sip_password"
}
  }'
```

> **API Reference**: [Create Outbound Gateway](/api-reference/realtime-communication/sip/outbound-gateway/create-outbound-gateway)



### 4. Create Routing Rules


Routing rules determine how calls are handled.

#### Inbound Routing
For inbound calls, you need to route the call to a specific meeting room.

1. Go to **Telephony > Routing Rules**.
2. Click **Add Routing Rule**.
3. Select your **Inbound Gateway**.
4. Select the **Phone Number**.
5. Under **Dispatch**, select **Room**.
6. Choose **Dynamic** (creates a new room) or **Static** (connects to a specific room ID).
7. Click **Create**.

#### Outbound Routing
For outbound calls, the routing rule selects which Outbound Gateway to use based on the dialed number.

1. Go to **Telephony > Routing Rules**.
2. Click **Add Routing Rule**.
3. Select your **Outbound Gateway**.
4. Enter the **Phone Number** pattern (e.g., `+1*`).
5. Click **Create**.

<div style={{textAlign: 'center'}}>
  
</div>



## Connect SIP User

### Inbound Call
Now that everything is configured, a SIP user can join the meeting by simply dialing the phone number configured in the Inbound Gateway.
1. The call reaches your SIP provider.
2. The provider forwards it to VideoSDK.
3. VideoSDK checks the Routing Rule.
4. The user is connected to the VideoSDK Room.

### Outbound Call
To dial a SIP user from the meeting, you can use the `dispatch` API or the SDK method if available.

```bash title="cURL"
curl --request POST \
  --url https://api.videosdk.live/v2/sip/call \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "gatewayId": "outbound-gateway-id",
    "sipCallTo": "+1234567890",
    "destinationRoomId": "room-id"
  }'
```

> **API Reference**: [Make Outbound Call](/api-reference/realtime-communication/sip/calls/call-trigger)

## Webhooks

You can configure webhooks to receive real-time updates about SIP calls.

### Available Webhook Events
Below is the list of all supported webhook events:

| Event Name | Description |
| :--- | :--- |
| `call-started` | Triggered when a new outbound or inbound call is initiated. |
| `call-answered` | Triggered when the call is answered by the recipient. |
| `call-hangup` | Triggered when the call is completed or hung up by either party. |
| `call-transferred` | Call transferred to another destination. |
| `call-missed` | Triggered when the call is not answered or missed by the recipient. |
| `call-update` | Triggered when there is an update in the call status. |
| `call-ringing` | Triggered when the call is ringing at the destination endpoint. |
| `call-transfer-initiated` | Call transfer has been initiated. |
| `call-transfer-accepted` | Call transfer has been accepted by the target. |
| `call-transferring` | Call is being transferred to another destination. |
| `call-transfer-ringing` | Call is ringing at the transfer target. |
| `call-transfer-failed` | Call transfer failed. |

You can configure these in the **Telephony > Webhooks** section of the dashboard.

## Configuring Webhooks

You can set up webhooks using:

- **Dashboard:** Navigate to the SIP section and add a webhook by specifying your target URL and selecting the events you want to subscribe to.
- **API:** Use the `POST /v2/sip/webhooks` endpoint to register a webhook.



## API Reference

- [Create Webhook API](/api-reference/realtime-communication/sip/webhook/create-webhook)
- [Fetch all Webhook API](/api-reference/realtime-communication/sip/webhook/fetch-all-webhooks)
- [Fetch a Webhook API](/api-reference/realtime-communication/sip/webhook/fetch-webhook)
- [Update Webhook API](/api-reference/realtime-communication/sip/webhook/update-webhook)
- [Delete Webhook API](/api-reference/realtime-communication/sip/webhook/delete-webhook)



---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Explore video & audio calling

This guide will get you running with the VideoSDK video & audio calling in minutes.

## Overview

At it's core, VideoSDK RTC is a distributed SFU. It eanbles highly scalable video & audio meetings unlike vanilla webRTC.

VideoSDK enables opportunity to integrate video & audio calling to Web, Android, IOS applications. it provides Programmable SDKs and REST APIs to build up scalable video conferencing applications.

## Terminology

#### **Meeting**

A Meeting represents real-time audio, video, and/or screen-share session, and is the basic building block for media sharing among participants.

#### **Participants**

Participants are the client applications that are connected to a Meeting and shares video & audio media with one another.

#### **Local Participant**

Local Participant producing audio or video stream from the local client's media sources

#### **Streams**

Streams are indiviual video & audio streams produced by the participants in the meeting

#### **Active Speaker**

Active Speaker represents the participant who is currently producing highest decibels audio stream (in other words speaking)

#### **Active Presenter**

Active Presenter is the participant who is currently sharing his/her screen as a video stream

#### **Main participant**

Main Participant represents the client who shall be displayed on the main screen indicating that he/she is either presenting or speaking

## Architecture

This diagram demonstrates end-to-end flow to implement video & audio calling, record calls and go-live on social media.



---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>


# Explore video & audio calling

This guide will get you running with the VideoSDK video & audio calling in minutes.

## Overview

At it's core, VideoSDK RTC is a distributed SFU. It enables highly scalable video & audio meetings unlike vanilla webRTC.

VideoSDK enables opportunity to integrate video & audio calling to Web, Android, IOS applications. it provides Programmable SDKs and REST APIs to build up scalable video conferencing applications.

## Terminology

#### **Room**

A Room represents real-time audio, video, and/or screen-share session, and is the basic building block for media sharing among participants.

#### **Participants**

Participants are the client applications that are connected to a Room and shares video & audio media with one another.

#### **Local Participant**

Local Participant producing audio or video stream from the local client's media sources

#### **Streams**

Streams are individual video & audio streams produced by the participants in the room

#### **Active Speaker**

Active Speaker represents the participant who is currently producing highest decibels audio stream (in other words speaking)

#### **Active Presenter**

Active Presenter is the participant who is currently sharing his/her screen as a video stream

#### **Main participant**

Main Participant represents the client who shall be displayed on the main screen indicating that he/she is either presenting or speaking

## Architecture

This diagram demonstrates end-to-end flow to implement video & audio calling, record calls and go-live on social media.



---

# Supported Browser and Device OS - Flutter




---

<head>
<meta data-rh="true" name="robots" content="noindex, follow"></meta>
</head>

# Supported platforms

## For video & audio calling SDK

This guide will follow installation guide for all the VideoSDK for Video & Audio Calling. Follow the below guide to install VideoSDK RTC in your website or App

## Web SDK

1. [JavaScript](/javascript/guide/video-and-audio-calling-api-sdk/getting-started)
2. [React JS](/react/guide/video-and-audio-calling-api-sdk/concept-and-architecture)

## Mobile SDK

1. [React Native Android](/react-native/guide/video-and-audio-calling-api-sdk/react-native-android-sdk)
2. [React Native IOS](/react-native/guide/video-and-audio-calling-api-sdk/react-native-ios-sdk)
3. [Android](/android/guide/video-and-audio-calling-api-sdk/concept-and-architecture)
4. [IOS](/ios/guide/video-and-audio-calling-api-sdk/concept-and-architecture)
5. [Flutter](/flutter/guide/video-and-audio-calling-api-sdk/getting-started)


---

# Post Transcription & Summary - Flutter

This guide will walk you through the necessary steps to enable post-transcription functionality in your application, allowing users to access transcriptions of recorded meetings.

Moreover, VideoSDK offers flexibility in configuring post-time transcription, allowing you to set up webhooks for this purpose.

## Integrating Post Transcription Feature

![alt text](/img/transcription/post-transcription.png)

In the image above, the recording begins with transcription and summary features turned on. This triggers a webhook call for the start of recording. When the recording stops, another webhook is activated. After the recording, our transcriber starts transcribing, which in turn activates a webhook. Once the transcription is finished, it's sent to the summarizer for summary generation, and then another webhook is triggered.

### **Step 1: Configure Post Transcription & Summary**

- In this step, we set up the configuration for post transcription and summary generation. We define the webhook URL where the webhooks will be received.

```js
// Webhook URL where, webhooks are received
const String webhookUrl = "https://webhook.your-api-server.com";

Map<String, dynamic> config = { 
  'layout': {
    'type': 'GRID',
    'priority': 'SPEAKER',
    'gridSize': 4,
  },
  'theme': "LIGHT",
  "mode": "video-and-audio",
};

PostTranscriptionConfig postTranscriptionConfig = PostTranscriptionConfig(
  enabled: true,
  modelId: "raman_v1",
  summaryConfig: SummaryConfig(
    enabled: true,
    prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
  ),
);
```

### **Step 2: Start Recording with Transcription Configuration**

- Once the configuration is set, we initiate the recording process for the meeting, incorporating the transcription configuration we defined earlier.

```js
// Start Recording
room.startRecording(
  webhookUrl: webhookUrl,
  config: config,
  postTranscriptionConfig: postTranscriptionConfig
);
```

### **Step 3: Stop Recording**

- When the meeting concludes or recording is no longer needed, we stop the recording process.

```js
// Stop Recording
room.stopRecording();
```

### **Step 4: Fetch Post Transcriptions**

- After the meeting recording is stopped, post transcription and summary data can be obtained using the [Post Transcription API](/api-reference/realtime-communication/fetch-post-transcriptions-summary).

- The API provides information such as the status of transcription, file paths for transcription data in various formats (JSON, SRT, TXT, TSV, VTT), and a summarized text file.

- The transcription document is structured as follows:

```json
{
  "id": "40b0a4ed-9842-40c9-a288-e4b1bf98a90a",
  "status": "completed",
  "roomId": "abc-xyzw-lmno",
  "sessionId": "621497578bea0d0404c35c4c",
  "recordingId": "65d303d6d2c373dfd71b38a2",
  "filePath": "https://cdn.videosdk.live/encoded/videos/dummy.mp4",
  "transcriptionFilePaths": {
    "json": "https://cdn.videosdk.live/transcriptions/dummy/dummy.json",
    "srt": "https://cdn.videosdk.live/transcriptions/dummy/dummy.srt",
    "txt": "https://cdn.videosdk.live/transcriptions/dummy/dummy.txt",
    "tsv": "https://cdn.videosdk.live/transcriptions/dummy/dummy.tsv",
    "vtt": "https://cdn.videosdk.live/transcriptions/dummy/dummy.vtt"
  },
  "summarizedFilePaths": {
    "txt": "https://cdn.videosdk.live/transcriptions/dummy/dummy-summary.txt"
  },
  "userStorage": null,
  "start": "2024-02-27T16:00:36.828Z",
  "end": "2024-02-27T16:01:46.939Z"
}
```

### Example

- The following code snippet allows you to start and stop recording meetings with just a click. When you click the "Start Recording" button, it begins recording the meeting and enables post-transcription, which generates a summary of the meeting's content. Clicking the "Stop Recording" button ends the recording.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    ...
  }

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      ElevatedButton(
        onPressed: () {
          //highlight-start
          // Configuration for post transcription
          const String webhookUrl = "https://webhook.your-api-server.com";

          Map<String, dynamic> config = {
            'layout': {
              'type': 'GRID',
              'priority': 'SPEAKER',
              'gridSize': 4,
            },
            'theme': "LIGHT",
            "mode": "video-and-audio",
          };

          PostTranscriptionConfig postTranscriptionConfig =
              PostTranscriptionConfig(
            enabled: true,
            modelId: "raman_v1",
            summaryConfig: SummaryConfig(
                enabled: true,
                prompt:
                    "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"),
          );

          _room.startRecording(
              webhookUrl: webhookUrl,
              config: config,
              postTranscriptionConfig: postTranscriptionConfig);
          //highlight-end
        },
        child: const Text("Start Recording"),
      ),
      ElevatedButton(
        onPressed: () {
          //highlight-start
          // Stop recording
          _room.stopRecording();
          //highlight-end
        },
        child: const Text("Stop recording"),
      ),
    ]);
  }
}

```

:::important

Please be aware that there may be a delay in processing the transcription data after the recording has been stopped. This delay could vary depending on factors such as server load and the duration of the meeting.

:::

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [startRecording()](/flutter/api/sdk-reference/room-class/methods#startrecording)
- [stopRecording()](/flutter/api/sdk-reference/room-class/methods#stoprecording)
- [fetchPostTranscriptions](/api-reference/realtime-communication/fetch-post-transcriptions-summary)


---

# Realtime Transcription - Flutter

Realtime transcription allows you to transcribe audio content into text in real-time during a session. This guide will walk you through using the `startTranscription()` and `stopTranscription()` functions to manage realtime transcription in your application.

Moreover, VideoSDK offers flexibility in configuring real-time transcription, allowing you to set up webhooks for this purpose.

## Integrating Realtime Transcription Feature

![alt text](/img/transcription/realtime-transcription.png)

The above image represents,

1. **Start Transcription:** The SDK Client initiates real-time transcription using the `startTranscription` method.

2. **Resource Acquisition:** VideoSDK server requests necessary resources from transcription service.

   - If the request is denied, the server sends a `transcription-failed` event to the SDK Client.
   - If the request is successful, the server sends a `transcription-started` event to the client, indicating that transcription has begun.

3. **Transcription Data:** As transcription progresses, the client receives `transcription-text` event with data such as the text itself, participant ID, and timestamp.

4. **Stop Transcription:** When the client decides to stop transcription, it informs the VideoSDK server to release resources.
   - The server then sends a `transcription-stopped` event to confirm that transcription has ended and resources are released.

### **Step 1: Configure Realtime Transcription**

- In this step, we set up the configuration for realtime transcription. We define the webhook URL where the webhooks will be received.

```js
// highlight-next-line
// Realtime Transcription Configuration
TranscriptionConfig transcriptionConfig = TranscriptionConfig(
    webhookUrl: "https://webhook.your-api-server.com",
    summaryConfig: SummaryConfig(
        enabled: true,
        prompt:
            "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"));

```

### **Step 2: Listen for the transcription events**

- Here, we configure the callback methods for transcription events.

```js
// Listen for transcription state changed event
room.on(Events.transcriptionStateChanged, (Map<String, dynamic> data) {
    var status = data['status'];
    var id = data['id'];

    if (TranscriptionState.TRANSCRIPTION_STARTING == status) {
        print(
            "onTranscriptionStateChanged, Realtime Transcription is starting, ID: $id");
    } else if (TranscriptionState.TRANSCRIPTION_STARTED == status) {
        print(
            "onTranscriptionStateChanged, Realtime Transcription has started, ID: $id");
    } else if (TranscriptionState.TRANSCRIPTION_STOPPING == status) {
        print(
            "onTranscriptionStateChanged, Realtime Transcription is stopping, ID: $id");
    } else if (TranscriptionState.TRANSCRIPTION_STOPPED == status) {
        print(
            "onTranscriptionStateChanged, Realtime Transcription has stopped, ID: $id");
    } else {
        print(
            "onTranscriptionStateChanged, Realtime Transcription status $status, ID: $id");
    }
});

// Listen for transcription text event
room.on(Events.transcriptionText, (TranscriptionText transcriptionText) {
  print("TranscriptionText : ${transcriptionText.participantName} (${transcriptionText.participantId}) :  ${transcriptionText.text} ${transcriptionText.timestamp}");

});
```

### **Step 3: Start realtime transcription**

- Initiate the realtime transcription using the `startTranscription()` method.

```js
// Starts realtime transcription
room.startTranscription(transcriptionConfig: transcriptionConfig);
```

### **Step 4: Stop realtime transcription**

- Terminate the realtime transcription using the `stopTranscription() `method.

```js
// Stops realtime transcription
room.stopTranscription();
```

:::important

You can access a summary of your realtime transcription using the **[<u>Fetch Realtime Transcription API</u>](/api-reference/realtime-communication/fetch-a-realtime-transcription)**.

:::

### Example

- The following code snippet allows you to start and stop realtime transcription with just a click. When you click the "Start Realtime Transcription" button, it begins realtime transcription. Clicking the "Stop Realtime Transcription" button ends the realtime transcription.

```js
import 'dart:developer';

import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  ...
}

class _MeetingScreenState extends State<MeetingScreen> {
  // Room object
  late Room _room;

  @override
  void initState() {
    ...
    //highlight-next-line
    setupRoomEventListener();
  }

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      ElevatedButton(
        onPressed: () {
          //highlight-start
          // Configuration for realtime transcription
          TranscriptionConfig transcriptionConfig = TranscriptionConfig(
              webhookUrl: "https://webhook.your-api-server.com",
              summaryConfig: SummaryConfig(
                  enabled: true,
                  prompt:
                      "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"));
          // Start realtime transcription
          _room.startTranscription(transcriptionConfig: transcriptionConfig);
          //highlight-end
        },
        child: const Text("Start Realtime Transcription"),
      ),
      ElevatedButton(
        onPressed: () {
          //highlight-start
          // Stop realtime transcription
          _room.stopTranscription();
          //highlight-end
        },
        child: const Text("Stop Realtime Transcription"),
      ),
    ]);
  }

  void setupRoomEventListener() {
    //highlight-start
    // Listen for transcription state changed event
    _room.on(Events.transcriptionStateChanged, (Map<String, dynamic> data) {
      //Status can be :: TRANSCRIPTION_STARTING
      //Status can be :: TRANSCRIPTION_STARTED
      //Status can be :: TRANSCRIPTION_STOPPING
      //Status can be :: TRANSCRIPTION_STOPPED
      log("Meeting transcription status : ${data['status']}");
    });
    //highlight-end

    //highlight-start
    // Listen for transcription text event
    _room.on(Events.transcriptionText, (TranscriptionText transcriptionText) {
      print(
          "TranscriptionText : ${transcriptionText.participantName} (${transcriptionText.participantId}) :  ${transcriptionText.text} ${transcriptionText.timestamp}");
    });
    //highlight-end
  }
}

```

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [startTranscription()](/flutter/api/sdk-reference/room-class/methods#starttranscription)
- [stopTranscription()](/flutter/api/sdk-reference/room-class/methods#stoptranscription)
- [Events.transcriptionStateChanged](/flutter/api/sdk-reference/room-class/events#transcriptionstatechanged)
- [Events.transcriptionText](/flutter/api/sdk-reference/room-class/events#transcriptiontext)


---

# Video Processor Android Setup - Flutter

- VideoSDK allows you to add unique effects to your video stream before transmission during video calls with custom native video processing code. This guide offers step-by-step instructions for creating and implementing a custom video processor for frame manipulation on Android.

- To enable native processor development on Android, add the following dependency to your `build.gradle` file located at `<project root>/android/build.gradle`:

```js title="build.gradle"
dependencies {
  implementation 'io.github.webrtc-sdk:android:125.6422.02'
  // other app dependencies
  }
```
## **Step-by-Step Guide: Integrating Native Video Processor in Flutter**

### **Step 1: Create Your Own Processor Code** 

- First, create a class that implements the `VideoProcessor` interface. In this class, define the `onFrameReceived` function, which will contain the logic for manipulating video frames according to your needs. After applying the desired effect, make sure to return the processed frame.



**Kotlin:**

```js title="YourOwnBackgroundProcessor.kt"
package com.yourOwnPackage

import live.videosdk.webrtc.VideoProcessor
import org.webrtc.VideoFrame

class YourOwnBackgroundProcessor : VideoProcessor {
// Override the onFrameReceived function to access VideoFrames
override fun onFrameReceived(videoFrame: VideoFrame): VideoFrame {
    // Function to manipulate frame as per requirement
    return applyEffect(videoFrame)
}

private fun applyEffect(videoFrame: VideoFrame): VideoFrame {
    // Add your custom code here to apply the effect and return the processed VideoFrame
    return processedVideoFrame 
}
}
```

---

**Java:**

```js title="YourOwnBackgroundProcessor.java"
package com.yourOwnPackage

import live.videosdk.webrtc.VideoProcessor;
import org.webrtc.VideoFrame;

public class YourOwnBackgroundProcessor implements VideoProcessor {
//Override the onFrameReceived function to get access to the VideoFrames
@Override
public VideoFrame onFrameReceived(VideoFrame videoFrame) {
    //Function to manupulate frame as per requirement.
    VideoFrame processedVideoFrame = applyEffect(videoFrame)
    return processedVideoFrame
}
private VideoFrame applyEffect(VideoFrame videoFrame) {
    // Add your custom code here to apply the effect and return the processed VideoFrame
    return processedVideoFrame
}
}
```

### **Step 2: Register your Processor** 

- In your `MainActivity`, register your custom video processor using the `registerVideoProcessor()` method from the `VideoSDK` class during app initialization. Provide a string representing the unique processor name along with an instance of your processor to complete the registration. This processor name will be used later to apply the effects offered by your processor.

**Kotlin:**

```js title="MainActivity.kt"
package com.example.example

import io.flutter.embedding.android.FlutterActivity
import android.os.Bundle
import com.yourOwnPackage.YourOwnBackgroundProcessor
import live.videosdk.videosdk.VideoSDK

class MainActivity : FlutterActivity() {

private lateinit var bgProcessor: YourOwnBackgroundProcessor

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    //Create an instance of your Processor 
    bgProcessor = YourOwnBackgroundProcessor()
    //Create an instance of the VideoSDK class
    val videoSDK = VideoSDK.getInstance()
    //Register your processor with a unique name and its instance
    videoSDK.registerVideoProcessor("ProcessorName", bgProcessor)
}
}
```

---

**Java:**

```js title="MainActivity.java"
package com.example.example;

import io.flutter.embedding.android.FlutterActivity;
import android.os.Bundle;
import com.yourOwnPackage.YourOwnBackgroundProcessor;
import live.videosdk.videosdk.VideoSDK;

public class MainActivity extends FlutterActivity {

private YourOwnBackgroundProcessor bgProcessor;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    //Create an instance of your Processor 
    bgProcessor = new YourOwnBackgroundProcessor();
    //Create an instance of the VideoSDK class
    VideoSDK videoSDK = VideoSDK.getInstance();
    //Register your processor with a unique name and its instance
    videoSDK.registerVideoProcessor("ProcessorName", bgProcessor);
}
}
```

### **Step 3: Apply the Processor** 

- Once you have registered the processor during initialization, you can use it throughout the entire app lifecycle. To apply the effect provided by the processor, use the `applyVideoProcessor()` method from the `VideoSDK` class. This method requires the name of the processor that was used during registration. 
- If you have registered multiple processors and wish to switch between them, simply call the `applyVideoProcessor()` method with the name of the desired processor.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    //Existing configuration
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        // To apply the effect from the processor, provide the name used during registration.
        ElevatedButton(
          onPressed:(){
            VideoSDK.applyVideoProcessor(videoProcessorName: "ProcessorName");
          },
          child: const Text("Apply Video Processor"),
        ),
    //highlight-end
      ]
    );
  }
}
```

### **Step 4: Remove the Processor** 

- You can remove the processor when you no longer need the effect. To do this, use the `removeVideoProcessor()` method from the `VideoSDK` class to eliminate the effect provided by the processor. This method will remove the effect of the currently active video processor.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    //Existing configuration
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        // To apply the effect from the processor, provide the name used during registration.
        ElevatedButton(
          onPressed:(){
            VideoSDK.removeVideoProcessor();
          },
          child: const Text("Remove Video Processor"),
        ),
    //highlight-end
      ]
    );
  }
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [registerVideoProcessor()](/flutter/api/sdk-reference/videosdk-class/native-android-methods#registervideoprocessor)
- [applyVideoProcessor](/flutter/api/sdk-reference/videosdk-class/methods#applyvideoprocessor)
- [removeVideoProcessor()](/flutter/api/sdk-reference/videosdk-class/methods#removevideoprocessor)


---

# Video Processor iOS Setup - Flutter

- VideoSDK allows you to add unique effects to your video stream before transmission during video calls with custom native video processing code. This guide offers step-by-step instructions for creating and implementing a custom video processor for frame manipulation on iOS.

- To enable native processor development on iOS, replace the `use_frameworks!` line with `use_frameworks! :linkage => :static` in your podfile:

```js title="Podfile"
target 'Runner' do
  //highlight-next-line
  use_frameworks! :linkage => :static
  use_modular_headers!

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end
```
## **Step-by-Step Guide: Integrating Native Video Processor in Flutter**

### **Step 1: Create Your Own Processor Code** 

- First, create a class that implements the `VideoProcessor` interface. In this class, define the `onFrameReceived` function, which will contain the logic for manipulating video frames according to your needs. After applying the desired effect, make sure to return the processed frame.



**Swift:**

```js title="YourOwnBackgroundProcessor.swift"
import Foundation

 public class YourOwnBackgroundProcessor: VideoProcessor {

 // Override the onFrameReceived function to access VideoFrames
 public override func onFrameReceived(_ frame: RTCVideoFrame) -> RTCVideoFrame? {
     // Function to manipulate frame as per requirement
     let processedframe = applyEffect(<#T##frame: RTCVideoFrame##RTCVideoFrame#>)
     return processedframe
     
 }

 private func applyEffect(_ frame:RTCVideoFrame) -> RTCVideoFrame?{
     // Add your custom code here to apply the effect and return the processed VideoFrame
     return processedFrame
 }
}
```

---

**Objective-C:**

```js title="YourOwnBackgroundProcessor.m"

#import <Foundation/Foundation.h>
#import <WebRTC/RTCVideoFrame.h>
#import "videosdk_webrtc/VideoProcessor.h"

@interface YourOwnBackgroundProcessor : VideoProcessor

@end

@implementation YourOwnBackgroundProcessor

// Override the onFrameReceived function to access VideoFrames
- (RTCVideoFrame *)onFrameReceived:(RTCVideoFrame *)frame {
// Function to manipulate frame as per requirement
RTCVideoFrame *processedFrame = [self applyEffect:frame];
return processedFrame;
}

- (RTCVideoFrame *)applyEffect:(RTCVideoFrame *)frame {
// Apply effect here and return the processed VideoFrame
return processedFrame; // Define processedFrame appropriately
}

@end
```

### **Step 2: Register your Processor** 

- In your `AppDelegate`, register your custom video processor using the `registerVideoProcessor()` method from the `VideoSDK` class during app initialization. Provide a string representing the unique processor name along with an instance of your processor to complete the registration. This processor name will be used later to apply the effects offered by your processor.

**Swift:**

```js title="AppDelegate.swift"
import UIKit
import Flutter
import videosdk
import Foundation 

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
{
    //Create an instance of your Processor 
    let bgProcessor = YourOwnBackgroundProcessor()
    //Create an instance of the VideoSDK class
    let videoSDK = VideoSDK.getInstance
    //Register your processor with a unique name and its instance
    videoSDK.registerVideoProcessor(videoProcessorName: "ProcessorName", videoProcessor: bgProcessor)
}

return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}
```

### **Step 3: Apply the Processor** 

- Once you have registered the processor during initialization, you can use it throughout the entire app lifecycle. To apply the effect provided by the processor, use the `applyVideoProcessor()` method from the `VideoSDK` class. This method requires the name of the processor that was used during registration. 
- If you have registered multiple processors and wish to switch between them, simply call the `applyVideoProcessor()` method with the name of the desired processor.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    //Existing configuration
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        // To apply the effect from the processor, provide the name used during registration.
        ElevatedButton(
          onPressed:(){
            VideoSDK.applyVideoProcessor(videoProcessorName: "ProcessorName");
          },
          child: const Text("Apply Video Processor"),
        ),
    //highlight-end
      ]
    );
  }
}
```

### **Step 4: Remove the Processor** 

- You can remove the processor when you no longer need the effect. To do this, use the `removeVideoProcessor()` method from the `VideoSDK` class to eliminate the effect provided by the processor. This method will remove the effect of the currently active video processor.

```js
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class MeetingScreen extends StatefulWidget {
  //Existing configuration
}

class _MeetingScreenState extends State<MeetingScreen> {
  late Room _room;

  @override
  void initState() {
    //highlight-next-line
    //Existing configuration
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children:[
        //highlight-start
        // To apply the effect from the processor, provide the name used during registration.
        ElevatedButton(
          onPressed:(){
            VideoSDK.removeVideoProcessor();
          },
          child: const Text("Remove Video Processor"),
        ),
    //highlight-end
      ]
    );
  }
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [registerVideoProcessor()](/flutter/api/sdk-reference/videosdk-class/native-ios-methods#registervideoprocessor)
- [applyVideoProcessor()](/flutter/api/sdk-reference/videosdk-class/methods#applyvideoprocessor)
- [removeVideoProcessor()](/flutter/api/sdk-reference/videosdk-class/methods#removevideoprocessor)



---

# Video Processor - Flutter

VideoSDK allows you to add custom effects to your video stream before it's transmitted during video calls. This lets you enhance your video in creative ways or achieve specific functionalities.

### Understanding Video Processing

Video processing involves manipulating raw video data (frames) captured by your camera. You can create native processors for Android and iOS to enhance video streams during meetings.

:::info

- Currently, Video Processing is supported only on Android and iOS devices.

:::

### The `VideoProcessor` Interface

The `VideoProcessor` Interface defines a way for your code to interact with the video stream. It essentially lets you intercept each frame before it's sent and apply your processing logic.

#### Key Function: `onFrameReceived`

This is the heart of video processing with VideoSDK. Whenever a new video frame is captured by your camera, the `onFrameReceived` function is called. This function provides you with the raw frame data, allowing you to modify it as needed.

### How it Works:

1. **Implement the Interface:** Create a class that implements the `VideoProcessor` interface. Within this class, define the `onFrameReceived` function.

2. **Process the Frame:** In the `onFrameReceived` function, access the raw video frame data. Apply your desired effects or manipulations to this data.

3. **Return the Processed Frame:** After processing the frame, return the modified version to VideoSDK. This processed frame will then be transmitted during the video call.

4. **Register Your Processor:** Create instances of all the processors you plan to use during the meeting and register them with the `registerVideoProcessor()` method from the `VideoSDK` class during your app's initialization.

5. **Apply the Processor:** Select the desired processor and apply it during the meeting using the `applyVideoProcessor()` method from the `VideoSDK` class to utilize its features.

6. **Remove the Processor:** Stop applying the selected video processor during the meeting, using the `removeVideoProcessor()` method from the `VideoSDK` class allowing you to switch to a different effect or processor as needed.

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [applyVideoProcessor()](/flutter/api/sdk-reference/videosdk-class/methods#applyvideoprocessor)
- [removeVideoProcessor()](/flutter/api/sdk-reference/videosdk-class/methods#removevideoprocessor)


---

# Firewall Setup

To ensure optimal performance when using VideoSDK, it's important to configure your network firewall (if any) to allow connection to  VideoSDK servers.

## Who This Applies To

If your organization uses a firewall for network security and it is not configured to allow connections to VideoSDK servers, you may encounter:

- Connection failures

- Disruptions during sessions

To avoid such problems, ensure your firewall allows the necessary traffic by implementing one of the recommended firewall policies outlined below.

## Firewall Policies

### Full Access Policy
The simplest policy is to allow connections from all subdomains of videosdk.live over both TCP and UDP across all ports.

This covers API, Signaling, Media, and TURN servers.
```
*.videosdk.live
```

### Fine Grained Policies
If broader policies are not permitted, you can apply the following rules:

1. **API Server**

    TCP: Port 443
    ```
    api.videosdk.live
    ```

2. **Signaling Server**

    TCP: Port 443
    
    **You have two configuration options:**

        1. **Wildcard Subdomain Access (Recommended)**
            Allow all regional signaling subdomains:
            ```
            *.rm.videosdk.live
            ```

        2. **Explicit Host Access**
            If wildcards are not permitted, allow these domains explicitly:
            ```
            in1.rm.videosdk.live
            sg1.rm.videosdk.live
            us2.rm.videosdk.live
            eu1.rm.videosdk.live
            uae1.rm.videosdk.live
            aus1.rm.videosdk.live
            ```

3. **Media Server**

    If the Primary connection fails, Fallback connection will be used.

    Primary: UDP on Ports 40000 to 60000

    Fallback: TCP on Ports 40000 to 60000
    ```
    media.videosdk.live
    ```

4.  **Turn Server**

    If the Primary connection fails, Fallback connection will be used.

    Primary: UDP & TCP on Port 3478

    Fallback: TCP on Port 443
    ```
    turn.videosdk.live
    ```




---

# AI Voice Agent Pricing

Deploy intelligent AI voice agents with VideoSDK's scalable infrastructure. Choose between voice-only or video + voice sessions based on your use case requirements.

### Agent Session Minutes Pricing

Pricing is based on agent session minutes - the time your AI agent spends actively in a session deployed on VideoSDK Cloud.



### Third-Party Cloud Deployment

If you deploy your agent on a third-party cloud (not VideoSDK Cloud), you are only charged for communication transport:



:::info
These communication transport charges are **already included** when the agent is deployed on VideoSDK Cloud. You do not pay them separately in that case.
:::

### Agent Deployments Limit

Maximum number of agents you can deploy on VideoSDK Cloud per plan tier.



### Concurrent Agent Sessions

Maximum number of concurrent sessions across all your deployed agents.



## Frequently Asked Questions

Find answers to common questions about AI Voice Agent pricing and billing.

### AI Voice Agent

### What are "Agent Session Minutes"?

* **Agent Session Minutes:** The total time your AI agent spends actively in a session when deployed on VideoSDK Cloud.
* *Example:* If your agent handles a 10-minute voice session, that's 10 agent session minutes.

### What's the difference between VideoSDK Cloud and Third-Party Cloud deployment?

* **VideoSDK Cloud Deployment:**
* You pay for agent session minutes based on type (voice-only or video + voice)
* Communication transport costs are included
* **Third-Party Cloud Deployment:**
* You pay only for communication transport (voice, video, or SIP)
* No agent session minute charges

### How is pricing calculated? Can you provide an example?

**Example: Voice-only agent on VideoSDK Cloud**
* Agent handles 20 sessions
* Average session duration: 5 minutes
* Total agent session minutes: 20 × 5 = 100 minutes
* Cost: 100 minutes × $0.015 = **$1.50**
**Example: Video + voice agent on VideoSDK Cloud**
* Agent handles 10 video sessions
* Average session duration: 8 minutes
* Total agent session minutes: 10 × 8 = 80 minutes
* Cost: 80 minutes × $0.030 = **$2.40**

### What happens if I exceed my agent deployment limit?

* **Free Plan:** Limited to 1 deployed agent
* **Pay-As-You-Go:** Limited to 2 deployed agents
* **Enterprise:** Unlimited agents
If you need more agents, you can upgrade your plan or contact our sales team.

### What happens if I exceed my concurrent session limit?

* **Free Plan:** Maximum 5 concurrent sessions
* **Pay-As-You-Go:** Maximum 20 concurrent sessions
* **Enterprise:** Unlimited concurrent sessions
Additional session requests beyond your limit may be queued or rejected depending on your configuration.

---

### Invoice & Billing

### Free vs. Paid Accounts

* **Free Account:** Default upon signup. Includes limits on agents and concurrent sessions.
* **Paid Account:** Activated when you add a credit card. You are charged based on actual agent session minutes used.

### When are invoices generated?

* Invoices are generated on the **2nd or 3rd of each month**.
* Auto-charge is attempted within 24 hours.
* If payment fails, services may be suspended after the due date (9th/10th).

### How do I get a volume discount?

* If your usage is consistently high, contact our sales team for volume discounts.
* Email: `support@videosdk.live` or visit [Contact Us](https://videosdk.live/contact).


---

# Audio & Video Conferencing Pricing

Power real-time audio and video conferencing with VideoSDK's scalable infrastructure. Our pay-as-you-go model ensures you only pay for what you use, with generous free tier limits to get you started.

### Plans

Choose the plan that fits your needs. All plans include access to our core conferencing features with varying limits and support levels.



### Pricing

Pricing is based on participant-minutes, calculated as the meeting duration multiplied by the number of participants. Video quality is determined by aggregate resolution - the total pixels a user receives from all video streams.



### Add-ons

Enhance your meetings with optional add-on services. The Free Plan includes 300 minutes of add-on credits per month to explore features like recording, transcription, and AI-powered summaries. 



### Concurrency Limits



## Feature & Plan Comparison



## Frequently Asked Questions

Find answers to common questions about Audio & Video Conferencing pricing, billing, and usage calculations.

### Audio-Video Calling

### What is a "participant-minute"?

* There are two terms: **meeting minutes** (duration of the meeting) and **participant minutes** (aggregate duration of all participants).
* Formula: `Meeting Duration x Number of Participants = Participant Minutes`.
* *Example:* 5 participants in a 30-minute meeting = 150 participant minutes.

### How is pricing calculated? Can you provide an example?

Let's say 5 people join a meeting for 30 minutes:
* **Meeting duration:** 30 minutes
* **Participant minutes:** 30 meeting minutes × 5 participants = **150 participant minutes**
* **Assuming HD video resolution:** $0.003 per participant-minute
* **Total cost:** 150 participant mins × $0.003 = **$0.45**

### What is included in the 10,000 free minutes?

* You get **10,000 free participant minutes** every month.
* This covers **all video resolutions** (HD, Full HD, 2K, 2K+) and Audio-only calls.
* *Note:* It does **not** include add-on services like Cloud Recording, RTMP-out, or Storage.

### Is Audio charged separately?

* **No**, audio cost is included in the video pricing.
* However, if a participant has their camera **OFF**, it is treated as an "Audio-only" participant and charged at the lower rate of **$0.0006/min**.

### How is the "Aggregate Video Resolution" calculated?

* Pricing is based on the **aggregate resolution** a user receives (views).
* It is the sum of resolutions of all video streams a user is watching.
* **Calculation Table:**
* **0 videos (Audio only):** $0.0006/min
* **1-5 videos (HD):** $0.003/min
* **6-10 videos (Full HD):** $0.007/min
* **11-17 videos (2K):** $0.007/min
* **18+ videos (2K+):** $0.007/min

### How can I reduce costs for large meetings?

* You can reduce the resolution of individual video tiles (e.g., to 320x180).
* If a user views 15 people at 320x180, the aggregate resolution stays within the **HD limit** (921,600 pixels), keeping the cost at **$0.003/min** instead of the higher Full HD/2K rates.

### Are live-messaging and signaling charged?

* **No.** Features like PubSub (live messaging, signaling, interactions) are currently **free**.

---

### Invoice & Billing

### Free vs. Paid Accounts

* **Free Account:** Default upon signup. Includes 10,000 free minutes.
* **Paid Account:** Activated when you add a credit card. You are **only charged** if you exceed the free limits or use add-on services.

### When are invoices generated?

* Invoices are generated on the **2nd or 3rd of each month**.
* Auto-charge is attempted within 24 hours.
* If payment fails, services may be suspended after the due date (9th/10th).

### Do unused free minutes roll over?

* **No.** The 10,000 free minutes reset at the beginning of each calendar month. They do not carry forward.

### Taxes and Indian GST

* **International:** No taxes applied unless local laws require it.
* **India:**
* Invoices are in **INR**.
* **18% GST** is applicable.
* TDS (2%) is applicable under section 194(C) or 194(J).
* GST and PAN details must be updated in the dashboard.

### How do I get a volume discount?

* If your usage exceeds **100,000 minutes/month**, contact our sales team for volume discounts.
* Email: `support@videosdk.live` or visit [Contact Us](https://videosdk.live/contact).


---

# Interactive Live Streaming (ILS & HLS) Pricing

Stream to thousands of viewers with ultra-low latency Interactive Live Streaming (ILS) or reach massive audiences with HTTP Live Streaming (HLS). Both options support multiple video quality levels and resolution-based pricing.

### Plans

Select a plan based on your streaming needs. Each tier offers different viewer concurrency limits and encoding capabilities.



### Base Pricing

Streaming costs are calculated separately for speakers (hosts/co-hosts) and viewers. Pricing varies based on video resolution, with higher quality streams incurring higher per-minute costs.



### HLS Encoding Charges (Applies only to HLS)



### Add-ons

Extend your streaming capabilities with cloud recording, RTMP re-streaming to social platforms, and secure cloud storage for your recorded content.



### Concurrency Limits



## Feature & Plan Comparison



## Frequently Asked Questions

Learn more about streaming pricing, free minute allocation, and how costs are calculated for speakers and viewers.

### Interactive & HTTP Live Streaming (ILS & HLS)

### What are "Speaker minutes" and "Viewer minutes"?

* **Speaker Minute:** Duration a host/speaker spends in the session. (`Duration x No. of Speakers`)
* **Viewer Minute:** Duration a viewer watches the stream. (`Duration x No. of Viewers`)
* *Example:* A 30-min stream with 2 speakers and 100 viewers:
* 60 Speaker Minutes
* 3000 Viewer Minutes

### How is Interactive Live Streaming pricing calculated? Can you provide an example?

Let's say 2 speakers stream for 30 minutes with 100 viewers:
* **Livestream duration:** 30 minutes
* **Speaker minutes:** 30 minutes × 2 speakers = **60 speaker-minutes**
* **Viewer minutes:** 30 minutes × 100 viewers = **3,000 viewer-minutes**
* **Assuming HD video resolution:**
* Speaker rate: $0.003/min
* Viewer rate: $0.0015/min
* **Total cost:**
* Speaker cost: 60 × $0.003 = $0.18
* Viewer cost: 3,000 × $0.0015 = $4.50
* **Total: $4.68**

### Do the 10,000 free minutes apply to streaming?

* **Yes.** The free monthly quota covers Speaker and Viewer minutes across all resolutions.
* It does **not** cover encoding charges (for HLS), recording, or RTMP-out.

### How does the free quota priority work?

* Free minutes are consumed in the following order (cheapest to most expensive):
1. Viewer Audio
2. Viewer HD -> Full HD -> 2K -> 2K+
3. Speaker Audio
4. Speaker HD -> Full HD -> 2K -> 2K+
5. Conferencing Audio -> HD -> Full HD -> ...
* This ensures you get the maximum value from your free tier.

### Why am I charged for HD if I set a low resolution?

* Charges are based on **aggregate resolution**.
* If a viewer watches 8 streams of 320x180, the total pixel count (518,400 px) falls into the **HD** category, so they are charged the HD rate.

---

### Invoice & Billing

### Free vs. Paid Accounts

* **Free Account:** Default upon signup. Includes 10,000 free minutes.
* **Paid Account:** Activated when you add a credit card. You are **only charged** if you exceed the free limits or use add-on services.

### When are invoices generated?

* Invoices are generated on the **2nd or 3rd of each month**.
* Auto-charge is attempted within 24 hours.
* If payment fails, services may be suspended after the due date (9th/10th).

### Do unused free minutes roll over?

* **No.** The 10,000 free minutes reset at the beginning of each calendar month. They do not carry forward.

### Taxes and Indian GST

* **International:** No taxes applied unless local laws require it.
* **India:**
* Invoices are in **INR**.
* **18% GST** is applicable.
* TDS (2%) is applicable under section 194(C) or 194(J).
* GST and PAN details must be updated in the dashboard.

### How do I get a volume discount?

* If your usage exceeds **100,000 minutes/month**, contact our sales team for volume discounts.
* Email: `support@videosdk.live` or visit [Contact Us](https://videosdk.live/contact).


---

# Inference Pricing

VideoSDK provides access to state-of-the-art AI models for building intelligent voice and video applications. Our inference API supports multiple providers including Google and Sarvam AI.

[Contact sales](https://videosdk.live/contact) for preferred rates on high-volume usage.

---

## Speech-to-Text (STT)

Transcribe audio to text with high accuracy and low latency.

| Model | Provider | Price (per minute) | Documentation |
| ----- | -------- | ------------------ | ------------- |
| Google STT Chirp 2 | Google | $0.01200 | [Pricing](https://cloud.google.com/speech-to-text/pricing) |
| Speech-to-Text | Sarvam | $0.00560 | [Pricing](https://www.sarvam.ai/pricing) |

---

## Large Language Models (LLM)

Build conversational AI agents with the latest language models from Google.

| Model | Provider | Input (per 1M tokens) | Output (per 1M tokens) | Documentation |
| ----- | -------- | --------------------- | ---------------------- | ------------- |
| Gemini 2.5 Flash | Google | $0.30 | $0.85 | [Pricing](https://ai.google.dev/pricing) |
| Gemini 2.5 Flash Lite | Google | $0.10 | $0.40 | [Pricing](https://ai.google.dev/pricing) |
| Gemini 2.0 Flash | Google | $0.10 | $0.40 | [Pricing](https://ai.google.dev/pricing) |
| Gemini 2.0 Flash Lite | Google | $0.07 | $0.30 | [Pricing](https://ai.google.dev/pricing) |

---

## Text-to-Speech (TTS)

Convert text to natural-sounding speech with multiple quality tiers.

| Model | Provider | Price (per 1M chars) | Documentation |
| ----- | -------- | -------------------- | ------------- |
| Google TTS Studio | Google | $160.00 | [Pricing](https://cloud.google.com/text-to-speech/pricing) |
| Google TTS Chirp 3 | Google | $30.00 | [Pricing](https://cloud.google.com/text-to-speech/pricing) |
| Google Cloud TTS Neural | Google | $16.00 | [Pricing](https://cloud.google.com/text-to-speech/pricing) |
| Google Cloud TTS Standard | Google | $4.00 | [Pricing](https://cloud.google.com/text-to-speech/pricing) |
| Text-to-Speech (TTS) | Sarvam | $17.00 | [Pricing](https://www.sarvam.ai/pricing) |

---

## Speech-to-Speech Models

Enable real-time voice conversations with native audio processing.

| Model | Provider | Input (per 1M tokens) | Output (per 1M tokens) | Documentation |
| ----- | -------- | --------------------- | ---------------------- | ------------- |
| Gemini Live 2.5 Flash Native Audio | Google | $3.00 | $12.00 | [Pricing](https://ai.google.dev/pricing) |

---

## Billing & Usage

### How Inference Pricing Works

- **Pay-as-you-go**: You are charged only for what you use
- **No minimum commitment**: Start small and scale as needed
- **Usage-based billing**: Charges are calculated based on actual API usage
- **Transparent Usage Charges**: You can track your usage through the VideoSDK Dashboard

### Usage Calculation

#### LLM & Speech-to-Speech Models
- **Input tokens**: Charged per 1 million input tokens processed
- **Output tokens**: Charged per 1 million output tokens generated
- Token counts are calculated based on the model's tokenizer

#### Text-to-Speech Models
- **Characters**: Charged per 1 million characters converted to speech
- All characters in the input text are counted, including spaces and punctuation

#### Speech-to-Text Models
- **Audio duration**: Charged per minute of audio transcribed
- Partial minutes are rounded up to the nearest minute

### Example Calculations

#### LLM Usage Example
If you process 5 million input tokens and generate 2 million output tokens using Gemini 2.0 Flash:
- Input cost: 5 × $0.10 = $0.50
- Output cost: 2 × $0.40 = $0.80
- **Total cost: $1.30**

#### TTS Usage Example
If you convert 10 million characters to speech using Google Cloud TTS Standard:
- Cost: 10 × $4.00 = $40.00
- **Total cost: $40.00**

#### STT Usage Example
If you transcribe 120 minutes of audio using Google STT Chirp 2:
- Cost: 120 × $0.01200 = $1.44
- **Total cost: $1.44**

---

## Frequently Asked Questions

#### **1. Are there any free tiers for inference APIs?**

Currently, inference APIs are billed on a pay-as-you-go basis without a free tier. However, we offer competitive pricing and volume discounts for high-usage customers.

#### **2. Can I use multiple models in my application?**

Yes, you can use any combination of models from our supported providers. Each model will be billed separately based on its usage.

#### **3. How do I monitor my inference usage?**

You can track your inference API usage through the VideoSDK Dashboard.

#### **4. What happens if I exhaust my balance?**

You will get usage alerts and can set auto-recharge in the VideoSDK Dashboard to prevent service outages.

#### **5. Are there volume discounts available?**

Yes! If you expect high volume usage, please [contact our sales team](https://videosdk.live/contact).

#### **6. Which providers are supported?**

We currently support Google (Gemini, Google Cloud TTS/STT) and Sarvam AI. We're continuously adding new providers and models based on customer demand.

#### **7. How are partial units billed?**

- **Tokens**: Charged per actual token count
- **Characters**: Charged per actual character count
- **Audio minutes**: Charged per actual audio minute

#### **8. Can I switch between models?**

Yes, you can switch between different models at any time, and you'll be charged for each model's actual usage.

---


---

# Pricing FAQ

## Audio-Video Calling

## **Charges**

#### **1. What is participant-minute?**

- There are 2 terms, **meeting mins** & **participant mins**. Participant-mins is a per-participant min.
- In other words, `(Meeting mins x No. of participants = Participant-mins)`
- 10,000 participant-mins are free every month.

#### **2. What are the charges?**

- It’s pay-as-you-go, or use the service this month & pay next month.
- Every month, the first 10,000 participant-mins (communication-mins) are FREE!
- Charges are as below,
  - **Communication charges**, per participant-min (First 10,000 free)
    | Resolution | Per participant min |
    | ------------- | ------------------- |
    | Audio | $0.0006 |
    | HD Video | $0.003 |
    | Full HD Video | $0.007 |
    | 2K Video | $0.007 |
    | 2K+ Video | $0.007 |
    (Note: In video resolution, audio cost is already included)
  - **Composer charges**, per used minute (irrespective of number of participants)
    | Service | Charge | Unit |
    | ----------------------------------------------- | ------- | ----------------------------------- |
    | Cloud Audio recording | $0.015 | Per recorded audio min |
    | Cloud Video recording (SD) - `low` | $0.015 | Per recorded video min |
    | Cloud Video recording (HD) - `med` | $0.015 | Per recorded video min |
    | Cloud Video recording (Full HD) - `high` | $0.030 | Per recorded video min |
    | Individual Cloud Audio recording | $0.002 | Per recorded audio min |
    | Individual Cloud Video recording (HD) | $0.006 | Per recorded video min |
    | Individual Cloud Video recording (Full HD) | $0.014 | Per recorded video min |
    | Storage (Recorded Audio storage) | $0.0003 | Per min of audio stored, in a month |
    | Storage (Recorded Video storage) | $0.003 | Per min of video stored, in a month |
    | Streaming (Watching cloud stored Audio) | $0.0003 | Per min of video viewed |
    | Streaming (Watching cloud stored HD Video) | $0.0015 | Per min of video viewed |
    | Streaming (Watching cloud stored Full HD Video) | $0.0035 | Per min of video viewed |
    | Re-streaming / RTMP out | $0.03 | Per re-streamed min |

#### **3. What are the Free Video SDK services?**

- You are getting free 10,000 participant mins for conferencing/calling, all video resolutions.

#### **4. What are charges for live-messaging & signaling?**

- For live-messaging, live-comments, signaling & interactions - You can use PubSub feature & it’s free. Currently, we don’t have plans to charge for it.

#### **5. Does Free 10,000 mins include all video call/conference resolutions?**

- Yes, Free 10,000 mins include all (HD, Full HD, 2K & 2K+) resolutions.

#### **6. Does Free 10,000 mins include composer service mins as well?**

- No, Free 10,000 mins includes only call/conference; composer services like cloud recording, re-streaming (RTMP-out), and recorded video hosting (Storage) are not included.

## **Calculation method**

#### **1. Does the Video SDK charge separately for Audio?**

- No, Audio cost is already included in video cost. Although, audio conferencing cost ($0.0006/Audio min) applies only when there’s ONLY AUDIO conference going on.
- In other words, if no one in the video conference has their camera ON, then it will be considered as Audio conference & $0.0006/Audio min would be charged.

#### **2. Please explain pricing calculation with an example**

- It’s easy, let’s say 5 people have joined a meeting for half an hour. Here, 30 minutes is a meeting minutes.
  - Participant minutes = 30 meeting minutes x 5 participants
    = 150 participant minutes used
  - Considering $0.003/participant-min (HD Resolution)
    Total cost = 150 participant mins x $0.003
    = $0.45

#### **3. If I am using less than 10,000 mins every month & not using add-on services (cloud recording, re-streaming, etc.), then will the Video SDK be free for me?**

- Technically.. YES, in such a case the Video SDK would be free for you.

#### **4. If I have used, total of 25000 mins, among which 7000 audio mins & 18000 HD mins, then which mins will be counted as free mins?**

- Free 10,000 mins are exhausted as per below sequence

  i. Audio mins

  ii. HD Video mins

  iii. Full HD Video mins

  iv. 2K Video mins

  v. 2K+ Video mins

- in your case, first 7000 audio mins would be considered FREE & then 3000 HD mins
- Hence, you will be invoiced for 15000 HD mins.

#### **5. I have used only 4000 mins this month, will the remaining free mins (6000 mins) be carried forward to next month?**

- No. The remaining free mins will be cleared at the end of each calendar month

#### **6. I have usage more than 100K mins per month & my invoice size is larger. How to reduce it?**

- It’s really justified to reduce your costs at volume usage. If your monthly usage is more than 100K mins per month, please contact sales on [https://videosdk.live/contact](https://videosdk.live/contact) or write on support@videosdk.live

#### **7. I have set the maxResolution to be (320 x 180) only, then why am I charged for HD video?**

- You would be using either HD, Full HD, 2K or 2K+, by aggregate resolution.
- Aggregate resolution means a sum resolution of all video-streams, a user is watching at a time.
- If a user is watching 8 video-streams of (320 x 180) then he is consuming [(360 x 180) x 8 video = 4,60,800px] hence he will be charged for HD resolution min.

#### **8. How do you calculate the aggregate video resolution?**

- It’s an aggregated resolution, the end-user is downloading/viewing. You can check the table below for reference.
  | Videos on-screen\* | Aggregated resolution | Price, per user per minute |
  | ------------------ | --------------------- | -------------------------- |
  | 0 | Only audio | $0.0006 |
  | 1-5 | HD | $0.003 |
  | 6-10 | Full HD | $0.007 |
  | 11-17 | 2K | $0.007 |
  | 18+ | 2K+ | $0.007 |
  - Considering HD (1280 x 720) resolution (16:9) per video, and one local user (self) video.

#### **9. In detail, how do you calculate the aggregate video resolution?**

- As described above, it’s an aggregate resolution, the end-user is downloading/viewing. We are following below standard resolution to calculate your usage.
  | Video type | Aggregate resolution (px) | 16:9 Aspect ratio |
  | ---------- | --------------------------- | ------------------ |
  | HD | {'<='}9,21,600px | 720p: 1280 × 720 |
  | Full HD | 9,21,601px to 20,73,600px | 1080p: 1920 x 1080 |
  | 2K | 20,73,601px to 36,86,400px | 2K: 2560 × 1440 |
  | 2K+ | 36,86,401px to 82,94,400px+ | 2K+: 3840 × 2160 |

#### **10. I want to show 15 people on-screen but don’t want to use Full HD or 2K resolution to save my costs, how to do that?**

- You can reduce the resolution of each video tile to (320 x 180), hence the aggregated resolution won’t cross HD (9,21,600px) & your cost will be saved.

## Interactive Livestreaming

## Charges

#### **1. What is speaker-min & viewer-min?**

- There are 3 terms: livestream mins, speaker-mins, viewer-mins.
- Live stream mins is the duration of livestream; speaker-mins is per speaker min & viewer-min is per viewer min.
- In other words, (Livestream mins x No. of speakers = speaker-mins)
- And, (Livestream mins x No. of viewers = viewer-mins)
- 10,000 speaker & viewer-mins are free every month.

#### **2. What are the charges?**

- It’s pay-as-you-go, or use the service this month & pay next month.
- Every month, the first 10,000 participant-mins are FREE!
- Charges are as below,

  - Speaker & Viewer charges, per min (First 10,000 free)

    | Resolution      | Per speaker min | Per viewer min |
    | --------------- | --------------- | -------------- |
    | Audio           | $0.0006         | $0.0003        |
    | Video (HD)      | $0.003          | $0.0015        |
    | Video (Full HD) | $0.007          | $0.0035        |
    | Video (2K)      | $0.007          | $0.0035        |
    | Video (2K+)     | $0.007          | $0.0035        |

    (Note: In video resolution, audio cost is already included)

  - **Composer charges**, per used minute (irrespective of number of participants)
    | Service | Charge | Unit |
    | ------------------------------------------- | ------------------ | ----------------------------------- |
    | Cloud Audio recording | $0.015 | Per recorded audio min |
    | Cloud Video recording (HD) | $0.015 | Per recorded video min |
    | Cloud Video recording (Full HD) | $0.030 | Per recorded video min |
    | Individual Cloud Audio recording | $0.002 | Per recorded audio min |
    | Individual Cloud Video recording (HD) | $0.006 | Per recorded video min |
    | Individual Cloud Video recording (Full HD) | $0.014 | Per recorded video min |
    | Re-streaming / RTMP Out | $0.03 | Per re-streamed min (RTMP-out) |

#### **3. What are the Free Video SDK services?**

- You are getting free 10,000 speaker & viewer-mins every month, all video resolutions.

#### **4. What are charges for live-messaging & signaling?**

- For live-messaging, live-comments, signaling & interactions - You can use PubSub feature & it’s free. Currently, we don’t have plans to charge for it.

#### **5. Does Free 10,000 mins include all video resolutions?**

- Yes, Free 10,000 mins include all (HD, Full HD, 2K & 2K+) resolutions in Interactive livestreaming.

#### **6. Does Free 10,000 mins include composer service mins as well?**

- No, Free 10,000 mins includes only speaker & viewer-min service; composer services like cloud recording, re-streaming (RTMP-out) & recorded video hosting (Storage) are not included.

## Calculation method

#### **1. Does the Video SDK charge separately for Audio?**

- No, Audio cost is already included in video cost. And, audio streaming cost applies only when there’s ONLY AUDIO streaming going on.
- In other words, if no speaker in the live streaming has their camera ON, then it will be considered as Audio streaming & $0.0006/speaker-audio min, $0.0003/viewer-audio min would be charged.

#### **2. Please explain Interactive Live Streaming pricing calculation, with an example**

- It’s easy, let’s say 2 speakers have joined a livestream for half an hour, with 100 viewers. Here, 30 minutes is livestream minutes.
  - Speaker minutes = 30 livestream minutes x 2 speakers
    = 60 speaker-minutes used
  - Viewer minutes = 30 livestream minutes x 100 viewers
    = 3,000 viewers-minutes used
  - Considering $0.003/speaker-min & $0.0015/viewer-min (HD Resolution)
    Total cost = (60 speaker mins x $0.003) + (3000 viewer mins x $0.0015)
    = $0.18 + $4.50
    = $4.68
  - For detailed information, please refer to our [pricing blog](https://videosdk.live/blog/video-sdk-api-pricing)

#### **3. If I am using less than 10,000 mins every month & not using add-on services (cloud recording, re-streaming, etc.), then will the Video SDK be free for me?**

- Technically.. YES, in such a case the Video SDK would be free for you.

#### **4. If I have used, total of 13200 free mins, among which 100 speaker-audio mins, 4000 viewer-audio mins, 100 speaker-HD mins & 9000 viewer-HD mins, then which mins will be counted as free mins?**

- Free 10,000 mins are exhausted as per below sequence

  i. Viewer-audio mins

  ii. Viewer-HD mins

  iii. Viewer-Full HD mins

  iv. Viewer-2K mins

  v. Viewer-2K+ mins

  vi. Speaker-audio mins

  vii. Speaker-HD mins

  viii. Speaker-Full HD mins

  ix. Speaker-2K mins

  x. Speaker-2K+ mins

- In your case, first 4000 viewer-audio mins, then 6000 viewer-HD mins would be considered FREE.
- Hence, you will be invoiced for 3000 viewer-HD mins, 100 speaker-audio mins & 100 speaker-HD mins; plus livestream encoding charges.

#### **5. I have used only 4000 mins this month, will the remaining free mins (6000 mins) be carried forward to next month?**

- No. The remaining free mins will be cleared at the end of each calendar month.

#### **6. I have usage of more than 100K mins per month & my invoice size is larger. How to reduce it?**

- It’s really justified to reduce your costs at volume usage. If your monthly usage is more than 100K mins per month, please contact sales on [https://videosdk.live/contact](https://videosdk.live/contact) or write on support@videosdk.live

#### **7. I have set the maxResolution to be (320 x 180) only, then why am I charged for HD video?**

- You would be using either HD, Full HD, 2K or 2K+, by aggregate resolution.
- Aggregate resolution means a sum resolution of all video-streams, a speaker/viewer is watching at a time.
- If a speaker/viewer is watching 8 video-streams of (320 x 180) then he is consuming [(360 x 180) x 8 video = 4,60,800px] hence he will be charged for HD resolution min.

#### **8. How do you calculate the aggregate video resolution?**

- It’s an aggregated resolution, the end-user is downloading/viewing. You can check the table below for reference.

  | Videos on-screen\* | Aggregate resolution | Price, per speaker per min | Price, per viewer per min |
  | ------------------ | -------------------- | -------------------------- | ------------------------- |
  | 0                  | Only audio           | $0.0006                    | $0.0003                   |
  | 1-5                | HD                   | $0.003                     | $0.0015                   |
  | 6-10               | Full HD              | $0.007                     | $0.0035                   |
  | 11-17              | 2K                   | $0.007                     | $0.0035                   |
  | 18+                | 2K+                  | $0.007                     | $0.0035                   |

- Considering HD (1280 x 720) resolution (16:9) per video, and one local user (self) video

#### **9. In detail, how do you calculate the aggregate video resolution?**

- As described above, it’s an aggregate resolution, the end-user is downloading/viewing. We are following below standard resolution to calculate your usage.

  | Video type | Aggregate resolution (px)   | 16:9 Aspect ratio  |
  | ---------- | --------------------------- | ------------------ |
  | HD         | {'<='}9,21,600px            | 720p: 1280 × 720   |
  | Full HD    | 9,21,601px to 20,73,600px   | 1080p: 1920 x 1080 |
  | 2K         | 20,73,601px to 36,86,400px  | 2K: 2560 × 1440    |
  | 2K+        | 36,86,401px to 82,94,400px+ | 2K+: 3840 × 2160   |

#### **10. I want to show 15 speakers on-screen but don’t want to use Full HD or 2K resolution to save my costs, how to do that?**

- You can reduce the resolution of each video tile to (320 x 180), hence the aggregated resolution won’t cross HD (9,21,600px) & your cost will be saved.

## Http Live Streaming (HLS)

## Charges

#### **1. What is speaker-min & viewer-min?**

- There are 3 terms: livestream mins, speaker-mins, viewer-mins.
- Live stream mins is the duration of livestream; speaker-mins is per speaker min & viewer-min is per viewer min.
- In other words, (Livestream mins x No. of speakers = speaker-mins)
- And, (Livestream mins x No. of viewers = viewer-mins)
- 10,000 speaker & viewer-mins are free every month.

#### **2. What are the charges?**

- It’s pay-as-you-go, or use the service this month & pay next month.
- Every month, the first 10,000 participant-mins are FREE!
- Charges are as below,

  - Speaker & Viewer charges, per min (First 10,000 free)

    | Resolution      | Per speaker min | Per viewer min |
    | --------------- | --------------- | -------------- |
    | Audio           | $0.0006         | $0.0003        |
    | Video (HD)      | $0.003          | $0.0015        |
    | Video (Full HD) | $0.007          | $0.0035        |
    | Video (2K)      | $0.007          | $0.0035        |
    | Video (2K+)     | $0.007          | $0.0035        |

    (Note: In video resolution, audio cost is already included)

  - **Composer charges**, per used minute (irrespective of number of participants)
    | Service | Charge | Unit |
    | ------------------------------------------- | ------------------ | ----------------------------------- |
    | Encoding Audio (Livestream mins) | $0.04 | Per livestream audio min |
    | Encoding Video - SD (Livestream mins) | $0.04 | Per livestream video min |
    | Encoding Video - HD (Livestream mins) | $0.04 | Per livestream video min |
    | Encoding Video - Full HD (Livestream mins) | $0.08 | Per livestream video min |
    | Cloud Audio recording | $0.015 | Per recorded audio min |
    | Cloud Video recording (HD) | $0.015 | Per recorded video min |
    | Cloud Video recording (Full HD) | $0.030 | Per recorded video min |
    | Individual Cloud Audio recording | $0.002 | Per recorded audio min |
    | Individual Cloud Video recording (HD) | $0.006 | Per recorded video min |
    | Individual Cloud Video recording (Full HD) | $0.014 | Per recorded video min |
    | Storage (Recorded livestream Audio storage) | $0.0003 | Per min of video stored, in a month |
    | Storage (Recorded livestream Video storage) | $0.003 | Per min of video stored, in a month |
    | Streaming (Watching recorded livestream) | Same as viewer-min | Per min of video viewed |
    | Re-streaming / RTMP Out | $0.03 | Per re-streamed min (RTMP-out) |

#### **3. What are the Free Video SDK services?**

- You are getting free 10,000 speaker & viewer-mins every month, all video resolutions.

#### **4. What are charges for live-messaging & signaling?**

- For live-messaging, live-comments, signaling & interactions - You can use PubSub feature & it’s free. Currently, we don’t have plans to charge for it.

#### **5. Does Free 10,000 mins include all video resolutions?**

- Yes, Free 10,000 mins include all (HD, Full HD, 2K & 2K+) resolutions in Interactive livestreaming.

#### **6. Does Free 10,000 mins include composer service mins as well?**

- No, Free 10,000 mins includes only speaker & viewer-min service; composer services like cloud recording, re-streaming (RTMP-out), HLS Conversion & recorded video hosting (Storage) are not included.

## Calculation method

#### **1. Does the Video SDK charge separately for Audio?**

- No, Audio cost is already included in video cost. And, audio streaming cost applies only when there’s ONLY AUDIO streaming going on.
- In other words, if no speaker in the live streaming has their camera ON, then it will be considered as Audio streaming & $0.0006/speaker-audio min, $0.0003/viewer-audio min would be charged.

#### **2. Please explain Http Live Streaming (HLS) pricing calculation, with an example**

- It’s easy, let’s say 2 speakers have joined a livestream for half an hour, with 100 viewers. Here, 30 minutes is livestream minutes.
  - Speaker minutes = 30 livestream minutes x 2 speakers
    = 60 speaker-minutes used
  - Viewer minutes = 30 livestream minutes x 100 viewers
    = 3,000 viewers-minutes used
  - Considering $0.003/speaker-min & $0.0015/viewer-min (HD Resolution)
    Total cost = (60 speaker mins x $0.003) + (3000 viewer mins x $0.0015)
    = $0.18 + $4.50
    = $4.68
  - For detailed information, please refer to our [pricing blog](https://videosdk.live/blog/video-sdk-api-pricing)

#### **3. If I am using less than 10,000 mins every month & not using add-on services (cloud recording, re-streaming, etc.), then will the Video SDK be free for me?**

- Technically.. YES, in such a case the Video SDK would be free for you.

#### **4. If I have used, total of 13200 free mins, among which 100 speaker-audio mins, 4000 viewer-audio mins, 100 speaker-HD mins & 9000 viewer-HD mins, then which mins will be counted as free mins?**

- Free 10,000 mins are exhausted as per below sequence

  i. Viewer-audio mins

  ii. Viewer-HD mins

  iii. Viewer-Full HD mins

  iv. Viewer-2K mins

  v. Viewer-2K+ mins

  vi. Speaker-audio mins

  vii. Speaker-HD mins

  viii. Speaker-Full HD mins

  ix. Speaker-2K mins

  x. Speaker-2K+ mins

- In your case, first 4000 viewer-audio mins, then 6000 viewer-HD mins would be considered FREE.
- Hence, you will be invoiced for 3000 viewer-HD mins, 100 speaker-audio mins & 100 speaker-HD mins; plus livestream encoding charges.

#### **5. I have used only 4000 mins this month, will the remaining free mins (6000 mins) be carried forward to next month?**

- No. The remaining free mins will be cleared at the end of each calendar month.

#### **6. I have usage of more than 100K mins per month & my invoice size is larger. How to reduce it?**

- It’s really justified to reduce your costs at volume usage. If your monthly usage is more than 100K mins per month, please contact sales on [https://videosdk.live/contact](https://videosdk.live/contact) or write on support@videosdk.live

#### **7. I have set the maxResolution to be (320 x 180) only, then why am I charged for HD video?**

- You would be using either HD, Full HD, 2K or 2K+, by aggregate resolution.
- Aggregate resolution means a sum resolution of all video-streams, a speaker/viewer is watching at a time.
- If a speaker/viewer is watching 8 video-streams of (320 x 180) then he is consuming [(360 x 180) x 8 video = 4,60,800px] hence he will be charged for HD resolution min.

#### **8. How do you calculate the aggregate video resolution?**

- It’s an aggregated resolution, the end-user is downloading/viewing. You can check the table below for reference.

  | Videos on-screen\* | Aggregate resolution | Price, per speaker per min | Price, per viewer per min |
  | ------------------ | -------------------- | -------------------------- | ------------------------- |
  | 0                  | Only audio           | $0.0006                    | $0.0003                   |
  | 1-5                | HD                   | $0.003                     | $0.0015                   |
  | 6-10               | Full HD              | $0.007                     | $0.0035                   |
  | 11-17              | 2K                   | $0.007                     | $0.0035                   |
  | 18+                | 2K+                  | $0.007                     | $0.0035                   |

- Considering HD (1280 x 720) resolution (16:9) per video, and one local user (self) video

#### **9. In detail, how do you calculate the aggregate video resolution?**

- As described above, it’s an aggregate resolution, the end-user is downloading/viewing. We are following below standard resolution to calculate your usage.

  | Video type | Aggregate resolution (px)   | 16:9 Aspect ratio  |
  | ---------- | --------------------------- | ------------------ |
  | HD         | {'<='}9,21,600px            | 720p: 1280 × 720   |
  | Full HD    | 9,21,601px to 20,73,600px   | 1080p: 1920 x 1080 |
  | 2K         | 20,73,601px to 36,86,400px  | 2K: 2560 × 1440    |
  | 2K+        | 36,86,401px to 82,94,400px+ | 2K+: 3840 × 2160   |

#### **10. I want to show 15 speakers on-screen but don’t want to use Full HD or 2K resolution to save my costs, how to do that?**

- You can reduce the resolution of each video tile to (320 x 180), hence the aggregated resolution won’t cross HD (9,21,600px) & your cost will be saved.

## Invoice & Billing

## Free & Paid Accounts

#### 1. You can have either a "Free Account" or a "Paid Account”

- When you signup, you’re creating a “Free Account”.
- When you’re submitting your payment details, you’re upgrading to “Paid Account”.
- Please take note that your paid account will not be charged unless you use chargeable services.

#### 2. Both types of accounts receive 10,000 free minutes every month.

- Free minutes are only applicable to the following services:
  - Video Conferencing - Participant minutes
  - Http Live Streaming (HLS) - Speaker minutes
  - Http Live Streaming (HLS) - Viewer minutes
  - Interactive Live Streaming - Speaker minutes
  - Interactive Live Streaming - Viewer minutes
- Not applicable to the following services, also known as "Add-on services”
  - Cloud Recording
  - Cloud Storage
  - Cloud Streaming
  - Broadcasting
  - Livestream Encoding

#### 3. Limits for "Free Account"

- By default, maximum of 50 participants in one video conference room.
- By default, maximum of 15 speakers in one video conference room.
- By default, maximum of 200 viewers in one interactive Livestreaming room and 100 viewers in one Http Live Streaming (HLS) room.

Note: If one of the above-mentioned limits is reached, services will be held. In order to increase the above limits, please [upgrade the plan](https://app.videosdk.live/profile/billing?page=1&perPage=20&default_action=save-card) on our dashboard and then contact us here : https://www.videosdk.live/contact

## Monthly invoices

- The monthly invoices would be issued via Stripe on the second/third day of the month, with a due date of the ninth/tenth day of the month, in USD as standard currency.
- The generated invoice will be shared via email and may also be seen and downloaded via the Video SDK Dashboard, invoice page.
- The invoice will be auto-charged from the saved payment details in 24 hours.
- Whatever invoice that cannot be auto-charged for any reason must be paid manually by the user using Stripe before the invoice due date.
- If the invoice due date is missed, Video SDK services will be suspended and will be reactivated upon payment via Stripe
- Any concerns about the invoice should be made through email to support@videosdk.live within 24 hours of receipt.
- Any discount agreed upon in the legal agreement will be applied to the three services listed below, on all resolutions
  1. Conferencing minutes (per-participant minutes)
  2. Interactive Livestream - Speaker minutes
  3. Interactive Livestream - Viewer minutes
- For three services that comes under free quota of 10,000 minutes, it’s usage will be added up at the end of the month, and the 10,000 free minutes will be adjusted against the used services in the order shown below.
  1. Viewer-audio mins
  2. Viewer-HD mins
  3. Viewer-Full HD mins
  4. Viewer-2K mins
  5. Viewer-2K+ mins
  6. Speaker-audio mins
  7. Speaker-HD mins
  8. Speaker-Full HD mins
  9. Speaker-2K mins
  10. Speaker-2K+ mins
  11. Audio conferencing mins
  12. HD Video conferencing mins
  13. Full HD Video conferencing mins
  14. 2K Video conferencing mins
  15. 2K+ Video conferencing mins
- No taxes are applied on an invoice, unaltered until respective government law update
- Exceptions for Indian registered businesses
  - Invoice currency will be INR at the foreign exchange rate on the day of invoice generation.
  - As per the GST guidelines, 18% GST will be imposed on the final invoice amount, unmodified until the Government of India's law modification. And, under SAC Code - 998313, the applicable TDS would be 2%, under section 194(C) or 194(J) as technical services.
  - Users are required to submit their registered GST and Company PAN details on the Video SDK user dashboard no later than the last day of the month. This ensures the generation of the GST invoice at the end of that month.

## Quotas & limits

- For "Free Account"

  - By default, maximum of 50 participants in one video conference room.
  - By default, maximum of 15 speakers in one video conference room.
  - By default, maximum of 200 viewers in one interactive Livestreaming room and 100 viewers in one Http Live Streaming (HLS) room.

Note: If one of the above-mentioned limits is reached, services will be held. In order to increase the above limits, please [upgrade the plan](https://app.videosdk.live/profile/billing?page=1&perPage=20&default_action=save-card) on our dashboard and then contact us here : https://www.videosdk.live/contact

- For “Paid Accounts”
  - By default, maximum of 100 participants in one video conference room.
  - By default, maximum of 15 speakers in one video conference room.
  - By default, maximum of 1000 viewers in one interactive Livestreaming room and 500 viewers in one Http Live Streaming (HLS) room.

📌 Note: Please contact us if you want to enhance the aforementioned quota for your [subscribed account](https://videosdk.live/contact)


---

# Pricing FAQ

## General Pricing

#### **1. What is the VideoSDK pricing model?**

VideoSDK offers three pricing plans to suit different scale and business needs:

- **Free Plan**: Ideal for individuals and startups exploring VideoSDK. It includes a **$20 one-time free balance** to try out all paid features and products.
- **Pay-As-You-Go (On-Demand)**: A flexible, prepaid model for developers and growing businesses. You add funds to your wallet and pay only for the resources you consume (minutes, recordings, agents, etc.) with no monthly subscriptions or commitments.
- **Enterprise Plan**: Tailored for high-volume users and businesses requiring custom SLAs, dedicated support channels (Slack/WhatsApp), and solutions engineering.

#### **2. Do I get any free credits when I sign up?**

Yes! Every new account receives **$20 one-time free balance** to get started with VideoSDK services.

#### **3. How do I add funds to my wallet?**

You can add funds through the VideoSDK Dashboard using:
- Credit/Debit cards via Stripe
- Multiple currency support available
- Secure payment processing

#### **4. Is this a prepaid or postpaid model?**

VideoSDK operates on a **prepaid model**. You must add funds to your wallet before using services. Charges are deducted automatically from your wallet balance. There are no postpaid invoices.

#### **5. What happens if my wallet balance runs out?**

When your wallet balance is insufficient, services will be paused. You'll receive notifications before your balance runs low. Simply add more funds to continue using services.

#### **6. Can I set up auto-recharge for my wallet?**

Yes, you can configure auto-recharge settings in the VideoSDK Dashboard to automatically add funds when your balance falls below a certain threshold.

#### **7. How do I monitor my usage and balance?**

You can track your real-time usage and wallet balance through the VideoSDK Dashboard. Detailed usage reports are available for each product and service.

---

## Products & Services

#### **1. What products does VideoSDK offer?**

VideoSDK offers three core products:
- **Agent**: AI-powered voice and video agents sdk infrastructure
- **Video Call**: High-quality video conferencing and calling
- **Live Streaming**: Interactive and scalable live streaming

#### **2. Can I use multiple products in the same application?**

Yes! You can use any combination of Agent, Video Call, and Live Streaming products. Each product is billed based on actual usage.



---

## Agent Pricing

#### **1. What is an Agent Session?**

An Agent Session represents one active AI agent instance. You're charged $0.01 per agent session over your included limits.

#### **2. What are the Agent pricing charges?**

**Serverless Agents:**

| Service | Charge | Unit |
| ------- | ------ | ---- |
| Agent Session CPU-Small (0.5 Cores, 1 GB) | $0.01 | Per session min |
| Agent Session CPU-Medium (1 Core, 2 GB) | $0.02 | Per session min |
| Agent Session CPU-Large (2 Cores, 3 GB) | $0.03 | Per session min |
| Agent Reserved CPU-Small (0.5 Cores, 1 GB) | $0.0005 | Per reserved min |
| Agent Reserved CPU-Medium (1 Core, 2 GB) | $0.001 | Per reserved min |
| Agent Reserved CPU-Large (2 Cores, 3 GB) | $0.002 | Per reserved min |
| Agent Observability | Currently free | - |



**SIP Participants:**

| Service | Charge | Unit |
| ------- | ------ | ---- |
| SIP Participant | $0.002 | Per participant minute |



**Participant Minutes:**

| Service | Charge | Unit |
| ------- | ------ | ---- |
| Voice | $0.001 | Per participant minute |
| Video HD | $0.004 | Per participant minute |
| Video Full HD | $0.008 | Per participant minute |
| Video 2K | $0.016 | Per participant minute |
| Video 2K+ | $0.036 | Per participant minute |

**Recording:**

| Service | Charge | Unit |
| ------- | ------ | ---- |
| Meeting Audio Recording | $0.015 | Per recorded audio min |
| Meeting Video Recording (SD) - Low | $0.015 | Per recorded video min |
| Meeting Video Recording (HD) - Med | $0.015 | Per recorded video min |
| Meeting Video Recording (Full HD) - High | $0.030 | Per recorded video min |
| Participant Audio Recording | $0.006 | Per recording audio min |
| Participant Video Recording | $0.006 | Per recording video min |
| Participant Audio Track Recording | $0.0005 | Per individual audio min |
| Participant Video Track Recording | $0.0005 | Per individual video min |

#### **3. What are SIP Participants in Agent?**

SIP Participants allow traditional phone systems to connect to your AI agents. Charged at $0.002 per participant minute.

#### **4. Are Agent features like Instant Rollback and Observability included?**

Yes, Instant Rollback and Agent Observability are included features at no additional cost.

#### **5. How much do phone numbers and usage cost?**

- **US Local Number:** 1 phone number free. Additional local numbers cost **$5.00/month**. 
- **Inbound Usage (Local):** $0.02 per inbound call min.
- **Inbound Usage (Toll-Free):** $0.04 per inbound call min.

#### **6. What is PubSub / Data pricing?**

PubSub / Data is currently free for data transfer.

---

## Video Call Pricing

#### **1. How is video call pricing calculated?**

Video call pricing is based on **participant-minutes** and **resolution**:
- Participant-minutes = Meeting duration × Number of participants
- Resolution determines the per-minute rate (Voice, HD, Full HD, 2K, 2K+)

#### **2. What is a participant-minute?**

A participant-minute is one participant in a call for one minute. For example:
- 5 participants in a 10-minute call = 50 participant-minutes
- 10 participants in a 30-minute call = 300 participant-minutes

#### **3. What are the Video Call charges?**



**Participant Minutes:**

| Service | Charge | Unit |
| ------- | ------ | ---- |
| Voice | $0.001 | Per participant minute |
| Video HD | $0.004 | Per participant minute |
| Video Full HD | $0.009 | Per participant minute |
| Video 2K | $0.016 | Per participant minute |
| Video 2K+ | $0.036 | Per participant minute |

**Recording:**

| Service | Charge | Unit |
| ------- | ------ | ---- |
| Meeting Audio Recording | $0.015 | Per recorded audio min |
| Meeting Video Recording (SD) - Low | $0.015 | Per recorded video min |
| Meeting Video Recording (HD) - Med | $0.015 | Per recorded video min |
| Meeting Video Recording (Full HD) - High | $0.030 | Per recorded video min |
| Participant Audio Recording | $0.006 | Per recording audio min |
| Participant Video Recording | $0.006 | Per recording video min |
| Participant Audio Track Recording | $0.0005 | Per individual audio min |
| Participant Video Track Recording | $0.0005 | Per individual video min |

**SIP Participants:**

| Service | Charge | Unit |
| ------- | ------ | ---- |
| SIP Participant | $0.002 | Per participant minute |

**Storage & Transcription:**


| Service | Charge | Unit |
| ------- | ------ | ---- |
| Storage (Recorded Audio storage) | $0.003 | Per min of audio stored, in a month |
| Storage (Recorded Video storage) | $0.003 | Per min of audio stored, in a month |
| Streaming (Watching cloud stored Audio) | $0.0005 | Per min of video viewed |
| Streaming (Watching cloud stored HD Video) | $0.002 | Per min of video viewed |
| Streaming (Watching cloud stored Full HD Video) | $0.004 | Per min of video viewed |
| Real-time Transcription | $0.02 | Per transcribed minute |
| Prompt Based Summary | $0.0045 | Per summarised minute |
| Post-Call Transcription | $0.004 | Per transcribed minute |



#### **4. How do you calculate video resolution charges?**

Charges are based on **aggregate resolution** - the total resolution of all video streams a participant is viewing at a time.


| Videos on-screen | Aggregate Resolution | Price per participant per minute |
| ---------------- | -------------------- | -------------------------------- |
| 0 | Only audio | $0.001 |
| 1-5 | HD | $0.004 |
| 6-10 | Full HD | $0.008 |
| 11-17 | 2K | $0.016 |
| 18+ | 2K+ | $0.036 |

*Note: Considering HD (1280 x 720) resolution (16:9) per video, and one local user (self) video.*

#### **5. In detail, how do you calculate the aggregate video resolution?**

Aggregate resolution is the sum of all video streams an end-user is downloading/viewing. We follow these standard resolutions:

| Video Type | Aggregate Resolution (px) | 16:9 Aspect Ratio |
| ---------- | ------------------------- | ----------------- |
| HD | ≤ 921,600px | 720p: 1280 × 720 |
| Full HD | 921,601px to 2,073,600px | 1080p: 1920 x 1080 |
| 2K | 2,073,601px to 3,686,400px | 2K: 2560 × 1440 |
| 2K+ | 3,686,401px to 8,294,400px+ | 2K+: 3840 × 2160 |

#### **6. Does video pricing include audio?**

Yes, audio cost is already included in video pricing. Audio-only pricing applies only when no participant has their camera on.

#### **7. What is the difference between Meeting and Participant recording?**

- **Meeting Recording**: Records the final composed view of the session (e.g., grid layout, active speaker). This captures what a user sees during the meeting.
  
- **Participant Recording**: Records individual participant's audio and video combined in a single file. 

- **Participant Track Recording**: Records individual audio and video tracks separated into different files (one for audio, one for video). 

**Key Differences:**

| Recording Type | Description | Use Case | Price (Audio) | Price (Video) |
| -------------- | ----------- | -------- | ------------- | ------------- |
| Meeting Recording | Single composed file | Replays, Archives | $0.015/min | $0.015 - $0.030/min |
| Participant Recording | Individual combined file per user | Archives, Single-File | $0.0005/min | $0.0005/min |
| Participant Track Recording | Separate audio/video files per user | Post-Production, Editing | $0.0005/min | $0.0005/min |

#### **8. What are the Storage and Transcription charges?**

Storage and Transcription services are charged as follows:

| Service | Charge | Unit |
| ------- | ------ | ---- |
| Storage (Recorded Audio storage) | $0.003 | Per min of audio stored, in a month |
| Storage (Recorded Video storage) | $0.003 | Per min of audio stored, in a month |
| Streaming (Watching cloud stored Audio) | $0.0005 | Per min of video viewed |
| Streaming (Watching cloud stored HD Video) | $0.002 | Per min of video viewed |
| Streaming (Watching cloud stored Full HD Video) | $0.004 | Per min of video viewed |
| Real-time Transcription | $0.02 | Per transcribed minute |
| Prompt Based Summary | $0.0045 | Per summarised minute |
| Post-Call Transcription | $0.004 | Per transcribed minute |

#### **9. Please explain Video Call pricing calculation with an example**

Let's say 5 people have joined a meeting for 30 minutes:
- Meeting minutes = 30 minutes
- Participant minutes = 30 meeting minutes × 5 participants = 150 participant minutes
- Considering HD Resolution: $0.004/participant-min
- **Total cost = 150 participant mins × $0.004 = $0.60**

#### **10. I have set the maxResolution to be (320 x 180) only, then why am I charged for HD video?**

You are charged based on **aggregate resolution** - the sum of all video streams a user is watching at a time.

If a user is watching 8 video streams of (320 x 180), they are consuming:
- (320 × 180) × 8 videos = 460,800px

This falls within HD range (≤ 921,600px), so they will be charged for HD resolution.

#### **11. I want to show 15 people on-screen but don't want to use Full HD or 2K resolution to save costs. How?**

You can reduce the resolution of each video tile to (320 x 180). This way, the aggregated resolution won't cross HD (921,600px) and your cost will be saved.

For example:
- 15 videos × (320 × 180) = 864,000px (still within HD range)

---

## Interactive Live Streaming Pricing

#### **1. How is Interactive Live Streaming pricing calculated?**

Interactive Live Streaming has two components:
- **Speaker minutes**: For hosts/speakers in the stream
- **Viewer minutes**: For viewers watching the stream

#### **2. What are the Interactive Live Streaming charges?**

| Service | Per Speaker Min | Per Viewer Min |
| ------- | --------------- | -------------- |
| Voice | $0.001 | $0.0005 |
| Video HD | $0.004 | $0.002 |
| Video Full HD | $0.008 | $0.004 |
| Video 2K | $0.016 | $0.008 |
| Video 2K+ | $0.036 | $0.018 |

**Recording & RTMP:**

| Service | Charge | Unit |
| ------- | ------ | ---- |
| Meeting Audio Recording | $0.015 | Per recorded audio min |
| Meeting Video Recording (SD) - Low | $0.015 | Per recorded video min |
| Meeting Video Recording (HD) - Med | $0.015 | Per recorded video min |
| Meeting Video Recording (Full HD) - High | $0.030 | Per recorded video min |
| Participant Audio Recording | $0.006 | Per recording audio min |
| Participant Video Recording | $0.006 | Per recording video min |
| Participant Audio Track Recording | $0.0005 | Per individual audio min |
| Participant Video Track Recording | $0.0005 | Per individual video min |
| RTMP | $0.03 | Per re-streamed minute |

**SIP Participants:**

| Service | Charge | Unit |
| ------- | ------ | ---- |
| SIP Participant | $0.002 | Per participant minute |

**HLS Encoding:**

| Service | Charge | Unit |
| ------- | ------ | ---- |
| HLS Encoding Audio (Livestream mins) | $0.04 | Per livestream audio min |
| HLS Encoding Video - SD (Livestream mins) | $0.04 | Per livestream video min |
| HLS Encoding Video - HD (Livestream mins) | $0.04 | Per livestream video min |
| HLS Encoding Video - Full HD (Livestream mins) | $0.08 | Per livestream video min |


**Storage & Transcription:**

| Service | Charge | Unit |
| ------- | ------ | ---- |
| Storage (Recorded Audio storage) | $0.003 | Per min of audio stored, in a month |
| Storage (Recorded Video storage) | $0.003 | Per min of audio stored, in a month |
| Streaming (Watching cloud stored Audio) | $0.0005 | Per min of video viewed |
| Streaming (Watching cloud stored HD Video) | $0.002 | Per min of video viewed |
| Streaming (Watching cloud stored Full HD Video) | $0.004 | Per min of video viewed |
| Real-time Transcription | $0.02 | Per transcribed minute |
| Prompt Based Summary | $0.0045 | Per summarised minute |
| Post-Call Transcription | $0.004 | Per transcribed minute |



#### **3. What's the difference between Speaker and Viewer charges?**

- **Speaker charges**: Applied to hosts/speakers who are actively streaming (same as video call rates)
- **Viewer charges**: Applied to viewers watching the stream (typically lower rates)

#### **4. Are RTMP and HLS included?**

Yes, RTMP streaming and HLS delivery are charged based on usage. RTMP is charged at $0.03 per minute, and HLS Encoding is charged based on resolution ($0.04 for HD and $0.08 for Full HD).

#### **5. What encoding options are available?**

Live streaming includes encoding for multiple resolutions (SD, HD, Full HD, 2K, 2K+) to deliver the best experience to viewers on different devices and network conditions.

#### **6. Can I stream to multiple platforms simultaneously?**

Yes, you can use RTMP Out to stream to multiple platforms. Each RTMP output stream is charged separately.

#### **7. Please explain Live Streaming pricing calculation with an example**

Let's say 2 hosts have joined a livestream for 30 minutes, with 100 viewers:
- Livestream minutes = 30 minutes
- Host minutes = 30 livestream minutes × 2 hosts = 60 host-minutes
- Viewer minutes = 30 livestream minutes × 100 viewers = 3,000 viewer-minutes
- Considering HD Resolution:
  - Host cost: 60 × $0.004 = $0.24
  - Viewer cost: 3,000 × $0.002 = $6.00
- **Total cost = $0.24 + $6.00 = $6.24**

---

## Add-Ons & Compliance

#### **1. What are Add-Ons?**

Add-Ons are optional compliance and security features you can subscribe to enhance your VideoSDK implementation.

#### **2. What Add-Ons are available and what are the charges?**

**Compliance & Security Add-Ons:**



| Add-On | Monthly Price | Description |
| ------ | ------------- | ----------- |
| [ISO 27001](https://app.videosdk.live/profile/billing?tab=addons#:~:text=Add-,ISO%2027001,-International%20standard%20for) | $100 | Information Security Management System certification |
| [SOC2 Type 2](https://app.videosdk.live/profile/billing?tab=addons#:~:text=Remove-,SOC%202%20Type%20II,-Controls%20for%20security) | $100 | Service Organization Control 2 Type 2 certification |
| [HIPAA](https://app.videosdk.live/profile/billing?tab=addons#:~:text=supercharge%20your%20experience-,HIPAA%20Compliance,-Healthcare%2Dgrade%20data) | $500 | Health Insurance Portability and Accountability Act compliance |
| [GDPR](https://app.videosdk.live/profile/billing?tab=addons#:~:text=Remove-,GDPR%20Compliance,-EU%2Dstandard%20data) | $100 | General Data Protection Regulation compliance |
| [CERT-IN](https://app.videosdk.live/profile/billing?tab=addons#:~:text=Add-,CERT%2DIN%20Compliance,-Compliance%20with%20India%E2%80%99s) | $500 | Indian Computer Emergency Response Team compliance |
| [Geo-fencing - Geo Restriction](https://app.videosdk.live/profile/billing?tab=addons#:~:text=Geo%2Dfencing%20(Geo%20Restriction)) | $500 | Geographic access restrictions |
| [Cloud Proxy](https://app.videosdk.live/profile/billing?tab=addons#:~:text=Add-,Cloud%20Proxy,-Secure%20traffic%20routing) | $200 | Enhanced network routing and security |

#### **3. Can I subscribe to multiple Add-Ons?**

Yes, you can subscribe to any combination of Add-Ons based on your compliance and security requirements.

#### **4. How are Add-Ons billed?**

Add-Ons are subscription-based and billed monthly or annually. Choose annual billing to save approximately 17% compared to monthly billing.

#### **5. Can I cancel an Add-On subscription?**

Yes, you can cancel Add-On subscriptions at any time. Monthly subscriptions can be canceled with no penalty. Annual subscriptions may have different terms, [contact support](https://videosdk.live/contact) for more details.

#### **6. What is HIPAA compliance and when do I need it?**

HIPAA (Health Insurance Portability and Accountability Act) compliance is required for applications handling protected health information (PHI) in the United States. If you're building healthcare applications, telemedicine platforms, or any service that transmits patient data, you need HIPAA compliance.

#### **7. What is GDPR compliance and when do I need it?**

GDPR (General Data Protection Regulation) compliance is required when processing personal data of individuals in the European Union. If your application serves EU users, GDPR compliance ensures you meet data protection and privacy requirements.

#### **8. How do I subscribe to compliance add-ons from the dashboard?**

You can subscribe to any compliance or security add-on directly from the VideoSDK Dashboard:

1. Navigate to **Billing > Add-ons** tab in the dashboard.
2. Locate the compliance/security add-on you want to subscribe to (e.g., HIPAA, GDPR, SOC2).
3. Click the **"Add"** button next to the add-on.
4. Review the total monthly subscription cost at the bottom.
5. Click **Continue**, add/confirm payment details, and pay.
6. Your monthly subscription will be active immediately.

![Subscribe to Add-ons](https://assets.videosdk.live/images/add_ons.png)

For detailed information about each compliance add-on, see the [Security & Privacy documentation](../help_docs/security-and-privacy/iso-27001).

---

## Concurrency Packages

#### **1. What is concurrency?**

Concurrency refers to the maximum number of simultaneous sessions, participants, or resources you can have active at the same time.

#### **2. What are included concurrency limits?**

Each product comes with base concurrency limits included with your Pay-As-You-Go plan. Check your VideoSDK Dashboard for your current limits.

#### **3. How do I increase concurrency limits?**

You can purchase Usage limits Packs to increase your limits.

#### **4. What are the Concurrency Packages?**

**Concurrency Usage limits Packs:**

| Items | Free Plan | PAYG (On-demand) | Pay-As-You-Go (Add-On Packs) | Max Pack Buy on Dashboard |
| :--- | :--- | :--- | :--- | :--- |
| **Participants (Hosts)** | Up to 50 concurrent hosts | Up to 100 concurrent hosts | Add 100 hosts for $20 / pack / month | 5 |
| **Recordings** | Up to 1 recordings | Up to 10 recordings | Add 10 recordings for $20 / pack / month | 5 |
| **Agent Cloud Sessions** | Up to 1 Agent sessions | Up to 10 Agent sessions | Add 10 sessions for $20 / pack / month | 5 |
| **VideoSDK Inference (STT, LLM, TTS, STS)** | Up to 1 units | Up to 10 units | Add 10 units for $20 / pack / month | 5 |
| **Viewers (HLS/RTC)** | Up to 100 concurrent viewers | Up to 200 concurrent viewers | Add 200 viewers for $20 / pack / month | 10 |
| **HLS Encoding** | Up to 1 encoding | Up to 10 encoding | Add 10 units for $20 / pack / month | 5 |
| **SIP Connect** | Up to 1 SIP Connect | Up to 10 SIP Connect | Add 10 SIP lines for $20 / pack / month | 5 |
| **Real-time Transcription** | Up to 1 live Transcription | Up to 10 live Transcription | Add 10 sessions for $20 / pack / month | 5 |
| **RTMP** | Up to 1 RTMP streams | Up to 10 RTMP streams | Add 10 RTMP streams for $20 / pack / month | 5 |

#### **5. How much do usage limits packs cost?**

Most usage limits packs cost **$20 per pack per month**. Each pack includes a specific quantity (e.g., 100 hosts, 200 viewers, 10 recordings).

#### **6. Is there a limit to how many packs I can purchase?**

Yes, each pack type has a maximum limit on how many packs you can buy through the dashboard:
- **Viewers (HLS/RTC) packs**: 10 max packs
- **Most other packs**: 5 max packs

If you need more than the maximum, [contact our sales team](https://videosdk.live/contact) for custom solutions.

#### **7. Can I cancel usage limits packs?**

Yes, usage limits packs are monthly subscriptions and can be canceled at any time. Cancellation takes effect at the end of the current billing period.

#### **8. How can I increase my concurrency limits from the dashboard?**

You can purchase Add-On Packs directly from the VideoSDK Dashboard. Navigate to **Billing > Usage Limits**, click the **"+"** button next to the service you want to increase, review the total cost, and complete payment.

For a detailed step-by-step guide, see [How to increase concurrency from the dashboard](./quotas-and-limit#how-to-increase-concurrency-from-the-dashboard).

---

## Billing & Payment

#### **1. What payment methods are accepted?**

We accept:
- Credit cards (Visa, Mastercard, American Express)
- Debit cards
- Payment processing via Stripe

#### **2. What currency is used for billing?**

- **Default**: USD (US Dollars)
- **Indian businesses**: INR (Indian Rupees)

#### **3. Are there any taxes applied?**

- **International**: No additional taxes by default
- **Indian businesses**: 18% GST applicable (SAC Code - 998313), plus 2% TDS under section 194(C) or 194(J)

#### **4. How do I get GST invoices (for Indian businesses)?**

Submit your registered GST and Company PAN details in the VideoSDK Dashboard. GST invoices will be generated automatically for all transactions.

#### **5. Can I get a refund if I don't use all my credits?**

Wallet credits are non-refundable. However, they never expire and can be used for any VideoSDK service at any time.

#### **6. Do I receive invoices for wallet top-ups?**

Yes, you'll receive a receipt via email for every wallet top-up transaction. Receipts are also available in the VideoSDK Dashboard.

---

## Usage & Calculation

#### **1. Does VideoSDK charge separately for Audio?**

No, audio cost is already included in the video cost. Audio-only pricing ($0.001/min) applies only when **no participant has their camera ON**. If anyone has their camera ON, video rates apply.

#### **2. Please explain pricing calculation with an example**

Let's say 5 people join a meeting for 30 minutes.
- **Meeting Duration**: 30 minutes
- **Participant Minutes**: 30 mins × 5 participants = 150 participant-minutes
- **Cost Calculation (HD Resolution)**: 150 mins × $0.004 = **$0.60**

#### **3. If I have a mix of Audio and Video usage, how is my free $20 balance used?**

Your $20 free balance is a monetary credit that applies to **all** usage types automatically. It doesn't distinguish between audio or video minutes.
- If you use $5 worth of Audio minutes and $10 worth of HD Video minutes, your balance simply deducts $15.

#### **4. I have used only $9 this month. Will the remaining free balance ($11) carry forward?**

Yes! The **$20 free balance** is a one-time credit with no expiration. It will carry forward to the next month and remain available until fully consumed.

#### **5. My usage is over 100k minutes/month. How can I reduce costs?**

Volume discounts are available for high-scale usage. If you consume more than 100k minutes per month, please [contact our sales team](https://videosdk.live/contact) or email [support@videosdk.live](mailto:support@videosdk.live) for a custom quote.

#### **6. I set maxResolution to (320x180), so why am I charged for HD?**

Charges are based on **aggregate resolution**, the sum of all video streams a user is viewing.
- If a user views 8 streams of 320x180, total pixels = (320×180) × 8 = **460,800 px**.
- This total falls within the **HD** range (≤ 921,600 px), so the HD rate applies.

#### **7. How do you calculate aggregate video resolution?**

Aggregate resolution is the total pixels of all streams a user downloads.

| Videos on-screen | Aggregate Resolution Type | Price (approx.) |
| ---------------- | ------------------------- | --------------- |
| 0 (Audio Only) | Audio | $0.001 |
| 1-5 | HD | $0.004 |
| 6-10 | Full HD | $0.008 |
| 11-17 | 2K | $0.016 |
| 18+ | 2K+ | $0.036 |

*Note: Assumes standard HD (1280x720) streams.*

#### **8. In detail, what are the resolution thresholds?**

We classify resolution based on total pixel count:

| Video Type | Aggregate Resolution (px) | Equivalent (16:9) |
| ---------- | ------------------------- | ----------------- |
| **HD** | ≤ 921,600 px | 720p (1280×720) |
| **Full HD** | 921,601 - 2,073,600 px | 1080p (1920×1080) |
| **2K** | 2,073,601 - 3,686,400 px | 1440p (2560×1440) |
| **2K+** | > 3,686,400 px | 4K (3840×2160) |

#### **9. I want to show 15 people but avoid high resolution costs. How?**

To save costs while showing many participants, you can explicitly reduce the resolution of each tile.
- If you set each of the 15 tiles to **320x180**:
- Total Pixels: 15 × (320×180) = **864,000 px**
- This stays within the **HD** limit (921,600 px), keeping you at the lower HD price tier.

#### **10. How are partial minutes billed?**

Partial minutes are rounded up to the nearest minute for all services.

#### **11. Can I set balance auto-reload?**

Yes, you can configure auto-reload in the dashboard to add funds automatically when your balance drops below a set threshold.

#### **12. How often is usage calculated?**

Usage is calculated in real-time. Charges are deducted from your wallet balance instantly as services are consumed.

---

## Configuration & Controls

#### **1. Does Dashboard configuration override SDK configuration?**

It depends on the service:
- **Audio/Video Configurations**: **Yes**. Runtime dashboard settings have **higher precedence** and will override SDK configurations (e.g., forcing Full HD in dashboard overrides HD in code).
- **Recording & Streaming**: **No**. API/SDK configurations have **highest priority**. Dashboard settings are only applied as a fallback when no API values are defined.

For more details, see [API Settings & Controls](../ai_agents/authentication-and-token#api-settings--controls).

#### **2. How do I restrict video quality to manage bandwidth or costs?**

You can restrict the **Maximum Send Bitrate Per Participant** in the [VideoSDK Dashboard](https://app.videosdk.live/api-keys) under **API Settings > Audio/Video**.
\t
**Available limits:**
- **SD (800kbps)**
- **HD (1500kbps)**
- **Full HD (3000kbps)**

Setting this to **Auto** is recommended for quality, but forcing a limit (e.g., SD) ensures strict bandwidth and cost control.

Learn more in [Audio/Video Configurations](../ai_agents/authentication-and-token#audiovideo-configurations).

---

## Features & Support

#### **1. What features are included at no additional cost?**

The following platform features are included:
- Dashboard access
- Community support
- Email support
- End-to-end encryption
- Role-based access
- Region pinning

#### **2. What support is available?**

**Included:**
- Community support (forums, documentation)
- Email support

**Not Included (Contact Sales):**
- Shared Slack/WhatsApp channel
- Solutions Engineer
- Support SLA

#### **3. Can I get enterprise support?**

Yes! For enterprise support including dedicated Slack channels, Solutions Engineers, and SLA guarantees, please [contact our sales team](https://videosdk.live/contact).

---

## Volume & Enterprise

#### **1. Do you offer volume discounts?**

Yes! If your monthly usage exceeds certain thresholds, we offer custom pricing. Contact our sales team at [support@videosdk.live](mailto:support@videosdk.live) or visit [videosdk.live/contact](https://videosdk.live/contact).

#### **2. Can I get a custom pricing plan?**

Yes, we offer custom pricing plans for:
- High-volume usage
- Enterprise deployments
- Special compliance requirements
- Custom SLAs

Contact our sales team to discuss your specific needs.

#### **3. Do you offer annual contracts?**

Yes, we can provide annual contracts with custom pricing and terms. Contact our sales team for details.

---

## Getting Started

#### **1. How do I get started with VideoSDK?**

1. [Sign up](https://app.videosdk.live) for a free account
2. Receive $20 free balance automatically
3. Add additional funds to your wallet
4. Start using Agent, Video Call, or Live Streaming
5. Monitor usage in real-time through the dashboard

#### **2. Do I need a credit card to sign up?**

No credit card is required to sign up and receive your $20 free balance. You'll need to add payment details when you want to add more funds to your wallet.

#### **3. Can I test the service before committing?**

Yes! Use your $20 free balance to test all VideoSDK features and products before adding additional funds.

#### **4. Where can I find documentation?**

Visit [docs.videosdk.live](https://docs.videosdk.live) for comprehensive documentation, guides, and API references.

#### **5. How do I contact support?**

- **Email**: [support@videosdk.live](mailto:support@videosdk.live)
- **Contact Form**: [videosdk.live/contact](https://videosdk.live/contact)
- **Community**: Join our community forums for peer support

---

For more questions or assistance, please contact us at [support@videosdk.live](mailto:support@videosdk.live)


---

## Understanding Usage Quota Limits

In this documentation, you will find detailed information about the quotas associated with each plan, including usage limits for various features and functionalities. Understanding these quotas will help you optimize your usage, selecting the best pricing plan and make the most of your VideoSDK experience.

## How VideoSDK limits concurrent usage quota

VideoSDK's approach to limiting usage focuses on concurrent usage rather than overall usage. Concurrent usage refers to the number of participants or requests that can be hosted or processed simultaneously.

For example, if there's a limit of 50 concurrent participants per organization, users can run multiple calls (sessions) simultaneously, with a maximum of 50 participants across all sessions combined.

## How to view my current plan’s quota limits?

To view the current quota limits on your organization, simply navigate to the [VideoSDK Dashboard](https://app.videosdk.live/), go to your Profile section, and click on the Billing tab.

## Free Plan

Since, we’ve designed Free Plan for developers who are just exploring, we’ve kept the limits that would get you started without a hitch.

Organisations on Free Plan have the following limits on concurrent usage:

| Feature                            | Concurrent Limit               |
| ---------------------------------- | ------------------------------ |
| Participants in Video Calls        | 50 concurrent participants     |
| Viewers in Interactive Live Stream | 200 concurrent viewers         |
| Viewers in Http Live Stream (HLS)  | 100 concurrent viewers         |
| Recording Request                  | 1 concurrent request at a time |
| HLS Encoding Request               | 1 concurrent request at a time |
| RTMP-Out Request                   | 1 concurrent request at a time |

### How to increase my limits?

To increase your limits, simply upgrade your plan by providing billing details and credit card information.

## Pay-as-you-Go Plan

We've increased participant limits for this paid plan. This way, it won't significantly impact users heavily involved in production or integration.

Organisations on Pay-as-you-Go have the following limits on concurrent usage:

| Feature                            | Concurrent Limit               |
| ---------------------------------- | ------------------------------ |
| Participants in Video Calls        | 100 concurrent participants    |
| Viewers in Interactive Live Stream | 1000 concurrent viewers        |
| Viewers in Http Live Stream (HLS)  | 500 concurrent viewers         |
| Recording Request                  | 5 concurrent request at a time |
| HLS Encoding Request               | 5 concurrent request at a time |
| RTMP-Out Request                   | 5 concurrent request at a time |

### How to increase my limits?

To increase your limits further more, simply get in touch with us. [Contact us](https://www.videosdk.live/contact) directly or reach out via email at [support@videosdk.live](mailto:support@videosdk.live), and we'll handle the rest gladly.

## Enterprise Plan

For Enterprise users, all limits are tailored to the specific needs. Customised limits ensure optimal performance for your unique requirements.

To get started as an Enterprise user, simply get in touch with us, explain your requirements and use case, and we’ll customise the quota and limits according to your needs.

## Examples to understand concurrent limits

**Example #1**

Let's say you're using video callings (RTC) in your organization on the Free Plan. In this scenario, you can concurrently host up to 50 participants. However, the number of calls (sessions) you initiate is unrestricted.

To simplify, you can run multiple sessions simultaneously, but concurrently, you can only accommodate a maximum of 50 participants across all sessions. If a 51st participant attempts to join, they won't be able to access the session until you upgrade your plan to increase your participant limits.

**Example #2**

Let’s say you're using live streaming in your organization on the Free Plan. In this setup, you can concurrently host up to 100 viewers joining the sessions. While you have the flexibility to host multiple live streaming sessions, the number of viewers joining session concurrently is restricted.

**Example #3**

Lets say you’re using video callings (RTC) in your organization on the Pay-as-you-Go Plan and you're hosting 5 concurrent calls (sessions), all of which are being recorded. Now, when you initiate the 6th call (session) and request recording, VideoSDK will not process your recording request. Instead, it will throw an error because you've reached your recording request limit.

If you have any questions regarding quota limits and pricing plan, post in our [Discord community](https://discord.com/invite/Qfm8j4YAUJ), [contact us](https://www.videosdk.live/contact) directly, or reach out to us on [support@videosdk.live](mailto:support@videosdk.live).


---

## Understanding Usage Quota Limits

In this documentation, you will find detailed information about the quotas associated with each plan, including usage limits for various features and functionalities. Understanding these quotas will help you optimize your usage, selecting the best pricing plan and make the most of your VideoSDK experience.

## How VideoSDK limits concurrent usage quota

VideoSDK's approach to limiting usage focuses on concurrent usage rather than overall usage. Concurrent usage refers to the number of participants or requests that can be hosted or processed simultaneously.

For example, if there's a limit of 50 concurrent participants per organization, users can run multiple calls (sessions) simultaneously, with a maximum of 50 participants across all sessions combined.

## How to view my current plan’s quota limits?

To view the current quota limits on your organization, simply navigate to the [VideoSDK Dashboard](https://app.videosdk.live/), go to your Profile section, and click on the Billing tab.

## Usage Quota Limits by Plan

VideoSDK provides different default limits based on your account type. You can increase these limits by purchasing Add-On Packs.

### Detailed Usage Limits

| Items | Free Plan | PAYG (On-demand) | Pay-As-You-Go (Add-On Packs) | Max Pack Buy on Dashboard |
| :--- | :--- | :--- | :--- | :--- |
| **Participants (Hosts)** | Up to 50 concurrent hosts | Up to 100 concurrent hosts | Add 100 hosts for $20 / pack / month | 5 |
| **Recordings** | Up to 1 recordings | Up to 10 recordings | Add 10 recordings for $20 / pack / month | 5 |
| **Agent Cloud Sessions** | Up to 1 Agent sessions | Up to 10 Agent sessions | Add 10 sessions for $20 / pack / month | 5 |
| **VideoSDK Inference (STT, LLM, TTS, STS)** | Up to 1 units | Up to 10 units | Add 10 units for $20 / pack / month | 5 |
| **Viewers (HLS/RTC)** | Up to 100 concurrent viewers | Up to 200 concurrent viewers | Add 200 viewers for $20 / pack / month | 10 |
| **HLS Encoding** | Up to 1 encoding | Up to 10 encoding | Add 10 units for $20 / pack / month | 5 |
| **SIP Connect** | Up to 1 SIP Connect | Up to 10 SIP Connect | Add 10 SIP lines for $20 / pack / month | 5 |
| **Real-time Transcription** | Up to 1 live Transcription | Up to 10 live Transcription | Add 10 sessions for $20 / pack / month | 5 |
| **RTMP** | Up to 1 RTMP streams | Up to 10 RTMP streams | Add 10 RTMP streams for $20 / pack / month | 5 |

### How to increase my limits?

If you are on the **Free Plan**, simply upgrade to **Pay-As-You-Go** by providing billing details and credit card information to increase your default limits.

If you are already on **Pay-As-You-Go** and need even higher limits, you can purchase the **Add-On Packs** listed above directly from the [VideoSDK Dashboard](https://app.videosdk.live/).

#### **How to increase concurrency from the dashboard:**

1. Navigate to **Billing** > **Usage Limits** tab in the dashboard.
2. Locate the specific service (e.g., Participants, Recordings) you want to increase.
3. Click on the **"+"** button to add packs.
4. Review the total monthly subscription cost at the bottom.
5. Click **Continue**, confirm card details, and pay.
6. Your increased limits will be active immediately.

![Increase Concurrency](https://assets.videosdk.live/images/usage_limits.png)

For custom enterprise requirements, please [Contact us](https://www.videosdk.live/contact).


## Enterprise Plan

For Enterprise users, all limits are tailored to the specific needs. Customised limits ensure optimal performance for your unique requirements.

To get started as an Enterprise user, simply get in touch with us, explain your requirements and use case, and we’ll customise the quota and limits according to your needs.

## Examples to understand concurrent limits

**Example #1**

Let's say you're using video callings (RTC) in your organization on the Free Plan. In this scenario, you can concurrently host up to 50 participants. However, the number of calls (sessions) you initiate is unrestricted.

To simplify, you can run multiple sessions simultaneously, but concurrently, you can only accommodate a maximum of 50 participants across all sessions. If a 51st participant attempts to join, they won't be able to access the session until you upgrade your plan to increase your participant limits.

**Example #2**

Let’s say you're using live streaming in your organization on the Free Plan. In this setup, you can concurrently host up to 100 viewers joining the sessions. While you have the flexibility to host multiple live streaming sessions, the number of viewers joining session concurrently is restricted.

**Example #3**

Lets say you’re using video callings (RTC) in your organization on the Pay-as-you-Go Plan and you're hosting 5 concurrent calls (sessions), all of which are being recorded. Now, when you initiate the 6th call (session) and request recording, VideoSDK will not process your recording request. Instead, it will throw an error because you've reached your recording request limit.

If you have any questions regarding quota limits and pricing plan, post in our [Discord community](https://discord.com/invite/Qfm8j4YAUJ), [contact us](https://www.videosdk.live/contact) directly, or reach out to us on [support@videosdk.live](mailto:support@videosdk.live).


---

# VideoSDK CERT-IN Compliance Overview

## What is CERT-IN?

The Indian Computer Emergency Response Team (CERT-IN) is the national nodal agency for cybersecurity in India. It establishes frameworks, best practices, and mandatory security standards to protect digital infrastructure by ensuring secure systems, vulnerability reporting, incident management, and proactive threat mitigation for organizations operating within India.

## How VideoSDK Ensures CERT-IN Compliance

### 1. Infrastructure Security
VideoSDK systems are hosted on secure cloud providers that align with CERT-IN cybersecurity guidelines. We ensure continuous monitoring, threat protection, and controlled access across network and infrastructure layers.

### 2. Incident Response & Monitoring
We maintain an internal incident response plan based on CERT-IN directives. In case of cybersecurity events, VideoSDK follows mandatory reporting processes, ensures timely mitigation, and coordinates with concerned authorities when required.

### 3. Secure Data Handling
All data transmissions are encrypted using TLS/SRTP with adherence to CERT-IN security protocols. No customer content, including video or audio, is stored unless explicitly configured.

### 4. Access Control & Authentication
Role-based access controls (RBAC) and JWT-based authentication safeguard customer environments. Critical systems follow multi-factor authentication and restricted privilege policies.

### 5. Regular Audits & Vulnerability Management
VideoSDK conducts periodic internal audits, vulnerability assessments, and patch management in alignment with CERT-IN standards to eliminate security gaps before exploitation.

### 6. Compliance Documentation
Compliance-related technical documentation, audit support, and clarification are available to help customers evaluate CERT-IN requirements for their own organizations.

## Customer Responsibilities

While VideoSDK follows CERT-IN-aligned practices, customers remain responsible for:

*   Secure integration & configuration of VideoSDK within their applications
*   Managing user permissions, authentication, and access within their systems
*   Ensuring compliance at an organizational and application level

## Compliance Add-On

- **Price / month:** $500
- **[Subscribe in Dashboard](https://app.videosdk.live/profile/billing?tab=addons#:~:text=Add-,CERT%2DIN%20Compliance,-Compliance%20with%20India%E2%80%99s)**

The CERT-IN compliance support add-on includes:

- Documentation for security audits
- CERT-IN alignment guidance
- Incident response assistance
- Infrastructure compliance support

Available for **Pay-As-You-Go** plan.

### How to Subscribe

Subscribe directly from the [VideoSDK Dashboard](https://app.videosdk.live/profile/billing?tab=addons#:~:text=Add-,CERT%2DIN%20Compliance,-Compliance%20with%20India%E2%80%99s) by navigating to **Billing > Add-ons**, clicking **Add** next to CERT-IN Compliance, and completing payment.

For detailed step-by-step instructions, see [How to subscribe to compliance add-ons](../pricing#8-how-do-i-subscribe-to-compliance-add-ons-from-the-dashboard).

## Contact & Support

For CERT-IN inquiries, audit documentation, or security alignment requests:
[**security@videosdk.live**](mailto:security@videosdk.live)
[**www.videosdk.live**](http://www.videosdk.live)


---

# Cloud Proxy

Our Platform features a Cloud Proxy that allows you to manage how your streaming content is routed through different network paths. This feature ensures compliance with various regional internet regulations by restricting traffic to specified proxy servers, based on your needs and the geographical location of users.

This capability is crucial for adhering to local data protection laws and optimizes the streaming experience by overcoming geographical network constraints. By directing user connections to appropriate regional servers, Cloud Proxy enhances overall service performance and reliability.

## Operating Modes

Cloud Proxy offers three operating modes to fit different business and firewall requirements:

- **UDP_OVER_TCP (Default)**: In this mode, the connection starts by attempting to establish a UDP connection for media transmission. If that fails, it will automatically shift to a secure TCP connection, which is compatible with most firewalls.
- **Force UDP**: This mode uses only UDP to send media, ensuring high-quality streams. It's ideal for environments where media quality is critical and the firewall can be configured accordingly.
- **Force TCP**: Only uses TCP for secure media transmission, suitable for strict firewall settings that only permit TCP traffic over certain ports. This might require additional firewall configuration and could affect media quality under poor network conditions.

## How it works

The Cloud Proxy acts as an intermediary between the client and the destination media servers.

1. **Client to Proxy Server:** The client sends a request to the proxy server, which processes and forwards it based on predefined rules.
2. **Proxy Server to Destination Server:** The proxy server sends the request to the destination server, receives the response, and relays it back to the client.

---

## Pricing

| Add-On | Monthly Price | Description |
| ------ | ------------- | ----------- |
| [Cloud Proxy](https://app.videosdk.live/profile/billing?tab=addons#:~:text=Add-,Cloud%20Proxy,-Secure%20traffic%20routing) | $200 | Enhanced network routing and security |

Cloud Proxy is available as an add-on for **Pay-As-You-Go** plan.

### How to Subscribe

Subscribe directly from the [VideoSDK Dashboard](https://app.videosdk.live/profile/billing?tab=addons#:~:text=Add-,Cloud%20Proxy,-Secure%20traffic%20routing) by navigating to **Billing > Add-ons**, clicking **Add** next to Cloud Proxy, and completing payment.

For detailed step-by-step instructions, see [How to subscribe to compliance add-ons](../pricing#8-how-do-i-subscribe-to-compliance-add-ons-from-the-dashboard).

### Contact & Activation

For more information on setting up Cloud Proxy for your organization, please contact:
[**security@videosdk.live**](mailto:security@videosdk.live)


---

# VideoSDK GDPR Compliance Overview

## What is GDPR?

The General Data Protection Regulation (GDPR) is a comprehensive EU regulation that safeguards the privacy and personal data of individuals in the European Economic Area (EEA). It establishes strict requirements regarding transparency, security, data processing, user permissions, and the rights of individuals.

## How VideoSDK Ensures GDPR Compliance

### 1. Data Minimization
We collect and process only the data necessary to deliver video, audio, and engagement services.

### 2. Encryption
All real-time media streams are encrypted in transit using secure industry-standard protocols (TLS/SRTP).

### 3. Data Residency Options
Customers can host workloads on EU-based infrastructure to ensure that all data remains within the region.

### 4. Consent-Based Recording
Recording is disabled by default. Any recording requires explicit user consent and can be controlled at the application level.

### 5. No Audio/Video Storage Without Consent
VideoSDK does not store live audio or video streams unless recording is explicitly enabled by the customer.

### 6. Right to Erasure & Access
We support user data access and deletion requests in accordance with GDPR requirements.

### 7. Data Processing Agreement (DPA)
A formal DPA is available for customers, outlining our responsibilities as a data processor.

### 8. Secure Authentication
We use JWT-based authentication and role-based permissions to ensure secure and controlled access to services.

## Customer Responsibilities

While VideoSDK provides tools and infrastructure to support GDPR compliance, customers remain responsible for:

*   Configuring platform settings appropriately
*   Obtaining end-user permissions
*   Managing personal data as the data controller

## Compliances (Add-Ons)

- **Price / month:** $100
- **[Subscribe in Dashboard](https://app.videosdk.live/profile/billing?tab=addons#:~:text=Remove-,GDPR%20Compliance,-EU%2Dstandard%20data)**

GDPR compliance features and the Data Processing Agreement (DPA) are available as add-ons for Pay-As-You-Go plan.

### How to Subscribe

Subscribe directly from the [VideoSDK Dashboard](https://app.videosdk.live/profile/billing?tab=addons#:~:text=Remove-,GDPR%20Compliance,-EU%2Dstandard%20data) by navigating to **Billing > Add-ons**, clicking **Add** next to GDPR Compliance, and completing payment.

For detailed step-by-step instructions, see [How to subscribe to compliance add-ons](../pricing#8-how-do-i-subscribe-to-compliance-add-ons-from-the-dashboard).

## Contact & Documentation

For compliance questions, security documentation, or DPA requests, contact:
[**security@videosdk.live**](mailto:security@videosdk.live)


---

# Geo Fencing

Our Platform includes a region geofencing feature to comply with local laws and regulations worldwide. It restricts connections to servers within specified regions, ensuring users connect only to designated areas, regardless of their location.

This helps meet regional data protection requirements and enhances user experience by addressing geographical network limitations.

## How it works

When geo-fencing is configured, all users attempting to join a session will be routed to the designated geographic region, even if their physical location is closer to another region.

## Considerations

- **Network Quality:** If a user’s location differs significantly from the chosen region, the network quality between these locations may be poor, potentially affecting audio and video quality.
- **Compliance Use Case:** Avoid using geofencing unless your specific scenario requires regional compliance or data isolation.

## Available Regions

- **INDIA**
- **USA**
- **UAE**
- **EUROPE**
- **SINGAPORE**


---

## Pricing

| Add-On | Monthly Price | Description |
| ------ | ------------- | ----------- |
| [Geo-fencing - Geo Restriction](https://app.videosdk.live/profile/billing?tab=addons#:~:text=Geo%2Dfencing%20(Geo%20Restriction)) | $500 | Geographic access restrictions |

Geo-fencing is available as an add-on for **Pay-As-You-Go** plan.

### How to Subscribe

Subscribe directly from the [VideoSDK Dashboard](https://app.videosdk.live/profile/billing?tab=addons#:~:text=Geo%2Dfencing%20(Geo%20Restriction)) by navigating to **Billing > Add-ons**, clicking **Add** next to Geo-fencing, and completing payment.

For detailed step-by-step instructions, see [How to subscribe to compliance add-ons](../pricing#8-how-do-i-subscribe-to-compliance-add-ons-from-the-dashboard).

### Contact & Activation

For more information on setting up Geo-fencing for your organization, please contact:
[**security@videosdk.live**](mailto:security@videosdk.live)

---

# VideoSDK HIPAA Compliance Overview

## What is HIPAA?

The **Health Insurance Portability and Accountability Act (HIPAA)** is a United States federal law that establishes strict standards for the protection of **Protected Health Information (PHI)**. It governs how healthcare providers, partners, and service vendors collect, store, transmit, and manage sensitive patient data.

HIPAA requires organizations to implement strong **physical, technical, and administrative safeguards** to ensure the confidentiality, integrity, and availability of PHI.

## How VideoSDK Ensures HIPAA Compliance

### 1. PHI Protection & Data Handling
VideoSDK can be deployed in a **HIPAA-aligned environment** to ensure that Protected Health Information is safeguarded across all stages of processing, routing, and communication.

### 2. Encryption (In-Transit & At-Rest)
All data including video, audio, metadata, and signaling is encrypted using industry-standard security protocols, including:

*   **Transport Layer Security (TLS)** for secure network communication
*   **Secure Real-time Transport Protocol (SRTP)** for media encryption

Where applicable, storage systems support **encryption at rest** to ensure PHI remains protected even when stored.

### 3. Access Controls & Authentication
VideoSDK uses secure authentication and access control mechanisms including:

*   **JSON Web Token (JWT)**–based authentication
*   **Role-based permissions** for enforcing least-privilege access

### 4. Business Associate Agreement (BAA)
VideoSDK offers a formal **Business Associate Agreement (BAA)** to covered entities and business associates. The BAA outlines required safeguards, shared responsibilities, confidentiality requirements, and HIPAA regulatory obligations.

### 5. Secure Media Routing
Media routing can be performed through **HIPAA-aligned cloud infrastructure**, featuring:

*   Strict network isolation
*   Limited administrative access
*   Secure environment segmentation
*   Configurable routing options designed to protect PHI

### 6. No Storage Without Explicit Enablement
*   VideoSDK does **not store any audio, video, or screen-sharing data** unless customers explicitly enable features such as recording or archiving.
*   **Recordings are uploaded directly to the customer’s cloud storage bucket**, minimizing exposure of Protected Health Information (PHI).
*   This default behavior significantly reduces the risk of PHI exposure and ensures customers maintain full control over stored media.

## Customer Responsibilities

While VideoSDK provides HIPAA-aligned infrastructure and security controls, customers acting as **data controllers** are responsible for:

*   Proper management of PHI
*   Configuring privacy settings and access controls
*   Ensuring that only authorized end-users access PHI
*   Handling patient **consent**, auditing, data retention, and lawful disclosure
*   Ensuring HIPAA compliance within their own application logic and data workflows

HIPAA compliance is a **shared responsibility**, and customers must ensure their implementation meets regulatory requirements.

## HIPAA-Compliant Features (Allowed)

*   **Composite Recording** (customer’s cloud storage required)
    *   Recordings are uploaded directly to the customer’s bucket and deleted immediately from VideoSDK
    *   VideoSDK has write-only access and cannot read customer storage
*   **Noise Cancellation:** Client-side; no PHI storage
*   **Whiteboard & Polls & Quizzes:** No PHI stored.
*   **SIP Audio & Video:** Encrypted and HIPAA-aligned.
*   **Chat:** Not stored; disappears after session.

## Disabled Features in HIPAA

The following services are not supported:

*   **Live Transcription**
*   **Closed Captions**
*   **Post-Call Transcription**
*   **AI-Generated Summaries**
*   **Live Streaming (HLS)**
*   **Live Streaming (RTMP-Out)**
*   **Live Transcription for HLS**

## Compliances (Add-Ons)

### HIPAA Add-On

- **Price / month:** $500
- **[Subscribe in Dashboard](https://app.videosdk.live/profile/billing?tab=addons#:~:text=supercharge%20your%20experience-,HIPAA%20Compliance,-Healthcare%2Dgrade%20data)**

HIPAA features and the Business Associate Agreement are available as **add-ons** for both **Enterprise** and **Pay-As-You-Go** plans.

### How to Subscribe

Subscribe directly from the [VideoSDK Dashboard](https://app.videosdk.live/profile/billing?tab=addons#:~:text=supercharge%20your%20experience-,HIPAA%20Compliance,-Healthcare%2Dgrade%20data) by navigating to **Billing > Add-ons**, clicking **Add** next to HIPAA Compliance, and completing payment.

For detailed step-by-step instructions, see [How to subscribe to compliance add-ons](../pricing#8-how-do-i-subscribe-to-compliance-add-ons-from-the-dashboard).

## Contact & Documentation

For compliance questions, BAA requests, or security documentation, contact:
[**security@videosdk.live**](mailto:security@videosdk.live)


---

# VideoSDK ISO 27001 Compliance Overview

## What is ISO 27001?

ISO 27001 is an international standard for Information Security Management Systems (ISMS). It provides a structured framework for managing and protecting sensitive information through documented policies, risk management practices, and continuous security improvements.

## How VideoSDK Ensures ISO 27001 Alignment

### 1. Information Security Management System (ISMS)
VideoSDK follows ISO 27001-aligned ISMS practices to govern security, evaluate risks, enforce controls, and continually improve security posture across the organization.

### 2. Data Governance & Asset Protection
Customer data, source code, infrastructure, and internal systems are classified, monitored, and safeguarded with strict access controls, encryption, and lifecycle management policies.

### 3. Risk Management & Assessment
Regular risk assessments are conducted to identify threats and vulnerabilities. Mitigation and remediation actions are implemented based on priority and ISO 27001 Annex A controls.

### 4. Access Control & Identity Management
Role-based access control (RBAC) and least-privilege principles are enforced across all internal and customer-facing systems. Authentication is supported by secure identity and access management frameworks.

### 5. Incident Response & Business Continuity
Incident management procedures and continuity plans are in place to ensure prompt response, transparency, and minimum disruption in the event of security incidents.

### 6. Employee & Operational Security
Personnel undergo periodic security training, certifications, and policy awareness programs to uphold information security standards across all business processes.

## Customer Responsibilities

While VideoSDK maintains ISO 27001-aligned practices, customers remain responsible for:

*   Managing internal compliance requirements and policy mapping
*   Secure configuration of their application and infrastructure
*   Maintaining access control and governance inside their systems
*   Ensuring integration-level compliance with ISO 27001 controls

## Compliance Add-On 

- **Price / month:** $100
- **[Subscribe in Dashboard](https://app.videosdk.live/profile/billing?tab=addons#:~:text=Add-,ISO%2027001,-International%20standard%20for)**

**ISO 27001 Support Package Includes:**

- Documentation for vendor audits
- ISMS policy mapping support
- Architecture security references
- Support during customer due diligence

Available for **Pay-As-You-Go** plan.

### How to Subscribe

Subscribe directly from the [VideoSDK Dashboard](https://app.videosdk.live/profile/billing?tab=addons#:~:text=Add-,ISO%2027001,-International%20standard%20for) by navigating to **Billing > Add-ons**, clicking **Add** next to ISO 27001, and completing payment.

For detailed step-by-step instructions, see [How to subscribe to compliance add-ons](../pricing#8-how-do-i-subscribe-to-compliance-add-ons-from-the-dashboard).

## Contact & Documentation

For ISO 27001 inquiries, security documentation, or compliance support:
[**security@videosdk.live**](mailto:security@videosdk.live)
[**www.videosdk.live**](http://www.videosdk.live)


---

# VideoSDK SOC 2 Type II Compliance Overview

## What is SOC 2 Type II?

SOC 2 Type II (System and Organization Controls) is an internationally recognized compliance framework that evaluates the effectiveness of an organization’s internal security controls over a defined period of time. It focuses on ensuring systems are designed and operated to protect customer data based on the **Trust Service Criteria**: Security, Availability, Processing Integrity, Confidentiality, and Privacy.

## How VideoSDK Ensures SOC 2 Type II Compliance

### 1. Security Controls
VideoSDK implements strict administrative, technical, and physical controls to protect systems and customer data. Access to production systems is restricted, monitored, and logged.

### 2. Continuous Monitoring
Operational controls are monitored continuously to validate system integrity, detect anomalies, and respond to emerging threats. Event logging, SIEM monitoring, and automated alerts are active across environments.

### 3. Data Encryption & Confidentiality
Sensitive data is encrypted at rest and in transit using industry-standard algorithms (TLS/SRTP). Confidentiality protections are enforced through secure data flows, privacy boundaries, and granular permission control.

### 4. Change Management & Auditing
We maintain documented policies for system changes, code deployments, and version control. All modifications undergo review, testing, and approval as part of our secure DevOps pipeline.

### 5. Risk Management & Vulnerability Assessment
VideoSDK conducts regular vulnerability assessments, penetration tests, and risk evaluations. Identified issues are remediated with defined SLAs based on severity.

### 6. Third-Party Governance
All third-party vendors and cloud providers undergo security reviews to ensure their controls align with SOC 2 Type II standards and compliance expectations.

## Customer Responsibilities

While VideoSDK ensures SOC 2 Type II aligned controls, customers are responsible for:

*   Secure usage and configuration of VideoSDK services
*   Managing authentication and identity lifecycle within their application
*   Maintaining compliance for systems integrated with VideoSDK
*   Ensuring internal policies align with SOC 2 Type II requirements

## Compliance Add-On

- **Price / month:** $100
- **[Subscribe in Dashboard](https://app.videosdk.live/profile/billing?tab=addons#:~:text=Remove-,SOC%202%20Type%20II,-Controls%20for%20security)**

The SOC 2 Type II compliance add-on includes:

- Support for audit documentation & control mapping
- Architecture diagrams & technical security references
- Compliance questionnaire assistance
- Support for customer SOC 2 audit preparation

Available for **Pay-As-You-Go** plan.

### How to Subscribe

Subscribe directly from the [VideoSDK Dashboard](https://app.videosdk.live/profile/billing?tab=addons#:~:text=Remove-,SOC%202%20Type%20II,-Controls%20for%20security) by navigating to **Billing > Add-ons**, clicking **Add** next to SOC 2 Type II, and completing payment.

For detailed step-by-step instructions, see [How to subscribe to compliance add-ons](../pricing#8-how-do-i-subscribe-to-compliance-add-ons-from-the-dashboard).

## Contact & Support

For SOC 2 Type II documentation, assessor support, or compliance queries:
[**security@videosdk.live**](mailto:security@videosdk.live)
[**www.videosdk.live**](http://www.videosdk.live)


---

## Custom Video Track - iOS

- You can create a Video Track using `createCameraVideoTrack()` method of `VideoSDK` class.
- This method can be used to create video track using different encoding parameters, camera facing mode, bitrateMode and optimization mode.

### Parameters

- **encoderConfig**:

  - type: `CustomVideoTrackConfig`
  - required: `false`
  - default: `h720p_w1280p`
  - You can choose from the below mentioned list of values for the encoder config.

| Config | Resolution | Frame Rate |   Optimized (kbps)   |   Balanced (kbps)   |   High Quality (kbps)   |
| -------------- | :--------: | :--------: | :----------: | :----------: | :----------: |
| h90p_w160p     |  160x90    |   30 fps   |  40   |  90   |  120   |
| h180p_w320p    |  320x180   |   30 fps   |  60   |  120  |  180   |
| h360p_w640p    |  640x360   |   30 fps   |  300  |  450  |  600   |
| h540p_w960p    |  960x540   |   30 fps   |  600  |  900  |  1200  |
| h720p_w1280p   |  1280x720  |   30 fps   |  1000  |  1500  |  2000  |
| h1080p_w1920p  | 1920x1080  |   30 fps   |  1500  |  2200  |  2700  |
| h120p_w160p    |  160x120   |   30 fps   |  40  |  90  |  120  |
| h180p_w240p    |  240x180   |   30 fps   |  90  |  120  |  180  |
| h240p_w320p    |  320x240   |   30 fps   |  100  |  150  |  200  |
| h360p_w480p    |  480x360   |   30 fps   |  270  |  360  |  540  |
| h480p_w640p    |  640x480   |   30 fps   |  350  |  600  |  900  |
| h720p_w960p    |  960x720   |   30 fps   |  900  |  1200  |  1600  |
| h1080p_w1440p  | 1440x1080  |   30 fps   |  1500  |  2000  |  2700  |

:::note

Above mentioned encoder configurations are valid for both, landscape as well as portrait mode.

:::

- **facingMode**:

  - type: `AVCaptureDevice.Position`
  - required: `false`
  - Allowed values : `.front` | `.back`
  - It will specify whether to use front or back camera for the video track.

- **multiStream**

  - type: `boolean`
  - required: `false`
  - default: `true`
  - It will specify if the stream should send multiple resolution layers or single resolution layer.

- **codec**

  - type: `String`
  - required: `false`
  - default: `VP8`
  - A video codec for compresses video data for efficient transmission over the internet, balancing quality and bandwidth usage.

- **bitrateMode**:

  - type: `BitrateMode`
  - required: `false`
  - Allowed values : `BitrateMode.BANDWIDTH_OPTIMIZED` | `BitrateMode.BALANCED` | `BitrateMode.HIGH_QUALITY`
  - Controls the video quality and bandwidth consumption. You can choose between `BitrateMode.HIGH_QUALITY` for the best picture, `BitrateMode.BANDWIDTH_OPTIMIZED` to save data, or `BitrateMode.BALANCED` for a mix of both. Defaults to `BitrateMode.BALANCED`.

- **maxLayer**:

  - type: `EncodingLayer`
  - required: `false`
  - Allowed values : `MAX_LAYER_2` | `MAX_LAYER_3`
  - default: `MAX_LAYER_3`
  - Specifies the maximum number of simulcast layers to publish. This parameter only has an effect if `multiStream` is set to true.

:::info

- To learn more about optimizations and best practices for using custom video tracks, [follow this guide](/ios/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track).
- This parameter is only available from `v2.0.6`.

:::

#### Returns

- `RTCVideoTrack`

### Example

```javascript
guard let videoMediaTrack = try? VideoSDK.createCameraVideoTrack(
 		encoderConfig: .h720p_w960p,
		facingMode: .front,
		multiStream: true,
        codec: .H264, // Default: .VP8
        bitrateMode: .HIGH_QUALITY, // Default: .BALANCED,
        maxLayer: .MAX_LAYER_2 // Default: .MAX_LAYER_3
) else { return }
```

## Custom Audio Track

- You can create a Video Track using `createAudioTrack()` method of `VideoSDK` class.
- This method can be used to create audio track using different noise configs.

### Parameters

- **noiseConfig**

  - **noiseSuppression**

    - type: `Bool`
    - required: `false`
    - If `true`, noise suppression would be turned on; otherwise, it would be off.

  - **echoCancellation**

    - type: `Bool`
    - required: `false`
    - If `true`, echo cancellation would be turned on; otherwise, it would be off.

  - **autoGainControl**

    - type: `Bool`
    - required: `false`
    - If `true`, autogain control would be turned on; otherwise, it would be off.

  - **highPassFilter**
    - type: `Bool`
    - required: `false`
    - If `true`, highpass filter would be turned on; otherwise, it would be off.

#### Returns

- `RTCAudioTrack`

### Example

```javascript
guard
  let audioMediaTrack = try? VideoSDK.createAudioTrack(
    noiseConfig: noiseConfig(
        noiseSupression: true,
        echoCancellation: true,
        autoGainControl: true,
        highPassFilter: true
      )
  )
else { return }
```


---

# Meeting Error Codes - iOS

If you encounter any of the errors listed below, refer to the [Developer Experience Guide](../../guide/best-practices/developer-experience.md#listen-for-error-events), which offers recommended solutions based on common error categories.



### 1. Errors associated with Organization 

This table lists errors that occur due to the configuration and limitations within your organization’s account. These include account status, participant limits, and add-on service availability.

| Type                                   | Code  | Message                                             |
|----------------------------------------|-------|-----------------------------------------------------|
| ACCOUNT_DEACTIVATED                   | 4006  | Your account has been deactivated. Please contact VideoSDK support. |
| ACCOUNT_DISCONTINUED                  | 4007  | Your account has been discontinued. Please reach out to support for more details. |
| MAX_PARTICIPANT_REACHED               | 4009  | You have reached the maximum participant limit for this meeting. |
| MAX_SPEAKER_REACHED                   | 4010  | The maximum number of speakers for this meeting has been reached. |
| MAX_SPEAKER_LIMIT_REACHED_ON_ORGANIZATION | 4026  | Your organization has reached the maximum number of speakers allowed. |
| MAX_VIEWER_LIMIT_REACHED_ON_ORGANIZATION | 4027  | Your organization has reached the maximum number of viewers allowed. |
| ADD_ON_SERVICES_DISABLED              | 4021  | Add-On services have been disabled. Please contact support to enable them. |
| MAX_RECORDING_LIMIT_REACHED_ON_ORGANIZATION              | 4028  | You have reached max limit of recording on organization. To increase contact at support@videosdk.live |
| MAX_HLS_LIMIT_REACHED_ON_ORGANIZATION  | 4029  | You have reached max limit of hls on organization. To increase contact at support@videosdk.live |
| MAX_LIVESTREAM_LIMIT_REACHED_ON_ORGANIZATION  | 4030  | You have reached max limit of livestream on organization. To increase contact at support@videosdk.live |

### 2. Errors associated with Token

Errors listed here are related to issues with the API key, authentication tokens, or permissions assigned to users. These errors can occur when tokens are missing, expired, or improperly configured.

| Type                                    | Code  | Message                                                |
|-----------------------------------------|-------|--------------------------------------------------------|
| INVALID_API_KEY                        | 4001  | The provided API key is either missing or invalid. |
| INVALID_TOKEN                          | 4002  | The provided token is empty, invalid, or has expired. |
| INVALID_PERMISSIONS                    | 4008  | The permissions in the token are incorrect. Please verify them. |
| UNAUTHORIZED_MEETING_ID                | 4022  | The provided token is not authorized for this meeting ID. |
| UNAUTHORIZED_PARTICIPANT_ID            | 4023  | The provided token is not authorized for this participant ID. |
| UNAUTHORIZED_ROLE                      | 4024  | The role specified in the token is not valid for joining this meeting. |
| UNAUTHORIZED_REQUEST                      | 4025 | Your request does not match the security configuration. |

### 3. Errors associated with Meeting and Participant

This table lists errors resulting from invalid or missing meeting or participant details, including cases where a participant attempts to join with a duplicate ID.

| Type                    | Code  | Message                                         |
|-------------------------|-------|-------------------------------------------------|
| INVALID_MEETING_ID      | 4003  | The meeting ID provided is either invalid or missing. |
| INVALID_PARTICIPANT_ID  | 4004  | The participant ID is either invalid or missing. |
| DUPLICATE_PARTICIPANT   | 4005  | This participant has joined from another device. |

### 4. Errors associated with Add-on Service

This section addresses errors that occur while using VideoSDK's add-on services such as recording, livestreaming, HLS streaming, and transcription.

### Recording-related errors

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_RECORDING_FAILED      | 4011  | Failed to start recording. Please try again.   |
| STOP_RECORDING_FAILED       | 4012  | Failed to stop recording. Please try again.    |
| RECORDING_FAILED            | 5001  | Recording was stopped due to an error.         |
| START_PARTICIPANT_RECORDING_FAILED | 4035 | Failed to start participant recording. Please check the request. |
| STOP_PARTICIPANT_RECORDING_FAILED  | 4036 | Failed to stop participant recording. |
| PARTICIPANT_RECORDING_FAILED       | 5012 | Participant recording has stopped due to an error. |
| START_TRACK_RECORDING_FAILED | 4037 | Failed to start track recording.                |
| STOP_TRACK_RECORDING_FAILED  | 4038 | Failed to stop track recording.                 |
| TRACK_RECORDING_FAILED  | 5013 | Track recording stopped due to an unknown error.                 |
| PREV_RECORDING_PROCESSING  | 4018 | Previous recording session is being processed, please try again after few seconds.                 |
| RECORDING_DURATION_LIMIT_REACHED | 5004 | Recording stopped due to maximum duration being reached. |

### Livestream-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| INVALID_LIVESTREAM_CONFIG           | 4015  | Livestream 'outputs' configuration provided was invalid            |
| START_LIVESTREAM_FAILED     | 4013  | Failed to start livestream. Please try again.  |
| STOP_LIVESTREAM_FAILED      | 4014  | Failed to stop livestream. Please try again.   |
| LIVESTREAM_FAILED           | 5002  | Livestream stopped due to an error.            |
| PREV_RTMP_RECORDING_PROCESSING | 4019 | Previous RTMP recording session is being processed, please try again after few seconds! |
| LIVESTREAM_DURATION_LIMIT_REACHED | 5005 | Livestream stopped due to maximum duration being reached. |

### HLS-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_HLS_FAILED            | 4016  | Failed to start HLS stream.                    |
| STOP_HLS_FAILED             | 4017  | Failed to stop HLS stream.                     |
| HLS_FAILED                  | 5003  | HLS streaming stopped due to an error.         |
| PREV_HLS_STREAMING_PROCESSING | 4020 | Previous HLS streaming session is still being processed. |
| HLS_DURATION_LIMIT_REACHED  | 5006  | HLS stream stopped due to maximum duration being reached. |

### Transcription-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_TRANSCRIPTION_FAILED  | 4031  | Failed to start transcription. Please try again. |
| STOP_TRANSCRIPTION_FAILED   | 4032  | Failed to stop transcription.                  |
| TRANSCRIPTION_FAILED        | 5007  | Transcription stopped due to an error.         |

### 5.Errors associated with Media

These errors involve media access, device availability, or permission-related issues affecting camera, microphone, and screen sharing.

### Device permission-related errors
| Type                                      | Code  | Message                                          |
|-------------------------------------------|-------|--------------------------------------------------|
| ERROR_GET_VIDEO_MEDIA_PERMISSION_DENIED  | 3014  | Video capture permission denied. |
| ERROR_GET_AUDIO_MEDIA_PERMISSION_DENIED  | 3015  | Audio capture permission denied. |
| ERROR_GET_DISPLAY_MEDIA_PERMISSION_DENIED | 3016 | Screen sharing permission denied. |

### Device-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| ERROR_GET_VIDEO_MEDIA      | 3011  | Your browser/Device does not support Video. |
| ERROR_GET_AUDIO_MEDIA      | 3012  | Your browser/Device does not support Audio. |
| ERROR_GET_DISPLAY_MEDIA      | 3013  | Your browser/Device does not support Screen Sharing. |


---

# Initializing a Meeting - iOS

<div class="api">

## config()

Before initializing the meeting, you will need to first provide `token`. Please refer this [documentation](/api-reference/realtime-communication/intro/) to generate a token.

```js
//meeting configuration using VideoSDK

VideoSDK.config("<your token>");
```

You can initialize the meeting using a factory method provided by the SDK called `initMeeting()`. By passing the parameters according to the need, it will generate a new `Meeting` class and the initiated meeting will be returned.

## initMeeting()

```js title="Swift"
let meeting = VideoSDK.initMeeting(
  meetingId: "abcd-efgh-xyzw",
  participantId: "JD", // optional
  participantName: "John Doe",
  micEnabled: true,
  webcamEnabled: true
  customCameraVideoStream: customVideoStream, //optional
  customAudioStream: customAudioStream, //optional
  mode: .SEND_AND_RECV, //optional (default mode is conference)
);
```

## Meeting Initialization Parameters

---

### meetingId

- Unique Id of the meeting where that participant will be joining.

  - type : `String`
  - `REQUIRED`

Please refer this [documentation](/api-reference/realtime-communication/create-room) to create a room.

---

### participantId

- Unique Id of the participant. If not passed then SDK will create an Id by itself and will use that id.

  - type : `String`
  - `OPTIONAL`

---

### participantName

- Name of the participant who will be joining the meeting, this name will be displayed to other participants in the same meeting.

  - type : `String`
  - `REQUIRED`

---

### micEnabled

- Whether `mic` of the participant will be on while joining the meeting. If it is set to `false`, then mic of that participant will be `disabled` by default, but can be `enabled` or `disabled` later.

  - type: `Boolean`
  - defaultValue : true
  - `OPTIONAL`

---

### webcamEnabled

- Whether `webcam` of the participant will be on while joining the meeting. If it is set to `false`, then webcam of that participant will be `disabled` by default, but can be `enabled` or `disabled` later.

  - type: `Boolean`
  - defaultValue : true
  - `OPTIONAL`

---

### customCameraVideoStream:

- If you want to set the initial video custom track, then you can pass the customVideoTrack created using `createCameraVideoTrack` method of `VideoSDK` class.

  - It has to be of [`CustomRTCMediaStream`](/ios/api/sdk-reference/custom-tracks) type.
  - defaultValue : `nil`
  - `OPTIONAL`

---

### customAudioStream:

- If you want to set the initial audio custom track, then you can pass the customAudioTrack created using `createAudioTrack` method of `VideoSDK` class.

  - It has to be of [`CustomRTCMediaStream`](/ios/api/sdk-reference/custom-tracks) type.
  - defaultValue : `nil`
  - `OPTIONAL`

---

### mode:

- There are 3 types of modes:

  1. `SEND_AND_RECV` : Both audio and video streams will be produced and consumed in this mode.
  2. `SIGNALLING_ONLY` : Audio and video streams will not be produced or consumed in this mode.
  3. `RECV_ONLY` : This mode allows only the consumption of audio and video streams without producing any.

- It has to be of `String` type.
- If you passed `null` then by default VideoSDK will set `SEND_AND_RECV` mode.




---

## Returns

### meeting

- After initializing the meeting, `initMeeting()` will return a new [`Meeting`](/javascript/api/sdk-reference/meeting-class/introduction) instance.

</div>


---

# Meeting Class Events - iOS

<div class="sdk-api-ref-only-h4">

---

### onMeetingJoined()

- This event will be emitted when a [localParticipant](./properties#localparticipant) successfully joined the meeting.

#### Example

```js
meeting.listeners.onMeetingJoined()
```

---

### onMeetingLeft()

- This event will be emitted when a [localParticipant](./properties#localparticipant) left the meeting.
- For more context on why the participant left, use the overloaded `onMeetingLeft(LeaveReason reason)` method.

#### Example

```js
meeting.listeners.onMeetingLeft()
```

---

### onMeetingLeft(reason: LeaveReason)

- This event is an overload for `onMeetingLeft()` and provides the specific reason why the local participant left the meeting.

#### Event callback parameters

- **reason**: `LeaveReason` - The reason why the participant left. See [LeaveReasons Enum](./properties#leavereason-enum) for all possible values.

#### Example

```js
meeting.listeners.onMeetingLeft(reason: reason)
```

---

### onParticipantJoined()

- This event will be emitted when a new [participant](../participant-class/introduction) joined the meeting.

#### Event callback parameters

- **participant**: [Participant](../participant-class/introduction)

#### Example

```js
meeting.listeners.onParticipantJoined(participant)
```

---

### onParticipantLeft(_ participant: Participant)

- This event will be emitted when a joined [participant](../participant-class/introduction) left the meeting.
- For more context on why the participant left, use the overloaded `onParticipantLeft(_ participant: Participant, reason: LeaveReason)` method.

#### Event callback parameters

- **participant**: [Participant](../participant-class/introduction)

#### Example

```js
meeting.listeners.onParticipantLeft(participant)
```

---

### onParticipantLeft(_ participant: Participant, reason: LeaveReason)

- This event is an overload for `onParticipantLeft()` and provides the specific reason why a remote participant left the meeting.

#### Event callback parameters

- **participant**: [Participant](../participant-class/introduction)
- **reason**: `LeaveReason` - The reason why the participant left. See [LeaveReasons Enum](./properties#leavereason-enum) for all possible values.

#### Example

```js
meeting.listeners.onParticipantLeft(participant, reason: reason)
```

---

### onSpeakerChanged()

- This event will be emitted when a active speaker changed.
- If you want to know which participant is actively speaking, then this event will be used.
- If no participant is actively speaking, then this event will pass `null` as en event callback parameter.

#### Event callback parameters

- **participantId**: String?

#### Example

```js
meeting.listeners.onSpeackerChanged(participantId: participantId)
```

---

### onMicRequested()

- This event will be emitted to the participant `B` when any other participant `A` requests to enable mic of participant `B`.
- On accepting the request, mic of participant `B` will be enabled.

#### Event callback parameters

- **participantId**: String?
- **accept**: Closure
- **reject**: Closure

#### Example

```js
meeting.listeners.onMicRequested(participantId: participantId) {
    // request accepted
} reject: {
    // request rejected
}
```

---

### onWebcamRequested()

- This event will be emitted to the participant `B` when any other participant `A` requests to enable webcam of participant `B`.
- On accepting the request, webcam of participant `B` will be enabled.

#### Event callback parameters

- **participantId**: String?
- **accept**: Closure
- **reject**: Closure

#### Example

```js
meeting.listeners.onWebcamRequested(participantId: participantId) {
    // request accepted
} reject: {
    // request rejected
}
```

---

### onRecordingStateChanged()

- This event will be emitted when the meeting's recording status changed.

#### Example

```js
meeting.listeners.onRecordingStateChanged(state: RecordingState) {
    switch(state) {
        case .RECORDING_STARTING:
            print("recording starting")

        case .RECORDING_STARTED:
            print("recording started")

        case .RECORDING_STOPPING:
            print("recording stoping")

        case .RECORDING_STOPPED:
            print("recording stopped")
    }
}
```

---

### onRecordingStarted()

- This event will be emitted when recording of the meeting is started.

#### Example

```js
meeting.listeners.onRecordingStarted()
```

---

### onRecordingStopped()

- This event will be emitted when recording of the meeting is stopped.

#### Example

```js
meeting.listeners.onRecordingStopped()
```

---

### onLivestreamStateChanged()

- This event will be emitted when the meeting's livestream status changed.

#### Example

```js
meeting.listeners.onLivestreamStateChanged(state: LiveStreamState) {
    switch(state) {
        case .LIVESTREAM_STARTING:
            print("livestream starting")

        case .LIVESTREAM_STARTED:
            print("livestream started")

        case .LIVESTREAM_STOPPING:
            print("livestream stoping")

        case .LIVESTREAM_STOPPED:
            print("livestream stopped")
    }
}
```

---

### onLivestreamStarted()

- This event will be emitted when `RTMP` live stream of the meeting is started.

#### Example

```js
meeting.listeners.onLivestreamStarted()
```

---

### onLivestreamStopped()

- This event will be emitted when `RTMP` live stream of the meeting is stopped.

#### Example

```js
meeting.listeners.onLivestreamStopped()
```

---

### onHlsStateChanged()

- This event will be emitted when the meeting's HLS(Http Livestreaming) status changed.

#### Example

```js
meeting.listeners.onHlsStateChanged(state: HLSState, hlsUrl: HLSUrl?) {
    switch(state) {
        case .HLS_STARTING:
            print("HLS Starting")

        case .HLS_STARTED:
            self.hlsStreamStarted = true
            print("HLS Started")

        case .HLS_PLAYABLE:
            print("HLS Playable")

        case .HLS_STOPPING:
            print("HLS Stopping")

        case .HLS_STOPPED:
            self.hlsStreamStarted = false
            print("HLS Stopped")
    }
}
```

---

### onTranscriptionStateChanged()

- This event will be emitted when the meeting's transcription status is changed.
- All available TranscriptionStates are `TRANSCRIPTION_STARTING`, `TRANSCRIPTION_STARTED`, `TRANSCRIPTION_STOPPING`, `TRANSCRIPTION_STOPPED`.

#### Example

```js
meeting.listeners.onTranscriptionStateChanged(state: TranscriptionState) {
    switch(state) {
        case .TRANSCRIPTION_STARTING:
            print("transcription starting")

        case .TRANSCRIPTION_STARTED:
            print("transcription started")

        case .TRANSCRIPTION_STOPPING:
            print("transcription stopping")

        case .TRANSCRIPTION_STOPPED:
            print("transcription stopped")
    }
}
```

---

### onTranscriptionText()

- This event will be emitted when the transcription is received by the SDK.

#### Event callback parameters

- **data**: \{ **\_ data**: TranscriptionText }
  - **TranscriptionText.participantId**: String
  - **TranscriptionText.participantName**: String
  - **TranscriptionText.text**: String
  - **TranscriptionText.timestamp**: Int
  - **TranscriptionText.type**: String

#### Example

```js
meeting.listeners.onTranscriptionText(_ data: TranscriptionText) {
        print("transcription text: ", data.text)
        print("participant name", data.participantName)
    }
```

---

### onMeetingStateChanged()

- This event will be triggered when state of meeting changes.
- It will pass **`state`** as an event callback parameter which will indicate current state of the meeting.
- All available states are `CONNECTING`, `CONNECTED`, `CLOSING`, `CLOSED` and `CANCELLED`.

#### Event callback parameters

- **data**: \{ **meetingState**: MeetingState }
  - **meetingState**: MeetingState

#### Example

```js
meeting.listeners.onMeetingStateChanged(meetingState: MeetingState) {
    switch meetingState {
        case .CONNECTING:
            print("Meeting is connecting")

        case .CONNECTED:
            print("Meeting is connected")

        case .CLOSING:
            print("Meeting is closing")

        case .CLOSED:
            print("Meeting connection closed")

        case .CANCELLED:
            print("Meeting is cancelled")
    }
}
```

---

### onError()

- This event will be triggered when any error occured.
- It will pass **`error`** as an event parameter.
- To see all available error codes from SDK. [Meeting Error Codes](../error-codes)

#### Example

```js
meeting.listeners.onError(error: VideoSDKError) {
    switch error {
        case .INVALID_TOKEN: print("Invalid Token")

        case .INVALID_MEETING_ID: print("Invalid Meeting Id")

        case .INVALID_API_KEY: print("Invalid API Key")

        case .INVALID_PERMISSIONS: print("Invalid Permissions")

        ...
    }
}
```

---

### onPinStateChanged()

- This event will be triggered when participant pin state changes.
- It will pass **`participantId, pinType`** as an event parameter.
- All available pin states are `SHARE_AND_CAM`, `CAM` and `SHARE`.

#### Event parameters

- **data**: \{ **participantId**: String, **pinType**: PinType }
  - **participantId**: String
  - **pinType**: PinType

#### Example

```js
meeting.listeners.onPinStateChanged(participantId: String, pinType: PinType) {
    ...
}
```

---

### onParticipantModeChanged()

- This event will be triggered when participant mode changes.
- It will pass **`participantId, mode`** as an event parameter.
- All available participant modes are `SEND_AND_RECV`, `SIGNALLING_ONLY` and `RECV_ONLY`.




#### Event parameters

- **data**: \{ **participantId**: String, **mode**: Mode }
  - **participantId**: String
  - **mode**: Mode

#### Example

```js
meeting.listeners.onParticipantModeChanged(participantId: String, mode: Mode) {
    ...
}
```

---

### onMicChanged()

- This event will be emitted when a [localParticipant](./properties#localparticipant) change their audio output device using `changeMic` method.

#### Example

```js
meeting.listeners.onMicChanged()
```

---

### onWhiteboardStarted()

- This event will be triggered when whiteboard is successfully started and it will return the url.

#### Event callback parameters

- **url**: URL

#### Example

```js
meeting.listeners.onWhiteboardStarted(url: URL) {
    ...
}
```

---

### onWhiteboardStopped()

- This event will be triggered when whiteboard session is stopped.

#### Example

```js
meeting.listeners.onWhiteboardStopped()
```

---

### onPausedAllStreams()

- This callback is triggered when all or specified media streams within the meeting are successfully paused
#### Event callback parameters
- **`kind`**: Specifies the type of media stream that was paused.  
  - **Type**: `String`  
  - **Possible values**:
    - `"audio"`: Indicates that audio streams have been paused.
    - `"video"`: Indicates that video streams have been paused.
    - `"share"`: Indicates that screen-sharing video streams have been paused
    - `all` : Indicates that all stream have been paused. 

#### Example

```js
meeting.listeners.onPausedAllStreams(kind: String)
```

---

### onResumedAllStreams()

- This callback is triggered when all or specified media streams within the meeting are successfully resumed
#### Event callback parameters
- **`kind`**: Specifies the type of media stream that was resumed.  
  - **Type**: `String`  
  - **Possible values**:
    - `"audio"`: Indicates that audio streams have been resumed.
    - `"video"`: Indicates that video streams have been resumed.
    - `"share"`: Indicates that screen-sharing video streams have been resumed
    - `all` : Indicates that all stream have been resumed. 

#### Example

```js
meeting.listeners.onResumedAllStreams(kind: String)
```
---
### mediaRelayReceived()

- This callback is triggered when a request is recieved for media relay in the destination meeting.

#### Parameters

- **`participantId - (String)`**: Specifies the participantId who requested the media relay.

- **`meetingId - (String)`**: Specifies the meeting from where the media relay request was made.

- **`displayName - (String)`**: Specifies the displayName of the participant who requested the media relay.

- **`accept - (Function)`**: Specifies the function to accept the media relay request.

- **`reject - (Function)`**: Specifies the function to reject the media relay request..

#### Example

```javascript
    meeting.listeners.onMediaRelayRequestReceived(participantId: String, meetingId: String, displayName: String, accept: @escaping () -> Void, reject: @escaping () -> Void)
```

---

### mediaRelayResponse()

- This callback is triggered when a response is recieved for media relay request in the source meeting.

#### Parameters

- **`decidedBy - (String)`**: Specifies the participantId who responded the request for the media relay.

- **`decision - (String)`**: Specifies the decision whether the request for media relay was accepted or not.


#### Example

```javascript
 meeting.listeners.onMediaRelayRequestResponse(decision: String, decidedBy: String, meetingId: String)
```

---

### mediaRelayStarted()

- This callback is triggered when the media relay to the destination meeting succesfully starts.

#### Parameters

- **`meetingId - (String)`**: Specifies the meeting where the media relay started.

#### Example

```javascript
   meeting.listeners.onMediaRelayStarted(meetingId: String)
```

---

### mediaRelayStopped()

- This callback is triggered when the media relay to the destination meeting stops for any reason.

#### Parameters

- **`meetingId - (String)`**: Specifies the meeting where the media relay stopped.

- **`reason - (String)`**: Specifies the reason why the media relay stopped

#### Example

```javascript
   meeting.listeners.onMediaRelayStopped(meetingId: String)
```

---

### mediaRelayError()

- This callback is triggered when an error occurs during media relay to the destination meeting.

#### Parameters

- **`meetingId - (String)`**: Specifies the meeting where the media relay stopped.

- **`reason - (String)`**: Specifies the reason why the media relay stopped

#### Example

```javascript
 meeting.listeners.onMediaRealyError(meetingId: String, error: String)
```

---

### onQualityLimitation(type: QualityLimitationType, state: QualityLimitationState, timestamp: String)

- This callback is enables detection of bandwidth, network congestion, or CPU limitations during a meeting, helping monitor local call quality in real time.

#### Parameters

- **`type - (QualityLimitationType)`**: Specifies type of quality limitation reason from below enum values:
    -  `CONGESTION`, `BANDWIDTH` & `CPU`

- **`state - (QualityLimitationState)`**: Specifies the state of quality limitation from below enum values:
    - `DETECTED` & `RESOLVED`

- **`timestamp - (String)`**: The time (in milliseconds since epoch) when the event occurred.
    

#### Example

```javascript
 meeting.listeners.onQualityLimitation(type: type, state: state, timestamp: timestamp)
```

</div>


---

# Video SDK Meeting Class - iOS

<div class="sdk-api-ref">

## Introduction

The `Meeting` class includes properties, methods and events for managing a meeting, participants, video, audio and share streams, messaging and UI customization.





## Meeting Properties

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [id](./properties#id)

</div>
<div class="col col--4 margin-bottom--sm" >

- [localParticipant](./properties#localparticipant)

</div>
<div class="col col--4 margin-bottom--sm" >

- [participants](./properties#participants)

</div>
<div class="col col--4 margin-bottom--sm" >

- [pubsub](./pubsub)

</div>
<div class="col col--4 margin-bottom--sm" >

- [LeaveReason Enum](./properties#leavereason-enum)

</div>
<div class="col col--4 margin-bottom--sm" >

- [listeners](./properties#listeners)

</div>

<div class="col col--4 margin-bottom--sm" >

- [meetingState](./properties#meetingstate)

</div>

<div class="col col--4 margin-bottom--sm" >

- [hlsUrls](./properties#hlsurls)

</div>
<div class="col col--4 margin-bottom--sm" >

- [hlsState](./properties#hlsstate)

</div>
<div class="col col--4 margin-bottom--sm" >

- [liveStreamState](./properties#livestreamstate)

</div>
<div class="col col--4 margin-bottom--sm" >

- [recordingState](./properties#recordingstate)

</div>
<div class="col col--4 margin-bottom--sm" >

- [transcriptionState](./properties#transcriptionstate)

</div>

</div>

## Meeting Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [join](./methods#join)

</div>
<div class="col col--4 margin-bottom--sm" >

- [leave](./methods#leave)

</div>
<div class="col col--4 margin-bottom--sm" >

- [end](./methods#end)

</div>
<div class="col col--4 margin-bottom--sm" >

- [enableWebcam](./methods#enablewebcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disableWebcam](./methods#disablewebcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [switchWebcam](./methods#switchwebcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [unmuteMic](./methods#unmutemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [muteMic](./methods#mutemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startRecording](./methods#startrecording)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopRecording](./methods#stoprecording)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startLiveStream](./methods#startlivestream)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopLiveStream](./methods#stoplivestream)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startHLS](./methods#starthls)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopHLS](./methods#stophls)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startTranscription](./methods#starttranscription)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopTranscription](./methods#stoptranscription)

</div>
<div class="col col--4 margin-bottom--sm" >

- [enableScreenShare](./methods#enablescreenshare)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disableScreenShare](./methods#disablescreenshare)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getMics](./methods#getmics)

</div>
<div class="col col--4 margin-bottom--sm" >

- [changeMic](./methods#changemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [requestMediaRelay](./methods#requestmediarelay)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopMediaRelay](./methods#stopmediarelay)

</div>
<div class="col col--4 margin-bottom--sm" >

- [switchTo](./methods#switchto)

</div>
<div class="col col--4 margin-bottom--sm" >

- [uploadBase64File](./methods#uploadbase64file)

</div>
<div class="col col--4 margin-bottom--sm" >

- [fetchBase64File](./methods#fetchbase64file)

</div>
<div class="col col--4 margin-bottom--sm" >

- [setVideoProcessor](./methods#setvideoprocessor)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startWhiteboard](./methods#startwhiteboard)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopWhiteboard](./methods#stopwhiteboard)

</div>

<div class="col col--4 margin-bottom--sm" >

- [pauseAllStreams](./methods#pauseallstreams)

</div>
<div class="col col--4 margin-bottom--sm" >

- [resumeAllStreams](./methods#resumeallstreams)

</div>

</div>

## Meeting Events

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [onMeetingJoined](./events#onmeetingjoined)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onMeetingLeft](./events#onmeetingleft)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onParticipantJoined](./events#onparticipantjoined)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onParticipantLeft](./events#onparticipantleft)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onSpeakerChanged](./events#onspeakerchanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onMicRequested](./events#onmicrequested)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onWebcamRequested](./events#onwebcamrequested)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onRecordingStateChanged](./events#onrecordingstatechanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onRecordingStarted](./events#onrecordingstarted)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onRecordingStopped](./events#onrecordingstopped)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onLivestreamStateChanged](./events#onlivestreamstatechanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onLivestreamStarted](./events#onlivestreamstarted)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onLivestreamStopped](./events#onlivestreamstopped)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onHlsStateChanged](./events#onhlsstatechanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onTranscriptionStateChanged](./events#ontranscriptionstatechanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onTranscriptionText](./events#ontranscriptiontext)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onMeetingStateChanged](./events#onmeetingstatechanged)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onError](./events#onerror)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onPinStateChanged](./events#onpinstatechanged)

</div>

<div class="col col--4 margin-bottom--sm" >

- [onParticipantModeChanged](./events#onparticipantmodechanged)

</div>

<div class="col col--4 margin-bottom--sm" >

- [onMicChanged](./events#onparticipantmodechanged)

</div>

<div class="col col--4 margin-bottom--sm" >

- [onWhiteboardStarted](./events#onwhiteboardstarted)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onWhiteboardStopped](./events#onwhiteboardstopped)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onPauseAllStreams](./events#onPausedAllStreams)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onResumeAllStreams](./events#onResumedAllStreams)

</div>

<div class="col col--4 margin-bottom--sm" >

- [mediaRelayReceived](./events#mediarelayreceived)

</div>

<div class="col col--4 margin-bottom--sm" >

- [mediaRelayResponse](./events#mediarelayresponse)

</div>

<div class="col col--4 margin-bottom--sm" >

- [mediaRelayStarted](./events#mediarelaystarted)

</div>
<div class="col col--4 margin-bottom--sm" >

- [mediaRelayStopped](./events#mediarelaystopped)

</div>
<div class="col col--4 margin-bottom--sm" >

- [mediaRelayError](./events#mediarelayerror)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onQualityLimitation](./events#onqualitylimitationtype-qualitylimitationtype-state-qualitylimitationstate-timestamp-string)

</div>

</div>

</div>


---



---

# Meeting Class Methods - iOS

<div class="sdk-api-ref-only-h4">

### join()

- It is used to join a meeting.
- After meeting initialization by [`initMeeting()`](../initMeeting) it returns a new instance of [Meeting](./introduction). However by default, it will not automatically join the meeting. Hence, to join the meeting you should call `join()`.

#### Events associated with `join()`:

- Local Participant will receive a [`onMeetingJoined`](./events#onmeetingjoined) event, when successfully joined.
- Remote Participant will receive a [`addParticipant`] event with the newly joined [`Participant`](../participant-class/introduction) object from the event callback.

#### Returns

- _`void`_

---

### leave()

- It is used to leave the current meeting.

#### Events associated with `leave()`:

- Local participant will receive a [`onMeetingLeft`](./events#onmeetingleft) event.
- All remote participants will receive a [`onParticipantLeft`](./events#onparticipantleft) event with `participantId`.

#### Returns

- _`void`_

---

### end()

- It is used to end the current running session.
- By calling `end()`, all joined [participants](./properties#participants) including [localParticipant](./properties#localparticipant) of that session will leave the meeting.

#### Events associated with `end()`:

- All [participants](./properties#participants) and [localParticipant](./properties#localparticipant), will be emitted [`closeRoom`] event.

#### Returns

- _`void`_

---

### enableWebcam()

- It is used to enable self camera.
- [`onStreamEnabled`](../participant-class/events#onstreamenabled) event will be emitted with [`stream`](../stream-class/introduction) object from the event callback, inside that [participant](../participant-class/introduction) object.

#### Returns

- _`void`_

---

### disableWebcam()

- It is used to enable self camera.
- [`onStreamDisabled`](../participant-class/events#onstreamdisabled) event will be emitted with [`stream`](../stream-class/introduction) object from the event callback, inside that [participant](../participant-class/introduction) object.

#### Returns

- _`void`_

---

### switchWebcam()

- It is used to switch between front and back camera.

#### Returns

- _`void`_

---

### unmuteMic()

- It is used to enable self microphone.
- [`onStreamEnabled`](../participant-class/events#onstreamenabled) event will be emitted with [`stream`](../stream-class/introduction) object from the event callback, inside that [participant](../participant-class/introduction) object.

#### Returns

- _`void`_

---

### muteMic()

- It is used to disable self microphone.
- [`onStreamDisabled`](../participant-class/events#onstreamdisabled) event will be emitted with [`stream`](../stream-class/introduction) object from the event callback, inside that [participant](../participant-class/introduction) object.

#### Returns

- _`void`_

---

### startRecording()

- It is used to start meeting recording.
- All [participants](./properties#participants) and [localParticipant](./properties#localparticipant), will receive [`onRecordingStarted`](./events#onrecordingstarted) event.

- `webhookUrl` will be triggered when the recording is completed and stored into server. Read more about webhooks [here](https://en.wikipedia.org/wiki/Webhook).

#### Parameters

- **webhookUrl**: String

- **awsDirPath**: String?

- **config**:

  - **layout**:
    - **type**: _"GRID"_ | _"SPOTLIGHT"_ | _"SIDEBAR"_
    - **priority**: _"SPEAKER"_ | _"PIN"_
    - **gridSize**: Number _\`max 4\`_
  - **theme**: _"DARK"_ | _"LIGHT"_ | _"DEFAULT"_
  - **mode**: _"video-and-audio"_ | _"audio"_
  - **quality**: _"low"_ | _"med"_ | _"high"_
  - **orientation**: _"landscape"_ | _"portrait"_

- **transcription**: **PostTranscriptionConfig?**
  - **PostTranscriptionConfig.enabled**: Bool
  - **PostTranscriptionConfig.summary**: SummaryConfig?
    - **SummaryConfig.enabled**: Bool
    - **SummaryConfig.prompt**: String

#### Returns

- _`void`_

#### Example

```js
let webhookUrl = "https://webhook.your-api-server.com"

let awsDirPath = "/meeting-recordings/"

let config: RecordingConfig = RecordingConfig(
                                layout: ConfigLayout(
                                  type: .GRID,
                                  priority: .PIN,
                                  gridSize: 4
                                ),
                                theme: .DARK,
                                mode: .video_and_audio,
                                quality: .med,
                                orientation: .landscape
                              )

let transcription: PostTranscriptionConfig =  PostTranscriptionConfig(
            enabled: true,
            summary: SummaryConfig(
                  enabled: true,
                  prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
        )
)

startRecording(webhookUrl: webhookUrl!, awsDirPath: awsDirPath, config: config, transcription: transcription)
```

---

### stopRecording()

- It is used to stop meeting recording.
- All [participants](./properties#participants) and [localParticipant](./properties#localparticipant), will receive [`onRecordingStopped`](./events#onrecordingstopped) event.

#### Returns

- _`void`_

#### Example

```js
stopRecording();
```

---

### startLivestream()

- It is used to start meeting livestreaming.
- You will be able to start live stream meetings to other platforms such as Youtube, Facebook, etc. that support `RTMP` streaming.
- All [participants](./properties#participants) and [localParticipant](./properties#localparticipant), will receive [`onLivestreamStarted`](./events#onlivestreamstarted) event.

#### Parameters

- **outputs**: `[LivestreamOutput]`

#### Returns

- _`void`_

---

#### Example

```js

startLivestream(outputs: outputs)
```

### stopLivestream()

- It is used to stop meeting livestreaming.
- All [participants](./properties#participants) and [localParticipant](./properties#localparticipant), will receive [`onLivestreamStopped`](./events#onlivestreamstopped) event.

#### Returns

- _`void`_

#### Example

```js
stopLivestream();
```

---

### startHLS()

- `startHLS()` will start HLS streaming of your meeting.

- You will be able to start HLS and watch the live stream of meeting over HLS.

- `mode` is used to either start hls streaming of video-and-audio both or only audio. And by default it will be video-and-audio.

- `quality` is only applicable to video-and-audio.

#### Parameters

- **config**:

  - **layout**:
    - **type**: _.GRID_ | _.SPOTLIGHT_ | _.SIDEBAR_
    - **priority**: _.SPEAKER_ | _.PIN_
    - **gridSize**: Number _`max 25`_
  - **theme**: _.DARK_ | _.LIGHT_ | _.DEFAULT_
  - **mode**: _.video_and_audio_ | _.audio_
  - **quality**: _.low_ | _.med_ | _.high_

- **transcription**: **PostTranscriptionConfig?**
  - **PostTranscriptionConfig.enabled**: Bool
  - **PostTranscriptionConfig.summary**: SummaryConfig?
    - **SummaryConfig.enabled**: Bool
    - **SummaryConfig.prompt**: String

#### Returns

- _`void`_

#### Example

```js
var config: HLSConfig = HLSConfig(
                          layout: ConfigLayout(
                            type: .GRID,
                            priority: .SPEAKER,
                            gridSize: 4
                          ),
                          theme: .DARK,
                          mode: .video_and_audio,
                          quality: .high,
                          orientation: .portrait
                        )

let transcription: PostTranscriptionConfig =  PostTranscriptionConfig(
            enabled: true,
            summary: SummaryConfig(
                  enabled: true,
                  prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
        )
)

startHLS(config: config, transcription: transcription)
```

---

### stopHLS()

- `stopHLS()` is used to stop the HLS streaming.

#### Returns

- _`void`_

#### Example

```js
stopHLS();
```

---

### startTranscription()

- It is used to start realtime transcription.
- All [participants](../participant-class/introduction.md) and [localParticipant](../participant-class/introduction.md), will receive [`TRANSCRIPTION_STARTING`](./events.md#ontranscriptionstatechanged) event state and [`onTranscriptionText`](./events.md#ontranscriptiontext) event.

- `config: TranscriptionConfig: webhookUrl` will be triggered when the state of realtime transcription is changed. Read more about webhooks [here](https://en.wikipedia.org/wiki/Webhook).

- `config: TranscriptionConfig: summary : SummaryConfig` Set summary config for the transcription.

  - `SummaryConfig: enabled` indicates whether to generate summary when meeting ends.
  - `SummaryConfig: prompt` the specific prompt around which summary is to be written.

#### Parameters

- **config**: **TranscriptionConfig?**
  - **TranscriptionConfig.webhookUrl**: String?
  - **TranscriptionConfig.summary**: SummaryConfig?
    - **SummaryConfig.enabled**: Bool
    - **SummaryConfig.prompt**: String

#### Returns

- _`void`_

#### Example

```javascript
let config =  TranscriptionConfig(
        webHookUrl: "YOUR_WEBHOOK_URL",
        summary: SummaryConfig(
          enabled: true,
          prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
        )
)

startTranscription(config);
```

---

### stopTranscription()

- It is used to stop realtime transcription.
- All [participants](../participant-class/introduction.md) and [localParticipant](../participant-class/introduction.md), will receive [`TRANSCRIPTION_STOPPING`](./events.md#ontranscriptionstatechanged) event state.

#### Returns

- _`void`_

#### Example

```javascript
stopTranscription();
```

---

### changeMode()

- `changeMode()` is used to change the mode of participant.

#### Parameters

- **mode**: Mode
  - All available participant modes are `SEND_AND_RECV`, `SIGNALLING_ONLY` and `RECV_ONLY`.




#### Events associated with `changeMode()`:

- Every participant will receive a callback of state change of mode [`onParticipantModeChanged`](./events#onparticipantmodechanged)

#### Returns

- _`void`_

#### Example

```js
changeMode(.SIGNALLING_ONLY | .SEND_AND_RECV)
```

---

### enableScreenShare()

- `enableScreenShare()` is used to share your local screen to the remote participants in the meeting.

#### Returns

- _`void`_

#### Example

```js
Task {
  await meeting.enableScreenShare()
}
```

---

### disableScreenShare()

- `disableScreenShare()` is used to stop sharing your local screen.

#### Returns

- _`void`_

#### Example

```js
Task {
  await meeting.disableScreenShare()
}
```

---

### getMics()

- `getMics` method will return an array of tuples, where each tuple consists of two elements deviceName and deviceType.

#### Returns

- _`[deviceName: String, deviceType: String]`_

#### Example

```js
meeting.getMics();
// sample returned array
// [("Speaker","Speaker"), ("iPhone Microphone", "Receiver")]
```

---

### changeMic()

- `changeMic` method will return an array of tuples, where each tuple consists of two elements deviceName and deviceType.

#### Parameters

- **selectedDevice**: String
  - Here selectedDevice should be the exact string of the `deviceName` that you get after calling the `getMics` method.

#### Returns

- _`void`_

#### Example

```js
meeting.changeMic(selectedDevice: "Speaker")
```

---

### uploadBase64File()

- `uploadBase64File` method uploads a file to VideoSDK's temporary storage and returns the corresponding URL string to retrieve the file from the storage system.

#### Parameters

- **base64Data**: String
  - The Base64 encoded string of the file to be uploaded.
- **token**: String
  - The authentication token required to access VideoSDK's storage system.
- **fileName**: String
  - The name under which the file will be stored.
- **completion**: @escaping (String?) -> Void
  - A closure that will be called with the URL string of the uploaded file or `nil` if the upload fails.

#### Returns

- _`void`_

#### Example

```js
  let base64Data: String = "<Your-base64-File>"
  let token: String = "<Your-Token>"
  let fileName: String = "name.jpeg" // Provide file name with extension
//highlight-start
  meeting.uploadBase64File(base64Data: base64Data, token: token, fileName: fileName) { url in
        print("url: ", url)
    }
//highlight-end
```

---

### fetchBase64File()

- `fetchBase64File` method retrieves a file from VideoSDK's temporary storage and returns it in the form of a Base64 String.

#### Parameters

- **url**: String
  - The URL string of the file to be retrieved.
- **token**: String
  - The authentication token required to access VideoSDK's storage system.
- **completion**: @escaping (String?) -> Void
  - A closure that will be called with the Base64 string of the retrieved file or `nil` if the retrieval fails.

#### Returns

- _`void`_

#### Example

```js
  let url: String = "<Your FileUrl>" // Provide fileUrl which is returned by uploadBase64File()
  let token: String = "<Your-Token>"
//highlight-start
 meeting.fetchBase64File(url: url, token: token) { base64Data in
        print("base64: ", base64Data)
  }
  //highlight-end
```

---

### setVideoProcessor()

- `setVideoProcessor` method sets the processor that will be used in processing the local video frames.

#### Parameters

- **processor**: `VideoSDKVideoProcessor`?
  - An instance of a processor class that conforms to the `VideoSDKVideoProcessor` protocol.

#### Returns

- _`void`_

#### Example

```js
  let backgroundSource = URL(string: "https://cdn.videosdk.live/virtual-background/cloud.jpeg")!
  let processor = VideoSDKBackgroundProcessor(backgroundSource: backgroundSource)
  //highlight-next-line
  meeting.setVideoProcessor(processor: processor)
```

---

### startWhiteboard()

- `startWhiteboard` method starts the whiteboard session.

- All [participants](./properties#participants) and [localParticipant](./properties#localparticipant), will receive [`onWhiteboardStarted`](./events#onwhiteboardstarted) event along with the url of the whiteboard.

#### Returns

- _`void`_

#### Example

```js
meeting.startWhiteboard();
```

---

### stopWhiteboard()

- `stopWhiteboard` method stops the whiteboard session.

- All [participants](./properties#participants) and [localParticipant](./properties#localparticipant), will receive [`onWhiteboardStopped`](./events#onwhiteboardstopped) event.

#### Returns

- _`void`_

#### Example

```js
meeting.stopWhiteboard();
```

---

### pauseAllStreams()

- The `pauseAllStreams` method pauses active media streams within the meeting.

- Specifies the type of media stream to be paused. If this parameter is provided, only that particular type of media stream will be paused. Otherwise, by default, all media streams (audio, video, and screen share) will be paused. 

#### Returns

- _`void`_

#### Example

```js
meeting.pauseAllStreams(kind: "video");
```

---

### resumeAllStreams()

- `resumeAllStreams`  method resumes media streams that have been paused.

- Specifies the type of media stream to be resumed. If this parameter is provided, only that particular type of media stream will be resumed. Otherwise, by default, all media streams (audio, video, and screen share) will be resumed.

#### Returns

- _`void`_

#### Example

```js
meeting.resumeAllStreams(kind: "video");
```

</div>

---

### requestMediaRelay()

This method starts relaying selected media streams (like camera video, microphone audio, screen share, etc.) from the current meeting to a specified destination meeting.

#### Parameters

- **MeetingId (String) – Required**: ID of the target meeting where media should be relayed.

- **token (String) – Optional**: Authentication token for the destination meeting.

- **kinds (List of Strings) – Optional**: Array of media types to relay. 
  - Possible values:
    - `"audio"`: Resumes audio streams.
    - `"video"`: Resumes video streams.
    - `"share"`:Resumes screen-sharing video streams.
    - `"share_audio"`:Resumes screen-sharing audio streams.

#### Returns

- _`void`_

#### Example

```js
meeting.requestMediaRelay(meetingId: "", token: "")
```
---

### stopMediaRelay()
This method stops the ongoing media relay to a specific destination meeting.

#### Parameters

- **MeetingId (String) – Required**: ID of the destination meeting where the media relay should be stopped.

#### Returns

- _`void`_

#### Example

```js
meeting.stopMediaRelay(meetingId: "")
```

---

### switchTo()

This method enables a seamless transition from the current meeting to another, without needing to disconnect and reconnect manually.

#### Parameters

- **meetingId (String) – Required**: ID of the new meeting to switch to.

- **token (String) – Optional**: Authentication token for the new meeting.

#### Returns

- _`void`_

#### Example

```js
meeting?.switchToMeeting(meetingId: "", token: "")
```
--- 

---

# Meeting Class Properties - iOS

<div class="sdk-api-ref-only-h4">

### id

- type: `String`

- Unique id of the meeting where the participant has joined.

---

### localParticipant

- type: [Participant](../participant-class/introduction)

- It will be the instance of [Participant](../participant-class/introduction) class for the local participant(You) who joined the meeting.

---

### participants

- type: [`[Dictionary]`](https://developer.apple.com/documentation/swift/dictionary) of [Participant](../participant-class/introduction)

- [`String`: `Participant`]

  - [`participantId`, `Participant`]

- It will contain all joined participants in the meeting except the `localParticipant`.

- This will be the [`[Dictionary]`](https://developer.apple.com/documentation/swift/dictionary) what will container all participants attached with the key as id of that participant.

```js
let remoteParticipantId = "ajf897";

let remoteParticipant = participants[remoteParticipantId];
```

---

### meetingState

- type : `MeetingState`
- `MeetingState` will be the current state of the meeting.

---

### hlsUrls

- type : `HLSUrl`
  - **playbackHlsUrl**: `String`
  - **livestreamUrl**: `String`
- `hlsUrls` will proide all the URLs for the ongoing meeting HLS.

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

---

### hlsState

- type : `HLSState`
- `HLSState` will be the current state of the meeting HLS.

---

### liveStreamState

- type : `LiveStreamState`
- `LiveStreamState` will be the current state of the liveStream.

---

### recordingState

- type : `RecordingState`
- `RecordingState` will be the current state of the recording.

---

### `LeaveReason` Enum

The `LeaveReason` enum provides detailed context for why a meeting or participant departure event was triggered. The following table lists all possible values:

| Code | Reason | Description |
| :--- | :--- | :--- |
| 1001 | `websocketDisconnected` | Socket disconnected. |
| 1002 | `removePeer` | Participant was removed from the meeting. |
| 1003 | `removePeerViewerModeChanged` | Participant Removed because viewer mode was changed. |
| 1004 | `removePeerMediaRelayStop` | Participant Removed because media relay was stopped. |
| 1005 | `switchRoom` | Participant switched to a different room. |
| 1006 | `roomClose` | The meeting has been closed. |
| 1007 | `unknown` | Participant disconnected due to an unknown reason. |
| 1008 | `removeAll` | Remove All from the meeting. |
| 1009 | `meetingEndApi` | Meeting Ended. |
| 1010 | `removePeerApi` | Participant removed from the meeting. |
| 1011 | `duplicateParticipant` | Leaving meeting, since this 'participantId' joined from another device. |
| 1101 | `manualLeaveCalled` | Participant manually called the leave() method to exit the meeting. |
| 1102 | `websocketConnectionAttemptsExhausted` | Meeting left after multiple failed websocket connection attempts. |
| 1103 | `joinRoomFailed` | Meeting left due to an error while joining the room. |
| 1104 | `switchRoomFailed` | Meeting left due to an error while switching rooms. |

---

### listeners

- type: `MeetingMulticastDelegate`

- It will listens the events of [Meeting](./introduction) class for the local participant who joined the meeting.

### transcriptionState

- type: `TranscriptionState`

- It gives the current state of transcription in the meeting, initially it is `TRANSCRIPTION_STOPPED`.

</div>


---

# PubSub - iOS

- `PubSub` one of the properties of a [Meeting Class](../meeting-class/introduction.md) is used for messaging purpose for an ongoing meeting

<div class="sdk-api-ref-only-h4">

## Methods

### publish()

- `publish()` is used to publish messages on a specified topic in the meeting.
- While publishing message, if you provide `persist` as `true`, then it will persist the message throughout the meeting and newly joined participant will get all old messages of a meeting, otherwise not.

#### Parameters

- topic :

  - type : `String`
  - Participants can deliver messages to that particular topic.

- message :

  - type: `String`
  - Any arbitrary message you want to publish.

- options :
  - type : `[String: Any]`
  - specifies the options for the message.

- payload :
  - type : `[String: Any]?`
  - specifies the payload for the message.

#### Returns

- `void`

#### Example

```swift
//write this block on btnClick event
do {
    try await meeting.pubsub.publish(
        topic: topic,
        message: text,
        options: ["persist": true],
        payload: ["sender": meeting.localParticipant.displayName, "messageType": "text"]
    )
} catch {
    print("Error while sending message: \(error.localizedDescription)")
}
```

---

### subscribe()

- `subscribe()` is used to subscribe a particular topic to get all the messages of that particular topic in the meeting.

#### Parameters

- topic :

  - type : `String`
  - Participants can listen to messages on that particular topic.

- forListener :
  - type : `PubSubMessageListener`
  - in this listener, you will get `callback` for subscribe the topic, which contains [Pubsub message data](#pubsub-message-data)

#### Returns

- This will return old messages for this topic, if you passed `persist` to `true` while [publish](#publish)

- Array{'<'}[message](#pubsub-message-data)>

#### Example

```js
//subscribing messages on topic CHAT
meeting.pubsub.subscribe(topic: "CHAT", forListener: self)
```

---

### unsubscribe()

- `unsubscribe()` is used to unsubscribe a particular topic on which you have subscribed priviously.

#### Parameters

- topic :

  - type : `String`

- forListener :
  - type : `PubSubMessageListener`
  - in this listener, you will get `callback` for unsubscribe the topic.

#### Returns

- `void`

#### Example

```js
//unsubscribing messages on topic CHAT
meeting.pubSub.unsubscribe("CHAT");
```

---

### getMessagesForTopic()

- `getMessagesForTopic()` is used to retrieve messages for specified topic which are `persisted`.

#### Parameters

- topic :

  - type : `String`

#### Returns

- `[PubSubMessage]`

#### Example

```js
//getting all the messages of topic CHAT
let messages = meeting.pubSub.getMessagesForTopic("CHAT");
```

## Pubsub message data

### id

- type : `String`

- Unique id of the message.

### message

- type : `String`

- Message that has been published on the specific topic.

### senderId

- type : `String`

- id of a sender who has published this message.

### senderName

- type : `String`

- Name of a sender who has published this message.

### timesatmp

- type : `DateTime`

- Timestamp of when a message has been published.

### topic

- type : `String`

- Name of the topic.

### payload

- type : `[String: Any]`

- Payload of the message for providing addition information.

---

</div>


---

# RealtimeStore – iOS

The `RealtimeStore`, a property of the `Meeting` class, allows you to **set**, **get**, and **listen** to value changes for specific keys shared across all participants in a meeting.

It provides a simple key–value storage system that stays synchronized in real time among all connected participants.

---

## Methods

### `set()`

The `set()` method is used to store or update data in the Realtime Store. If a key already exists, it will be overwritten with the new value. Passing `nil` as the value deletes the key.

#### Parameters

- **`key`** (`String`) – The unique key under which the data will be stored.
- **`value`** (`String?`) – The value to be stored. Pass `nil` to delete the key.

#### Throws
- An error if:
   - Key is missing or not of type `String`.
   - Payload size exceeds 1 KB per key.
   - Session exceeds the 100-key limit.
   - Request fails due to network or internal issues.

#### Example

```swift
let REALTIME_STORE_KEY = "Blocked_Students"
Task {
    do {
        try await meeting.realtimeStore.set(key: REALTIME_STORE_KEY, value: "[Deep, Lily]")
        print("Data set successfully!")
    } catch {
        print("Failed to set data: \(error.localizedDescription)")
    }
}
```

---

### `get()`

The `get()` method retrieves the current value associated with a given key from the Realtime Store.

#### Parameters

- **`key`** (`String`) – The key whose value you want to retrieve.

#### Returns

- **`String?`** — The stored value, or `nil` if the key does not exist.

#### Throws
- An error if:
   - Key is missing or not of type `String`.
   - Request fails due to network or internal issues.

#### Example

```swift
let REALTIME_STORE_KEY = "Blocked_Students"
Task {
    do {
        let value = try await meeting.realtimeStore.get(key: REALTIME_STORE_KEY)
        let displayValue = value ?? "nil (key not found)"
        print("Current value: \(displayValue)")
    } catch {
        print("Failed to get data: \(error.localizedDescription)")
    }
}
```

---

### `observe()`

The `observe()` method subscribes to real-time updates for a given key. When the value of that key changes, the delegate method on your listener is triggered automatically for all participants.

#### Parameters

- **`key`** (`String`) – The key to observe for changes.
- **`forListener`** (`RealtimeStoreListener`) – An object that conforms to the `RealtimeStoreListener` protocol.

#### Throws
- An error if the observer could not be set up.

#### Example
First, conform to the `RealtimeStoreListener` protocol:
```swift
extension MeetingViewController: RealtimeStoreListener {
    func onValueChanged(key: String, value: String?, updatedBy: String) {
        print("RealtimeStore Value Changed - Key: \(key), Value: \(value ?? "nil"), UpdatedBy: \(updatedBy)")
    }
}
```

Then, start observing:
```swift
let REALTIME_STORE_KEY = "Blocked_Students"
Task {
    do {
        try await meeting.realtimeStore.observe(key: REALTIME_STORE_KEY, forListener: self)
        print("Started observing key successfully!")
    } catch {
        print("Failed to observe key: \(error.localizedDescription)")
    }
}
```

---

### `stopObserving()`

The `stopObserving()` method stops receiving updates for a previously observed key for a specific listener.

#### Parameters

- **`key`** (`String`) – The key to stop observing.
- **`forListener`** (`RealtimeStoreListener`) – The listener to remove.

#### Throws
- An error if it fails to stop observing.

#### Example

```swift
let REALTIME_STORE_KEY = "Blocked_Students"
Task {
    do {
        try await meeting.realtimeStore.stopObserving(key: REALTIME_STORE_KEY, forListener: self)
        print("Stopped observing successfully!")
    } catch {
        print("Failed to stop observing: \(error.localizedDescription)")
    }
}
```

---

---

# Participant Class Events - iOS

<div class="sdk-api-ref-only-h4">

### onStreamEnabled

- `onStreamEnabled` is a callback which gets triggered whenever a participant's video, audio or screen share stream is enabled.

#### Example

```js
participantListener.onStreamEnabled(stream: `MediaStream`, forParticipant: `Participant`) {
  //
}
```

---

### onStreamDisabled

- `onStreamDisabled` is a callback which gets triggered whenever a participant's video, audio or screen share stream is disabled.

#### Example

```js
participantListener.onStreamDisabled  (stream: `MediaStream`, forParticipant: `Participant`) {
  //
}
```

</div>


---

# Video SDK Participant Class - iOS

<div class="sdk-api-ref">





Participant class includes all the properties, methods and events related to all the participants joined in a particular meeting.

## Get local and remote participants

You can get the local streams and participant meta from meeting.localParticipant. And a Map of joined participants is always available via meeting.participants.

```js
let localParticipant = meeting.localParticipant;
let participants = meeting.participants;
```

## Participant Properties

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [id](./properties#id)

</div>
<div class="col col--4 margin-bottom--sm" >

- [displayName](./properties#displayname)

</div>
<div class="col col--4 margin-bottom--sm" >

- [videoQuality](./properties#videoquality)

</div>
<div class="col col--4 margin-bottom--sm" >

- [isLocal](./properties#islocal)

</div>
<div class="col col--4 margin-bottom--sm" >

- [streams](./properties#streams)

</div>

</div>

## Participant Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [enableWebcam](./methods#enablewebcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disableWebcam](./methods#disablewebcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [enableMic](./methods#enablemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disableMic](./methods#disablemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [setQuality](./methods#setquality)

</div>
<div class="col col--4 margin-bottom--sm" >

- [pin](./methods#pin)

</div>
<div class="col col--4 margin-bottom--sm" >

- [unpin](./methods#unpin)

</div>
<div class="col col--4 margin-bottom--sm" >

- [remove](./methods#remove)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getAudioStats](./methods#getaudiostats)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getVideoStats](./methods#getvideostats)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getShareStats](./methods#getsharestats)

</div>
<div class="col col--4 margin-bottom--sm" >

- [captureImage](./methods#captureimage)

</div>

</div>

## Participant Events

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [onStreamEnabled](./events#onstreamenabled)

</div>
<div class="col col--4 margin-bottom--sm" >

- [onStreamDisabled](./events#onstreamdisabled)

</div>

</div>

</div>


---

# Participant Class Methods - iOS

<div class="sdk-api-ref-only-h4">

### enableWebcam()

- `enableWebcam()` is used to enable webcam of participant.

#### Events associated with `enableWebcam()`:

- First the participant will get a callback on [`onWebcamRequested()`](../meeting-class/events#onwebcamrequested) and once the participant accepts the request, webcam will be enabled.

- Every Participant will receive a [`onStreamEnabled()`](./events#onstreamenabled) event with stream object.

#### Returns

- `void`

---

### disableWebcam()

- `disableWebcam()` is used to disable webcam of participant.

#### Events associated with `disableWebcam()`:

- Every Participant will receive a [`onStreamDisabled()`](./events#onstreamdisabled) event with stream object.

#### Returns

- `void`

---

### enableMic()

- `enableMic()` is used to enable mic of participant.

#### Events associated with `enableMic()`:

- First the participant will get a callback on [`onMicRequested()`](../meeting-class/events#onmicrequested) and once the participant accepts the request, mic will be enabled.

- Every Participant will receive a [`onStreamEnabled()`](./events#onstreamenabled) event with stream object.

#### Returns

- `void`

---

### disableMic()

- `disableMic()` is used to disable mic of participant.

#### Events associated with `disableMic()`:

- Every Participant will receive a [`onStreamDisabled()`](./events#onstreamdisabled) event with stream object.

#### Returns

- `void`

---

### setQuality()

- `setQuality()` is used to set the quality of the participant's video stream.

#### Parameters

- `quality`: VideoQuality ( low | medium | high )

#### Returns

- `void`

---

### remove()

- `remove()` is used to remove this participant.

#### Parameters

- `id`: `String`

#### Returns

- `void`

---

### pin()

- `pin()` is used to pin this participant.

#### Parameters

- `peerId`: `String`
- `pinType`: `PinType`

#### Returns

- `void`

---

### unpin()

- `unpin()` is used to unpin this participant.

#### Parameters

- `pinType`: `PinType`

#### Returns

- `void`

---

### getAudioStats()

- `getAudioStats()` will return an Dictionary which will contain details regarding the participant's critical audio metrics such as **Jitter**, **Packet Loss** etc.

#### Returns

- `Dictionary`
  - `jitter` : It represents the distortion in the stream.
  - `bitrate` : It represents the bitrate of the stream which is being transmitted.
  - `totalPackets` : It represents the total packet count which were transmitted for that particiular stream.
  - `packetsLost` : It represents the total packets lost during the transimission of the stream.
  - `rtt` : It represents the time between the stream being reached to client from the server in milliseconds(ms).
  - `codec`: It represents the codec used for the stream.
  - `network`: It represents the network used to transmit the stream

#### Returns

- `[String:Any]`

---

### getVideoStats()

- `getVideoStats()` will return an Dictionary which will contain details regarding the participant's critical video metrics such as **Jitter**, **Packet Loss** etc.

#### Returns

- `Dictionary`
  - `jitter` : It represents the distortion in the stream.
  - `bitrate` : It represents the bitrate of the stream which is being transmitted.
  - `totalPackets` : It represents the total packet count which were transmitted for that particiular stream.
  - `packetsLost` : It represents the total packets lost during the transimission of the stream.
  - `rtt` : It represents the time between the stream being reached to client from the server in milliseconds(ms).
  - `codec`: It represents the codec used for the stream.
  - `network`: It represents the network used to transmit the stream
  - `size`: It is object containing the height, width and frame rate of the stream.

#### Returns

- `[String:Any]`

---

### getShareStats()

- `getShareStats()` will return an Dictionary which will contain details regarding the participant's critical video metrics such as **Jitter**, **Packet Loss** etc.

#### Returns

- `Dictionary`
  - `jitter` : It represents the distortion in the stream.
  - `bitrate` : It represents the bitrate of the stream which is being transmitted.
  - `totalPackets` : It represents the total packet count which were transmitted for that particiular stream.
  - `packetsLost` : It represents the total packets lost during the transimission of the stream.
  - `rtt` : It represents the time between the stream being reached to client from the server in milliseconds(ms).
  - `codec`: It represents the codec used for the stream.
  - `network`: It represents the network used to transmit the stream
  - `size`: It is object containing the height, width and frame rate of the stream.

#### Returns

- `[String:Any]`

### captureImage()

- It is used to capture image of local participant's current videoStream.

#### Parameters

- `height` : `CGFloat` _(Optional)_
- `width` : `CGFloat` _(Optional)_
- **completion**: @escaping (String?) -> Void
  - A closure that will be called with the `base64` String of the captured image or `nil`if the capture fails.

#### Returns

- _`void`_

</div>


---

# Participant Class Properties - iOS

<div class="sdk-api-ref-only-h4">

### id

- type: `String`

- Unique id of the participant who has joined the meeting.

---

### displayName

- type: `String`

- It will be the `displayName` of the participant..

---

### videoQuality

- type: enum `VideoQuality`

- It will be the `videoQuality` of the participant.

---

### isLocal

- type: `Bool`

- It is the `status` of participant (is it remote or local?) who has the meeting.
- It will represents whether the participant is [`LocalParticipant`](../meeting-class/properties#localparticipant)(You) or not. If it is true, then participant is [`LocalParticipant`](../meeting-class/properties#localparticipant) otherwise RemoteParticipant.

---

### streams

- type: `[String: MediaStream]`

- It will represents the stream for that particular participant who has joined the meeting. Streams could be `audio` , `video` or `share`.

---

### pinState

- type: `ParticipantPinState`

- It will represents the state for that particular participant who has joined the meeting.

---

### mode

- type: `Mode`

- It will represents the mode for that particular participant who has joined the meeting. modes could be `SIGNALLING_ONLY` or `SEND_AND_RECV`.

</div>


---

# Setup - iOS

## Setting up iOS sdk

IOS SDK is client for real-time communication for ios devices. It inherits the same terminology as all other SDKs does.

## Minimum OS/SDK versions

It supports the following OS/SDK versions.

- IOS 13.0+

## Installation

It requires `Xcode 12.0+` and `Swift 5.0+` installed.

### Step 1: To integrate VideoSDK into your Xcode project using CocoaPods, specify it in your `Podfile`:

```js title="Install via CocoaPods"
pod 'VideoSDKRTC'
```

OR

```js title="Install via Github"
pod 'VideoSDKRTC', :git => 'https://github.com/videosdk-live/videosdk-rtc-ios-sdk.git'
```

:::caution

- Currently this only supports IOS device (arm64). Running on simulator is not supported.
- You will need to set `Enable Bitcode` to `false`.

:::

### Step 2: Your app needs to add permissions to use microphone and camera. Add below code your app's `info.plist`

```js title="info.plist"
<key>NSCameraUsageDescription</key>
<string>Allow camera access to start video.</string>

<key>NSMicrophoneUsageDescription</key>
<string>Allow microphone access to start audio.</string>
```

### Step 3: To integrate VideoSDK into your Xcode project using CocoaPods, specify it in your `Podfile`:

```js title="Start using it in your project"
import VideoSDK

// Configure token, fetch it via auth API
VideoSDK.config(token: <server token here>)

// Intialize meeting
let meeting = VideoSDK.initMeeting(
    meetingId: <meetingId>,
    participantId: <participantId>, // optional
    participantName: <your name>,
    micEnabled: true,
    webcamEnabled: true)
```

:::info

Check ios SDK example for more information on [videosdk-rtc-ios-example](https://github.com/videosdk-live/videosdk-rtc-ios-sdk-example)

:::


---

# Stream Class Events - iOS

<div class="sdk-api-ref-only-h4">

---

### state

- This callback is triggered when the state of a video or screen-share video stream changes.
- It helps track whether the stream is active, stuck, frozen, resolved, or ended.

:::note
This event is emitted exclusively for remote participants, specifically for their video and screen share video streams.
:::

#### Parameters

- **`state`**: Specifies the current state of the stream.

  - **Type**: `MediaStreamEventType`
  - **Possible values**:
    - `MediaStreamEventType.ACTIVE`: Stream is working normally.
    - `MediaStreamEventType.STUCK`: Stream is not progressing as expected.
    - `MediaStreamEventType.FREEZE_DETECTED`: Video freeze has been detected.
    - `MediaStreamEventType.FREEZE_RESOLVED`: Video freeze has been resolved.
    - `MediaStreamEventType.ENDED`: Stream has ended.

#### Example

```swift
stream.on(.state) { state in
  
}
```

---

</div>


---

# Video SDK Stream Class - iOS

<div id="tailwind" class="sdk-api-ref">




Stream class is responsible for handling audio, video and screen sharing streams.

Stream class defines instance of audio, video and shared screen stream of participants.

## Stream Properties

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [id](./properties#id)

</div>
<div class="col col--4 margin-bottom--sm" >

- [kind](./properties#kind)

</div>
<div class="col col--4 margin-bottom--sm" >

- [track](./properties#track)

</div>

</div>

## Stream Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [resume](./methods#resume)

</div>
<div class="col col--4 margin-bottom--sm" >

- [pause](./methods#pause)

</div>

</div>

## Stream Events

<div class="row">

<div class="col col--4 margin-bottom--sm">

- [state](./events.md#state)

</div>

</div>

</div>


---

# Stream Class Methods - iOS

<div class="sdk-api-ref-only-h4">

### resume()

- By using `resume()`, a participant can resume the stream of Remote Participant.

#### Returns

- `void`

---

### pause()

- By using `pause()`, a participant can pause the stream of Remote Participant.

#### Returns

- `void`

</div>


---

# Stream Class Properties - iOS

<div class="sdk-api-ref-only-h4">

### id

- type: `String`

- Represents the id for that stream .

---

### kind

- type: `String`

- `kind` represents the type of stream which could be `audio` | `video` or `share` .

---

### track

- type: `MediaStreamTrack`

- It represents a single media track within a stream.

</div>


---

# Stream Class

## using Stream Class

The `Stream Class` includes methods and events video & audio streams.




### Properties


      
      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>


---

<h1> {props.title} </h1>{" "}

When integrating VideoSDK, you will come across with multiple terms like meeting, room, session and many more.

Let's discuss each term in detail so while integrating VideoSDK you don't get confused.

### Meeting / Room

- A Meeting or Room is a VideoSDK object which represents a real-time audio, video, and/or screen-share session, and is the basic building block for media sharing among participants which is returned by the VideoSDK once a successful connection is established.
- Meeting or Room can be uniquely identified by `meetingId` or `roomId`.

:::note
Meeting and Room are both the same. Similarly `meetingId` and `roomId` are same.
:::

### Session

- A Session is the instance of an ongoing meeting/room which has one or more participants in it. A single room or meeting can have multiple sessions.
- Each session can be uniquely identified by `sessionId`.
- All the sessions are associated with `meetingId`/`roomId` and can be listed using it.

### Participant

- Participant is a VideoSDK object which represents each user/client in the meeting or room and can share audio/video media with other.
- There can be multiple participants in a meeting/room and each participant can be uniquely identified by `participantId`.

### MediaStream

- MediaStream is the collection of audio and video tracks which holds the segments of audio/video media that are send and received by all the participants in the meeting.

### RTMP Live Stream

- RTMP live streaming is used to live stream your video conferencing apps to platforms like YouTube, Twitch, Facebook, etc. by providing the platform specific `streamKey` and `streamUrl`.

### Interactive Live streaming (HLS)

- Interactive live streaming is used to live stream your video conferencing apps within your own platform to allow a larger number of viewers who can not be accomodated in a real-time conference.



---

# VideoSDK Class - iOS

<div class="sdk-api-ref">

## Introduction

The `VideoSDK` class includes methods to set token, start meeting and methods for managing permissions and devices.





## VideoSDK Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [config](./methods#config)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getAudioPermissionStatus](./methods#getaudiopermissionstatus)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getVideoPermissionStatus](./methods#getvideopermissionstatus)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getAudioPermission](./methods#getaudiopermission)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getVideoPermission](./methods#getvideopermission)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getCameras](./methods#getcameras)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getAudioDevices](./methods#getaudiodevices)

</div>

</div>
</div>



---

# VideoSDK Class Methods - iOS

<div class="sdk-api-ref-only-h4">

### config()

- Before initializing the meeting, you will first need to provide `token`. By using `config()` method, you can set the token property of VideoSDK class. 
- Please refer this [documentation](/api-reference/realtime-communication/intro/) to generate a token.

#### Returns

- `void`

---

### getAudioPermissionStatus()

- Gives the status of Status for Audio Permission of your app.

#### Returns

- `authorisationStatus`

    - authorisationStatus: 
        - notDetermined
        - restricted
        - denied
        - authorised

#### Example

```js
VideoSDK.getAudioPermissionStatus()
```

---

### getVideoPermissionStatus()

- Gives the status of Status for Video Permission of your app.

#### Returns

- `authorisationStatus`
 
    - authorisationStatus: 
        - notDetermined
        - restricted
        - denied
        - authorised

#### Example

```js
VideoSDK.getVideoPermissionStatus()
```
---

### getAudioPermission()

- It prompts the system alert to access the microphone for your app.

- It will only prompt when the `authorisationStatus` for the audio permission is `notDetermined`.

- If the `authorisationStatus` is `restricted` or `denied`, you need to open settings using the `handlePermission` function of the `AuthorisationDelegate` protocol to manually approve the microphone permission. 

- Checkout our guide on how you can use `handlePermission` function to handle manual approval of permissions [here](/ios/guide/video-and-audio-calling-api-sdk/setup-call/precall)

#### Returns

- _`void`_

#### Example

```js
VideoSDK.getAudioPermission()
```

---

### getVideoPermission()

- It prompts the system alert to access the camera for your app.

- It will only prompt when the `authorisationStatus` for the audio permission is `notDetermined`.

- If the `authorisationStatus` is `restricted` or `denied`, you need to open settings using the `handlePermission` function of the `AuthorisationDelegate` protocol to manually approve the camera permission.

- Checkout our guide on how you can use `handlePermission` function to handle manual approval of permissions [here](/ios/guide/video-and-audio-calling-api-sdk/setup-call/precall)

#### Returns

- _`void`_

#### Example

```js
VideoSDK.getVideoPermission()
```

---

### getCameras()

- It gives a string array of available cameras.

#### Returns

- _`[String]`_

#### Example

```js
VideoSDK.getCameras()
    //Sample Output
    ["Front Camera", "BackCamera"]
```

---

### getAudioDevices()

- It gives a string array of available audio output devices.

#### Returns

- _`[String]`_

#### Example

```js
VideoSDK.getAudioDevices()
    //Sample Output
    ["Speaker", "iPhone Microphone"]
```


</div>


---

# VideoSDK Class - iOS

The entry point into real-time communication SDK.

## using VideoSDK Class

The `VideoSDK Class` includes methods and events to initialize and configure the SDK. It is a factory class.




### Methods


      
        
      </MethodListGroup>
      
        
         // Optional
        
        
        
      </MethodListGroup>
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>

## Example

```js title="Config and Init Example"
import VideoSDK

// Configure the token
VideoSDK.config(token: meetingData.token)

// Initialize the meeting
meeting = VideoSDK.initMeeting(
    meetingId: meetingData.meetingId,
    participantName: meetingData.name,
    micEnabled: meetingData.micEnabled,
    webcamEnabled: meetingData.cameraEnabled
)
```


---

# Developer Experience Guidelines - iOS

This section provides best practices for creating a smooth and efficient development process when working with VideoSDK. From handling errors gracefully to managing resources and event subscriptions, these guidelines help developers build more reliable and maintainable applications. Following these practices can simplify troubleshooting, prevent common pitfalls, and improve overall application performance.

## Initiate Key Features After Meeting Join Event

To provide a seamless and reliable meeting experience, initiate specific features **only** after the [onMeetingJoined()](https://docs.videosdk.live/ios/api/sdk-reference/meeting-class/events#onmeetingjoined) event has been triggered.

- **Trigger Key Actions After Joining the Meeting** : Initiating crucial actions after the `onMeetingJoined()` event helps avoid errors and optimizes the meeting setup, ensuring a smoother experience for participants. If your application utilizes any of the following features or you want to perform any action as soon as meeting joins, it's recommended to call them only after the meeting has successfully started:

    - `Chat Subscription`: To enable in-meeting chat functionality, subscribe to the chat topic after the `onMeetingJoined()` event is triggered. This ensures that messages are reliably received by participants.

    <br/>
    <div style={{textAlign: 'center'}}>

    <img src="https://cdn.videosdk.live/docs/best-practices/mobile/ios_chat_correct_incorrect_code.png" />

    </div>

    - `Device Management`: If you need users to use specific audio or video devices when the meeting is first joined, you can utilize the custom track. Pass the `cameraId` to the [createCameraVideoTrack()](https://docs.videosdk.live/ios/api/sdk-reference/custom-tracks#custom-video-track---ios) method for video, and the `microphoneId` to the [createAudioTrack()](https://docs.videosdk.live/ios/api/sdk-reference/custom-tracks#custom-audio-track) method for audio. Once the track is created, provide it to the [initMeeting()](https://docs.videosdk.live/ios/api/sdk-reference/initMeeting#initmeeting) method.

    - `Recording and Transcription`: To automatically start recording or transcription as soon as the meeting begins, configure the `autoStartConfig` in the `createMeeting` API. For detailed information, refer to the documentation [here](https://docs.videosdk.live/api-reference/realtime-communication/create-room#autoCloseConfig).




## Listen for Error Events

Listening to error events enables your application to handle unexpected issues efficiently, providing users with clear feedback and potential solutions. Error codes pinpoint specific problems, whether from configuration settings, account restrictions, permission limitations, or device constraints. Here are recommended solutions based on common error categories:

1. [Errors associated with Organization](../../api/sdk-reference/error-codes#1-errors-associated-with-token): If you encounter errors related to your organization (e.g., account status or participant limits), reach out to support at support@videosdk.live or reach out to us on [Discord](https://discord.com/invite/Qfm8j4YAUJ) for assistance.

2. [Errors associated with Token](../../api/sdk-reference/error-codes#2-errors-associated-with-token): For errors related to authentication tokens, ensure the token is valid and hasn’t expired, then try the request again.

3. [Errors associated with Meeting and Participant](../../api/sdk-reference/error-codes#3-errors-associated-with-meeting-and-participant): Check that meetingId and participantId are correctly passed and valid. Also, ensure each participant has a unique participantId to avoid duplicate entries.

4. [Errors associated with Add-on Service](../../api/sdk-reference/error-codes#4-errors-associated-with-add-on-service): If you encounter errors with add-on services (such as recording or streaming), try restarting the service after receiving a failure event. For example, if a `START_RECORDING_FAILED` error event occurs, attempt to call the `startRecording()` method again. If you're using webhooks, you can also retry on [recording-failed](https://docs.videosdk.live/api-reference/realtime-communication/user-webhooks#recording-failed) hook.

5. [Errors associated with Media](../../api/sdk-reference/error-codes#5errors-associated-with-media): Inform the user about media access issues, such as microphone or camera permissions. Design the UI to clearly indicate what is preventing the mic or camera from enabling, helping the user understand the problem.

6. [Errors associated with Track](../../api/sdk-reference/error-codes#6errors-associated-with-track): Ensure that the track you’ve created and passed to enable the mic or camera methods meets the required specifications.

7. [Errors associated with Actions](../../api/sdk-reference/error-codes#7errors-associated-with-actions): If you need to perform actions as soon as a meeting joins, only initiate them after receiving the [onMeetingJoined()](https://docs.videosdk.live/ios/api/sdk-reference/meeting-class/events#onmeetingjoined) event, otherwise it will not work well.

- Here's how to listen for the error event:

```js
import VideoSDKRTC

extension MeetingViewController: MeetingEventListener {
func onError(error: VideoSDKError) {
        switch error {
            //...
        }
    }
}
```

---

# Handle Large Rooms - iOS

Managing large meetings requires specific strategies to ensure performance, stability, and a seamless user experience. This section provides best practices for optimizing VideoSDK applications to handle high participant volumes effectively. By implementing these recommendations, you can reduce lag, maintain video and audio quality, and provide a smooth experience even in large rooms.

## User Interface Optimization

When hosting large meetings, an optimized UI helps manage participant visibility and ensures smooth performance.

Recommended Practices:

- `Limit Visible Participants`: Display only a limited number of participants on screen at any given time, adapting the view based on screen size. Use pagination to allow users to browse or switch between additional participants seamlessly. For example, you could display only users whose video stream is enabled, or you could choose to display all active speakers. This approach helps manage screen space efficiently, ensuring that the most relevant participants are visible without overwhelming the interface.
- `Prioritize Active Speakers`: Ensure all active speakers are displayed on the screen to highlight who is currently talking, helping participants stay engaged and aware of ongoing discussions. To identify which participant is speaking, you can use the [onSpeakerChanged()](https://docs.videosdk.live/ios/api/sdk-reference/meeting-class/events#onspeakerchanged) event.

## Optimizing Media Streams 

In large video calls, it’s important to manage media streams effectively to optimize system resources while maintaining a smooth user experience. 

Recommended Practices:

- `Pause Streams for Non-Visible Participants`: To optimize performance, pause the video and/or audio streams of participants who are not currently visible on the screen. This reduces unnecessary resource consumption.
- `Resume Streams When Visible`: Once a participant comes into view, resume their stream to provide an uninterrupted experience as they appear on the screen.

For detailed setup instructions on how to achieve this, check out our in-depth documentation [here](https://docs.videosdk.live/ios/guide/video-and-audio-calling-api-sdk/render-media/layout-and-grid-management#pauseresume-stream).

## Media Stream Quality Adjustment

In large meetings, managing media stream quality is essential to balance performance and user experience. 

Recommended Practices:

- `High Quality for Active Speakers`: For all active speakers, set the video stream quality to a higher level using the setQuality method (e.g., `setQuality("high")`). This ensures that participants will receive higher-quality video for active speakers, providing a clearer and more engaging experience.
- `Lower Quality for Non-Speaking Participants`: For other participants who are not actively speaking, set their video stream quality to a lower level (e.g., `setQuality("low")`). This helps conserve bandwidth and system resources while maintaining overall meeting performance.

Checkout the documentation for `setQuality()` method [here](https://docs.videosdk.live/ios/api/sdk-reference/participant-class/methods#setquality) 

---

# User Experience Guidelines - iOS

This guide aims to help developers optimize the user experience and functionality of video conferencing applications with VideoSDK. By following these best practices, you can create smoother interactions, minimize common issues, and deliver a more reliable experience for users.

Here are our recommended best practices to enhance the user experience in your application:

| **Section**                          | **Description**                                                                                                                                                      |
|--------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Configure Precall for Effortless Meeting Join](#configure-precall-for-effortless-meeting-join) | Users may enter meetings unprepared due to device or connection issues. A Precall setup can help them configure devices and settings beforehand for a smooth start. |
| [Listen Key Events for Optimal User Experience](#listen-key-events-for-optimal-user-experience) | Users can feel lost without real-time updates on meeting status, events, and errors. Event monitoring and notifications keep them informed and engaged.              |
| [Handling Media Devices](#handling-media-devices)                                             | Users may want to change their audio or video setup mid-meeting but struggle to manage device controls. Providing easy device switching enhances control and flexibility. |
| [Monitoring Real-Time Participant Statistics](#monitoring-real-time-participant-statistics)   | Poor video or audio quality without real-time feedback leaves users frustrated. Real-time stats let them assess connection quality and troubleshoot issues actively.    |

## Configure Precall for Effortless Meeting Join

A Precall step is crucial for ensuring users are set up correctly and have no device before joining a meeting. This step allows users to configure their devices and settings before entering a meeting, leading to a smoother experience and minimizing technical issues once the call begins.

Recommended Practices:

- `Request Permissions`: Prompt users to grant microphone, and camera permissions before entering the meeting, ensuring seamless access to their devices.
- `Device Selection`: Allow users to select their preferred camera, and microphone giving them control over their setup from the start.
- `Entry Preferences`: Provide options to join with the microphone and camera either on or off, letting users choose their level of engagement upon entry.
- `Camera Preview`: Show a live camera preview, allowing users to adjust angles and lighting to ensure they appear clearly and professionally.
- `Virtual Backgrounds`: Allow users to choose from different virtual backgrounds or enter with a virtual background enabled, enhancing privacy and creating a more polished appearance.

For detailed setup instructions on each of these features, check out our in-depth documentation [here](https://docs.videosdk.live/ios/guide/video-and-audio-calling-api-sdk/setup-call/precall).

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_precall.gif" />

</div>

## Monitor Key Events for Optimal User Experience

Listening for crucial events is vital for providing users with a responsive and engaging experience in your application. By effectively managing state changes and user notifications, you can keep participants informed and enhance their overall experience during meetings.

Recommended Practices:

- `Monitor State Change Events`: Listen for state change events, such as `onMeetingStateChanged` and `onRecordingStateChanged`, and notify users promptly about these transitions. Keeping users informed helps them understand the current state of the meeting.

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_meeting_state.jpg" />

</div>

- `UI Handling on Event Trigger`: Update the user interface only in response to specific events. For instance, display that the meeting is recording only when the `onRecordingStateChanged` event with the status `RECORDING_STARTED` is received, rather than when the record button is clicked. This ensures users receive accurate and timely updates.

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_recording.gif" />

</div>

- `Notify Participants of Join/Leave Events`: Keep users informed about participant activity by notifying them when someone joins or leaves the meeting. This fosters a sense of presence and awareness of who is currently available to engage.
- `Listen for Error Events`: It is crucial to monitor error events and notify users promptly when issues arise. Clear communication about errors can help users troubleshoot and address problems quickly, minimizing disruptions to the meeting.


## Handling Media Devices

Providing seamless control over devices enhances user convenience and allows participants to adjust their setup for the best meeting experience. Proper device management within the UI also helps users stay informed about their current settings and troubleshoot issues effectively.

Recommended Practices:

- `Allow Device Switching`: Provide users with the option to switch between available microphone, and camera devices during the meeting. This flexibility is essential, especially if users want to adjust their setup mid-call.
- `Display Selected Devices`: Ensure the UI shows users which microphone, and camera devices are currently selected. Clear device labeling in the interface can reduce confusion and help users verify their setup at a glance.

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_audio_selected_device.jpg" />

</div>

## Monitoring Real-Time Participant Statistics

Providing real-time insights into stream quality allows participants to monitor and optimize their connection for the best experience. With detailed metrics on video, audio, and screen sharing, users can assess and troubleshoot quality issues, ensuring smooth and uninterrupted meetings. To display these statistics, you can use the [getVideoStats()](https://docs.videosdk.live/ios/api/sdk-reference/participant-class/methods#getvideostats), [getAudioStats()](https://docs.videosdk.live/ios/api/sdk-reference/participant-class/methods#getaudiostats), and [getShareStats()](https://docs.videosdk.live/ios/api/sdk-reference/participant-class/methods#getsharestats) methods.


<div style={{textAlign: 'center'}}>



</div>

<br/>


---

# Face Match API (BETA)


This API verifies whether two provided images are same or not. It returns a boolean value indicating whether the faces match.

:::important

This API is available in Enterprise plan only.

:::

## HTTP Method and Endpoint

**<span style={{ color: "#86EFAC", fontWeight: "bold" }}>POST</span>** | `https://api.videosdk.live/ai/v1/face-verification/verify`

## Headers Parameter

### Authorization

**values** : YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

_Note_ : the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by referring to this Guide: [Generate Auth token](https://docs.videosdk.live/api-reference/realtime-communication/intro)

### Content-Type

**values** : `application/json`

This is useful for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.

## Data Parameter

#### Base64 Encoding Format

The images should be converted from binary format to a Base64 string




Images must be Base64 encoded in the following format:

```
data:image/jpeg;base64,${Base64data}
```

#### Request Format

The request body should contain two Base64-encoded images in the following format:

```js
const data = {
  img1: "data:image/jpeg;base64,${Base64data}", // Base64-encoded image 1
  img2: "data:image/jpeg;base64,${Base64data}", // Base64-encoded image 2
};
```

## Sending Image Comparison Request

The request is made using the following code:




This sends the encoded images to the specified URL for comparison.

## Code Snippet for API Integration

Below is a code snippet demonstrating how to use the Face Match API (BETA) with Node.js:

```js




// Load environment variables from .env file
dotenv.config();

// Get the directory of the current file
const __dirname = path.resolve();

// Function to read image files and convert them to base64
function getBase64Image(imageName) {
  const filePath = path.join(__dirname, "image", imageName);
  console.log(`Resolved file path: ${filePath}`);
  try {
    const image = readFileSync(filePath);
    const base64Data = Buffer.from(image).toString("base64");
    return `data:image/jpeg;base64,${base64Data}`;
  } catch (error) {
    console.error(`Error reading image file: ${filePath}`, error.message);
    throw error;
  }
}

// Function to perform Face Match
async function faceMatch(ovdImageName, selfieImageName) {
  const url = "https://api.videosdk.live/ai/v1/face-verification/verify";
  const headers = {
    Authorization: `${process.env.API_KEY}`,
    "Content-Type": "application/json",
  };

  const data = {
    img1: getBase64Image(ovdImageName),
    img2: getBase64Image(selfieImageName),
  };

  try {
    const response = await axios.post(url, data, { headers });
    console.log("Face Match Result:", response.data);
  } catch (error) {
    console.error(
      "Error during face match:",
      error.response ? error.response.data : error.message
    );
  }
}

// Main function to run the API calls
async function main() {
  const ovdImageName = "img1.jpg";
  const selfieImageName = "img2.jpg";

  await faceMatch(ovdImageName, selfieImageName);
}

// Run the main function
main().catch((error) =>
  console.error("Error in main function:", error.message)
);
```

## Examples of Face Match API (BETA) Usage

### Example 1 : Matching Images of the Same Person

In this scenario, we take two different pictures of the same individual. For instance:

<div
  style={{ display: "flex", justifyContent: "center", alignItems: "center" }}
>
  <div style={{ textAlign: "center", marginRight: "-15px" }}>
    <img
      src="https://cdn.videosdk.live/website-resources/docs-resources/face_match_girl_1.png"
      alt="Image 1"
      width="90%"
    />
    <p>Image 1</p>
  </div>
  <div style={{ textAlign: "center", marginLeft: "-15px" }}>
    <img
      src="https://cdn.videosdk.live/website-resources/docs-resources/face_match_girl_2.png"
      alt="Image 2"
      width="90%"
    />
    <p>Image 2</p>
  </div>
</div>

When these images are sent to the Face Match API (BETA), the expected output would be:

```
Face Match Result: { "verified": true }
```

This result indicates that despite differences in lighting, angle, or expression, the API successfully recognizes that both images depict the same individual.

### Example 2 : Matching Images of Different Persons

In this case, we compare two photos of different individuals. For example:

<div
  style={{ display: "flex", justifyContent: "center", alignItems: "center" }}
>
  <div style={{ textAlign: "center", marginRight: "-15px" }}>
    <img
      src="https://cdn.videosdk.live/website-resources/docs-resources/face_match_male_1.png"
      alt="Image 1"
      width="90%"
    />
    <p>Image 1</p>
  </div>
  <div style={{ textAlign: "center", marginLeft: "-15px" }}>
    <img
      src="https://cdn.videosdk.live/website-resources/docs-resources/face_match_male_2.png"
      alt="Image 2"
      width="90%"
    />
    <p>Image 2</p>
  </div>
</div>

When these images are processed through the Face Match API (BETA), the expected output would be:

```
Face Match Result: { "verified": false }
```

This result demonstrates the API's ability to differentiate between distinct individuals accurately.



---

# Face Spoof Detection (BETA)


This API verifies if the image is original or spoofed. It returns a boolean value spoof_detected in output.

:::important

This API is available in Enterprise plan only.

:::

## HTTP Method and Endpoint

**<span style={{ color: "#86EFAC", fontWeight: "bold" }}>POST</span>** | `POST https://api.videosdk.live/ai/v1/face-verification/detect-spoof`

## Headers Parameter

### Authorization

**values** : YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

_Note_ : the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by refering this Guide: [Generate Auth token](https://docs.videosdk.live/api-reference/realtime-communication/intro)

### Content-Type

**values** : `application/json`

This is usefull for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.




## Data Parameter

#### Base64 Encoding Format

The images should be converted from binary format to a Base64 string




Images must be Base64 encoded in the following format:

```
data:image/jpeg;base64,${Base64data}
```

#### Request Format

The request body should contain two Base64-encoded images in the following format:

```js
const data = {
  img: "data:image/jpeg;base64,${Base64data}", // Base64-encoded image
};
```

## Sending Image Comparison Request

The request is made using the following code:




This sends the encoded images to the specified URL for comparison.

## Code Snippet for API Integration

Below is a code snippet demonstrating how to use the Face Spoof Detection API (BETA) with Node.js:

```js




// Load environment variables from .env file
dotenv.config();

// Get the directory of the current file
const __dirname = path.resolve();

// Function to read image files and convert them to base64
function getBase64Image(imageName) {
  const filePath = path.join(__dirname, "image", imageName);
  console.log(`Resolved file path: ${filePath}`);
  try {
    const image = readFileSync(filePath);
    const base64Data = Buffer.from(image).toString("base64");
    return `data:image/jpeg;base64,${base64Data}`;
  } catch (error) {
    console.error(`Error reading image file: ${filePath}`, error.message);
    throw error;
  }
}

async function spoofDetection(spoofimg) {
  const url = "https://api.videosdk.live/ai/v1/face-verification/detect-spoof";
  const headers = {
    Authorization: `${process.env.API_KEY}`,
    "Content-Type": "application/json",
  };
  const data = {
    img: getBase64Image(spoofimg),
  };

  try {
    const response = await axios.post(url, data, { headers });
    console.log(response.data);
  } catch (error) {
    console.error(
      "Error during spoof detection:",
      error.response ? error.response.data : error.message
    );
  }
}

// Main function to run the API calls
async function main() {
  const spoofimg = "img.jpg";
  await spoofDetection(spoofimg);
}

// Run the main function
main().catch((error) =>
  console.error("Error in main function:", error.message)
);
```

##### Given below is a test run of the example.

**Input Image** :

<div
  style={{
    display: "flex",
    justifyContent: "left",
    alignItems: "left",
    gap: "10px",
  }}
>
  <img
    src="https://cdn.videosdk.live/website-resources/docs-resources/input_spoof.jpg"
    alt="Image 1"
    width="45%"
  />
</div>

When this image is sent to the Face Spoof Detection API (BETA), the response will return a boolean value spoof_detected in output :

```js
{
  spoof_detected: true; // true if spoof detected in image else false
  accuracy: 0.9899068176746368; // accuracy of spoof detection
}
```



---

# Number of Face Detection (BETA)


This API checks how many faces are there in the image and returns an int value number_of_faces in output.

:::important

This API is available in Enterprise plan only.

:::

## HTTP Method and Endpoint

**<span style={{ color: "#86EFAC", fontWeight: "bold" }}>POST</span>** | `https://api.videosdk.live/ai/v1/face-verification/detect-faces`

## Headers Parameter

### Authorization

**values** : YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

_Note_ : the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by refering this Guide: [Generate Auth token](https://docs.videosdk.live/api-reference/realtime-communication/intro)

### Content-Type

**values** : `application/json`

This is usefull for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.




## Data Parameter

#### Base64 Encoding Format

The images should be converted from binary format to a Base64 string




Images must be Base64 encoded in the following format:

```
data:image/jpeg;base64,${Base64data}
```

#### Request Format

The request body should contain two Base64-encoded images in the following format:

```js
const data = {
  img: "data:image/jpeg;base64,${Base64data}", // Base64-encoded image
};
```

## Sending Image Comparison Request

The request is made using the following code:




This sends the encoded images to the specified URL for comparison.

## Code Snippet for API Integration

Below is a code snippet demonstrating how to use the number of faces detection API with Node.js:

```js




// Load environment variables from .env file
dotenv.config();

// Get the directory of the current file
const __dirname = path.resolve();

// Function to read image files and convert them to base64
function getBase64Image(imageName) {
  const filePath = path.join(__dirname, "image", imageName);
  console.log(`Resolved file path: ${filePath}`);
  try {
    const image = readFileSync(filePath);
    const base64Data = Buffer.from(image).toString("base64");
    return `data:image/jpeg;base64,${base64Data}`;
  } catch (error) {
    console.error(`Error reading image file: ${filePath}`, error.message);
    throw error;
  }
}

async function noOfFaces(getImg) {
  const url = "https://api.videosdk.live/ai/v1/face-verification/detect-faces";
  const headers = {
    Authorization: `${process.env.API_KEY}`,
    "Content-Type": "application/json",
  };
  const data = {
    img: getBase64Image(getImg),
  };

  try {
    const response = await axios.post(url, data, { headers });
    console.log(response.data);
  } catch (error) {
    console.error(
      "Error during Number of face detection :",
      error.response ? error.response.data : error.message
    );
  }
}

// Main function to run the API calls
async function main() {
  const getImg = "img1.jpg";
  await spoofDetection(getImg);
}

// Run the main function
main().catch((error) =>
  console.error("Error in main function:", error.message)
);
```

##### Given below is a test run of the example.

**Input Image** : group_photo.jpg - A photo showing a group of five people.

<div style={{ display: "flex", alignItems: "center", gap: "10px" }}>
  <img
    src="https://cdn.videosdk.live/website-resources/docs-resources/group_of_people.jpg"
    alt="Image 1"
    width="45%"
  />
</div>

When this image is sent to the Face Detection API, The response will return an int value number_of_faces in output :

```js
{
  number_of_faces: 5; // number of faces detected
}
```



---

# OCR API (BETA)


---
title: Ocr | Android SDK Documentation | VideoSDK
description: Learn how to implement ocr using VideoSDK's Android SDK. Step-by-step integration guide for seamless identity verification or SIP connectivity.
---

This API will take front and back part of the document in input, scan through the document and return all the available fields of the document in JSON formatted response. Fields can vary as per type of document in response..

:::important

This API is available in Enterprise plan only.

:::

## HTTP Method and Endpoint

**<span style={{ color: "#86EFAC", fontWeight: "bold" }}>POST</span>** | `https://api.videosdk.live/ai/v1/ocr`

## Headers Parameter

### Authorization

**values** : YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

_Note_ : the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by referring this Guide: [Generate Auth token](https://docs.videosdk.live/api-reference/realtime-communication/intro)

### Content-Type

**values** : `application/json`

This is useful for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.




## Data Parameter

#### Base64 Encoding Format

The images should be converted from binary format to a Base64 string




Images must be Base64 encoded in the following format:

```
data:image/jpeg;base64,${Base64data}
```

#### Request Format

The request body should contain two Base64-encoded images in the following format:

```
const data = {
   "frontpart": "data:image/jpeg;base64,${Base64data}", // Base64-encoded image
   "backpart": "data:image/jpeg;base64,${Base64data}", // Base64-encoded image
}
```

## Sending Image Comparison Request

The request is made using the following code:




This sends the encoded images to the specified URL for comparison.

## Response

The response will return all the available fields of document in JSON formated response :

```javascript
{
   idType: "", // document Type
   idNumber: "", // document Number
   name: "", // name
   dateOfBirth: "",
   address: "",
   gender: "",
   mobileNumber: ""
};
```

## Code Snippet for API Integration

Below is a code snippet demonstrating how to use OCR API (BETA) with Node.js:

```javascript




// Load environment variables from .env file
dotenv.config();

// Get the directory of the current file
const __dirname = path.resolve();

// Function to read image files and convert them to base64
function getBase64Image(imageName) {
  const filePath = path.join(__dirname, "image", imageName);
  console.log(`Resolved file path: ${filePath}`);
  try {
    const image = readFileSync(filePath);
    const base64Data = Buffer.from(image).toString("base64");
    return `data:image/jpeg;base64,${base64Data}`;
  } catch (error) {
    console.error(`Error reading image file: ${filePath}`, error.message);
    throw error;
  }
}

async function ocr(frontImg, backImg) {
  const url = "https://api.videosdk.live/ai/v1/ocr";
  const headers = {
    Authorization: `${process.env.API_KEY}`,
    "Content-Type": "application/json",
  };
  const data = {
    frontPart: getBase64Image(frontImg),
    backPart: getBase64Image(backImg),
  };

  try {
    const response = await axios.post(url, data, { headers });
    console.log(response.data);
  } catch (error) {
    console.error(
      "Error during OCR :",
      error.response ? error.response.data : error.message
    );
  }
}

// Main function to run the API calls
async function main() {
  const frontImg = "img4.jpg";
  const backImg = "img5.jpg";
  await ocr(frontImg, backImg);
}

// Run the main function
main().catch((error) =>
  console.error("Error in main function:", error.message)
);
```



---

# Understanding Analytics Dashboard - iOS

Welcome to the world of actionable insights and empowered decision-making. VideoSDK's session analytics dashboard is your gateway to understanding, optimizing, and elevating every aspect of your sessions.

## Accessing Analytics Made Easy

Navigating through session data is a breeze with VideoSDK. Simply head to your session page at https://app.videosdk.live/meetings/sessions, where a treasure trove of session information awaits.

### How to Access Analytics?

Open Session Analytics effortlessly by following these steps:

1. **Click on Meeting-ID:**
    - Directly access analytics by clicking on the meeting-ID within the session table.
2. **Hover and Click View Analytics:**
    - Hover over a specific meeting row to reveal the **View Analytics** button in the Actions Column.
    - Click on **View Analytics** to open the Session Overview sidebar, unlocking a wealth of insights.

![Access Analytics](https://cdn.videosdk.live/website-resources/docs-resources/access_analytics.png)

---

There are three tabs available within the session analytics view:

## **1. Session Overview**

This tab provides an overview of the session, including its duration and participant details. You can explore individual participant statistics to understand their session performance better.

## **2. Errors**

In this tab, you can find information about any errors encountered during the session. It helps you identify and address issues like network problems or technical glitches promptly.

:::note

Session errors are visible with JS SDK v0.0.82 or higher, React SDK v0.1.85 or higher, and React Native v0.1.6 or newer versions.

:::

## **3. Session Stats**

Explore data and metrics sent and received by participants to measure performance of the session in this tab. It offers insights into data exchange among participants, including metrics on jitter, RTT, and packet loss, resolutions, and fps aiding in assessing communication efficiency.

Let's dive deeper into each of these tabs to gain a better understanding of session analytics.

# Session Overview

The session overview page is your compass in the sea of data. Here's what you'll uncover:

- **Meeting ID:** Unique identifier for the meeting in the format of `abcd-efgh-ijkl`.
- **Session ID:** Unique identifier for each session, uniquely identified by its `sessionId`.
- **Session Status:** Indicates if the session is ongoing or ended.
- **Session Initiating Time:** Time taken by the first participant to establish the connection.
- **Start and End Time:** Marks the start and end of the session.
- **Total Unique Participants Joined:** Total number of unique participants in the session.
- **Total Session Duration:** Overall duration of the session from start to end.
- **Total Participant Minutes:** A sum of all participant duration.
- **Recording, HLS, RTMP:** Additional services used in the session.

### Participant Table List

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for each participant.
- **Join Time:** Time taken by the participant to establish connection.
- **Duration:** Total time spent by this participant in the session.

### Efficient Session Management with Actions

Enhance your session management with streamlined actions:

- **Kick Out Participants:** Effortlessly remove/kickout participants from ongoing sessions.
- **Detailed Participant Analytics:**
- Hover over a specific participant row to reveal the `View Stats` button at the end of the row.
- Click on `View Stats` to open the Participant Overview sidebar.


![View Stats](https://cdn.videosdk.live/website-resources/docs-resources/view_stats.png)


## Explore Participant Insights

Discover valuable participant data that provides a clear view of engagement and experience:

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for better interaction.
- **Joined At:** Indicates the precise moment when participant connects to the session.
- **Left At:** Indicates the precise moment when participant left the session.
- **Total Duration:** Total duration of participant within that session.
- **Joining Time:** Time taken by the this participant to establish the connection.
- **Location:** Approx. geographic location from where the participant joined.
- **Platform:** Specifies whether participants are using a desktop or mobile device.
- **Device Info:** Offers details regarding the participant's device.
- **OS:** Provides information about the participant's OS.
- **Browser:** Provides specifics about the participant's browser
- **SDK Version:** Indicates the version of the SDK used by participants.

### Understanding Participant Call Health

We've developed call health to offer a rapid assessment of participant performance during calls. This feature highlights the performance of audio, video, and screen sharing audio-video separately. We've utilized color theory, with green indicating good performance, orange for moderate, and red for poor performance, to enhance clarity. For detailed insights, simply hover over the bars

![Participant Call Health](https://cdn.videosdk.live/website-resources/docs-resources/participant_call_health.png)

## Participant Session Stats

Dive into Participant Session Stats for valuable insights into your session experience! With just a click on `View Session Stats` at the bottom of the page, unlock a treasure trove of data crucial for understanding audio and video experiences.

Within this section, you can observe quality metrics for the selected participant, comparing them to others. Additionally, the `Sessions Stats` covers quality stats comparison for every participant. Keep reading to explore more about Session Stats.

**Visualizing Session Performance from Both Sides**

This section provides a two-sided view of your session's metrics.

- **Left Side: Sender Participant Graph** This section displays graphs representing the metrics sent by the sender participant.. Here, you can see how the various factors impacted the data you transmitted.
- **Right Side: Receiver Participant Graph** On the right side, you'll find a dropdown menu where you can select a specific participant. Choosing a receiver will display graphs showcasing the metrics **received by that participant**. This allows you to compare the sending experience (left side) with the receiving experience (right side) for different participants.

![VideoSDK Jitter Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_jitter_graph.png)

**See How Your Session Performed**

These metrics give you a clear picture of your session's quality. Understanding them helps you spot any issues and keep things running smoothly. Let's dive into what each metric means!

**Jitter:** Imagine your internet connection like a bumpy road. Jitter is how much those bumps cause your signal to bounce around. Less jitter means a smoother ride for your data (audio and video, threshold ≤ 30ms).

**RTT (Latency):** This is how long it takes for data to travel between you and the server you're connected to. Think of it like the time it takes for a message to get delivered – a lower RTT means a faster delivery (affects both audio and video, threshold ≤ 300ms).

**Bitrate:** This measures the amount of data flowing through your connection per second. Imagine it like the width of a water pipe – a higher bitrate allows for more data to flow, which can be good for high-quality audio/video or fast downloads.

**Packet Loss:** Think of data traveling in tiny packets. Packet loss is when some of those packets get dropped along the way. More packet loss means information might be missing, affecting things like audio/video quality or lag in games (threshold ≤ 5%).

**Resolution:** This refers to the sharpness and detail of an image or video. Think of it like the number of pixels on your screen – a higher resolution means a crisper picture (**Video Only**).

**FPS (Frames Per Second):** This measures how many images (frames) are displayed on your screen every second. Imagine it like a flipbook – a higher FPS creates a smoother and more fluid animation or video experience (**Video Only**).

![VideoSDK FPS Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_fps_graph.png)

![VideoSDK Resolution Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_resolution_graph.png)

---

# **Analyse Session Stats**

Similar to `Participant Session Stats`, this tab covers quality statistics sent by individual participants. You can select any participant to compare effectively with others.

Choose a sender participant from the dropdown menu on the left and select a recipient on the right to compare data over different time frames. This allows you to identify and explore issues within specific durations.

This tab covers the same metrics as covered in the `participant session stats`: Jitter, RTT (Latency), Bitrate, Packet-loss, Resolution (Video only), and FPS (Video only).

![VideoSDK Session Stats](https://cdn.videosdk.live/website-resources/docs-resources/session_stats.png)

---

# Understanding Call Quality - iOS

When developing a video call app, customer satisfaction heavily depends on your app's video and audio quality and its fluctuation.

## Call Quality

If we look at the video quality from the user's perspective, a good video quality can be defined as smooth and clear video, along with a crystal clear audio. If the same is viewed from the developer's perspective, a good video quality can be determined as a high resolution, high frame rate video with minimal latency along with a high bitrate audio with minimal audio loss.

## Factors affecting Quality

When it comes to measuring the video and audio quality of a call, there are multiple variables to consider, and the most common factors which affect the video and audio quality are:

### `1. Network Bandwidth`

- Network bandwidth is a measurement of a user's network capability to how large data can be received and send.
- If the bandwidth is low at participant side, he/she is likely to get pixelated or frozen video along with robotic voice or minor breaking in the audio.
- Frequent change in the network providers can also result in high fluctuation of the internet bandwidth, which can also result in poor quality video.

### `2. Latency`

- Latency basically means the time it takes for data to transfer from one machine to another.
- If the meeting is hosted in `Ohio` region, and users are joining from `Singapore` region, so this will create long delay for data to transfer from one machine to another, thus you should pick a server according to your user base.
- In VideoSDK you can set the server during creation of Meeting/Room.

### `3. CPU Usage`

- CPU Usage is an also quite determining factor as all the audio and video streams which are going out and coming in will have to encoded or decoded which will require a significant amount of computation.
- The high the resolution and frame rate of the videos, the larger would be the computation required, which can be a reason for the bottleneck of delivering a good quality video.
- If the CPU is being consumed heavily, it can also result in a choppy or robotic audio.

### `4. Camera and Mic Quality`

- The camera and microphone should capture good quality of streams so that remote user doesn't get low quality stream even if he/she has good network bandwidth

## Identifying the Quality Issues

In order to identify quality issues, VideoSDK collects multiple audio and video related metrics which can help in pinpointing the quality issues. Let's have a look at those metrics and understand what the indicates.

### `1. Resolutions and Framerates`

- Resolution and frame rate are key metrics for video quality in a video call app. Resolution refers to the number of pixels in a video image, while frame rate refers to the number of frames displayed per second.

- Higher resolutions and frame rates can provide better video quality, but they also require more bandwidth and processing power. It's important to optimize this metrics for the devices and network conditions of your users.

- For example, if most of your users are on mobile devices, a lower resolution and frame rate may be more appropriate to ensure smooth playback and minimize bandwidth usage.

- If most of your users are on mobile and desktop devices, having higher resolution for desktop and mid-resolutions for mobile devices can help in improving the performance and quality as we will be saving the bandwidth on the mobile end.

### `2. Bitrate`

- Bitrate is the number of bits per second send or received during the transmission of audio or video streams. Bitrate can be a key parameter to determine the quality of the audio or video streams, as it should be fine-tuned for each resolution to achieve the best match of performance and bandwidth utilization.

- If the users are having excellent network conditions, higher bitrate can result in much better video quality but on the other hand, having very high bitrates on the mobile devices can result in heating issues due to high computation required to encode and decode the videos.

##### Example

We joined using the same phone **(iPhone 14)**, but the resolution and bitrate were different, first participant having resolution **`1280x720`** with bitrate **`1442 kbps`** and second participant having resolution **`960x540`** with bitrate **`642 kbps`**, so as we can see both participants' video appeared to be of equal quality even though resolution and bitrate are different.

![resolution-and-bitrate](/img/resolution-and-bitrate.png)

### `3. Packet Loss`

- Packet loss is a metric that indicates how many data packets are lost during transmission from the sender to the receiver. Packet loss can occur due to network congestion, hardware or software issues, or network latency. Higher packet loss can result in poor video and audio quality, as the missing packets can cause gaps or distortions in the media stream.


<div style={{textAlign: 'center'}}>



</div>

### `4. Jitter`

- The audio and video packets are sent out at random intervals over a specified time frame as they are being sent between the server and client. Nevertheless, jitter is produced when there is a variation in transmitting or receiving this data packets as a result of a faulty network connection.

- When data packets delay while being transmitted to the participant, usually because the network is busy. They'll display as pixelated video on a video call or sound choppy, distorted, or robotic on a voice call as they arrive. They'll arrive at random intervals, creating jitter.

### `5. Round Trip Time (Latency)`

- Round trip time is the amount of time required to transmit the data packets to send or receive from the server. If the servers are located very far from the user's location, they can observe a high latency (delay).

- With VideoSDK, this factor is taken care of as we automatically choose the nearest available server for participants. But if you are geofencing to a certain region, you should make sure that you choose the server which will be nearest to your users.

<center>

![resolution-and-bitrate](/img/rtt.png)

</center>

## Checking Realtime Statistics

VideoSDK provides methods to check the realtime statistics of the audio and video of all the participants.

### `getVideoStats()`

- `getVideoStats()` returns an array of object containing the different quality parameters for video stream which can be accessed through the `Participant` class.

- This objects will have values for the specific participant's video stream resolution, frame rate, bitrate, jitter, round trip time, and packet loss.

<div style={{textAlign: 'center'}}>



</div>

### `getAudioStats()`

- `getAudioStats()` returns an array of object containing the different quality parameters for audio stream which can be accessed through the `Participant` class.

- This objects will have values for the specific participant's audio stream bitrate, jitter, round trip time and packet loss.

### `getShareStats()`

- `getShareStats()` returns an array of object containing the different quality parameters for screen share stream which can be accessed through the `Participant` class.

- This objects will have values for the specific participant's screen share stream resolution, frame rate, bitrate, jitter, round trip time, and packet loss.

## Quality analysis Graphs

For all the sessions taken using the VideoSDK, you can find the quality analysis graphs from the [VideoSDK Dashboard](https://app.videosdk.live/meetings/sessions) which can help you visualize the data you are seeing in realtime and identify the spikes of a few parameters happing during call which can help figure out the reason for the quality issue.

![quality analysis](/img/quality-analysis.png)

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [getVideoStats()](/ios/api/sdk-reference/participant-class/methods#getvideostats)
- [getAudioStats()](/ios/api/sdk-reference/participant-class/methods#getaudiostats)
- [getShareStats()](/ios/api/sdk-reference/participant-class/methods#getsharestats)


---

# Change Mode - iOS

In a live stream, audience members usually join in `RECV_ONLY` mode, meaning they can only view and listen to the hosts. However, if a host invites an audience member to actively participate (e.g., to speak or present), the audience member can switch their mode to `SEND_AND_RECV` using the changeMode() method.

This guide explains how to use the changeMode() method and walks through a sample implementation where a host invites an audience member to become a host using PubSub.

### `changeMode()`

- The `changeMode()` method from the `Meeting` class allows a participant to switch between modes during a live stream—for example, from audience to host.

#### Example

```js
@IBAction func changeModeTapped(_ sender: UIButton) {
    meeting?.changeMode(to: "SEND_AND_RECV") { error in
        if let error = error {
            print("Failed to change mode: \(error.localizedDescription)")
        } else {
            print(" Mode changed to SEND_AND_RECV")
        }
    }
}
```

#### Implementation Guide

#### Step 1 : Create a Pubsub Topic

- Set up a PubSub topic to send a mode change request from the host to a specific audience member.

```js
func inviteParticipantAsHost(participantId: String) {
    let topic = "REQUEST_TO_JOIN_AS_HOST_\(participantId)"
    let message = "SEND_AND_RECV"
    meeting?.pubSub.publish(topic: topic, message: message, options: nil)
    print("Invitation sent to participant: \(participantId)")
}
```

#### Step 2 : Create an Invite Button

- Add an "Invite on Stage" button for each audience member. When clicked, it publishes a PubSub message with the mode "SEND_AND_RECV" to that participant.

```js
@objc func inviteButtonTapped(for participant: Participant) {
    // Only invite participants who are in RECV_ONLY mode
    guard participant.mode == "RECV_ONLY" else { return }
    inviteParticipantAsHost(participantId: participant.id)
}
```

#### Step 3 : Create a Listener to Change the Mode

- On the audience side, subscribe to the specific PubSub topic. When a mode request is received, update the participant’s mode using changeMode().

```js
func setupModeChangeListener() {
    guard let localParticipantId = meeting?.localParticipant?.id else { return }
    
    // Subscribe to the specific topic for this participant
    let topic = "REQUEST_TO_JOIN_AS_HOST_\(localParticipantId)"
    
    meeting?.pubSub.subscribe(topic: topic) { message in
        if let mode = message.message as? String {
            // When a request is received, change the mode
            self.meeting?.changeMode(to: mode) { error in
                if let error = error {
                    print("Failed to change mode: \(error.localizedDescription)")
                } else {
                    print("Mode changed to \(mode)")
                }
            }
        }
    }
}
```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [changeMode()](/ios/api/sdk-reference/meeting-class/methods#changemode)
- [participant](/ios/api/sdk-reference/participant-class/properties)
- [meeting](/ios/api/sdk-reference/meeting-class/properties)
- [pubsub()](/ios/api/sdk-reference/meeting-class/pubsub)


---

# Remove Participant - iOS

When hosting a live stream, it's essential for the host to have the capability to to remove a participant from the live stream. This can be useful in various scenarios where a participant is causing disturbance, behaving inappropriately, or is not following the guidelines. This guide focuses on this very aspect of removing a particpant from the live stream.

VideoSDK provides three ways to do so:

1. [Using SDK](#1-using-sdk)
2. [Using VideoSDK Dashboard](#2-using-videosdk-dashboard)
3. [Using Rest API](#3-using-rest-api)

## 1. Using SDK

### `remove()`

The `remove()` method allows for the removal of a participant during an on-going session. This can be helpful when moderation is required in a particular live stream.

```js
class LiveStreamViewController {
    //Button when tapped will remove the participant with given participantID
    @IBAction func removeParticipant(_ sender: Any) {
        var participantID = "ABCD"

        guard let index = self.participants.firstIndex(where: { $0.id == participantID }) else {
            return
        }
        // remove participant from list
        participants.remove(at: index)
    }
```

### Events associated with remove()

Following callbacks are received when a participant is removed from the meeting.

- Participant who was removed from the meeting will receive a callback on[`onMeetingLeft`](/ios/api/sdk-reference/meeting-class/events#onmeetingleft).

- All other [remote participants](../concept-and-architecture#2-participant) will receive a callback [`onParticipantLeft`](/ios/api/sdk-reference/meeting-class/events#onparticipantleft) with Participant object.


## 2. Using VideoSDK Dashboard

- For removing a participant using the VideoSDK Dashboard, navigate to the session page on [VideoSDK Dashboard](https://app.videosdk.live/meetings/sessions). Select the specific session, and from the list of participants, choose the participant you wish to remove. Utilize the provided options to remove the selected participant from the session.


<div style={{textAlign: 'center'}}>



</div>

## 3. Using Rest API

- You can also remove a particular participant from the live stream [using the REST API](/api-reference/realtime-communication/remove-participant).
- To employ this method, you need the `sessionId` of the live stream and the `participantId` of the individual you intend to remove.

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [remove()](/ios/api/sdk-reference/participant-class/methods#remove)
- [onMeetingLeft()](/ios/api/sdk-reference/meeting-class/events#onmeetingleft)
- [onParticipantLeft()](/ios/api/sdk-reference/meeting-class/events#onparticipantleft)


---

# Audience Polls during Live Stream - iOS

Interactive polls are a great way to increase engagement during livestreams. Using VideoSDK’s PubSub mechanism, you can easily implement real-time audience polling, where viewers can vote and see live results instantly.

This guide walks you through how to create, send, and visualize poll results during a livestream.

### Step 1: Creating and Publishing a Poll

The host initiates a poll by publishing a message to the POLL topic using the `publish()` method of the `pubSub` property from the `Meeting` class. The poll message includes a unique identifier, a question, and multiple options. Setting the `persist` option to `true` ensures that the poll message is retained and delivered to participants who join the meeting later.

```js title="PollHostViewController.swift"
import UIKit
import VideoSDKRTC

class PollHostViewController: UIViewController {
    var meeting: Meeting! 

    @IBAction func startPollTapped(_ sender: UIButton) {
        let pollData: [String: Any] = [
            "id": "\(Date().timeIntervalSince1970)",
            "question": "Which feature do you love the most?",
            "options": ["Reactions", "Screen Share", "Whiteboard", "Polls"]
        ]
        let options = ["persist": true]
        if let pollMessage = try? JSONSerialization.data(withJSONObject: pollData, options: []),
           let pollString = String(data: pollMessage, encoding: .utf8) {
            meeting.pubSub.publish(topic: "POLL", message: pollString, options: options)
        }
    }
}
```

### Step 2: Subscribing to Polls and Displaying Options

Participants subscribe to the `POLL` topic using the `subscribe()` method of the pubSub property. Upon receiving a new poll message, they can parse the content and render the voting options dynamically.
```js
import UIKit
import VideoSDKRTC

class PollParticipantViewController: UIViewController, PubSubMessageListener {
    var meeting: Meeting!
    var currentPoll: [String: Any]?

    override func viewDidLoad() {
        super.viewDidLoad()
        meeting.pubSub.subscribe(topic: "POLL", forListener: self)
    }

    func onMessageReceived(message: PubSubMessage) {
        if let data = message.message.data(using: .utf8),
           let poll = try? JSONSerialization.jsonObject(with: data, options: []) as? [String: Any] {
            currentPoll = poll
            DispatchQueue.main.async {
                self.displayPoll(poll)
            }
        }
    }

    func displayPoll(_ poll: [String: Any]) {
        // Implement UI to display poll question and options
        // For each option, add a button that calls submitVote(option:)
    }

    func submitVote(option: String) {
        guard let pollId = currentPoll?["id"] as? String else { return }
        let response: [String: Any] = [
            "pollId": pollId,
            "option": option
        ]
        if let responseData = try? JSONSerialization.data(withJSONObject: response, options: []),
           let responseString = String(data: responseData, encoding: .utf8) {
            meeting.pubSub.publish(topic: "POLL_RESPONSE", message: responseString, options: [:])
        }
    }
}
```

### Step 3: Aggregating and Displaying Poll Results

The host subscribes to the `POLL_RESPONSE` topic to collect participants' responses in real-time. By parsing each incoming message, the host can aggregate the results and update the UI accordingly.
```js
import UIKit
import VideoSDKRTC

class PollResultsViewController: UIViewController, PubSubMessageListener {
    var meeting: Meeting!
    var pollResults: [String: [String: Int]] = [:] // [pollId: [option: count]]

    override func viewDidLoad() {
        super.viewDidLoad()
        meeting.pubSub.subscribe(topic: "POLL_RESPONSE", forListener: self)
    }

    func onMessageReceived(message: PubSubMessage) {
        if let data = message.message.data(using: .utf8),
           let response = try? JSONSerialization.jsonObject(with: data, options: []) as? [String: Any],
           let pollId = response["pollId"] as? String,
           let option = response["option"] as? String {
            var results = pollResults[pollId] ?? [:]
            results[option] = (results[option] ?? 0) + 1
            pollResults[pollId] = results
            DispatchQueue.main.async {
                self.updateResultsUI(for: pollId)
            }
        }
    }

    func updateResultsUI(for pollId: String) {
        // Implement UI update to display poll results
    }
}

```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [PubSub()](/ios/api/sdk-reference/meeting-class/pubsub)


---

<h1> {props.title} </h1>{" "}

### Why we are using JWT based Token ?

Token based authentication allows users to verify their identity by providing generated API key and secret.

We use JWT token for the authentication purpose because Token-based authentication is **widely used** in modern web applications and APIs because it offers several benefits over traditional authentication. For example, it can **reduce the risk of the credentials being misused**, and it allows for **more fine-grained control** over access to resources. Additionally, tokens can be easily revoked or expired, making it easier to manage access rights.

### How to generate Token ?

To manage secured communication, every participant that connects to the meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key` which you can get from [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

#### 1. Generating token from Dashboard

If you are looking to do **testing or for development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for getting token includes generating it from your backend server which will help in **keeping your credentials safe**.
:::

#### 2. Generating token in your backend

- Your server will generate access token using your API key and secret.
  - While generating a token, you can provide **expiration time, permissions and roles** which are discussed later in this section.
- Your client obtains token from your backend server.
- For token validation, client will pass this token to VideoSDK server.
- VideoSDK server will only allow entry in the meeting if the token is valid.

![img2.png](../../static/img/authentication-and-token.png)




Follow our official example repositories to setup token API [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)

### Payload while generating token

```js
{
 apikey: API_KEY, //MANDATORY
 permissions: [`allow_join`], //`ask_join` || `allow_mod` //MANDATORY
 version: 2, //OPTIONAL
 roomId: ROOM_ID, //OPTIONAL,
 participantId: PARTICIPANT_ID, //OPTIONAL
 roles: ['crawler', 'rtc'], //OPTIONAL
}
```

- **`apikey`(Mandatory)**: This must be the API Key generated from the VideoSDK Dashboard. You can get it from [here](https://app.videosdk.live/api-keys).

- **`permissions`(Mandatory)**: By providing the permissions, you can control what a participant can do in the meeting and whether he can join the meeting directly.

  Available permissions are:

  - **`allow_join`**: The participant is **allowed to join** the meeting directly.
  - **`ask_join`**: The participant is required to **ask for permission to join** the meeting. The participant having the permission `allow_join` can accept or reject a participant whenever someone wants to join.
  - **`allow_mod`**: The participant is **allowed to toggle** webcam & mic of other participants.

- **`version`(optional)**: For accessing the [v2 API](/api-reference/realtime-communication/intro), you need to provide `2` as the version value.

  - For passing `roomId`, `participantId` or `roles` parameters in payload, it is essential to set the version value to `2`.

- **`roomId`(optional)**: To provide customised access control, you can make the token applicable to a particular room by including the `roomId` in the payload.

- **`participantId`(optional)**: You can include the `participantId` in the payload to limit the token's access to a particular participant.

- **`roles`(optional)**:

  - **`crawler`**: This role is only for accessing [v2 API](/api-reference/realtime-communication/intro), you can not use this token for running the `Meeting`/`Room`.
  - **`rtc`**: This role is only allowed for running the `Meeting` / `Room`, with this role you can not use [server-side APIs](/api-reference/realtime-communication/intro).

Then, you have to sign this payload with your **`SECRET KEY`** and `jwt` options using the **`HS256 algorithm`**.

### Expiration time

You can set any expiration time to the token. But in the **production environment**, it is recommended to generate a token with **short expiration time** because by any chance if someone gets hold of the token, it won't be valid for a longer period of time.

### What happens if token is expired?

If your token is expired, the user won't be able to join the meeting and all the API calls will give error with message `Token is invalid or expired`.

:::note
Token is validated only once while joining the meeting, so if a person joins the meeting and the token gets expired after that, there won't be any issue in the current meeting.
:::

## How to check validity of token?

1. After generating the token, visit [jwt.io](https://jwt.io) and paste your token in the given area.
2. You will be able to see the payload you passed while generating the token and also be able to see the expiration time and token creation time.

![img1.png](../../static/img/validate-token.png)

## API Settings & Controls

The VideoSDK Dashboard provides a powerful [API Settings](https://app.videosdk.live/api-keys) section where you can configure various services and controls for your meetings. These settings allow you to customize the behavior of different features directly from the dashboard without requiring code changes.

## Audio/Video Configurations

:::note
Runtime configuration from the dashboard has higher precedence than static SDK configurations.
If a value is modified in the dashboard, it will override any previously defined SDK settings for that session.

Example:
Code: Video = HD → Dashboard: Video = Full HD → Applied: Full HD
:::

### Maximum Send Bitrate Per Participant

Control the maximum total upload bandwidth for all media streams from a single participant.

![Maximum Send Bitrate](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.00.11%E2%80%AFPM.png)

**Available Options:**
- **Auto**: Removes the upload bitrate limit (recommended for best quality)
- **SD (800kbps)**: Standard definition bitrate
- **HD (1500kbps)**: High definition bitrate
- **Full HD (3000kbps)**: Full high definition bitrate

:::tip
Setting this to **Auto** provides the best video quality as it removes upload bitrate constraints, allowing adaptive streaming based on network conditions.
:::

## Recording & Streaming Configuration

:::note
Recording and HLS follow a precedence-based configuration model:

API/SDK configuration → Highest priority
Dashboard configuration → Used only when no API values are defined

Any parameters explicitly set via the API will not be overridden by dashboard changes.
:::

### Recording Configuration

Configure recording settings for your meetings including layout, quality, and auto-start options.

![Recording Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.01.00%E2%80%AFPM.png)

**Recording Controls:**
- **Enabled**: Toggle to enable/disable recording functionality
- **Enabled Modes**: Choose between Video & Audio or Audio Only recording
- **Start Recording Automatically**: Auto-start recording when meeting begins
- **Layout Style**: Select Grid layout for recording composition
- **Maximum Tiles In Grid**: Set the number of participants visible in grid (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme for recordings
- **Video Orientation**: Choose between Landscape or Portrait mode
- **Recording Quality**: Select quality level (e.g., HD Medium)
- **Recording Mode**: Choose between Video & Audio or Audio Only

### HLS Streaming Configuration

Configure HTTP Live Streaming (HLS) settings for broadcasting your meetings.

![HLS Streaming Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.02.18%E2%80%AFPM.png)

**HLS Streaming Controls:**
- **Enabled**: Toggle to enable/disable HLS streaming
- **Enabled Modes**: Choose between Video & Audio or Audio Only streaming
- **Auto Start HLS**: Automatically start HLS when meeting begins
- **Record HLS Stream**: Enable recording of the HLS stream
- **Layout Style**: Select Grid layout for stream composition
- **Maximum Tiles In Grid**: Set the number of participants visible (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme
- **HLS Orientation**: Choose between Landscape or Portrait mode
- **HLS Quality**: Select streaming quality (e.g., HD Medium)
- **HLS Streaming Mode**: Choose between Video & Audio or Audio Only

### Additional Service Controls

Enable or disable additional services for your API key.

![Service Controls](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.08%E2%80%AFPM.png)

**Available Services:**
- **RTMP Output**: Enable RTMP streaming to external platforms
- **SIP Integration**: Enable SIP (Session Initiation Protocol) integration for telephony
- **Realtime Translation**: Enable real-time language translation in meetings

### Transcription & Summary

Configure transcription and domain whitelisting for your API key.

![Transcription Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.50%E2%80%AFPM.png)

**Transcription Controls:**
- **Enabled**: Toggle to enable/disable transcription and summary features
- **Whitelist Domain**: Add domain restrictions for API key usage
  - Enter domain names in the format `https://domain.name`
  - Click "Add Domain" to whitelist specific domains
  - Only whitelisted domains can use this API key
  - When no domains are whitelisted, the API key can be used from any domain


---

# Developer Experience Guidelines - iOS

This section provides best practices for creating a smooth and efficient development process when working with VideoSDK. From handling errors gracefully to managing resources and event subscriptions, these guidelines help developers build more reliable and maintainable applications. Following these practices can simplify troubleshooting, prevent common pitfalls, and improve overall application performance.

## Initiate Key Features After Meeting Join Event

To provide a seamless and reliable meeting experience, initiate specific features **only** after the [onMeetingJoined()](https://docs.videosdk.live/ios/api/sdk-reference/meeting-class/events#onmeetingjoined) event has been triggered.

- **Trigger Key Actions After Joining the Meeting** : Initiating crucial actions after the `onMeetingJoined()` event helps avoid errors and optimizes the meeting setup, ensuring a smoother experience for participants. If your application utilizes any of the following features or you want to perform any action as soon as meeting joins, it's recommended to call them only after the meeting has successfully started:

    - `Chat Subscription`: To enable in-meeting chat functionality, subscribe to the chat topic after the `onMeetingJoined()` event is triggered. This ensures that messages are reliably received by participants.

    <br/>
    <div style={{textAlign: 'center'}}>

    <img src="https://cdn.videosdk.live/docs/best-practices/mobile/ios_chat_correct_incorrect_code.png" />

    </div>

    - `Device Management`: If you need users to use specific audio or video devices when the meeting is first joined, you can utilize the custom track. Pass the `cameraId` to the [createCameraVideoTrack()](https://docs.videosdk.live/ios/api/sdk-reference/custom-tracks#custom-video-track---ios) method for video, and the `microphoneId` to the [createAudioTrack()](https://docs.videosdk.live/ios/api/sdk-reference/custom-tracks#custom-audio-track) method for audio. Once the track is created, provide it to the [initMeeting()](https://docs.videosdk.live/ios/api/sdk-reference/initMeeting#initmeeting) method.

    - `Recording and Transcription`: To automatically start recording or transcription as soon as the meeting begins, configure the `autoStartConfig` in the `createMeeting` API. For detailed information, refer to the documentation [here](https://docs.videosdk.live/api-reference/realtime-communication/create-room#autoCloseConfig).




## Listen for Error Events

Listening to error events enables your application to handle unexpected issues efficiently, providing users with clear feedback and potential solutions. Error codes pinpoint specific problems, whether from configuration settings, account restrictions, permission limitations, or device constraints. Here are recommended solutions based on common error categories:

1. [Errors associated with Organization](/ios/api/sdk-reference/error-codes#1-errors-associated-with-organization): If you encounter errors related to your organization (e.g., account status or participant limits), reach out to support at support@videosdk.live or reach out to us on [Discord](https://discord.com/invite/Qfm8j4YAUJ) for assistance.

2. [Errors associated with Token](/ios/api/sdk-reference/error-codes#2-errors-associated-with-token): For errors related to authentication tokens, ensure the token is valid and hasn’t expired, then try the request again.

3. [Errors associated with Meeting and Participant](/ios/api/sdk-reference/error-codes#3-errors-associated-with-meeting-and-participant): Check that meetingId and participantId are correctly passed and valid. Also, ensure each participant has a unique participantId to avoid duplicate entries.

4. [Errors associated with Add-on Service](/ios/api/sdk-reference/error-codes#4-errors-associated-with-add-on-service): If you encounter errors with add-on services (such as recording or streaming), try restarting the service after receiving a failure event. For example, if a `START_RECORDING_FAILED` error event occurs, attempt to call the `startRecording()` method again. If you're using webhooks, you can also retry on [recording-failed](https://docs.videosdk.live/api-reference/realtime-communication/user-webhooks#recording-failed) hook.

5. [Errors associated with Media](/ios/api/sdk-reference/error-codes#5errors-associated-with-media): Inform the user about media access issues, such as microphone or camera permissions. Design the UI to clearly indicate what is preventing the mic or camera from enabling, helping the user understand the problem.

6. [Errors associated with Track](/ios/api/sdk-reference/error-codes#6errors-associated-with-track): Ensure that the track you’ve created and passed to enable the mic or camera methods meets the required specifications.

7. [Errors associated with Actions](/ios/api/sdk-reference/error-codes#7errors-associated-with-actions): If you need to perform actions as soon as a meeting joins, only initiate them after receiving the [onMeetingJoined()](https://docs.videosdk.live/ios/api/sdk-reference/meeting-class/events#onmeetingjoined) event, otherwise it will not work well.

- Here's how to listen for the error event:

```js
import VideoSDKRTC

extension MeetingViewController: MeetingEventListener {
func onError(error: VideoSDKError) {
        switch error {
            //...
        }
    }
}
```

---

# Handle Large Rooms - iOS

Managing large meetings requires specific strategies to ensure performance, stability, and a seamless user experience. This section provides best practices for optimizing VideoSDK applications to handle high participant volumes effectively. By implementing these recommendations, you can reduce lag, maintain video and audio quality, and provide a smooth experience even in large rooms.

## User Interface Optimization

When hosting large meetings, an optimized UI helps manage participant visibility and ensures smooth performance.

Recommended Practices:

- `Limit Visible Participants`: Display only a limited number of participants on screen at any given time, adapting the view based on screen size. Use pagination to allow users to browse or switch between additional participants seamlessly. For example, you could display only users whose video stream is enabled, or you could choose to display all active speakers. This approach helps manage screen space efficiently, ensuring that the most relevant participants are visible without overwhelming the interface.
- `Prioritize Active Speakers`: Ensure all active speakers are displayed on the screen to highlight who is currently talking, helping participants stay engaged and aware of ongoing discussions. To identify which participant is speaking, you can use the [onSpeakerChanged()](https://docs.videosdk.live/ios/api/sdk-reference/meeting-class/events#onspeakerchanged) event.

## Optimizing Media Streams 

In large video calls, it’s important to manage media streams effectively to optimize system resources while maintaining a smooth user experience. 

Recommended Practices:

- `Pause Streams for Non-Visible Participants`: To optimize performance, pause the video and/or audio streams of participants who are not currently visible on the screen. This reduces unnecessary resource consumption.
- `Resume Streams When Visible`: Once a participant comes into view, resume their stream to provide an uninterrupted experience as they appear on the screen.

For detailed setup instructions on how to achieve this, check out our in-depth documentation [here](https://docs.videosdk.live/ios/guide/video-and-audio-calling-api-sdk/render-media/layout-and-grid-management#pauseresume-stream).

## Media Stream Quality Adjustment

In large meetings, managing media stream quality is essential to balance performance and user experience. 

Recommended Practices:

- `High Quality for Active Speakers`: For all active speakers, set the video stream quality to a higher level using the setQuality method (e.g., `setQuality("high")`). This ensures that participants will receive higher-quality video for active speakers, providing a clearer and more engaging experience.
- `Lower Quality for Non-Speaking Participants`: For other participants who are not actively speaking, set their video stream quality to a lower level (e.g., `setQuality("low")`). This helps conserve bandwidth and system resources while maintaining overall meeting performance.

Checkout the documentation for `setQuality()` method [here](https://docs.videosdk.live/ios/api/sdk-reference/participant-class/methods#setquality) 

---

# User Experience Guidelines - iOS

This guide aims to help developers optimize the user experience and functionality of video conferencing applications with VideoSDK. By following these best practices, you can create smoother interactions, minimize common issues, and deliver a more reliable experience for users.

Here are our recommended best practices to enhance the user experience in your application:

| **Section**                          | **Description**                                                                                                                                                      |
|--------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Configure Precall for Effortless Meeting Join](#configure-precall-for-effortless-meeting-join) | Users may enter meetings unprepared due to device or connection issues. A Precall setup can help them configure devices and settings beforehand for a smooth start. |
| [Listen Key Events for Optimal User Experience](#listen-key-events-for-optimal-user-experience) | Users can feel lost without real-time updates on meeting status, events, and errors. Event monitoring and notifications keep them informed and engaged.              |
| [Handling Media Devices](#handling-media-devices)                                             | Users may want to change their audio or video setup mid-meeting but struggle to manage device controls. Providing easy device switching enhances control and flexibility. |
| [Monitoring Real-Time Participant Statistics](#monitoring-real-time-participant-statistics)   | Poor video or audio quality without real-time feedback leaves users frustrated. Real-time stats let them assess connection quality and troubleshoot issues actively.    |

## Configure Precall for Effortless Meeting Join

A Precall step is crucial for ensuring users are set up correctly and have no device before joining a meeting. This step allows users to configure their devices and settings before entering a meeting, leading to a smoother experience and minimizing technical issues once the call begins.

Recommended Practices:

- `Request Permissions`: Prompt users to grant microphone, and camera permissions before entering the meeting, ensuring seamless access to their devices.
- `Device Selection`: Allow users to select their preferred camera, and microphone giving them control over their setup from the start.
- `Entry Preferences`: Provide options to join with the microphone and camera either on or off, letting users choose their level of engagement upon entry.
- `Camera Preview`: Show a live camera preview, allowing users to adjust angles and lighting to ensure they appear clearly and professionally.
- `Virtual Backgrounds`: Allow users to choose from different virtual backgrounds or enter with a virtual background enabled, enhancing privacy and creating a more polished appearance.

For detailed setup instructions on each of these features, check out our in-depth documentation [here](https://docs.videosdk.live/ios/guide/video-and-audio-calling-api-sdk/setup-call/precall).

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_precall.gif" />

</div>

## Monitor Key Events for Optimal User Experience

Listening for crucial events is vital for providing users with a responsive and engaging experience in your application. By effectively managing state changes and user notifications, you can keep participants informed and enhance their overall experience during meetings.

Recommended Practices:

- `Monitor State Change Events`: Listen for state change events, such as `onMeetingStateChanged` and `onRecordingStateChanged`, and notify users promptly about these transitions. Keeping users informed helps them understand the current state of the meeting.

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_meeting_state.jpg" />

</div>

- `UI Handling on Event Trigger`: Update the user interface only in response to specific events. For instance, display that the meeting is recording only when the `onRecordingStateChanged` event with the status `RECORDING_STARTED` is received, rather than when the record button is clicked. This ensures users receive accurate and timely updates.

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_recording.gif" />

</div>

- `Notify Participants of Join/Leave Events`: Keep users informed about participant activity by notifying them when someone joins or leaves the meeting. This fosters a sense of presence and awareness of who is currently available to engage.
- `Listen for Error Events`: It is crucial to monitor error events and notify users promptly when issues arise. Clear communication about errors can help users troubleshoot and address problems quickly, minimizing disruptions to the meeting.


## Handling Media Devices

Providing seamless control over devices enhances user convenience and allows participants to adjust their setup for the best meeting experience. Proper device management within the UI also helps users stay informed about their current settings and troubleshoot issues effectively.

Recommended Practices:

- `Allow Device Switching`: Provide users with the option to switch between available microphone, and camera devices during the meeting. This flexibility is essential, especially if users want to adjust their setup mid-call.
- `Display Selected Devices`: Ensure the UI shows users which microphone, and camera devices are currently selected. Clear device labeling in the interface can reduce confusion and help users verify their setup at a glance.

<div style={{textAlign: 'center'}}>

<img height="400" src="https://cdn.videosdk.live/docs/best-practices/mobile/mobile_audio_selected_device.jpg" />

</div>

## Monitoring Real-Time Participant Statistics

Providing real-time insights into stream quality allows participants to monitor and optimize their connection for the best experience. With detailed metrics on video, audio, and screen sharing, users can assess and troubleshoot quality issues, ensuring smooth and uninterrupted meetings. To display these statistics, you can use the [getVideoStats()](https://docs.videosdk.live/ios/api/sdk-reference/participant-class/methods#getvideostats), [getAudioStats()](https://docs.videosdk.live/ios/api/sdk-reference/participant-class/methods#getaudiostats), and [getShareStats()](https://docs.videosdk.live/ios/api/sdk-reference/participant-class/methods#getsharestats) methods.


<div style={{textAlign: 'center'}}>



</div>

<br/>


---

# Chat during Live Stream - iOS

Enhance your live stream experience by enabling real-time audience chat using VideoSDK's usePubSub hook. Whether you’re streaming a webinar, online event, or an interactive session, integrating a chat system lets your viewers engage, ask questions, and react instantly. This guide shows how to build a group or private chat interface for a live stream using the Publish-Subscribe (PubSub) mechanism.

This guide focuses on implementing chat functionality in an iOS application using VideoSDK's PubSub mechanism. If you're new to the `PubSub` system and the `pubSub` class, this guide will walk you through the necessary steps.


## Implementing Chat

### `Group Chat`(Public Chat for All Viewers)

To allow your entire audience to chat during the stream:

1. Participants need to subscribe to a common topic, such as "CHAT", to receive incoming messages.

```js
import UIKit
import VideoSDKRTC

class GroupChatViewController: UIViewController, PubSubMessageListener {
    var meeting: Meeting!
    var messages: [PubSubMessage] = []

    override func viewDidLoad() {
        super.viewDidLoad()
        // Subscribing to the "CHAT" topic
        meeting.pubSub.subscribe(topic: "CHAT", forListener: self)
    }

    // Callback method when a new message is received
    func onMessageReceived(message: PubSubMessage) {
        messages.append(message)
        DispatchQueue.main.async {
            self.updateChatUI()
        }
    }

    // Method to update the chat UI with new messages
    func updateChatUI() {
        // Implement UI update to display chat messages
    }
}
```

In above setup, the `GroupChatViewController` class conforms to the `PubSubMessageListener` protocol, allowing it to receive messages published to the "CHAT" topic. The `onMessageReceived` method appends incoming messages to the `messages` array and updates the chat UI accordingly.


2. Participants can send messages by publishing to the "CHAT" topic. Setting `persist` to `true` ensures that messages are retained for participants who join later.

```js
@IBAction func sendMessageTapped(_ sender: UIButton) {
    let messageText = "Hello, everyone!"
    let options = ["persist": true]
    // Publishing the message to the "CHAT" topic
    meeting.pubSub.publish(topic: "CHAT", message: messageText, options: options)
}
```

### `Private Chat` (1:1 between Host and Viewer)

Private messaging is ideal when a host or moderator needs to directly respond to a viewer’s question. This can be achieved using the `sendOnly` property.

```js
@IBAction func sendPrivateMessageTapped(_ sender: UIButton) {
    let messageText = "Hello, this is a private message."
    let recipientId = "participant_id_here" // Replace with actual participant ID
    let options = ["sendOnly": [recipientId]]
    meeting.pubSub.publish(topic: "CHAT", message: messageText, options: options)
}
```

### Display Latest Message Notificaiton

To alert hosts/moderators about new incoming chat messages in real-time:

```js
func onMessageReceived(message: PubSubMessage) {
    messages.append(message)
    DispatchQueue.main.async {
        self.updateChatUI()
        self.showNewMessageAlert(message: message)
    }
}

func showNewMessageAlert(message: PubSubMessage) {
    let alert = UIAlertController(title: "New Message", message: "\(message.senderName) says: \(message.message)", preferredStyle: .alert)
    alert.addAction(UIAlertAction(title: "OK", style: .default))
    self.present(alert, animated: true)
}
``` 

## Downloading Chat Messages

All the messages from PubSub published with `persist : true` can be downloaded as an `.csv` file. This file will be accessible in the VideoSDK dashboard and through the [Sessions API](/api-reference/realtime-communication/fetch-session-using-sessionid).

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [PubSub()](/ios/api/sdk-reference/meeting-class/pubsub)


---

# Cloud Proxy - iOS


Our SDK features a Cloud Proxy that allows you to manage how your streaming content is routed through different network paths. This feature ensures compliance with various regional internet regulations by restricting traffic to specified proxy servers, based on your needs and the geographical location of users.

This capability is crucial for adhering to local data protection laws and optimizes the streaming experience by overcoming geographical network constraints. By directing user connections to appropriate regional servers, Cloud Proxy enhances overall service performance and reliability.

Cloud Proxy offers three straightforward operating modes to fit different business and firewall requirements:

- **UDP_OVER_TCP (Default)**: In this mode, the connection starts by attempting to establish a UDP connection for media transmission. If that fails, it will automatically shifts to a secure TCP connection, which is compatible with most firewalls.

- **Force UDP**: This mode uses only UDP to send media, ensuring high-quality streams. It's ideal for environments where media quality is critical and the firewall can be configured accordingly.

- **Force TCP**: Only uses TCP for secure media transmission, suitable for strict firewall settings that only permit TCP traffic over centain ports. This might require additional firewall configuration and could affect media quality under poor network conditions.




### In this sequence diagram:
- Client to Proxy Server: The client sends a request to the proxy server, which processes and forwards it based on predefined rules.
- Proxy Server to Destination Server: The proxy server sends the request to the destination server, receives the response, and relays it back to the client.

:::info

Cloud Proxy is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Implementation

```js
  let meeting = VideoSDK.initMeeting(
            meetingId: "abcd-efgh-hijk",
            participantId: "TD", //optional
            participantName: "Ted Doe",
            micEnabled: true,
            webcamEnabled: true,
            customCameraVideoStream: customVideoStream, //optional
            customAudioTrack: customAudioStream, //optional
            mode: .SEND_AND_RECV, //optional (default mode is conference)
            preferredProtocol: .UDP_ONLY, //optional(default is .UDP_OVER_TCP),
            signalingBaseUrl: "proxy.yourwebsite.com" //optional
        )
```

### Parameters

- preferredProtocol:
  - UDP_OVER_TCP (default): Initially the server attempts to establish a connection using UDP, if that fails it automatically switches to TCP protocol.
  - UDP_ONLY: Force UDP protocol
  - TCP_ONLY: Force TCP protocol
- signalingBaseUrl: Proxy URL to origin signaling and media.

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [MeetingProvider](/ios/api/sdk-reference/meeting-class/introduction)


---

# Concept and Architecture - iOS

Before diving into the concept, let's understand the VideoSDK, VideoSDK is a software development kit that offers tools and APIs for creating apps that are based on video and audio. It typically includes features such as video and audio calls, chat, cloud recording, simulcasting (RTMP), interactive live streaming (HLS), and many more across a wide range of platforms and devices.

## Concepts

![img.png](../../../../static/img/room-concept.png)

### `1. Meeting / Room`

- Meeting or Room object in the VideoSDK provide a virtual place for participants to interact and engage in real-time voice, video, and screen-sharing sessions. The object is in charge of handling media streams and participant communication.

- Meeting or Room can be uniquely identified by `meetingId` or `roomId`.

### `2. Participant`

- Participant is a VideoSDK object that represents each user/client in the meeting or room and allows them to share audio/video assets.

- `2.1 Local Participant` :
  The local participant is the one that runs on the user's device. The local participant has control over their own media streams, including the ability to start and stop audio and video.

  - The local participant in a meeting/room can also connect with other participants by transmitting and receiving audio and video streams, exchanging chat messages, and more.

- `2.2 Remote Participant` :
  The remote participant receives audio and video streams from the local participant and other remote participants and also has the ability to exchange audio, video, and chat messages with the local participant.

- Each participant in VideoSDK can be uniquely identified by `participantId`.

### `3. MediaStream & Track`

- A mediastream is a collection of audio & video tracks that can be transmitted between participants in real-time.

- A track is a continuous flow of audio or video data and can be thought of as a stream of media frames.

- A mediastream can contain multiple tracks. One video track for the video feed from the camera and one audio track for the audio feed from the microphone. These tracks can be transmitted between participants in VideoSDK Meeting / Room.

### `4. Events / Notifications`

- Events / Notifications can be used to inform users about various activities happening in a Meeting / Room, including participant join/leave and new messages. They can also be used to alert users about any SDK-level errors that occur during a call.

### `5. Session`

- A Session is the instance of an ongoing meeting/room which has one or more participants in it. A single room or meeting can have multiple sessions.
- Each session can be uniquely identified by `sessionId`.

![img.png](../../../../static/img/meeting-session.jpg)

---

![img.png](../../../../static/img/recording-hls-rtmp.png)

### `6. Cloud Recording`

- Cloud recording in VideoSDK refers to the process of recording audio or video content and storing it on a remote server or VideoSDK server.

### `7. Simulcasting (RTMP)`

- RTMP is a popular protocol for live streaming video content from a VideoSDK to platforms such as YouTube, Twitch, Facebook, and others.
- By providing the platform-specific `stream key` and `stream URL`, the VideoSDK can connect to the platform's RTMP server and transmit the live video stream.

### `8. Http Live Streaming (HLS)`

- Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

- In an interactive live stream (HLS), viewers can take part in a variety of activities like live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

## Architecture

This diagram demonstrates end-to-end flow to implement video & audio calls, record calls, and go live on social media.

![Video-sdk-architecture!](/img/video-sdk-archietecture.svg)


---

# Custom Audio Sources - iOS

For a high-quality streaming experience, fine-tuning audio tracks becomes essential—especially when delivering content to a broader live audience.

To enhance your live audio pipeline, we've introduced the capability to provide a custom audio track for a hosts's stream both before and during a live session.


### `How to Create Custom Audio Track ?`

- You can create a Audio Track using `createAudioTrack()` method of `VideoSDK` class.

- This method can be used to create audio track using different noise configurations.

#### Example



**Swift:**

```js
guard let audioMediaTrack = try? VideoSDK.createAudioTrack(
 		noiseConfig: noiseConfig(
        //highlight-next-line
        // It is used to improve the quality of audio by removing background noise
        //highlight-next-line
        // that can interfere with the clarity of speech.
        noiseSupression: true, 

        //highlight-next-line
        // It is used to remove unwanted echoes from voice.
        echoCancellation: true, 

        //highlight-next-line
        // It is used to maintain a consistent level of loudness or amplitude in a voice.
        autoGainControl: true, 

        //highlight-next-line
        // It removes low frequency sounds hence making the audio clearer.
        highPassFilter: true
)
) else {return}
```


### `How to Setup Custom Audio Track ?`

The custom track can be set up both before and after the initialization of the meeting.

1. [Setting up a Custom Track during the initialization of a meeting](#1-setting-up-a-custom-track-during-the-initialization-of-a-meeting)
2. [Setting up a Custom Track with methods](#2-setting-up-a-custom-track-with-methods)

##### 1. Setting up a Custom Track during the initialization of a meeting

If you are passing `micEnabled: true` in the `initMeeting` of `VideoSDK` and want to use custom tracks from start of the meeting, you can pass custom track in the `initMeeting` as shown below.

:::caution
Custom Track will not apply on `micEnabled: false` configuration.
:::

##### Example

**Swift:**

```js
//highlight-start
guard let customAudioStream = try? VideoSDK.createAudioTrack(
 		noiseConfig: noiseConfig(
        noiseSupression: true, 
        echoCancellation: true, 
        autoGainControl: true, 
        highPassFilter: true
)
) else {return}
//highlight-end

let meeting = VideoSDK.initMeeting(
  meetingId: meetingId,
  participantName: name,
  micEnabled: true, // when passed true, it creates an audio track with defined configs
  webcamEnabled: cameraEnabled // optional, default: true

  // Pass the custom audio track here which will be used to when mic is auto started
  //highlight-next-line
  customAudioStream: customAudioStream
)
```

#### 2. Setting up a Custom Track with methods

In order to switch tracks during the meeting, you have to pass the `customAudioStream` in the `unmuteMic()` method of `Meeting`.

:::tip
Make sure to call `muteMic()` before you create a new track as it may lead to unexpected behavior.
:::

##### Example

**Swift:**

```js
@IBAction func unmuteButtonTapped(_ sender: Any) {
  if !on {
//highlight-start
guard
  let audioMediaTrack = try? VideoSDK.createAudioTrack(
    noiseConfig: noiseConfig(
        noiseSupression: true,
        echoCancellation: true,
        autoGainControl: true,
        highPassFilter: true
    )
  )
else { return }
//highlight-end

self.meeting?.unmuteMic(customAudioStream: audioMediaTrack)
  } else {
self.meeting?.muteMic()
  }
}
```

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [Custom Audio Track](/ios/api/sdk-reference/custom-tracks#custom-audio-track)


---

# Custom Video Sources - iOS

To deliver high-quality livestreams, it's essential to fine-tune the video tracks being broadcasted. Whether you’re hosting a webinar, or streaming an event, using custom video tracks gives you better control over stream quality and performance.

## Custom Video Track

In a livestream, your webcam feed plays a central role. With custom video tracks, you can:
- Define the resolution and frame rate using encoder settings. and camera facing mode for livestream.

### `How to Create a Custom Video Track ?`

- You can create a Video Track using `createCameraVideoTrack()` method of `VideoSDK` class.

- This method can be used to create video track using different encoding parameters and camera facing mode, it return `RTCVideoTrack?`.

#### Example



**Swift:**

```javascript
import WebRTC
guard let videoMediaTrack = try? VideoSDK.createCameraVideoTrack(
  // highlight-next-line
  // This will accept the enum value of CustomVideoTrackConfig which contains resolution (height x width) of video you want to capture.
  encoderConfig: .h720p_w1280p, // .h540p_w960p | .h720p_w1280p ... // Default : .h360p_w640p

  // highlight-next-line
  // It will specify whether to use front or back camera for the video track.
  facingMode: .front, // .back,  Default : .front

  // highlight-next-line
  // We will discuss this parameter in next step.
  multiStream:true // false,  Default : true

  // highlight-next-line
  // A video codec for compresses video data for efficient transmission over the internet, balancing quality and bandwidth usage.
  codec: .H264 // Default: .VP8

) else { return}
```

:::caution
The capabilities of the device have a significant impact on how custom track configurations behave. Assuming a case where you set encoder configuration to 1080p but the webcam only supports 720p, then encoder configuration will automatically switch to the highest resolution that the device can handle, which is 720p.
:::

##### What is `multiStream`?

- It will specify if the stream should send multiple resolution layers or single resolution layer.

**`multiStream : true`** By default, VideoSDK sends multiple resolution video streams to the server (whether you are using custom video track or not), For instance, user device capabilty is 720p, so VideoSDK sends 720p along with 640p and 480p streams. This allows VideoSDK to deliver the appropriate stream to each participant based on their network bandwidth.

<center>

![Multi Stream False](/img/multistream_true.png)

</center>

**`multiStream : false`** If you want to restrict the VideoSDK to send only one stream to maintain quality, you can set `multiStream` to `false`.

<center>

![Multi Stream False](/img/multistream_false.png)

</center>

:::danger
`setQuality` would not have any effect if multiStream is set to `false`.
:::

### `How to Setup a Custom Video Track ?`

The custom track can be set up both before and after the initialization of the meeting.

1. [Setting up a Custom Track during the initialization of a meeting](#1-setting-up-a-custom-track-during-the-initialization-of-a-meeting)
2. [Setting up a Custom Track with methods](#2-setting-up-a-custom-track-with-methods)

##### 1. Setting up a Custom Track during the initialization of a meeting

If you are passing `webcamEnabled: true` in the `createRoom` and want to use custom tracks from start of the meeting, you can pass custom track in the `customCameraVideoTrack` as shown below.

:::caution

- Custom Track will not apply on `webcamEnabled: false` configuration.

- Custom video track's `facingMode` takes precedence over the `cameraPosition` specified during the `join` method. Ensure you set `facingMode` appropriately to achieve the desired camera orientation.

:::

##### Example

**Swift:**

```javascript
import VideoSDKRTC

guard let videoMediaTrack = try? VideoSDK.createCameraVideoTrack(
encoderConfig: .h720p_w1280p,
facingMode: .front,
multiStream: true,
codec: .H264 // .VP8
) else {
return
}

let meeting = VideoSDK.initMeeting(
meetingId: meetingId,
participantName: name,
micEnabled: micEnabled, // optional, default: true
webcamEnabled: cameraEnabled, // optional, default: true
// highlight-next-line
// Pass the custom track here which will be used to when webcam is auto started
customCameraVideoStream: customVideoStream
)

```

#### 2. Setting up a Custom Track with methods

In order to switch tracks during the meeting, you have to pass the `CustomTrack` in the **`enableWebCam()`** method of `Room`.

:::tip
Make sure to call `disableCam()` before you create a new track as it may lead to unexpected behavior.
:::

##### Example

**Swift:**

```javascript
import VideoSDKRTC

@IBAction func videoButtonTapped(_ sender: Any) {
if !on {
    guard let videoMediaTrack = try? VideoSDK.createCameraVideoTrack(
        encoderConfig: .h360p_w480p,
        facingMode: .front,
        multiStream: false,
        codec: .H264 // .VP8
    ) else {
        return
    }
    self.meeting?.enableWebcam(customVideoStream: videoMediaTrack)
} else {
    self.meeting?.disableWebcam()
}
}
```


### `Which Configuration is suitable for Device ?`

In this section, we will understand participant size wise `encoder(Resolution)` and `multiStream` configuration.

<center>
<img src='https://cdn.videosdk.live/website-resources/docs-resources/mobile_device_config.png' />
</center>

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [Custom Video Track](/ios/api/sdk-reference/custom-tracks)


---

# Customized Live Stream - iOS

VideoSDK is a platform that offers a range of video streaming tools and solutions for content creators, publishers, and developers.

### Custom Template

- Custom template is template for live stream, which allows users to add real-time graphics to their streams.
- With custom templates, users can create unique and engaging video experiences by overlaying graphics, text, images, and animations onto their live streams. These graphics can be customized to match the branding.
- Custom templates enable users to create engaging video content with real-time graphics, with live scoreboards, social media feeds, and other customizations, users can easily create unique and visually appealing streams that stands out from the crowd.

:::note

Custom templates can be used with recordings and RTMP service provided by VideoSDK as well.

:::

### What you can do with Custom Template

Using a custom template, you may create a variety of various modes. Here are a few of the more well-known modes that you can create.

- **`PK Host:`** Host can organise player vs player battle. Below image is example of gaming battle.

- **`Watermark:`** Host can add & update watermark anywhere in the template. In below image we have added VideoSDK watermark on top right side of the screen.

- **`News Mode:`** Host can add dynamic text in lower third banner. in below image we have added some sample text in bottom left of the screen.

![Mobile Custom Template ](https://cdn.videosdk.live/website-resources/docs-resources/mobile_custom_template.png)

## Custom template with VideoSDK

In this section, we will discuss how Custom Templates work with VideoSDK.

- **`Host`**: The host is responsible for starting the live streaming by passing the `templateURL`. The `templateURL` is the URL of the hosted template webpage. The host is also responsible for managing the template, such as changing text, logos, and switching template layout, among other things.

- **`VideoSDK Template Engine`** : The VideoSDK Template Engine accepts and opens the templateURL in the browser. It listens to all the events performed by the Host and enables customization of the template according to the Host's preferences.

- **`Viewer`**: The viewer can stream the content. They can watch the live stream with the added real-time graphics, which makes for a unique and engaging viewing experience.

![custom template](https://cdn.videosdk.live/website-resources/docs-resources/custom_template.png)

### Understanding Template URL

The template URL is the webpage that VideoSDK Template Engine will open while composing the live stream.

The template URL will appear as shown below.

![template url](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_url.png)

The Template URL consists of two parts:

- Your actual page URL, which will look something like `https://example.com/videosdk-template`.
- Query parameters, which will allow the VideoSDK Template Engine to join the meeting when the URL is opened. There are a total of three query parameters:
  - `token`: This will be your token, which will be used to join the meeting.
  - `meetingId`: This will be the meeting ID that will be joined by the VideoSDK Template Engine.
  - `participantId`: This will be the participant ID of the VideoSDK Template Engine, which should be passed while joining the template engine in your template so that the tempalte engine participant is not visible to other participants. **This parameter will be added by the** **VideoSDK**.

:::info

Above mentioned query parameters are mandatory. Apart from these parameters, you can pass any other extra parameters which are required according to your use-case.

:::

### **Creating Template**

**`Step 1:`** Create a new React App using the below command

```js
npx create-react-app videosdk-custom-template
```

:::note

You can use VideoSDK's React or JavaScript SDK to create custom template. Following is the example of building custom template with React SDK.

:::

**`Step 2:`** Install the VideoSDK using the below-mentioned npm command.

Make sure you are in your react app directory before you run this command.

```js
npm install "@videosdk.live/react-sdk"

//For the Participants Video
npm install "react-player"
```

###### App Architecture

![template architechture](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_arch.png)

###### Structure of the Project

```jsx title="Project Structure"
   root
   ├── node_modules
   ├── public
   ├── src
   │    ├── components
   │          ├── MeetingContainer.js
   │          ├── ParticipantsAudioPlayer.js
   │          ├── ParticipantsView.js
   │          ├── Notification.js
   │    ├── icons
   │    ├── App.js
   │    ├── index.js
   ├── package.json
   .
```

**`Step 3:`** Next we will fetch the query parameters, from the URL which we will later use to initialize the meeting

```js title=App.js
function App() {
  const { meetingId, token, participantId } = useMemo(() => {
    //highlight-start
    const location = window.location;

    const urlParams = new URLSearchParams(location.search);

    const paramKeys = {
      meetingId: "meetingId",
      token: "token",
      participantId: "participantId",
    };

    Object.keys(paramKeys).forEach((key) => {
      paramKeys[key] = urlParams.get(key)
        ? decodeURIComponent(urlParams.get(key))
        : null;
    });

    return paramKeys;
    //highlight-end
  }, []);
}
```

**`Step 4:`** Now we will initialize the meeting with the parameters we extracted from the URL. Make sure `joinWithoutUserInteraction` is specified, so that the template engine is able to join directly into the meeting, on the page load.

```js title=App.js
function App(){
//highlight-next-line
...

return meetingId && token && participantId ? (
  <div>
    
    </MeetingProvider>
  </div>
) : null;

}
```

**`Step 5:`** Let us create the `MeetingContainer` which will render the meeting view for us.

- It will also listen to the PubSub messages from the `CHANGE_BACKGROUND` topic, which will change the background color of the meeting.
- It will have `Notification` component which will show any messages share by Host

:::note

We will be using the PubSub mechanism to communicate with the template. You can learn more about [PubSub from here](../video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

:::




```js title=MeetingContainer.js




export const MeetingContainer = () => {
  const { isMeetingJoined, participants, localParticipant } = useMeeting();
  //highlight-next-line
  const { messages } = usePubSub("CHANGE_BACKGROUND");

  const remoteSpeakers = [...participants.values()].filter((participant) => {
    return (
      participant.mode == Constants.modes.SEND_AND_RECV && !participant.local
    );
  });

  return isMeetingJoined ? (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        height: "100vh",
        //highlight-start
        backgroundColor:
          messages.length > 0
            ? messages.at(messages.length - 1).message
            : "#fff",
        //highlight-end
      }}
    >
      //highlight-next-line
      
      <div
        style={{
          display: "grid",
          gridTemplateColumns: remoteSpeakers?.length > 1 ? "1fr 1fr" : "1fr",
          flex: 1,
          maxHeight: `100vh`,
          overflowY: "auto",
          gap: "20px",
          padding: "20px",
          alignItems: "center",
          justifyItems: "center",
        }}
      >
        {[...remoteSpeakers].map((participant) => {
          return (
            //highlight-start
            
            //highlight-end
          );
        })}
      </div>
      //highlight-next-line
      
    </div>
  ) : (
    <div
      style={{
        display: "flex",
        justifyContent: "center",
        alignItems: "center",
        height: "100vh",
      }}
    >
      <div class="loader"></div>
    </div>
  );
};
```

**`Step 6:`** Let us create the `ParticipantView` and `ParticipantsAudioPlayer` which will render the video and audio of the participants respectively.

```js title=ParticipantView.js




export const ParticipantView = (props) => {
  const { webcamStream, webcamOn, displayName, micOn } = useParticipant(
    props.participantId
  );

  const videoStream = useMemo(() => {
    if (webcamOn && webcamStream) {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(webcamStream.track);
      return mediaStream;
    }
  }, [webcamStream, webcamOn]);

  return (
    <div
      style={{
        width: "100%",
        height: "400px",
        maxWidth: "600px",
        display: "flex",
        flex: 1,
        alignItems: "center",
        justifyContent: "center",
        position: "relative",
        backgroundColor: "#1A1C22",
        borderRadius: "10px",
        overflow: "hidden",
      }}
      class="video-cover"
    >
      {webcamOn && webcamStream ? (
        
      ) : (
        <div
          style={{
            fontSize: "50px",
            color: "#fff",
          }}
        >
          {String(displayName).charAt(0).toUpperCase()}
        </div>
      )}
      <div
        style={{
          position: "absolute",
          left: "10px",
          bottom: "10px",
          backgroundColor: "#050A0E",
          color: "#fff",
          padding: "4px",
          borderRadius: "4px",
          alignItems: "center",
          justifyItems: "center",
          display: "flex",
        }}
      >
        {displayName}{" "}
        {!micOn && }
      </div>
    </div>
  );
};
```

```js title=ParticipantsAudioPlayer.js


const ParticipantAudio = ({ participantId }) => {
  const { micOn, micStream, isLocal } = useParticipant(participantId);
  const audioPlayer = useRef();

  useEffect(() => {
    if (!isLocal && audioPlayer.current && micOn && micStream) {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(micStream.track);

      audioPlayer.current.srcObject = mediaStream;
      audioPlayer.current.play().catch((err) => {});
    } else {
      audioPlayer.current.srcObject = null;
    }
  }, [micStream, micOn, isLocal, participantId]);

  return <audio autoPlay playsInline controls={false} ref={audioPlayer} />;
};

export const ParticipantsAudioPlayer = () => {
  const mMeeting = useMeeting();

  const participants = mMeeting?.participants;

  return participants ? (
    [...participants.keys()].map((participantId) => (
      
    ))
  ) : (
    <></>
  );
};
```

**`Step 7:`** Let us create the `Notification` component which will listen to PubSub messages for the topic `VIEWER_MESSAGE` and show a notification on the lower left corner.

```js title=Notification.js


export const Notification = () => {
  const timeoutRef = useRef(null);
  const handleChatMessage = (msg) => {
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
    }
    setMessage(msg);
    timeoutRef.current = setTimeout(() => {
      setMessage(null);
    }, 3200);
  };
  const [message, setMessage] = useState(null);
  const { publish } = usePubSub("VIEWER_MESSAGE", {
    onMessageReceived: handleChatMessage,
  });
  useEffect(() => {
    return () => {
      if (timeoutRef.current) {
        clearTimeout(timeoutRef.current);
      }
    };
  }, []);
  return message ? (
    <div
      style={{
        backgroundColor: "#232830",
        padding: "10px",
        textAlign: "center",
        color: "#fff",
        position: "absolute",
        bottom: "50px",
        left: "30px",
        borderRadius: "10px",
        animation: "fadein 0.5s",
      }}
    >
      <strong>
        {message.senderName} says {message.message}
      </strong>
    </div>
  ) : null;
};
```

:::note

For the CSS stylings and animations used in the project, please [refer to this file](https://github.com/videosdk-live/quickstart/blob/main/react-custom-template-manager/src/index.css).

:::

**`Step 9:`** Once tested, you can deploy it using your backend or host it on services like [firebase](https://www.geeksforgeeks.org/how-to-deploy-react-project-on-firebase/) or vercel.

:::tip

You can checkout the github repository for sample custom template we just [created here](https://github.com/videosdk-live/videosdk-custom-recording-template-react-example).

:::

### Setup Livestream Using Custom Template

- To use Custom Template, you will need Host and Viewer setup from where the host will start the livestream and viewer can watch them.

![iOS Custom Template Example](https://cdn.videosdk.live/website-resources/docs-resources/ios_custom_template.png)

- You can clone this example and run it on your system.

```bash
git clone https://github.com/videosdk-live/quickstart.git
```

- The cloned example will contain one directory named as `ios-hls` which has to run.



**Swift:**

```swift
cd ios-hls
```

- To use the custom template which we just deployed, we will call the [Start HLS API](https://docs.videosdk.live/api-reference/realtime-communication/start-hlsStream) instead of the `startHls` method from the `Meeting` class. This code has already been added in the example you cloned with comments and NOTE for more information.

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

**Swift:**

```swift
func startHLS(meetingId: String, token: String) {
  //Update your Custom Template URL here if you have deployed your own, if not deployed you can use this template from our URL.
//highlight-start
let templateUrl = "TEMPLATE_URL"
//highlight-end

let body: [String: Any] = [
    "roomId": meetingId,
    "templateUrl": templateUrl,
    "config": [
        "orientation": "portrait"
    ]
]

guard let url = URL(string: "https://api.videosdk.live/v2/hls/start") else { return }

var request = URLRequest(url: url)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue(token, forHTTPHeaderField: "Authorization")
request.httpBody = try? JSONSerialization.data(withJSONObject: body)

URLSession.shared.dataTask(with: request) { data, response, error in
    if let error = error {
        print("API Error:", error.localizedDescription)
        return
    }
    guard let data = data else {
        print("No response data")
        return
    }
    do {
        let json = try JSONSerialization.jsonObject(with: data, options: [])
        print("HLS Response:", json)
    } catch {
        print("JSON Parse Error:", error)
    }
}.resume()
}
```

- This example has two option on the Host side which will allow them to change the background and send the messages to the viewer.

- Let's give this example a test run.


<div style={{textAlign: 'center'}}>



</div>
<br/>


:::tip

You can check out this [iOS example code](https://github.com/videosdk-live/quickstart/tree/main/ios-custom-template-manager) for custom template manager on GitHub

:::

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start HLS API](/api-reference/realtime-communication/start-hlsStream)
- [onHlsStateChanged](/ios/api/sdk-reference/meeting-class/events#onhlsstatechanged)


---

# Manage Audio and Video Devices - iOS

This feature allows hosts to switch their microphone, speaker, or camera devices during a live stream. Only hosts (in `SEND_AND_RECV` mode) can change input/output devices, ensuring they maintain control over their audio and video quality, while audience members (in `RECV_ONLY` mode) continue to receive the broadcast seamlessly.

### Changing Audio Input Device

###### `getMics()`

- The `getMics()` method will return an array of tuples, where each tuple consists of two elements deviceName and deviceType.

- returns `[deviceName: String, deviceType: String]`

#### Example


**Swift:**

```js
//highlight-next-line
let devices = meeting.getMics()
for device in devices {
print(device.deviceName)  //sample output [("Speaker","Speaker"), ("iPhone Microphone", "Receiver")]
}
```

###### `changeMic()`
- Participant can change the audio device using `changeMic(selectedDevice: String)` method of `Meeting` classs

#### Example

**Swift:**

```swift
func changeAudioDevice(device: String) {
changeMic(selectedDevice: "Speaker") //output will be changed to speaker
}
```

:::caution
 selectedDevice string should only be from the deviceName that you get from the returned array of `getMics()`.
:::

## Changing Camera Input Device

###### `switchWebcam()`

- By using `switchWebcam()` function, a participant can stream from front / rear camera during the meeting.

#### Example

**Swift:**

```js
/// keep track of camera position
private var cameraPosition = CameraPosition.front

@IBAction func cameraButtonTapped(_ sender: Any) {
cameraPosition.toggle()

// switch camera to front/back
// Values: .front, .back
//highlight-next-line
self.meeting?.switchWebcam(position: cameraPosition)
}
```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [switchWebcam()](/ios/api/sdk-reference/meeting-class/methods#switchwebcam)
- [getMics()](/ios/api/sdk-reference/meeting-class/methods#getmics)
- [changeMic()](/ios/api/sdk-reference/meeting-class/methods#changemic)
- [onMicChanged()](/ios/api/sdk-reference/meeting-class/events#onmicchanged)



---

# Mute / Unmute Mic - iOS

This feature allows hosts to communicate with each other during the livestream by enabling or disabling their microphones. While only hosts (participants in SEND_AND_RECV mode) can speak, audience members (in RECV_ONLY mode) can listen to the conversation in real time.

### `unmuteMic()`

- By using `unmuteMic()` function of `Meeting` class, the host can publish their audio to other hosts and audience members.

- You can call this method when the local participant is not broadcasting any audio to others.

- Audio stream of the participant can be accessed from the `onStreamEnabled` event of `ParticipantEventListener`.

### `muteMic()`

- By using `muteMic()` function of `Meeting` class, the host can stop publishing their audio to other hosts and audience members.

#### Example
### Example


**Swift:**

```js
@IBAction func micButtonTapped(_ sender: Any) {
if !micEnabled {
    // enable/unmute mic
    //highlight-next-line
    self.meeting?.unmuteMic()
} else {
    // disable/mute mic
    //highlight-next-line
    self.meeting?.muteMic()
}
}
```

### Events associated with `unmuteMic`

- Every Participant will receive a callback on [`onStreamEnabled()`](/ios/api/sdk-reference/participant-class/events#onstreamenabled) of the [`Participant`](/ios/api/sdk-reference/participant-class/introduction) with `Stream` object.

### Events associated with `muteMic`

- Every Participant will receive a callback on [`onStreamDisabled()`](/ios/api/sdk-reference/participant-class/events#onstreamdisabled) of the [`Participant`](/ios/api/sdk-reference/participant-class/introduction) with `Stream` object.


### Audio Permissions

- **`Step 1:`** Begin by ensuring that your application has audio permission to access user's microphone device. Utilize the `getAudioPermissionStatus()` method of the `VideoSDK` class to verify if permissions are granted. If the permissions are not granted, the method will request the required permissions.

:::note

In case permissions are blocked by the user, the app's permission request dialogue cannot be re-rendered programmatically. In such cases, consider providing guidance to users on manually adjusting their application settings.

:::

**Swift:**

```js
let audioPermission = VideoSDK.getAudioPermissionStatus(); // audio permission status
```

#### **Request Permissions**

- If permission status is `notDetermined`, use the `getAudioPermission()` methods of the `VideoSDK` class to prompt users to grant access to their devices.

- Calling the above functions will automatically handle the notDetermined state and prompt the user to grant permission.

**Swift:**

```js
class LiveStreamViewController: UIViewController {

override func viewDidLoad() {
    super.viewDidLoad()

    // UI Setup
    setupUI()

    // prompt user to grant permission when the app starts
    VideoSDK.getAudioPermission()
}

func setupUI() {
    // your UI code
}
}
```


## API Reference

The API references for all the methods and events utilized in this guide are provided below.


- [unmuteMic()](/ios/api/sdk-reference/meeting-class/methods#unmutemic)
- [muteMic()](/ios/api/sdk-reference/meeting-class/methods#mutemic)
- [onStreamEnabled()](/ios/api/sdk-reference/participant-class/events#onstreamenabled)
- [onStreamDisabled()](/ios/api/sdk-reference/participant-class/events#onstreamdisabled)
- [getAudioPermissionStatus()](/ios/api/sdk-reference/videosdk-class/methods#getaudiopermissionstatus)
- [getAudioPermission()](/ios/api/sdk-reference/videosdk-class/methods#getaudiopermission)


---

---
title: On / Off Camera | Video SDK
hide_title: true
hide_table_of_contents: false
description: Camera Controls features quick integrate in Javascript, React JS, Android, IOS, React Native, Flutter with Video SDK to add live video & audio conferencing to your applications.
sidebar_label: On / Off Camera
pagination_label: On / Off Camera
keywords:
  - audio calling
  - video calling
  - real-time communication
  - collaboration
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: on-off-camera
--- 

# On / Off Camera - iOS

This feature enables hosts to turn their cameras on or off to share their video stream with other hosts and audience members during the meeting. Only hosts (in `SEND_AND_RECV` mode) can broadcast their camera feed, while audience members (in `RECV_ONLY` mode) can view it in real time.

### `enableWebcam()`

- By using `enableWebcam()` function of `Meeting` class, the host can publish their video to to other hosts and audience members.

- You can also pass a customised video track in `enableWebcam()` by using [Custom Video Track](/ios/guide/interactive-live-streaming/custom-media-sources/custom-video-sources).

- Video stream of the participant can be accessed from the `onStreamEnabled` event of `ParticipantEventListener`.

### `disableWebcam()`

- By using `disableWebcam()` function of `Meeting` class, the host can stop publishing their video to to other hosts and audience members.

#### Example



**Swift:**

```js
@IBAction func videoButtonTapped(_ sender: Any) {
if !videoEnabled {
    // enable webcam/camera
    //highlight-next-line
    self.meeting?.enableWebcam()
} else {
    // disable webcam/camera
    //highlight-next-line
    self.meeting?.disableWebcam()
}
}
```

### Events associated with `enableWebcam`

- Every Participant will receive a callback on [`onStreamEnabled()`](/ios/api/sdk-reference/participant-class/events#onstreamenabled) of the [`Participant`](/ios/api/sdk-reference/participant-class/introduction) with `Stream` object.

### Events associated with `disableWebcam`

- Every Participant will receive a callback on [`onStreamDisabled()`](/ios/api/sdk-reference/participant-class/events#onstreamdisabled) of the [`Participant`](/ios/api/sdk-reference/participant-class/introduction) with `Stream` object.


### Video Permissions

# User Readiness Check - iOS

Before a user can engage with an live stream, the system must ensure that all necessary permissions—such as microphone access—are granted. This prevents technical issues and ensures a seamless interaction over livestream.

- **`Step 1:`** Begin by ensuring that your application has video/audio permission to access user's microphone and camera device. Utilize the `getVideoPermissionStatus()`method of the `VideoSDK` class to verify if permissions are granted. If the permissions are not granted, the method will request the required permissions.

:::note

In case permissions are blocked by the user, the app's permission request dialogue cannot be re-rendered programmatically. In such cases, consider providing guidance to users on manually adjusting their application settings.

:::

**Swift:**

```js
let audioPermission = VideoSDK.getVideoPermissionStatus(); // video permission status
```

#### **Request Permissions (if necessary)**

- If permission status is `notDetermined`, use the `getVideoPermission()` methods of the `VideoSDK` class to prompt users to grant access to their devices.

- Calling the above functions will automatically handle the notDetermined state and prompt the user to grant permission.

**Swift:**

```js
class LiveStreamViewController: UIViewController {

override func viewDidLoad() {
    super.viewDidLoad()

    // UI Setup
    setupUI()

    // prompt user to grant permission when the app starts
    VideoSDK.getVideoPermission()

}

func setupUI() {
    // your UI code
}
}
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [enableWebcam()](/ios/api/sdk-reference/meeting-class/methods#enablewebcam)
- [disableWebcam()](/ios/api/sdk-reference/meeting-class/methods#disablewebcam)
- [onStreamEnabled()](/ios/api/sdk-reference/participant-class/events#onstreamenabled)
- [onStreamDisabled()](/ios/api/sdk-reference/participant-class/events#onstreamdisabled)
- [getVideoPermissionStatus()](/ios/api/sdk-reference/videosdk-class/methods#getvideopermissionstatus)
- [getVideoPermission()](/ios/api/sdk-reference/videosdk-class/methods#getvideopermission)

---

---
title: Screen Share | Video SDK
hide_title: true
hide_table_of_contents: false
description: Share your Screen features quick integrate in Javascript, React JS, Android, IOS, React Native, Flutter with Video SDK to add live video & audio conferencing to your applications.
sidebar_label: Screen Share
pagination_label: Screen Share
keywords:
  - audio calling
  - video calling
  - real-time communication
  - collaboration
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: screen-share
--- 

# Screen Share - iOS

This feature enables hosts to start or stop sharing their screen with other hosts and audience members during the live stream. Only hosts (in `SEND_AND_RECV` mode) can broadcast their screen, while audience members (in `RECV_ONLY` mode) can view it in real time.

### `enableScreenShare()`

- By using the `enableScreenShare()` function of the `Meeting` Class, the host can share their mobile screen to other hosts and audience members.

### `disableScreenShare()`

- By using the `disableScreenShare()` function of the `Meeting` Class, the host can stop sharing their desktop screen to other hosts and audience members.

But before calling the above method, we need to follow the steps below to set up screen sharing.

## Create Broadcast Upload Extension in iOS

### Step 1 : Open Target

Open your project with xcode, the select **File > New > Target** in menu bar.

![IOS Screen Share](/img/ios-screenshare/step1-xcode.png)

### Step 2 : Select Target

Select **Broadcast Upload Extension** and click next.

![IOS Screen Share](/img/ios-screenshare/step2-xcode.png)

### Step 3 : Configure Broadcast Upload Extension

Enter the extension's name in the **Product Name** field, choose the team from the dropdown, uncheck the "Include UI extension" field, and click "Finish."

![IOS Screen Share](/img/ios-screenshare/step3-xcode.png)

### Step 4 : Activate Extension scheme

You will be prompted with a popup : **Activate "Your-Extension-name" scheme?**, click on activate.

![IOS Screen Share](/img/ios-screenshare/step4-xcode.png)
 
Now, the "Broadcast" folder will appear in the Xcode left side bar.

![IOS Screen Share](/img/ios-screenshare/step5-xcode.png)

### Step 5 : Add External file in Created Extension

Open the [videosdk-rtc-ios-sdk-example](https://github.com/videosdk-live/videosdk-rtc-ios-sdk-example/tree/main/VideoSDKScreenShare) repository, and copy the following files: `SampleUploader.swift`, `SocketConnection.swift`, `DarwinNotificationCenter.swift`, and `Atomic.swift` to your extension's folder. Ensure that these files are added to the target.

### Step 6 : Update `SampleHandler.swift` file

Open [SampleHandler.swift](https://github.com/videosdk-live/videosdk-rtc-ios-sdk-example/blob/main/VideoSDKScreenShare/SampleHandler.swift), and copy the content of the file. Paste this content into your extension's SampleHandler.swift file.

### Step 7 : Add Capability in App

In Xcode, navigate to **YourappName > Signing & Capabilities**, and click on **+Capability** to configure the app group.

![IOS Screen Share](/img/ios-screenshare/step8-xcode.png)

Choose **App Groups** from the list.

![IOS Screen Share](/img/ios-screenshare/step9-xcode.png)
 
After that, select or add the generated App Group ID that you have created before.

![IOS Screen Share](/img/ios-screenshare/step10-xcode.png)

### Step 8 : Add Capability in Extension

Go to **Your-Extension-Name > Signing & Capabilities** and configure **App Group** functionality which we had perform in previous steps. (Group id should be same for both targets).

![IOS Screen Share](/img/ios-screenshare/step11-xcode.png)

### Step 9 : Add App Group Id in Extension File

Go to the extension's `SampleHandler.swift` file and paste your group ID in the `appGroupIdentifier` constant.

![IOS Screen Share](/img/ios-screenshare/step12-xcode.png)

### Step 10 : Update App level info.plist file

1.  Add a new key **RTCScreenSharingExtension** in Info.plist with the extension's Bundle Identifier as the value.
2.  Add a new key **RTCAppGroupIdentifier** in Info.plist with the extension's App groups Id as the value.

**Note** : For the extension's Bundle Identifier, go to **TARGETS > Your-Extension-Name > Signing & Capabilities** .

![IOS Screen Share](/img/ios-screenshare/step13-xcode.png)

:::note

You can also check out the extension's [example code](https://github.com/videosdk-live/videosdk-rtc-ios-sdk-example/tree/main/VideoSDKScreenShare) on github.
:::

## Integrate ScreenShare in your App

After successfully creating Broadcast Upload Extension using the above listed steps, we can start using the `enableScreenShare` and `disableScreenShare` functions of the `Meeting` class.

### How to use the ScreenShare functions



**Swift:**

```js
@IBAction func ScreenShareButtonTapped(_ sender: Any) {
Task {
  self.meeting?.enableScreenShare()
}
}

@IBAction func StopScreenShareButtonTapped(_ sender: Any) {
Task {
  self.meeting?.disableScreenShare()
}
}
```

:::caution
  The function `enableScreenShare` and `disableScreenShare` are async functions; therefore use above syntax to call the screenshare functions.
:::

Calling the `enableScreenShare()` will prompt a `RPBroadcastPickerView` with the extension that was created using the above steps.

![IOS Screen Share](/img/ios-screenshare/step23-xcode.png)

After clicking the **Start Broadcast** button, you will be able to get the screen share stream in the session.

- When the broadcast is started, it creates a Stream that has `MediaStream.kind = .share`. Using the stream kind, you can prompt a ScreenShare view for remote peer when ScreenShare is started by the local peer.

- Similarly, you can use the same kind to dismiss the screenshare view on the remote peer when the screenshare was stopped.

### Example

**Swift:**

```js
extension MeetingViewController: ParticipantEventListener {
/// Participant has enabled mic, video or screenshare
/// - Parameters:
///   - stream: enabled stream object
///   - participant: participant object
func onStreamEnabled(_ stream: MediaStream, forParticipant participant: Participant) {
    
    if stream.kind == .share {
    // show screen share
        showScreenSharingView(true)
        screenSharingView.showMediastream(stream)
        return
    }
    
    // show stream in cell
    if let cell = self.cellForParticipant(participant) {
        cell.updateView(forStream: stream, enabled: true)
    }
    
    if participant.isLocal {
    // turn on controls for local participant
        self.buttonControlsView.updateButtons(forStream: stream, enabled: true)
    }
}

/// Participant has disabled mic, video or screenshare
/// - Parameters:
/// - stream: disabled stream object
/// - participant: participant object
func onStreamDisabled(_ stream: MediaStream, forParticipant participant: Participant) {
    
    if stream.kind == .share {
    // remove screen share
        showScreenSharingView(false)
        screenSharingView.hideMediastream(stream)
        return
    }
    
    // hide stream in cell
    if let cell = self.cellForParticipant(participant) {
        cell.updateView(forStream: stream, enabled: false)
    }
    
    if participant.isLocal {
    // turn off controls for local participant
        self.buttonControlsView.updateButtons(forStream: stream, enabled: false)
    }
}
}
```

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [enableScreenShare()](/ios/api/sdk-reference/meeting-class/methods#enablescreenshare)
- [disableScreenShare()](/ios/api/sdk-reference/meeting-class/methods#disablescreenshare)
- [onStreamEnabled()](/ios/api/sdk-reference/participant-class/events#onstreamenabled)
- [onStreamDisabled()](/ios/api/sdk-reference/participant-class/events#onstreamdisabled)



---

# Geo Fencing - iOS


Our SDK includes a region geofencing feature to comply with local laws and regulations worldwide. It restricts connections to servers within specified regions, ensuring users connect only to designated areas, regardless of their location. 

This helps meet regional data protection requirements and enhances user experience by addressing geographical network limitations.




### In this sequence diagram:
- User 1 (India) tries to connect to a meeting. In a regular scenario, the meeting would connect to the India region, but due to the geofence configuration, the meeting will connect to North America.

## Considerations
- If the user’s location differs from the chosen region, the network quality between these locations may be poor, affecting audio and video quality.
- Avoid using geofencing unless your scenario requires regional compliance.

:::info

Geo Fencing is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Available Regions
- INDIA
- USA
- UAE
- EUROPE
- SINGAPORE
- AUSTRALIA



---

---
title: Host vs Audience Modes | Video SDK
hide_title: true
hide_table_of_contents: false
description: Understand the differences between Host and Audience modes in Video SDK's Interactive Live Stream (ILS), their capabilities, and how participants transition between them.
sidebar_label: Host vs Audience Modes
pagination_label: Host vs Audience Modes
keywords:
  - audio calling
  - video calling
  - real-time communication
  - collaboration
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: join-meeting
--- 

# Host vs Audience Modes - iOS

Before diving into implementation, it's important to understand the two core modes of participation in an `Interactive Live Stream (ILS)` session powered by VideoSDK:

### Mode Architecture

Here’s a visual representation of how these modes function within an ILS session:

![Interactive Live Streaming architecture diagram](https://assets.videosdk.live/images/interactive-live-streaming-architecture.png)


By clearly separating hosts from viewers, and offering seamless transitions between roles, VideoSDK ILS ensures high performance, low latency, and exceptional flexibility for all live streaming scenarios.

:::note

Throughout the rest of this documentation, whenever we mention "Host", we are specifically referring to a participant in the `SEND_AND_RECV` mode. Similarly, when we mention "Audience" or "Viewer", we are referring to participants in the `RECV_ONLY` mode. These distinctions are important, as each mode comes with its own set of capabilities and limitations.

:::

### `1. SEND_AND_RECV` – Host / Co-host Mode

This mode is designed for Hosts or Co-hosts who need to broadcast their audio and video to the audience and potentially interact with other hosts. Following is the list of everything a host is capable of:

- Publish and receive media (audio/video/screen share)
- Participate in conversations with other hosts
- Engage with the audience using chat, polls, reactions, and more
- Moderate the stage and manage participants
- Invite audience members on stage to become temporary broadcasters

🔢 Supports 100+ simultaneous hosts/co-hosts (Need more? Contact support@videosdk.live)


### `2. RECV_ONLY` – Audience Mode

This mode is optimized for audience members who are viewing the live stream and engaging via non-verbal interaction tools. Following is the list of everything audience is capable of:

- Receive media from all active hosts in real time (audio/video/screen share)
- No media publishing – cannot share their own audio/video unless promoted
- Engage via:
  - Live chat
  - Polls and quizzes
  - Reactions (emojis, claps, hearts, etc.)
  - Virtual gifts
  - Hand raise to request stage access

🔢 Scales to 2,000+ real-time viewers (Need more? Contact support@videosdk.live)

### Seamless Transition Between Modes

VideoSDK offers a dynamic role management system, making it easy to transition a participant from audience to stage. If a host invites an audience member on stage, they can seamlessly switch from `RECV_ONLY` mode to `SEND_AND_RECV` mode. This allows them to publish their audio/video and interact like a host or co-host. Once their role is revoked, they can return to the audience mode.



---

# Overview - iOS

Interactive Live Streaming (ILS) is a low-latency streaming solution designed for real-time engagement at scale. Unlike traditional streaming protocols like HTTP Live Streaming (HLS), which typically have a delay of 15–30 seconds, ILS offers latency as low as 300 milliseconds—making it ideal for experiences that rely on immediate interaction.

While originally designed for meetings, VideoSDK seamlessly adapts to live streaming—supporting 100+ simultaneous hosts/co-hosts (Need more? Contact support@videosdk.live) and 2,000+ real-time viewers (scalable on request). This flexible architecture empowers dynamic events with multiple speakers, performers, or presenters.

ILS is not just about watching—it's about participating. While hosts and co-hosts can interact via audio/video and screen share, the audience consumes the content in real time and engages through interactive features like chat, polls and virtual gifting.

:::info

If you're already using VideoSDK for meetings, throughout this documentation you will learn how to extend its capabilities to support interactive live streaming.
Much of the core structure remains the same, but you'll discover how to adapt roles, scale the audience, and integrate interactive features to build engaging live stream experiences—all using the familiar tools and APIs you're used to.

:::

### Key Benefits:

- `Ultra-low latency`: Sub-second delivery for seamless interaction

- `Multiple host support`: Up to 100 simultaneous broadcasters

- `Scalable viewer capacity`: Handle up to 2,000 real-time audience members

- `Interactive tools`: Chat, polls, virtual gifts, hand raise, and more

- `Cross-platform compatibility`: Works across mobile, web, and desktop

<img src="https://www.videosdk.live/_next/image?url=https%3A%2F%2Fcdn.videosdk.live%2Fwebsite-resources%2Fproduct-pages%2Fils%2Freal-time-streaming-multiple-host.jpg&w=2048&q=100" />

## When to Use ILS?

Use Interactive Live Streaming when you need to:

- Run virtual events with multiple speakers
- Engage your audience actively during webinars
- Host fitness or coaching sessions with feedback
- Stream concerts, shows, or ceremonies with real-time reactions
- Organize town halls, investor calls, or product launches
- Facilitate audio rooms for casual or topic-based discussions
- Power social experiences like live meetups, talent shows, or community hangouts

:::info

If your requirement is strictly one-way broadcasting where interactivity is minimal and latency isn't critical (e.g., sports highlights, pre-recorded shows), http live streaming (HLS) may be more appropriate. To learn more about HLS, go through the [documentation](/ios/guide/video-and-audio-calling-api-sdk/recording-and-live-streaming/interactive-livestream).

:::

---

# Display Attendees Count - iOS

In this guide, we will see how you can display the number of attendees in realtime.

:::note
Before going forward in this guide, do make sure all the attendees join the meeting with mode as `SIGNALLING_ONLY`
:::

- We will get the all the `participants` except local participant using `participants` property of the the `Meeting` class. With all the participants, we will filter out participants who have joined as a `SIGNALLING_ONLY` and then display that count.



**Swift:**

```swift
class LiveStreamViewController: ObservableObject {
//highlight-next-line
@Published var viewerParticipantCount: Int = 0

//...
}

extension LiveStreamViewController: MeetingEventListener {    
func onMeetingJoined() {
    //...
    //highlight-next-line
    viewerParticipantCount = 1
}

func onParticipantJoined(_ participant: Participant) {
    //...
    //highlight-start
    viewerParticipantCount +=
        meeting?.participants.values.count { $0.mode == .SIGNALLING_ONLY } ?? 0
    //highlight-end
}
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [participants](/ios/api/sdk-reference/meeting-class/properties#participants)


---

# Invite Guest on Stage - iOS

In this guide, we will see how you can request a viewer to join your livestream by using the `changeMode()`.




Let's first have a look at how we will be using the `PubSub` mechanism to acheive the requesting and switching of the participant's mode.

![invite-guest-pubsub](https://cdn.videosdk.live/website-resources/docs-resources/invite_guest_pubsub.png)

:::note
Before going forward in this guide, do make sure all the attendees join the meeting with mode as `SIGNALLING_ONLY` and the host joins with mode as `SEND_AND_RECV`
:::

### Step 1: Loading Viewer List

The host will see a list of participants who have joined as `SIGNALLING_ONLY` along with a button that, when selected, will invite that user to join the livestream.

Here we are using `List` to display viewer list with button.

```swift title="ParticipantListView"
struct ParticipantListView: View {
    let participants: [Participant]
    let participantCameraStatus: [String: Bool]
    let participantMicStatus: [String: Bool]
    let onClose: () -> Void
    let sendHostRequest: (Participant) -> Void

    @State private var requestedParticipantId: String?

    var body: some View {
        VStack(alignment: .leading) {
            HStack {
                Text("Participants (\(participants.count))")
                    .font(.headline)
                Spacer()
                Button("Close") {
                    onClose()
                }
                .foregroundColor(.blue)
            }
            .padding()

            List {
                ForEach(participants.indices, id: \.self) { index in
                    HStack {
                        Text("\(index + 1)")
                            .frame(width: 30, alignment: .leading)

                        // Participant name
                        Text(participants[index].displayName)
                            .frame(maxWidth: .infinity, alignment: .leading)

                        // Show "Host" or "Requested" tag
                        if participants[index].id == requestedParticipantId {
                            Text("Requested")
                                .font(.subheadline)
                                .foregroundColor(.orange)
                        } else if participants[index].mode == .SEND_AND_RECV {
                            Text("Host")
                                .font(.subheadline)
                                .foregroundColor(.blue)
                        }
                        if participants[index].isLocal != true {
                            // Camera status
                            Image(
                                systemName: participantCameraStatus[
                                    participants[index].id
                                ] ?? false ? "video.fill" : "video.slash.fill"
                            )
                            .foregroundColor(
                                participantCameraStatus[participants[index].id]
                                    ?? false ? .green : .red
                            )

                            // Mic status
                            Image(
                                systemName: participantMicStatus[
                                    participants[index].id
                                ] ?? false ? "mic.fill" : "mic.slash.fill"
                            )
                            .foregroundColor(
                                participantMicStatus[participants[index].id]
                                    ?? false ? .green : .red
                            )
                            .frame(width: 30)

                            // Option button to show options
                            Menu {
                                Button("Request to join as co-host") {
                                    requestedParticipantId =
                                        participants[index].id
                                    sendHostRequest(participants[index])
                                    onClose()
                                }
                            } label: {
                                Image(systemName: "ellipsis.circle.fill")
                                    .foregroundColor(.blue)
                            }
                        }
                    }
                    .padding(.vertical, 5)
                }
            }
        }
    }
}
```

- On the click of option menu button, host can request for being the co-host and request send via PubSub to the viewer, now viewer can accept and reject the request.



**Swift:**

```swift
struct LiveStreamView: View {
  @State private var showParticipantsList = false

   var body: some View {
    VStack {
      //...
      Button {
          showOptionSelector = true
      } label: {
          Image(systemName: "ellipsis")
              .font(.system(size: 20))
              .frame(width: 45, height: 45)
              .background(Color.white.opacity(0.3))
              .clipShape(RoundedRectangle(cornerRadius: 10))
              .foregroundColor(.white)
      }
      .confirmationDialog(
          "Select an Option", isPresented: $showOptionSelector) {
          //Other options...
          Button("Show Participants List") {
              showParticipantsList = true
          }
          Button("Cancel", role: .cancel) {}
      }
      //...
    }
    //highlight-start
    .sheet(isPresented: $showParticipantsList) {
        ParticipantListView(
            participants: controller.participants,
            participantCameraStatus: controller
                .participantCameraStatus,
            participantMicStatus: controller
                .participantMicStatus,
            onClose: { showParticipantsList = false },
            sendHostRequest: controller.sendTheHostRequest
        )
    }
    //highlight-end
   }
}
```

<center>

<img style={{height: '450px'}} src="https://cdn.videosdk.live/website-resources/docs-resources/ios_stage_request.png" />

</center>

### Step 2: Requesting a Viewer to Join Livestream

We have a Viewer list ready. Now, let us handle the click event for sending the request.

We will be using `HOSTREQUESTED` as the topic for PubSub.

**Swift:**

```swift
// sendTheHostRequest implementation to send request
func sendTheHostRequest(_ participant: Participant) {
let message = "Request for mode change your mode"
let senderName = participants.first?.displayName ?? "Unknown"
let senderId = participants.first?.id ?? "Unknown"
let payload = [
    "receiverId": participant.id,
    "senderName": senderName,
    "senderId": senderId,
]
Task {
    do {
        try await self.meeting?.pubsub.publish(
            topic: "HOSTREQUESTED",
            message: message,
            options: [:],
            payload: payload
        )
    } catch {
        print("Error while sending request to become host: \(error)")
    }
}
}
```

### Step 3: Showing Viewer Request Dialog

After implementing the Host requesting viewer to join the livestream, let's display the viewer's request dialogue and switch the `SIGNALLING_ONLY` mode to `SEND_AND_RECV`.

**Swift:**

```swift
struct LiveStreamView: View {
  @StateObject var controller: LiveStreamViewController
  
  var body: some View {
  VStack {
    //...
  }
  //highlight-start
  .alert(isPresented: $controller.showAlert) {
        if controller.showActionButtons {
            return Alert(
                title: Text(controller.alertTitle),
                message: Text(controller.alertMessage),
                primaryButton: .default(Text("Accept")) {
                    self.controller.acceptHostChange()
                },
                secondaryButton: .default(Text("Decline")) {
                    self.controller.declineHostChange()
                }
            )
        } else {
            return Alert(
                title: Text(controller.alertTitle),
                message: Text(controller.alertMessage),
                dismissButton: .default(Text("Okay")) {
                    self.controller.showAlert = false
                }
            )
        }
    }
    //highlight-end
  }
  
}

class LiveStreamViewController: ObservableObject {
  @Published var showAlert = false
  @Published var alertTitle = ""
  @Published var alertMessage = ""
  @Published var showActionButtons = false

  func showHostRequestAlert(participantId: String, participantName: String) {
  self.alertTitle = "Host Request"
  self.alertMessage =
      "\(participantName) has requested to become the host. Do you accept?"
  self.showAlert = true
  self.showActionButtons = true
  }

  func acceptHostChange() {
    let senderName = participants.first?.displayName ?? "Unknown"
    let recvID = requestFrom ?? "Unknown"
    let payload = [ "receiverId": recvID, "accpeterName": senderName ]
    Task {
        //highlight-next-line
        await meeting?.changeMode(.SEND_AND_RECV)
        do {
            try await self.meeting?.pubsub.publish(
                topic: "ACK",
                message: "ACCEPTED",
                options: [:],
                payload: payload)
        } catch { print("Error while accepting host request: \(error)") }
    }
}

func declineHostChange() {
    let senderName = participants.first?.displayName ?? "Unknown"
    let recvID = requestFrom ?? "Unknown"
    let payload = [ "receiverId": recvID, "accpeterName": senderName ]
    Task {
        do {
            try await self.meeting?.pubsub.publish(
                topic: "ACK",
                message: "DECLINED",
                options: [:],
                payload: payload)
        } catch { print("Error in declining host request: \(error)") }
    }
}
}

extension LiveStreamViewController: MeetingEventListener {

func onMeetingJoined() {
  //... subscribing the event of pubsub while joining the meeting to get the messages...
  Task {
    //highlight-start
    await meeting?.pubsub.subscribe(topic: "HOSTREQUESTED", forListener: self)
    await meeting?.pubsub.subscribe(topic: "ACK", forListener: self)
    //highlight-end
  }
}
}

extension LiveStreamViewController: PubSubMessageListener {
   func onMessageReceived(_ message: VideoSDKRTC.PubSubMessage) {
  print("Message Received:= " + message.message)
  switch message.topic {
    //... other cases
    case "HOSTREQUESTED":
      if message.senderId != participants.first?.id {
        let json = message.payload
        if !json.isEmpty {
            if let participantId = json["receiverId"] as? String,
                let participantName = json["senderName"] as? String
            {
                self.requestFrom = json["senderId"] as? String
                if participantId == participants.first?.id {
                    DispatchQueue.main.async {
                        self.showHostRequestAlert(
                            participantId: participantId,
                            participantName: participantName
                        )
                    }
                }
            }
        }
    }
    case "ACK":
      let json = message.payload
      if !json.isEmpty {
          if let toSendTo = json["receiverId"] as? String,
              let toPrintName = json["accpeterName"] as? String
            {
              if toSendTo == participants.first?.id {
                  if message.message == "ACCEPTED" {
                      DispatchQueue.main.async {
                          self.alertTitle = "Host Request Accepted"
                          self.alertMessage =
                              "The request to become the host has been accepted by \(toPrintName)."
                          self.showAlert = true
                          self.showActionButtons = false
                      }
                  } else if message.message == "DECLINED" {
                      DispatchQueue.main.async {
                          self.alertTitle = "Host Request Rejected"
                          self.alertMessage =
                              "The request to become the host has been declined by \(toPrintName)."
                          self.showAlert = true
                          self.showActionButtons = false
                      }
                  }
              }
          }
      }
  }
   }
}
```

<center>

<img style={{height: '450px'}} src="https://cdn.videosdk.live/website-resources/docs-resources/ios_stage_request_dialog.png" />

</center>

### Step 4: Pin the participant

We need to pin the participant so that he/she can appears on the livestream. To achieve this, we will listen to the callback on the `onParticipantModeChanged` of `Meeting` class.

**Swift:**

```swift
//...
extension LiveStreamViewController: MeetingEventListener {
  //...
  func onParticipantModeChanged(participantId: String, mode: VideoSDKRTC.Mode) {
  let participant = self.participants.first { $0.id == participantId }
  if participant != nil {
      DispatchQueue.main.async {
          //highlight-start
          if (participant?.mode == .SEND_AND_RECV) {
              participant?.pin()
          } else {
              participant?.unpin()
          }
          //highlight-end
          //...
      }
  }
  }
  //...
}
//...
```

<br/>

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Meeting](/ios/api/sdk-reference/meeting-class/introduction)
- [pubSub](/ios/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub)
- [onParticipantModeChanged()](/ios/api/sdk-reference/meeting-class/events#onparticipantmodechanged)


---

# Manage On-Screen Participants - iOS

It is important that only the necessary person are present on the screen when livestream is on. To handle this, we will be using the `pin` and `unpin` methods of the `Participant` class.

:::note
To ensure only the hosts/speakers are shown in the grid, you should use the `SPOTLIGHT` layout and `pin` as the priority when starting the interactive livestream.
:::

Let us first explore two methods that we will be using to manage on-screen participants.

### `pin()`

With these method you can pin any participant's Camera, Screen Share or both. This can be useful to identify the participants based on which you can perform rendering participant grid.

### `unpin()`

With these methods you can unpin any participant's Camera, Screen Share or both. This can be useful to reset pin state of the participant.




### Managing On-Screen Participants

1. If you want to pin all the hosts/speakers automatically, you can do it by listenting to the `onMeetingJoined` callback and `onParticipantModeChanged`, where you can `pin` and `unpin` based on the mode.



**Swift:**

```swift
class LiveStreamViewController: ObservableObject {
  //...
//highlight-start
// Add event listeners and join the meeting
meeting?.addEventListener(self)
//highlight-end
  //...
}

extension LiveStreamViewController: MeetingEventListener {
func onMeetingJoined() {
  guard let localParticipant = self.meeting?.localParticipant else { return }
    self.localParticipant = localParticipant
    localParticipant.addEventListener(self)
    //highlight-start 
    //We will pin the participant if mode is SEND_AND_RECV 
    if (localParticipant.mode == .SEND_AND_RECV) {
        localParticipant.pin()
    } else {
        localParticipant.unpin()
    }
    //highlight-end
}

func onParticipantModeChanged(participantId: String, mode: VideoSDKRTC.Mode) {
    let participant = self.participants.first { $0.id == participantId }
    if participant != nil {
      //highlight-start 
      //We will pin the participant if mode is SEND_AND_RECV 
        if (participant?.mode == .SEND_AND_RECV) {
            participant?.pin()
        } else {
            participant?.unpin()
        }
      //highlight-end
    }
}
//...
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [pin](/ios/api/sdk-reference/participant-class/methods#pin)
- [unpin](/ios/api/sdk-reference/participant-class/methods#unpin)


---

# Manage Roles - iOS

## Roles with VideoSDK

When doing interactive live streaming maintaining the role of users is quite important. To help manage these roles better, VideoSDK allows a participant with two types of modes:

**`1. SEND_AND_RECV`** When a participant is joining with mode set to `SEND_AND_RECV`, we will be able to **publish and consume the media** of other participants and also interact with them using the features like chat, poll etc.

**`2. SIGNALLING_ONLY`** When a participant is joining with mode set to `SIGNALLING_ONLY`, that participant is **not allowed to publish or consume any media** from other participants. Although they can interact with other participants using chat, polls etc.




**_This image is for education purpose_**

![manage-roles](https://cdn.videosdk.live/website-resources/docs-resources/meeting_modes.jpg)

## When to use the Roles?

##### 1. Simple Adaptive Streaming

- Simple Adaptive Streaming (SAS) is a type of livestreaming that requires minimal interaction between the host and viewers.

- It is particularly useful for events with a large number of viewers who prefer not to engage with the host.

- In SAS, each speaker attends a VideoSDK meeting in `SEND_AND_RECV` mode, while viewers can simply watch the livestream using the `playbackHlsUrl` or `livestreamUrl`. Unlike the speakers, viewers do not need to join the meeting in `SEND_AND_RECV` or `SIGNALLING_ONLY` mode. This allows for a seamless streaming experience without any unnecessary interruptions or distractions.
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

**_This video is for education purpose_**


<div style={{textAlign: 'center'}}>



</div>

##### 2. Adaptive Streaming with increased engagement

- If you're looking to increase engagement with your audience during a live streaming event, consider using Adaptive Streaming technology. With this approach, you can incorporate interactive features such as polls and conversations, and give viewers the ability to join and leave the livestream as the host decides.

- To set this up, have all speakers join as `SEND_AND_RECV` mode participants, while the audience joins as `SIGNALLING_ONLY` mode participants. This way, everyone can participate in the interactive elements of the live stream and create a more dynamic and engaging experience for all.

**_This video is for education purpose_**

<div style={{textAlign: 'center'}}>



</div>

## Using roles

When you initialize the meeting, you can set the mode of Participant.



**Swift:**

```js
class MeetingViewController: ObservableObject {
init(meetingId: String, role: UserRole) {    
  //...
  initializeMeeting()
}


// MARK: - Meeting Initialization
func initializeMeeting() {
    VideoSDK.config(token: AUTH_TOKEN)

    meeting = VideoSDK.initMeeting(
        meetingId: meetingId,
        participantName: "John doe",
        micEnabled: self.isMicOn,
        webcamEnabled: self.isWebcamOn,
        multiStream: true,
        //highlight-next-line
        mode: .SEND_AND_RECV // allowed: .SIGNALLING_ONLY, .RECV_ONLY & .SEND_AND_RECV
    )
    
    // highlight-start
    // Add event listeners and join the meeting
    meeting?.addEventListener(self)
    // highlight-end
    //...
}
}
```

## Getting Participant Mode

You can identify the participants role by using `mode` property from `Participant` class.

**Swift:**

```js
class MeetingViewController: ObservableObject {
  //...
  // highlight-start
  let participantMode = meeting?.localParticipant.mode
  print("Local participant's mode: \(participantMode?.rawValue)")
  // highlight-end
  //...
}
```

## Changing Participant's Mode

Let's say you are hosting a livestream and you want one of your viewer to join the livestream with you. In this case you can change the mode of the participant using the `changeMode()` of the `Meeting` class.

**Swift:**

```swift
class MeetingViewController: ObservableObject {
  //...
  func changeToSendRecieveMode() {
  Task {
      // change mode to SEND_AND_RECV
      // highlight-next-line
      await meeting?.changeMode(.SEND_AND_RECV)
  }
  }
  
  func changeToSignallingOnlyMode() {
  Task {
      // change mode to SIGNALLING_ONLY
      // highlight-next-line
      await meeting?.changeMode(.SIGNALLING_ONLY)
  }
  }
  //...
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Meeting](/ios/api/sdk-reference/meeting-class/introduction)
- [Participant](/ios/api/sdk-reference/participant-class/introduction)
- [changeMode()](/ios/api/sdk-reference/meeting-class/methods#changemode)


---

# Interactive Livestream (HLS) - iOS

### What is Interactive Livestream (HLS)?

Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

In an interactive live stream (HLS), viewers can take part in a variety of activities like live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

### What is Adaptive Live Streaming?

Livestream experience is important while undertaking interactive live streaming in order to increase audience. To do this, the livestream should be able to respond to the viewer's network bandwidth, and change the stream's resolution as necessary. Therefore, adaptive live streaming refers to a feed that automatically adjusts to a lower or higher resolution dependent on the user's preferences.

### What is Latency?

Latency is the delay between capturing video content and its playback. Key factors that affecting latency :

- **Buffering**: Balance buffer size for smoother playback against latency.
- **Network Conditions**: Efficient servers and network health contribute to lower latency.

Standard HLS has a latency around 5-6 seconds.

### HLS Architecture of VideoSDK

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/mobile_hls.png' />

</center>

When a host starts the interactive live stream, VideoSDK will use a default theme or user specified template to compose and encode a live stream which will be delivered to the viewers through a `M3U8` video file which can be played directly on the viewer end which will adapt to the viewer's network bandwidth.

When using VideoSDK for interactive live stream, you get multiple types of URLs which you can use based on your requirements.

**`1. Standard Streaming:`** This type of streaming is where the user is not allowed to go back in the live and can just stream it.

**`2. Rolling Playback:`** This type of streaming is where the user is allowed to do rewind and do a playback of the complete stream.

**`3. VoD Playback`** With this, users can playback the complete live stream on demand whenever needed.

## Using HLS with VideoSDK

You can use HLS with VideoSDK in two different ways.

#### 1. Simple Adaptive Streaming

When we talk about simple adaptive streaming, we imply that there is hardly any interaction between the hosts and the viewers.

These livestreams are helpful when there are a lot of viewers, and they don't want to engage with the host. In this scenario, every presenter attends a VideoSDK meeting, while every viewer only watches the livestream.

**_This video is for education purpose_**


<div style={{textAlign: 'center'}}>



</div>

#### 2. Adaptive Streaming with increased engagement

When you want to communicate with your audience by enabling polls, conversations, and the ability for viewers to join and leave the livestream based on the host's decision, adaptive streaming with enhanced engagement will be the best fit for you.

In this scenario, both the host and the viewer will have to join a VideoSDK meeting with different roles. To learn more about the roles [follow these guide.](../handling-participants/manage-roles)

**_This video is for education purpose_**

<div style={{textAlign: 'center'}}>



</div>


---

# Setup HLS Player - iOS

In this guide, we will add player which will be responsible for playing the HLS stream.
Before starting this guide, make sure you have a VideoSDK meetings setup allowing you to join the room. To learn more about setting up a VideoSDK meeting, follow this [quick start guide](/ios/guide/video-and-audio-calling-api-sdk/quick-start).

To play the HLS stream we will be using the native AVKit's VideoPlayer.

### `1. Setup player into your project`

**`Step 1:`** Let's first add common component for Video Player.

```swift title="Views/HLSPlayer.swift"
import SwiftUI
import AVKit

struct HLSVideoPlayer: View {
    let url: URL
    let width: CGFloat?
    let height: CGFloat?

    @State private var player: AVPlayer = AVPlayer()
    
    var body: some View {
        ZStack {
            VideoPlayer(player: player)
                .frame(width: width ?? 400, height: height ?? 400)
                .background(Color.black)
                .onAppear {
                    setupPlayer()
                }
                .onDisappear {
                    player.pause()
                }
        }
    }

    private func setupPlayer() {
        let item = AVPlayerItem(url: url)
        player.replaceCurrentItem(with: item)
        player.play()
    }
}
```

**`Step 2:`** Now let's add the `HLSVideoPlayer` which will display livestreaming in `MeetingView.swift`. For these, we will use the `onHlsStateChanged` event from the `MeetingEventListener` abstract class to identify if there is an active HLS.

```swift title="MeetingView.swift"
import SwiftUI
import VideoSDKRTC

struct MeetingView: View {    
    //...
    
    var body: some View {
        //...
            VStack(spacing: 20) {
                //...
                if controller.role == .host {
                    //... view when role of joinee is host
                } else {
                    if ((controller.hlsState == .HLS_STARTED || controller.hlsState == .HLS_PLAYABLE) && controller.playbackURL != nil) {
                        //highlight-start
                        HLSVideoPlayer(
                            url: URL(string: controller.playbackURL ?? "")!,
                            width: .infinity,
                            height: .infinity
                        )
                        .cornerRadius(12)
                        .padding()
                        //highlight-end                       
                        Spacer()
                    } else {
                        Spacer()
                        Text("Waiting for host\nto start the live streaming")
                            .font(.title)
                            .foregroundStyle(.white)
                            .bold(true)
                            .multilineTextAlignment(.center)
                        Spacer()
                    }
                }
                
                //...
            }
        }
        .navigationBarBackButtonHidden(true)
        .navigationBarHidden(true)
    }
    //...
```

### `2. Initialize player and Playing HLS stream`

Now that player is setup, let's initialize player and play the HLS once it becomes playable. For these, we will get the `playbackHlsUrl` and `livestreamUrl` when the `onHlsStateChanged` event of `MeetingEventListener` state changes to `HLS_PLAYABLE` then we will updated the controller's `playbackURL` variable and it will start video player automatically until then it will show label of `Waiting for host to start the live streaming` to the viewers.

- when you receive `HLS_PLAYABLE` status you will receive 2 urls
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

```swift title="MeetingViewController.swift"
//...
class MeetingViewController: ObservableObject {
    //...
    @Published var playbackURL: String? = nil

    init(meetingId: String, role: UserRole) {
        //...
        initializeMeeting()
    }
    
    // MARK: - Meeting Initialization
    func initializeMeeting() {
        VideoSDK.config(token: AUTH_TOKEN)
        
        let videoMediaTrack = try? VideoSDK.createCameraVideoTrack(
            encoderConfig: .h720p_w1280p,
            facingMode: .front,
            multiStream: true
        )
        meeting = VideoSDK.initMeeting(
            meetingId: meetingId,
            participantName: "John doe",
            micEnabled: self.isMicOn,
            webcamEnabled: self.isWebcamOn,
            customCameraVideoStream: videoMediaTrack,
            multiStream: true,
            mode: self.role == .viewer ? .SIGNALLING_ONLY : .SEND_AND_RECV
        )
        //highlight-start
        // Add event listeners and join the meeting
        meeting?.addEventListener(self)
        //highlight-end
        meeting?.join()
    }
    //...
}

extension MeetingViewController: MeetingEventListener {
    //...
    //highlight-start
    func onHlsStateChanged(state: HLSState, hlsUrl: HLSUrl?) {
        hlsState = state
        switch (state) {
        case .HLS_PLAYABLE:
            playbackURL = hlsUrl?.playbackHlsUrl ?? ""
        default:
            print("HLS State: \(state.rawValue)")
        }
    }
    //highlight-end
}
//...
```

<center>

<img style={{height: '450px',marginRight:'15px'}} src="https://cdn.videosdk.live/website-resources/docs-resources/ios_hls_quickstart_viewer_screen.png" />

</center>

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [onHlsStateChanged](/ios/api/sdk-reference/meeting-class/events#onhlsstatechanged)


---

# Start HLS - iOS

Before starting the HLS, the prequisite steps require you to have a VideoSDK Meeting running which you want to use for interactive livestream. To learn more about setting up a interactive live streaming, you can follow the steps [here in the quick start guide.](/ios/guide/video-and-audio-calling-api-sdk/quick-start-ios-hls)

## Starting HLS

Once the user has joined the meeting, `startHls()` can be used to start a interactive livestream of the meeting which can be accessed from the `Meeting` class. This method accepts two optional parameters:

- `config (optional)`: This parameter will define how the interactive livestream layout should look like.

- `transcription(optional)`: This parameter will be used to enable post transcription for the recording with the given config.



**Swift:**

```js
let config: HLSConfig = HLSConfig(

  // highlight-next-line
  // Layout Configuration
  layout: ConfigLayout(
type: .GRID, // .SPOTLIGHT | .SIDEBAR,  Default : .GRID
priority: .SPEAKER, // .PIN, Default : .SPEAKER
gridSize: 4 // MAX : 25
  ),

  // highlight-next-line
  // Theme of livestream
  theme: .DARK, //  .LIGHT | .DEFAULT

  // highlight-next-line
  // `mode` is used to either interactive livestream video & audio both or only audio.
  mode: .video_and_audio, // .audio, Default : .video_and_audio

  // highlight-next-line
  // Quality of livestream and is only applicable to `video-and-audio` type mode.
  quality: .high,  // .low | .med,  Default : .med

  //highlight-start
  // This mode refers to orientation of recording.
  // landscape : Livestream the meeting in horizontally
  // portrait : Livestream the meeting in vertically (Best for mobile view)
  //highlight-end
  orientation: .portrait  // .portrait,  Default : .landscape
)

//  let transcription: PostTranscriptionConfig =  PostTranscriptionConfig(
//   enabled: true,
//   summary: SummaryConfig(
//           enabled: true,
//           prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
//       )
//   )

startHLS(config: config)
```

:::note
If you want only the SEND_AND_RECV participants to be seen in the livestream, you can `pin` all the participants in the SEND_AND_RECV mode and start the livestream with the `SPOTLIGHT` layout and `pin` as the `PRIORITY`.

Deprecated: Use SEND_AND_RECV instead of CONFERENCE
:::

### Example

**Swift:**

```js
func startHLS() {
  let config: HLSConfig = HLSConfig(
layout: ConfigLayout(
  type: .GRID, // .SPOTLIGHT | .SIDEBAR,  Default : .GRID
  priority: .SPEAKER, // .PIN, Default : .SPEAKER
  gridSize: 4 // MAX : 25
),
theme: .DARK, //  .LIGHT | .DEFAULT
mode: .video_and_audio, // .audio, Default : .video_and_audio
quality: .high,  // .low | .med,  Default : .med
orientation: .portrait  // .portrait,  Default : .landscape
  )

  // let transcription: PostTranscriptionConfig =  PostTranscriptionConfig(
  //   enabled: true,
  //   summary: SummaryConfig(
  //           enabled: true,
  //           prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"))
  
  DispatchQueue.main.async {
//highlight-next-line
self.meeting?.startHLS(config: config)
  }
}
```

## Understanding Layouts

##### 1. GRID Layout

This layout is default layout if no participants are pinned, it will look same as a normal meeting grid layout, when any participant is pinned that participant will be moved on top of the main screen grid above all non pinned participants

While screenshare as well the main view will contain only screenshare media but the side panel view of participant grid will maintain same order of pinned and unpinned participants.

|                       Grid                        |                     Grid with Screenshare                     |
| :-----------------------------------------------: | :-----------------------------------------------------------: |
| ![prebuilt-grid](/img/prebuilt/prebuilt-grid.png) | ![prebuilt-grid-share](/img/prebuilt/prebuilt-grid-share.png) |

##### 2. SIDEBAR Layout

This layout will have one main screen view and other sidebar grid layout. Only pinned participant will be visible in this layout, all unpinned participants will not be visible in this layout. If more than one participant is pinned then the first participant who was pinned will appear in main screen layout and all other remaining pinned particiapants will be visible in sidebar.

If any pinned participant started screenshare then the screenshare media will be visible in main screen layout and all other pinned participants webcam view will be visible in sidebar

|                         Sidebar                         |                      Sidebar with Screenshare                       |
| :-----------------------------------------------------: | :-----------------------------------------------------------------: |
| ![prebuilt-sidebar](/img/prebuilt/prebuilt-sidebar.png) | ![prebuilt-sidebar-share](/img/prebuilt/prebuilt-sidebar-share.png) |

##### 3. SPOTLIGHT Layout

This layout will only contain main screen layout, multiple pinned participants will be visible in main screen view. Same as `SIDEBAR` layout only pinned participants will be visible in main screen.

If any pinned participant started screenshare then only screenshare view will be visible in main screen, no webcam view will be visible when any pinned participant started screenshare.

|                          Spotlight                          |                       Spotlight with Screenshare                        |
| :---------------------------------------------------------: | :---------------------------------------------------------------------: |
| ![prebuilt-spotlight](/img/prebuilt/prebuilt-spotlight.png) | ![prebuilt-spotlight-share](/img/prebuilt/prebuilt-spotlight-share.png) |

## Event associated with HLS

- **onHlsStateChanged** - Whenever meeting HLS state changes, then `onHlsStateChanged` event will trigger.

- You can get the `livestreamUrl` and `playbackHlsUrl` of the HLS to play it on the Viewer side when the state changes to `HLS_PLAYABLE`.
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

**Swift:**

```js
class MeetingViewController: ObservableObject {
//...
    //highlight-start
    // Add event listeners and join the meeting
    meeting?.addEventListener(self)
    //highlight-end
//...
}

extension MeetingViewController: MeetingEventListener {
//...
func onHlsStateChanged(state: HLSState, hlsUrl: HLSUrl?) {
    hlsState = state
    switch (state) {
    case .HLS_STARTING:
        print("HLS is Starting")
    case .HLS_STARTED:
        print("HLS is Started")
    case .HLS_PLAYABLE:
        print("HLS is Playable Now!")
        //highlight-start
        // on hls started you will receive playbackHlsUrl and livestreamUrl
        let playableURL = hlsUrl?.playbackHlsUrl ?? ""
        let liveStreamURL = hlsUrl?.livestreamUrl ?? ""
        //highlight-end
    case .HLS_STOPPING:
        print("HLS is Stopping")
    case .HLS_STOPPED:
        print("HLS is Stopped")
    @unknown default:
        fatalError("Unknown HLS State")
    }
}
}
//...
```

## Custom Template

With VideoSDK, you can also use your own custom designed layout template to livestream the meetings. In order to use the custom template, you need to create a template for which you can [follow this guide](/react/guide/interactive-live-streaming/custom-template). Once you have setup the template, you can use the [REST API to start](/api-reference/realtime-communication/start-livestream) the livestream with the `templateURL` parameter.

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startHls()](/ios/api/sdk-reference/meeting-class/methods#starthls)
- [stopHls()](/ios/api/sdk-reference/meeting-class/methods#stophls)
- [onHlsStateChanged](/ios/api/sdk-reference/meeting-class/events#onhlsstatechanged)


---

# Stop HLS - iOS

This could refer to stopping the transmission of an ongoing HLS stream, which would mean the stream is no longer available to viewers.

## Stopping HLS

- `stopHls()` is used to stop interactive livestream of the meeting which can be accessed from the `Meeting` class.



#### Example

**Swift:**

```js
  func stopHLS() {
  DispatchQueue.main.async {
      //highlight-next-line
      self.meeting?.stopHLS()
  }
  }
```

## Event associated with HLS

- **onHlsStateChanged** - Whenever meeting HLS state changes, then `onHlsStateChanged` event will trigger.

- You will get `HLS_STOPPING` and `HLS_STOPPED` status on calling `stopHls()`.

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

**Swift:**

```js
class MeetingViewController: ObservableObject {
//...
    //highlight-start
    // Add event listeners and join the meeting
    meeting?.addEventListener(self)
    //highlight-end
//...
}

extension MeetingViewController: MeetingEventListener {
//...
func onHlsStateChanged(state: HLSState, hlsUrl: HLSUrl?) {
    hlsState = state
    switch (state) {
    case .HLS_STARTING:
        print("HLS is Starting")
    case .HLS_STARTED:
        print("HLS is Started")
    case .HLS_PLAYABLE:
        print("HLS is Playable Now!")
        // on hls started you will receive playbackHlsUrl and livestreamUrl
        let playableURL = hlsUrl?.playbackHlsUrl ?? ""
        let liveStreamURL = hlsUrl?.livestreamUrl ?? ""
    //highlight-start
    case .HLS_STOPPING:
        print("HLS is Stopping")
    case .HLS_STOPPED:
        print("HLS is Stopped")
    //highlight-end
    @unknown default:
        fatalError("Unknown HLS State")
    }
}
}
//...
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startHls()](/ios/api/sdk-reference/meeting-class/methods#starthls)
- [stopHls()](/ios/api/sdk-reference/meeting-class/methods#stophls)
- [onHlsStateChanged](/ios/api/sdk-reference/meeting-class/events#onhlsstatechanged)


---

# Chat using PubSub - iOS

For the communication or any kind of messaging in between the participants, VideoSDK provides `pubSub` class which use Publish-Subscribe mechanism and can be used to develope wide varitey of functionalities. For example, participants could use it to send chat messages to each other, share files or other media, or even trigger actions like muting or unmuting audio or video.

Now we will see, how we can use PubSub to implement Chat functionality. If you are not familiar with the PubSub mechanism and `pubSub` class, you can [follow this guide](/ios/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

## Implementing Chat

### `Group Chat`

1. First step in creating a group chat is choosing the topic which all the participants will publish and subscribe to send and receive the messages. We will be using `CHAT` as the topic for this one.
2. On the send button, publish the message that the sender typed in the `TextField` field.



**Swift:**

```swift
import InputBarAccessoryView
import MessageKit
import UIKit
import VideoSDKRTC

class ChatViewController: MessagesViewController {
// MARK: - Properties
private let currentUser = Sender(senderId: "self", displayName: "Me")
/// Meeting Reference
public var meeting: Meeting
public var topic: String
/// Message List
private var messages: [Message] = []
private var metaData: [String: Any]?

// MARK: - Init
init(meeting: Meeting, topic: String, metaData: [String: Any]? = nil) {
    self.meeting = meeting
    self.topic = topic
    self.metaData = metaData
    let pubsubMessages = meeting.pubsub.getMessagesForTopic(topic)
    messages = pubsubMessages.map({ Message(pubsubMessage: $0) })
    super.init(nibName: nil, bundle: nil)
}
}

extension ChatViewController: InputBarAccessoryViewDelegate {
func inputBar(
    _ inputBar: InputBarAccessoryView,
    didPressSendButtonWith text: String
) {
    //... 
    Task {
        do {
            //highlight-start
            try await meeting.pubsub.publish(
                topic: "CHAT",
                message: text,
                options: ["persist": true]
            )
            //highlight-end
        } catch {
            print("Error while sending message: \(error)")
        }
    }
    // Clear the input bar and reload the collection view
    inputBar.inputTextView.text = ""
    //...
}
}

// Helper class to get updated messages
class onPubsubMessagGetPrint {
static let shared = onPubsubMessagGetPrint()
@Published var pubsubMessage: PubSubMessage? {
    didSet {
        messageUpdated?(pubsubMessage)
    }
}
var messageUpdated: ((PubSubMessage?) -> Void)?
private init() {}
}
```

3. Next step would be to display the messages others send. For this we have to `subscribe` to that topic i.e `CHAT` and display all the messages.

**Swift:**

```swift
class ChatViewController: MessagesViewController {
override func viewDidLoad() {
    super.viewDidLoad()
    //..
    //highlight-next-line
    onPubSubMessageReceived()
}
}

extension ChatViewController: InputBarAccessoryViewDelegate {
  func onPubSubMessageReceived() {
    onPubsubMessagGetPrint.shared.messageUpdated = {
        [weak self] pubsubMessage in
        guard let self = self, let pubsubMessage = pubsubMessage else { return }
        let message = Message(pubsubMessage: pubsubMessage)
        if message.sender.senderId != self.currentUser.senderId {
            self.messages.append(message)
        }
        if messages.isEmpty != false {
            self.messages.removeLast()
        }
    }
}
}

extension LiveStreamViewController: MeetingEventListener {
func onMeetingJoined() {
  Task {
    //highlight-next-line
    await meeting?.pubsub.subscribe(topic: "CHAT", forListener: self)
  }
}
}

extension LiveStreamViewController: PubSubMessageListener {
  func onMessageReceived(_ message: VideoSDKRTC.PubSubMessage) {
  switch message.topic {
   case "CHAT":
      //highlight-next-line
      onPubsubMessagGetPrint.shared.pubsubMessage = message
}
  }
}
```

4. Final step in the group chat would be `unsubscribe` to that topic, which you had previously subscribed but no longer needed. Here we are `unsubscribe` to `CHAT` topic on activity destroy.

**Swift:**

```swift
extension LiveStreamViewController: MeetingEventListener {
  func onMeetingLeft() {
    //...
    Task {
      //highlight-next-line
        await meeting?.pubsub.unsubscribe(topic: "CHAT", forListener: self)
    }
    //...
}
}
```

### `Private Chat`

In the above example, if you want to convert into the private chat between two participants, then all you have to do is pass `sendOnly` parameter in `options`.

**Swift:**

```swift
class ChatViewController: MessagesViewController {
  private func sendMessageTo(participant: Participant) {
//...
//highlight-start
let options: [String: Any] = ["persist" : false, "sendOnly" : [participant.id]]
Task {
    try await self.meeting?.pubsub.publish(topic: "CHAT", message: "Hello!", options: options)
}
//highlight-end
  }
}
```

### Downloading Chat Messages

All the messages from the PubSub which where published with `persist : true` and can be downloaded as an `.csv` file. This file will be available in the VideoSDK dashboard as well as throught the [Sessions API](/api-reference/realtime-communication/fetch-session-using-sessionid).

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub](/ios/api/sdk-reference/meeting-class/pubsub)


---

# Notify Attendees in Realtime - iOS

When doing livestream, you may want to broadcast message to all the viewers at once.

Let us see, how we can use PubSub to implement this functionality. If you are not familiar with the PubSub mechanism, you can [follow this guide](/ios/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

### Notifying Attendees

1. We will be publish the message that the sender typed in the `TextField` field to the topic `NOTIFY_ATTENDEES`.



**Swift:**

```swift
extension MeetingViewController: MeetingEventListener {
  func onMeetingJoined() {
//...
Task {
  //highlight-next-line
    await meeting?.pubsub.subscribe(topic: "NOTIFY_ATTENDEES", forListener: self)
}
//...
  }
}

extension MeetingViewController: PubSubMessageListener {
  func onMessageReceived(_ message: PubSubMessage) {
//...
if (message.topic == "NOTIFY_ATTENDEES") {
  //...
  print("Message Received:= " + message.message)    
}
  }
}
```

2. Now let us show an alert to all the viewers displaying the message posted by the speaker.

**Swift:**

```swift
extension MeetingViewController: MeetingEventListener {
/// Meeting started
func onMeetingJoined() {
  //...
  Task {
    //highlight-next-line
    await meeting?.pubsub.subscribe(topic: "NOTIFY_ATTENDEES", forListener: self)
  }
}
}

extension MeetingViewController: PubSubMessageListener {
  //highlight-start
func onMessageReceived(_ message: PubSubMessage) {
    let localParticipantID = participants.first(where: { $0.isLocal == true })?.id
    if(message.topic == "NOTIFY_ATTENDEES"){
        self.showToast(message: "Message: \(message.message)", font: .systemFont(ofSize: 18))
    }
}
  //highlight-end
}

extension UIViewController {
  func showToast(message: String, font: UIFont) {
    let toastLabel = UILabel(frame: CGRect(x: self.view.frame.size.width/2, y: self.view.frame.size.height, width: 250, height: 50))
    toastLabel.font = font
    toastLabel.textAlignment = .center;
    toastLabel.text = message
    self.view.addSubview(toastLabel)
    DispatchQueue.main.asyncAfter(deadline: .now() + 3.0) {
        toastLabel.removeFromSuperview()
    }
}
} 
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub](/ios/api/sdk-reference/meeting-class/pubsub)


---

# Raise Hand using PubSub - iOS

Let us see, how we can use PubSub to implement Raise Hand functionality. If you are not familiar with the PubSub mechanism and `pubSub` class, you can [follow this guide](/ios/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

## Implementing Raise Hand

1. First step in raise hand is choosing the topic which all the participants will publish and subscribe to know some participant raise their hand. We will be using `RAISE_HAND` as the topic for this one.
2. On the raiseHand button, publish any message to that specific topic.



**Swift:**

```swift
extension MeetingViewController: MeetingEventListener {
  func onMeetingJoined() {
//...
Task {
  //highlight-next-line
    await meeting?.pubsub.subscribe(topic: "RAISE_HAND", forListener: self)
}
//...
  }
}

extension MeetingViewController: PubSubMessageListener {
  func onMessageReceived(_ message: PubSubMessage) {
//...
if (message.topic == "RAISE_HAND") {
  //...
  print("Message Received:= " + message.message)    
}
  }
}
```

3. Now let us show an alert to all the participants showing who raised the hand.

**Swift:**

```swift
extension MeetingViewController: MeetingEventListener {
/// Meeting started
func onMeetingJoined() {
  //...
  Task {
    //highlight-next-line
    await meeting?.pubsub.subscribe(topic: "RAISE_HAND", forListener: self)
  }
}
}

extension MeetingViewController: PubSubMessageListener {
  //highlight-start
func onMessageReceived(_ message: PubSubMessage) {
    print("Message Received:= " + message.message)
    let localParticipantID = participants.first(where: { $0.isLocal == true })?.id
    if(message.topic == RAISE_HAND_TOPIC){
        self.showToast(message: "\(message.senderId == localParticipantID ? "You" : "\(message.senderName)") raised hand 🖐🏼", font: .systemFont(ofSize: 18))
    }
}
  //highlight-end
}

extension UIViewController {
  func showToast(message: String, font: UIFont) {
    let toastLabel = UILabel(frame: CGRect(x: self.view.frame.size.width/2, y: self.view.frame.size.height, width: 250, height: 50))
    toastLabel.font = font
    toastLabel.textAlignment = .center;
    toastLabel.text = message
    self.view.addSubview(toastLabel)
    DispatchQueue.main.asyncAfter(deadline: .now() + 3.0) {
        toastLabel.removeFromSuperview()
    }
}
} 
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub](/ios/api/sdk-reference/meeting-class/pubsub)


---

# Reactions - iOS

When doing a livestream, one of the way to increase the interaction in between the viewer and speaker is by showing the viewers reaction to all. You might have seen emojis flying around during the livestream happening on instagram.

Lets create a similar flying emoji by using the VideoSDK PubSub mechanism.

### Step 1: Creating a button to send reaction

When `Send` is clicked we will send the emoji name to all the participants using the VideoSDK PubSub mechanism and also shows emoji to localParticipant.
We have used SPM package to pick the emoji from below link: `https://github.com/Kelvas09/EmojiPicker.git`



**Swift:**

```swift
import EmojiPicker

struct LiveStreamView: View {
// for pubsub emojis
@State var selectedEmoji: Emoji?
@State var displayEmojiPicker: Bool = false

var body: some View {
    VStack {
        Button {
            displayEmojiPicker = true
        } label: {
          Image(systemName: "face.smiling")
              .font(.system(size: 20))
              .frame(width: 45, height: 45)
              .background(Color.white.opacity(0.3))
              .clipShape(RoundedRectangle(cornerRadius: 10))
              .foregroundColor(.white)
        }
        .sheet(isPresented: $displayEmojiPicker) {
            NavigationView {
                EmojiPickerView(
                    selectedEmoji: $selectedEmoji,
                    selectedColor: .orange)
                .navigationTitle("Select Reaction")
                .navigationBarTitleDisplayMode(.inline)
                .navigationBarItems(
                  //highlight-start
                    trailing: Button("Send") {
                        if let emoji = selectedEmoji {
                            controller.sendTheReaction(emoji)
                        }
                        displayEmojiPicker = false
                    }
                  //highlight-end
                )
            }
        }
    }
}
}

class LiveStreamViewController: ObservableObject {
//highlight-next-line
meeting?.addEventListener(self)

func sendTheReaction(_ emoji: Emoji) {
    Task {
        do {
          //highlight-start
            try await self.meeting?.pubsub.publish(topic: "REACTION", message: emoji.value, options: [:])
            //highlight-end
        } catch { print("Error while sendTheReaction: \(error)") }
    }
}
}
```

### Step 2: Displaying the Reactions to all the users

Here we will listen to the `onMessageReceived` event of `PubSubMessageListener` to know someone send the reactions, and show the flying emoji whenever it triggered.

**Swift:**

```swift
import EmojiPicker
import SwiftUI
import VideoSDKRTC
import WebRTC

struct LiveStreamView: View {

  @State private var visibleReactions: [Reaction] = []
  private let maxVisibleReactions = 13
  private let copiesPerReaction = 8

  private var reactionOverlay: some View {
  GeometryReader { geometry in
      ZStack {
          ForEach(visibleReactions) { reaction in
              Text(reaction.emoji)
                  .font(.system(size: 40))
                  .position(
                      x: geometry.size.width / 2 + reaction.startX,
                      y: geometry.size.height - 100
                  )
                  .modifier(
                      FloatingAnimation(
                          finalY: -geometry.size.height + 100,
                          horizontalOffset: reaction.horizontalOffset
                      )
                  )
          }
      }
  }
  }

  var body: some View {
  VStack {
      //...
      ZStack {
          //...
          // Add reaction overlay at the screen level
          reactionOverlay
      }
  }
  .onChange(
      of: controller.reactions,
      { oldValue, newValue in
          if let latestReaction = newValue.last {
              addReaction(latestReaction)
          }
      }
  )
  }

  private func addReaction(_ emoji: String) {
for _ in 0..<copiesPerReaction {
    let (horizontalOffset, startX) = randomOffset()
    let newReaction = Reaction(
        id: UUID(),
        emoji: emoji,
        startX: startX,
        horizontalOffset: horizontalOffset
    )
    withAnimation {
        visibleReactions.append(newReaction)
        DispatchQueue.main.asyncAfter(
            deadline: .now() + Double.random(in: 2.5...3.5)
        ) {
            withAnimation {
                visibleReactions.removeAll { $0.id == newReaction.id }
            }
        }
    }
}

if visibleReactions.count > maxVisibleReactions {
    visibleReactions.removeFirst(
        visibleReactions.count - maxVisibleReactions
    )
}
  }
}

class LiveStreamViewController: ObservableObject {
  @Published var reactions: [String] = []
}

extension LiveStreamViewController: PubSubMessageListener {
  func onMessageReceived(_ message: VideoSDKRTC.PubSubMessage) {
  if (message.topic == "REACTION") {
      self.reactions.append(message.message)
      DispatchQueue.main.asyncAfter(deadline: .now() + 2) {
          if let index = self.reactions.firstIndex(
              of: message.message
          ) {
              self.reactions.remove(at: index)
          }
      }
  }
  }
}
```

<center>


<div style={{textAlign: 'center'}}>



</div>
</center>

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub](/ios/api/sdk-reference/meeting-class/pubsub)


---

# Introduction

Welcome to the iOS Interactive Live Streaming (ILS). Build real-time, low-latency experiences where hosts and audiences connect, interact, and engage seamlessly using VideoSDK.

## Architecture Overview

**Architecture at a Glance** — Hosts join with `SEND_AND_RECV` permissions to broadcast and collaborate, while audiences connect with `RECV_ONLY` access to enjoy the stream without publishing their own media.

![Interactive Live Streaming architecture diagram](https://assets.videosdk.live/images/ils-architecture-live-streaming.png)

## Streaming Modes

**Interactive Live Streaming (ILS):** Low-latency, two-way sessions where hosts and promoted guests publish audio/video, manage roles, and drive rich audience participation.

**HTTP Live Streaming (HLS):** Broadcast delivery tuned for massive audiences with receiver-only playback and CDN scaling, perfect for town halls and one-to-many events.

- [Interactive Live Streaming Quick Start](/ios/guide/video-and-audio-calling-api-sdk/quick-start-ios-ils): Kick off a Swift-based ILS app with backstage, role management, and real-time engagement.
- [HTTP Live Streaming Quick Start](/ios/guide/video-and-audio-calling-api-sdk/recording-and-live-streaming/interactive-livestream): Follow the HLS streaming guide to broadcast VideoSDK sessions to massive iOS audiences.


Use the guide below to explore the modular capabilities that help you design each part of this flow.

## Key Features

- [Host & Layout Control](/ios/guide/interactive-live-streaming/layout-management/rendering-host-audience-views): Coordinate speakers, backstage roles, and layouts tailored for iOS events.
- [Audience Moderation](/ios/guide/interactive-live-streaming/audience-management/change-mode): Maintain control with flexible participant modes and moderation tools.
- [Advanced Device Tools](/ios/guide/interactive-live-streaming/device-management/change-devices): Switch cameras, microphones, and enable screen sharing with native controls.
- [Interactive Layers](/react-native/guide/interactive-live-streaming/chat-during-livestream): Add chat, reactions, polls, and raise-hand to keep viewers involved.
- [Session Analytics](/ios/guide/interactive-live-streaming/analytics/understanding-analytics-dashboard): Monitor stream health, latency, and participant trends in real time.
- [Recording & Archives](/ios/guide/interactive-live-streaming/recording/overview): Capture sessions, enable compliance workflows, and automate storage.
- [Geo & Network Controls](/ios/guide/interactive-live-streaming/geo-fencing): Respect geography and enterprise networking requirements with built-in policies.
- [Relay & Multistream](/ios/guide/interactive-live-streaming/relay-media): Distribute broadcasts across rooms and destinations using relay media.


## Sample Projects

- [iOS ILS Starter](https://github.com/videosdk-live/videosdk-ils-iOS-sdk-example): Explore a native host and viewer experience using VideoSDK's iOS frameworks.
- [iOS Video Call Toolkit](https://github.com/videosdk-live/videosdk-rtc-ios-sdk-example): Start from the core VideoSDK meeting sample and extend it with ILS features.


## Quick Start Paths

- [Install with CocoaPods](/ios/guide/interactive-live-streaming/ios-sdk): Set up the VideoSDK pods, entitlements, and permissions for your project.
- [Install with SPM](/ios/guide/interactive-live-streaming/ios-sdk-spm): Prefer Swift Package Manager? Follow the streamlined setup here.
- [Configure Tokens](/ios/guide/interactive-live-streaming/authentication-and-token): Implement API key and secret handling on your backend for secure joins.
- [Launch the ILS Sample](/ios/guide/video-and-audio-calling-api-sdk/run-a-sample-ils-project): Clone the ILS starter to validate iPhone and iPad experiences end-to-end.
- [Optimize the Experience](/ios/guide/interactive-live-streaming/best-practices/user-experience): Follow best practices for UX, low latency, and error handling on iOS.
- [Stay Updated](/ios/guide/interactive-live-streaming/release-notes): Review release notes and supported device matrices before shipping.



---

# Integrate VideoSDK Using Swift Package Manager (SPM) - iOS




---

# Client Setup using Pods - iOS




---

# Known Issues - iOS




---

# Pin/Unpin Participants - iOS

In a live stream setup, you often want to control which participant is actively visible on screen — whether it’s the host, a special guest, or someone screen sharing. To manage this dynamically, the `uParticipant` class provides two key methods:

- `pin()` – Focus on a specific participant’s camera or screen share

- `unpin()` – Remove that focus and return to the default layout

This allows you to programmatically decide who gets the spotlight in your live stream layout.

### `pin()`

The pin() method makes it easy to bring a host camera or screen share front and center in the broadcast layout. Once pinned, you can write the layout logic to place this host in the primary frame, e.g. fullscreen or in a highlighted position.

```js
func pinParticipant(participant: Participant, pinType: PinType) {
    participant.pin(pinType: pinType)
}
```

### `unpin()`

When a host is no longer the focus (e.g. their segment is over), you can reset their pinned state using unpin(). This allows your live stream UI to revert to a default grid view or automatically promote the next speaker.

```js
func unpinParticipant(participant: Participant, pinType: PinType) {
    participant.unpin(pinType: pinType)
}
```

### Events associated with pin/unpin

Following callbacks are received when a host is pinned or unpinned in the livestream.

- All [participants-including all the hosts and audience members](/ios/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a callback on the [`onPinStateChanged`](/ios/api/sdk-reference/meeting-class/events#onpinstatechanged) event with the data object containg the peerid of the participant who was pinned, the state and pinnedBy values.

```js
extension LiveStreamViewController : ParticipantEventListener {

  onPinStateChanged(participantId: String, pinType: PinType) {
    // Update your UI to reflect the new pin state
    print("Participant \(participantId) pin state changed to \(pinType)")
  }

}
```

:::info

- Based on the `onPinStateChanged` event, you should update your live stream layout for all participants (including the audience) to reflect the current pinned participant.
This means conditionally rendering the pinned participant in the main view or spotlight area across all clients.

:::


## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [pin()](/ios/api/sdk-reference/participant-class/methods#pin)
- [unpin()](/ios/api/sdk-reference/participant-class/methods#unpin)
- [onPinStateChanged()](/ios/api/sdk-reference/meeting-class/events#onpinstatechanged)


---

# Rendering Host and Audience Views - iOS

In a live stream setup, only hosts (participants in `SEND_AND_RECV` mode) can broadcast their audio and video. Audience members (in `RECV_ONLY` mode) are passive viewers who do not share their audio/video.

To ensure optimal performance and a clean user experience, your app should:

- **Render video only for hosts** (i.e., participants in `SEND_AND_RECV` mode).
- **Display the total audience count** to give context on viewership without rendering individual audience tiles.

## Filtering and Rendering Hosts

The steps involved in rendering the audio and video of hosts are as follows.

1. [Filtering Hosts and Checking their Mic/Webcam Status](#1-filtering-hosts-and-checking-their-micwebcam-status)
2. [Rendering Video Streams of Hosts](#2-rendering-video-streams-of-hosts)
3. [Handling Audience Views](#3-handling-audience-view)

### `1. Filtering Hosts and Checking their Mic/Webcam Status `

In a live stream, only participants in `SEND_AND_RECV` mode (i.e., hosts) actively share their audio and video. To render their streams, begin by accessing all participants using `Meeting` classs. Then, filter out only those in `SEND_AND_RECV` mode.

For each of these participants, use the `Participant` class, which provides real-time information like displayName, micOn, and webcamOn. Display their name along with the current status of their microphone and webcam. If the webcam is off, show a simple placeholder with their name. If it's on, render their video feed. This ensures only hosts are visible to the audience, keeping the experience clean and intentional.

In a live stream, only participants in `SEND_AND_RECV` mode (i.e., hosts) actively share their audio and video. To render their streams, begin by filtering all participants to show only those in `SEND_AND_RECV` mode.

```swift
// Function to get visible participants (hosts only)
private func getVisibleParticipants() -> [Participant] {
    // Only show participants who are in SEND_AND_RECV mode
    return liveStreamViewController.participants.filter { participant in
        participant.mode == .SEND_AND_RECV
    }
}
```

In the `LiveStreamViewController` class, we track the microphone status of each participant:

```swift
// Inside LiveStreamViewController's ParticipantEventListener implementation
func onStreamEnabled(_ stream: MediaStream, forParticipant participant: Participant) {
    DispatchQueue.main.async {
        // Only handle streams for SEND_AND_RECV participants
        if participant.mode == .SEND_AND_RECV {
            if let track = stream.track as? RTCVideoTrack {
                if case .state(let mediaKind) = stream.kind, mediaKind == .video {
                    self.participantVideoTracks[participant.id] = track
                    self.participantCameraStatus[participant.id] = true
                }
            }
            
            if case .state(let mediaKind) = stream.kind, mediaKind == .audio {
                self.participantMicStatus[participant.id] = true
            }
        } else {
            // For RECV_ONLY participants, ensure their tracks are removed
            self.participantVideoTracks.removeValue(forKey: participant.id)
            self.participantCameraStatus[participant.id] = false
            self.participantMicStatus[participant.id] = false
        }
    }
}

func onStreamDisabled(_ stream: MediaStream, forParticipant participant: Participant) {
    DispatchQueue.main.async {
        if case .state(let mediaKind) = stream.kind {
            switch mediaKind {
            case .video:
                self.participantVideoTracks.removeValue(forKey: participant.id)
                self.participantCameraStatus[participant.id] = false
            case .audio:
                self.participantMicStatus[participant.id] = false
            }
        }
    }
}
```

Then create a view for displaying each participant's video along with their name and microphone status:

```swift
struct ParticipantContainerView: View {
    let participant: Participant
    @ObservedObject var liveStreamViewController: LiveStreamViewController
    
    // Name and mic status overlay
    private var nameAndMicOverlay: some View {
        VStack {
            Spacer()
            HStack {
                Text(participant.displayName)
                    .foregroundColor(.white)
                    .padding(.horizontal, 8)
                    .padding(.vertical, 4)
                    .background(Color.black.opacity(0.5))
                    .cornerRadius(4)
                
                Image(systemName: liveStreamViewController.participantMicStatus[participant.id] ?? false ? "mic.fill" : "mic.slash.fill")
                    .foregroundColor(liveStreamViewController.participantMicStatus[participant.id] ?? false ? .green : .red)
                    .padding(4)
                    .background(Color.black.opacity(0.5))
                    .clipShape(Circle())
                
                Spacer()
            }
            .padding(8)
        }
    }
    
    var body: some View {
        // Only render if participant is in SEND_AND_RECV mode
        if participant.mode == .SEND_AND_RECV {
            ZStack {
                participantView(participant: participant, liveStreamViewController: liveStreamViewController)
                nameAndMicOverlay
            }
            .background(Color.black.opacity(0.9))
            .cornerRadius(10)
            .shadow(color: Color.black.opacity(0.7), radius: 10, x: 0, y: 5)
        }
    }
    
    private func participantView(participant: Participant, liveStreamViewController: LiveStreamViewController) -> some View {
        ZStack {
            ParticipantView(participant: participant, liveStreamViewController: liveStreamViewController)
        }
    }
}
```

### `2. Rendering Video Streams of Hosts`

Once you've filtered for participants in `SEND_AND_RECV` mode (i.e., hosts), you can use the `Participant` class to access their real-time data, including their webcamStream, webcamOn, and whether they are the local participant.

To render the video stream of a participant, we need to create a view that handles the WebRTC video track.


First, we define a `VideoView` class:

```swift
class VideoView: UIView {
    var videoView: RTCMTLVideoView = {
        let view = RTCMTLVideoView()
        view.videoContentMode = .scaleAspectFill
        view.backgroundColor = UIColor.black
        view.clipsToBounds = true
        view.transform = CGAffineTransform(scaleX: 1, y: 1)
        return view
    }()
    
    init(track: RTCVideoTrack?, frame: CGRect) {
        super.init(frame: frame)
        backgroundColor = .clear
        
        // Set videoView frame to match parent view
        videoView.frame = bounds
        
        DispatchQueue.main.async {
            self.addSubview(self.videoView)
            self.bringSubviewToFront(self.videoView)
            track?.add(self.videoView)
        }
    }
    
    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }
    
    override func layoutSubviews() {
        super.layoutSubviews()
        // Update videoView frame when parent view size changes
        videoView.frame = bounds
    }
}
```

Then create a SwiftUI wrapper to use this UIKit view:

```swift
struct VideoStreamView: UIViewRepresentable {
    let track: RTCVideoTrack
    
    func makeUIView(context: Context) -> VideoView {
        let view = VideoView(track: track, frame: .zero)
        return view
    }
    
    func updateUIView(_ uiView: VideoView, context: Context) {
        track.add(uiView.videoView)
    }
}
```

Now create a participant view to display either the video or a placeholder:

```swift
struct ParticipantView: View {
    let participant: Participant
    @ObservedObject var liveStreamViewController: LiveStreamViewController
    
    var body: some View {
        ZStack {
            if participant.mode == .SEND_AND_RECV,
               let track = liveStreamViewController.participantVideoTracks[participant.id] {
                VideoStreamView(track: track)
            } else {
                Color.black.opacity(1.0)
                VStack {
                    if participant.mode == .RECV_ONLY {
                        Text("Viewer")
                            .foregroundColor(.white)
                        Text(participant.displayName)
                            .foregroundColor(.gray)
                            .font(.caption)
                    } else {
                        Text("No media")
                            .foregroundColor(.white)
                    }
                }
            }
        }
    }
}
```

### `3. Handling Audience View`

For audience members, we provide a different set of controls and manage their view state. The main distinction is determining whether the current participant is in audience mode:

```swift
private var isAudienceMode: Bool {
    // Derive audience mode from the current participant's mode
    if let localParticipant = liveStreamViewController.participants.first(where: { $0.isLocal }) {
        return localParticipant.mode == .RECV_ONLY
    }
    return currentMode == .RECV_ONLY
}
```

:::note

Certainly! You can refer to the videosdk-ils-iOS-sdk-example directory in the official [VideoSDK iOS example repository](https://github.com/videosdk-live/videosdk-ils-iOS-sdk-example) for a comprehensive implementation of interactive live streaming features, including participant management and UI controls. 
:::



## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [Participant](/ios/api/sdk-reference/participant-class/properties)


---

# Live Captioning for Livestreams - iOS

Live captioning enhances your livestreams by converting hosts' speech into text in real-time, boosting accessibility and engagement. Using the `startTranscription()` and `stopTranscription()` functions you can enable or disable captions on the fly, and display captions dynamically in your UI for all viewers.

Video SDK offers flexible configuration and event-driven updates to help you integrate captions seamlessly into your broadcast layout.

### `startTranscription()`

The `startTranscription()` method, accessible from the `meeting` object, is used to initiate live captions in a live stream. This method accepts the following two parameters:

- `1. webhookUrl (optional)`: This is the webhook URL where you can listen to events related to the recording, such as the start and stop of recording. It triggers when the recording is completed and stored on the server. You can learn more about webhooks [here](https://en.wikipedia.org/wiki/Webhook)

- `2. summary (optional)`:
  - `enabled`: Indicates whether realtime transcription summary generation is enabled. Summary will be available after realtime transcription stopped. Default: false.
  - `prompt`: provides guidelines or instructions for generating a custom summary based on the realtime transcription content.

### `stopTranscription()`

The `stopTranscription()` method, accessible from the `useMeeting` object, is used to stop the live captions in a live stream.

#### Example

```js
@IBAction func startLiveCaptionTapped(_ sender: Any) {

    let config =  TranscriptionConfig(
            webHookUrl: "YOUR_WEBHOOK_URL",
            summary: SummaryConfig(
            enabled: true,
            prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
            )
    )

    meeting.startTranscription(config);
}

@IBAction func stopLiveCaptionTapped(_ sender: Any) {
    meeting.stopTranscription();
}
```

### Events associated with live captioning

- All [participants-including all the hosts and audience members](/ios/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a callback on the [`onTranscriptionStateChanged`](/ios/api/sdk-reference/meeting-class/events#ontranscriptionstatechanged) event with the current state of the captioning.
- All [participants-including all the hosts and audience members](/ios/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a callback on the [`onTranscriptionText`](/ios/api/sdk-reference/meeting-class/events#ontranscriptiontext) event with the latest captions whenever a host speaks.

```js
import VideoSDKRTC

extension LiveStreamViewController: MeetingEventListener {

// Listen for transcription state changed event
    func onTranscriptionStateChanged(state: TranscriptionState) {

        switch state {
        case .TRANSCRIPTION_STARTING:
            print("transcription starting")

        case .TRANSCRIPTION_STARTED:
            print("transcription started")

        case .TRANSCRIPTION_STOPPING:
            print("transcription stopping")

        case .TRANSCRIPTION_STOPPED:
            print("transcription stopped")
        }

    }

// Listen for transcription text event
    func onTranscriptionText(_ data: TranscriptionText) {
        print("transcription text: ", data.text)
        print("participant name", data.participantName)
    }
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startTranscription()](/ios/api/sdk-reference/meeting-class/methods#starttranscription)
- [stopTranscription()](/ios/api/sdk-reference/meeting-class/methods#stoptranscription)
- [onTranscriptionStateChanged](/ios/api/sdk-reference/meeting-class/events#ontranscriptionstatechanged)
- [onTranscriptionText](/ios/api/sdk-reference/meeting-class/events#ontranscriptiontext)


---

# Reactions during Live Stream - iOS

To enhance interaction between viewers and speakers during a livestream, a creative approach is to display viewers' reactions to everyone. This can be achieved by creating a lively atmosphere with flying emojis, similar to the experience seen in livestreams on platforms like Instagram.

This guide explains how to implement this engaging feature using the VideoSDK PubSub mechanism.

### Step 1: Add Models and Animation to LiveStreamView.swift

Add these models at the top of your file, next to your other model definitions:

```swift
// Add this alongside your other struct definitions
struct Reaction: Equatable, Identifiable {
    let id: UUID
    let emoji: String
    let startX: CGFloat
    let horizontalOffset: CGFloat
}

// Add the animation modifier
struct FloatingAnimation: ViewModifier {
    let finalY: CGFloat
    let horizontalOffset: CGFloat
    
    func body(content: Content) -> some View {
        content
            .offset(x: horizontalOffset, y: 0)
            .animation(
                Animation.easeOut(duration: 2.5)
                    .delay(Double.random(in: 0...0.5))
                    .speed(Double.random(in: 0.8...1.2))
            )
            .offset(y: finalY)
    }
}
```

### Step 2: Add State Variables to LiveStreamView

Add these state variables to your `LiveStreamView` struct:

```swift
// For emoji reactions
@State private var visibleReactions: [Reaction] = []
private let maxVisibleReactions = 13
private let copiesPerReaction = 8 // Number of copies for each reaction
```

### Step 3: Add the Reaction Helper Functions to LiveStreamView

Add these functions inside your `LiveStreamView` struct:

```swift
// Add a function to generate random offset
private func randomOffset() -> (CGFloat, CGFloat) {
    let horizontalOffset = CGFloat.random(in: -150...150)
    let startX = CGFloat.random(in: -50...50)
    return (horizontalOffset, startX)
}

// Add the addReaction function
private func addReaction(_ emoji: String) {
    // Create multiple copies of the same reaction with different paths
    for _ in 0..<copiesPerReaction {
        let (horizontalOffset, startX) = randomOffset()
        let newReaction = Reaction(
            id: UUID(),
            emoji: emoji,
            startX: startX,
            horizontalOffset: horizontalOffset
        )
        
        withAnimation {
            visibleReactions.append(newReaction)
            
            // Remove this specific reaction after animation
            DispatchQueue.main.asyncAfter(deadline: .now() + Double.random(in: 2.5...3.5)) {
                withAnimation {
                    visibleReactions.removeAll { $0.id == newReaction.id }
                }
            }
        }
    }
    
    // Limit total visible reactions
    if visibleReactions.count > maxVisibleReactions {
        visibleReactions.removeFirst(visibleReactions.count - maxVisibleReactions)
    }
}
```

### Step 4: Add the Reaction Overlay View

Add this to your `LiveStreamView` struct:

```swift
// Define the reaction overlay view
private var reactionOverlay: some View {
    GeometryReader { geometry in
        ZStack {
            ForEach(visibleReactions) { reaction in
                Text(reaction.emoji)
                    .font(.system(size: 40))
                    .position(
                        x: geometry.size.width/2 + reaction.startX,
                        y: geometry.size.height - 100
                    )
                    .modifier(FloatingAnimation(
                        finalY: -geometry.size.height + 100,
                        horizontalOffset: reaction.horizontalOffset
                    ))
            }
        }
    }
}
```

### Step 5: Add the Reactions to Your ZStack

Locate the main ZStack in your body property and add the reactionOverlay:

```swift
ZStack {
    // Your existing video content
    // ...
    
    // Controls and other UI
    // ...
    
    // Add reaction overlay at the screen level
    reactionOverlay
}
```

### Step 6: Modify Your Emoji Button

Find or add an emoji button for audience members in your controls section:

```swift
// Emoji button for audience mode
if isAudienceMode {
    Button {
        displayEmojiPicker = true
    } label: {
        Image(systemName: "face.smiling")
            .font(.system(size: 20))
            .frame(width: 45, height: 45)
            .background(Color.gray.opacity(0.8))
            .clipShape(RoundedRectangle(cornerRadius: 10))
            .foregroundColor(.white)
    }
    .sheet(isPresented: $displayEmojiPicker) {
        NavigationView {
            EmojiPickerView(selectedEmoji: $selectedEmoji, selectedColor: .orange)
                .navigationTitle("Select Reaction")
                .navigationBarTitleDisplayMode(.inline)
                .navigationBarItems(trailing: Button("Send") {
                    if let emoji = selectedEmoji {
                        liveStreamViewController.sendTheReaction(emoji)
                    }
                    displayEmojiPicker = false
                })
        }
    }
}
```

### Step 7: Add Reaction Observer

Add this to your view modifiers:

```swift
.onChange(of: liveStreamViewController.reactions) { newReactions in
    if let latestReaction = newReactions.last {
        addReaction(latestReaction)
    }
}
```

### Step 8: Update LiveStreamViewController

Ensure your LiveStreamViewController has:

1. A reactions array:
```swift
@Published var reactions: [String] = []
```

2. A sendTheReaction method:
```swift
func sendTheReaction(_ emoji: Emoji) {
    print("Sending reaction: \(emoji.value)")
    self.meeting?.pubsub.publish(topic: "REACTION", message: emoji.value, options: [:])
}
```

3. PubSub handling in the onMessageReceived method:
```swift
func onMessageReceived(_ message: VideoSDKRTC.PubSubMessage) {
    print("Message Received:= " + message.message)
    
    if message.topic == "REACTION" {
        DispatchQueue.main.async {
            print("Received reaction: \(message.message)")
            self.reactions.append(message.message)
            
            DispatchQueue.main.asyncAfter(deadline: .now() + 3) {
                if let index = self.reactions.firstIndex(of: message.message) {
                    self.reactions.remove(at: index)
                }
            }
        }
    }
    
    // Your other message handlers...
}
```

4. PubSub subscription in onMeetingJoined:
```swift
func onMeetingJoined() {
    // Your existing code...
    
    Task {
        await meeting?.pubsub.subscribe(topic: "REACTION", forListener: self)
        // Your other subscriptions...
    }
}
```

## How It Works

1. When a user selects an emoji in audience mode, it's sent via PubSub
2. All clients (including the sender) receive the emoji via PubSub
3. When received, multiple copies of the emoji are created with randomized paths
4. Emojis float upward with randomized animations
5. Emojis are automatically removed after their animation completes
6. The total number of visible emojis is limited to prevent performance issues

## Customization

You can customize the animations by modifying:

1. Number of copies per reaction (`copiesPerReaction`)
2. Maximum visible reactions (`maxVisibleReactions`)
3. Animation duration in the `FloatingAnimation` modifier
4. Emoji size and starting position
5. Random offset ranges for horizontal movement


---

Recording meetings is an essential feature that ensures all important discussions, decisions, and interactions are documented for future reference. VideoSDK offers three types of recordings: Meeting Recording, Participant Recording, and Participant Track Recording. Each type serves a specific purpose to cater to different recording needs during a meeting.

## Meeting Recording

Meeting Recording captures the entire meeting, including all participants, audio, video, and shared content. This comprehensive recording is ideal for reviewing the entire meeting, ensuring that nothing is missed. It provides a holistic view of the meeting, capturing every interaction and piece of information shared during the session.

![Meeting Recording](https://cdn.videosdk.live/website-resources/docs-resources/MeetingRecording.png)

## Participant Recording

Participant Recording focuses on individual participants, capturing both their audio and video into a single file. This type of recording is particularly useful for tracking the contributions of specific participants or for scenarios where detailed analysis of an individual’s participation is needed. When a participant mutes their audio or turns off their video, the recording continues but with silenced audio or a black screen, respectively. This ensures a continuous recording without interruptions, reflecting the participant's involvement throughout the meeting.

![Participant Recording](https://cdn.videosdk.live/website-resources/docs-resources/ParticipantRecording.png)

## Participant Track Recording

Participant Track Recording allows you to record specific tracks of a participant, either audio or video, based on user input. This targeted approach is perfect for capturing particular aspects of a participant’s contribution, such as only their audio or only their video. Multiple files are generated whenever there is a change in the track's status (e.g., starting after being muted ), ensuring focused documentation of each continuous segment. This method is especially useful in scenarios where detailed analysis of specific media (audio or video) is required.

![Participant Track Recording](https://cdn.videosdk.live/website-resources/docs-resources/TrackRecording.png)



---

# Geo Tag Meeting Recordings - iOS

To ensure compliance for BFSIs doing vKYC, it very important to include the co-ordinates(location) of the customer in the recordings. VideoSDK provides a very customizable solution to implement this feature. You will be using custom templates for this purpose.

We have created a ready to use template for this use case which can be found [here](https://github.com/videosdk-live/videosdk-rtc-react-prebuilt-ui/tree/template/geo-tag-watermark). To integrate this template with your recordings follow the below mentiond instructions.

### Host the template

1. Clone the template repository and switch to the branch `template/geo-tag-watermark`.

```bash
git clone https://github.com/videosdk-live/videosdk-rtc-react-prebuilt-ui.git
cd videosdk-rtc-react-prebuilt-ui
git checkout template/geo-tag-watermark
```

2. Install the dependencies and create a build of the project using below mentioned commands.

```bash
npm install
npm run build
```

3. Host the contents of the build folder on your server and check if the template is up and running.

:::note

If you want to create the complete template from scratch you can [follow this guide.](./custom-template.md)

:::

### Using the template for recording

1. To use the template that we deployed earlier, we will be using the `templateUrl` feature in the `startRecording` API.
   To generate the template URL, you will have to append the `meetingId`, and `token` has to be added in the query parameters. Also if you are using the template provided above you need to added a few extra paramters mentioned below. Here is the code snippet to generate the URL.

```js
async function main() {
  let meetingId = "Your MeetingID";
  let token = "Your Token";
  const templateUrl = `https://${YOUR Template URL}/?meetingId=${meetingId}&token=${token}&name=recorder&isRecorder=true&joinWithoutUserInteraction=true`;

  console.log(templateUrl);
}

main();
```

2. Now that we have the template URL, we will use this URL to start the recording using the below provided API call.

```js
async function main() {
  let meetingId = "Your MeetingID";
  let token = "Your Token";
  const templateUrl = `https://${YOUR Template URL}/?meetingId=${meetingId}&token=${token}&name=recorder&isRecorder=true&joinWithoutUserInteraction=true`;

  console.log(templateUrl);

  //Using the previouly created template URL and starting the recording using the API.
  const options = {
    method: "POST",
    headers: {
      Authorization: "$YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      roomId: "Your MeetingId",
      templateUrl: templateUrl,
    }),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();
```

### Updating the Geo Tagging Coordinates

We will be using the PubSub feature of VideoSDK to update the data of latitude and longitude. For the predefined template provided by us we are using `GEO_TAG` as topic name. We will be publishing the `participantName`, `latitude` and `longitude` of the participant for whom we want to show in the recording.

:::note

You will have to fetch the longitude and latitude of the participant before sending it using the pubsub.

:::

Here is the code how you will have to publish the message:

```js
function Watermark() {
  const { messages, publish } = usePubSub("GEO_TAG");

  const sendCoordinates = () => {
    publish(
      "GEO TAG DATA",
      { persist: true },
      {
        latitude: "LATITUDE OF PARTICIPANT",
        longitude: "LONGITUDE OF PARTICIPANT",
        participantName: "NAME OF PARTICIPANT",
      }
    );
  };

  return <></>;
}
```

After implementing this, you should get the recording in the following format:

![Geo Tagging Recoridng](https://cdn.videosdk.live/website-resources/docs-resources/geo-tag-recording-template.png)

If you wish to change how UI looks on recording, you can change it by updating the layout in the template itself.

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)
- [Learn more about Custom Templates](./custom-template.md)


---

You have the option to create presigned URL, allowing you to upload your recordings to AWS, Azure, or GCP securely.
presigned URL provide a secure and temporary way to upload objects to your cloud storage. Instead of sharing your entire credentials, you can create a special URL that allows uploading a specific file for a limited time.

:::important

While presigned URL offer a convenient way to upload files securely, each cloud provider (AWS, Azure, and GCP) might have different restrictions on how they work. It's advisable to refer the respective documentation for **[<u>AWS</u>](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)**, **[<u>Azure</u>](https://learn.microsoft.com/en-us/rest/api/storageservices/delegate-access-with-shared-access-signature)**, and **[<u>GCP</u>](https://cloud.google.com/cdn/docs/using-signed-urls)** to gain a clearer understanding of presigned URL.

:::

### Code Sample

This guide will walk you through the process of generating a presigned URL for uploading recordings to your cloud storage of choice. You can use this generated presigned URL in [Start Recording API](/api-reference/realtime-communication/start-recording#preSignedUrl).



**AWS:**

```js
const { S3Client, PutObjectCommand } = require("@aws-sdk/client-s3");
const { getSignedUrl } = require("@aws-sdk/s3-request-presigner");

const region = <YOUR S3 REGION>;
const bucket = <YOUR S3 BUCKET NAME>;
const key = <YOUR FILE NAME>; // test/abc.mp4
const accessKeyId = <YOUR S3 ACCESS KEY ID>;
const secretAccessKey = <YOUR S3 SECRET ACCESS KEY>;
const expiresIn = <URL EXPIRY IN SECONDS>; // this number should be higher than duraion of recording

const s3Client = new S3Client({
credentials: {
    accessKeyId: accessKeyId,
    secretAccessKey: secretAccessKey,
},
region: region,
});

const createPresignedUrlWithClient = async () => {
const command = new PutObjectCommand({ Bucket: bucket, Key: key });
const preSignedUrl = await getSignedUrl(s3Client, command, { expiresIn: expiresIn });
return preSignedUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await createPresignedUrlWithClient();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

---

**AZURE:**

```js
const { BlobServiceClient, BlobSASPermissions } = require("@azure/storage-blob");

const connectionString = <YOUR AZURE STORAGE CONNECTION STRING>;
const containerName = <YOUR AZURE CONTAINER NAME>;
const blobName = <YOUR AZURE BLOB NAME>;
const startsOn = <YOUR SASURL START TIME>; // (optional, defaults to now)
const expiresOn = <YOUR SASURL EXPIRY TIME>; // expiry time should be higher than duration of recording

const generateSASUrl = async () => {
let blobServiceClient = BlobServiceClient.fromConnectionString(connectionString);
let containerClient = blobServiceClient.getContainerClient(containerName);

await containerClient.createIfNotExists({
    access: "container",
});

const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const sasUrl = await blockBlobClient.generateSasUrl({
    startsOn: startsOn, // sasUrl start time
    expiresOn: expiresOn, // sasUrl expiration time
    permissions: BlobSASPermissions.parse("write"),
});
return sasUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await generateSASUrl();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

---

**GCP:**

```js
const { Storage } = require("@google-cloud/storage");

const projectId = <YOUR GCP PROJECT ID>;
const clientEmail = <YOUR GCP CLIENT EMAIL>;
const privateKey = <YOUR GCP PRIVATE KEY>;
const expires =<URL EXPIRY IN SECONDS>; // this number should be higher than duraion of recording
const bucketName = <YOUR GCP BUCKET NAME>;
const fileName = <YOUR FILE NAME>; // test/abc.mp4

const storage = new Storage({
projectId: projectId,
credentials: {
    client_email: clientEmail,
    private_key: privateKey,
},
});

const generateSignedUrl = async () => {
const options = {
    version: "v4",
    action: "write",
    expires: expires,
    contentType: "video/mp4",
};

const [signedUrl] = storage.bucket(bucketName).file(fileName).getSignedUrl(options);
return signedUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await generateSignedUrl();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)



---

VideoSDK offers individual participant recording, generating a single, continuous file for a participant.

This recording captures the participant's audio and video streams throughout the meeting, regardless of whether they are muted or have their camera turned off. During periods of audio muting or video disengagement, the respective tracks will be silent or display a black screen, respectively.

You can access the recorded files in the developer dashboard or opt to store them in your own cloud storage.

This guide provides an overview of the start and stop functionality for individual participant recording through APIs.


## Start Individual Participant Recording

To start a participant recording, you will have to call `/v2/recordings/participant/start` API with following body parameters.

- `roomId`: RoomId for which the participant recording is to be started
- `participantId`: participantId of the participant to be recorder.
- `fileFormat`: Currently only `webm` is supported as file format. We will add the support for other formats in future.
- `webhookUrl`: The webhook URL where you would like to get the status updates of the recording. To learn more about webhooks refer [here](#participant-track-recording-starting).
- `bucketDirPath`: If you are using your own storage, you can provide the directory path where you want to store the recording. To configure the storage please [refere this quide](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config).

The usual recording path would look like `${sessionId}/${participantId}/${filename}`.

```js
import Foundation

func startParticipantRecording() {
    let roomId = "<YOUR ROOM ID>"
    let participantId = "<PARTICIPANT ID>"
    let fileFormat = "<YOUR FILE FORMAT>" // (Optional) default: webm
    let bucketDirPath = "<YOUR CLOUD STORAGE BUCKET PATH>" // (Optional) test/abc
    let webhookUrl = "<YOUR WEBHOOK URL>" // (Optional)

    let url = URL(string: "https://api.videosdk.live/v2/recordings/participant/start")!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.addValue("$YOUR_TOKEN", forHTTPHeaderField: "Authorization")
    request.addValue("application/json", forHTTPHeaderField: "Content-Type")

    let json: [String: Any] = [
        "roomId": roomId,
        "participantId": participantId,
        "fileFormat": fileFormat,
        "bucketDirPath": bucketDirPath,
        "webhookUrl": webhookUrl
    ]

    let jsonData = try! JSONSerialization.data(withJSONObject: json)

    request.httpBody = jsonData

    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        guard let data = data, error == nil else {
            print("Error: \(error?.localizedDescription ?? "Unknown error")")
            return
        }
        let responseData = try? JSONSerialization.jsonObject(with: data, options: [])
        print(responseData)
    }

    task.resume()
}
```

## Stop Individual Participant Recording

To stop a participant recording, you will have to call `/v2/recordings/participant/stop` API with following body parameters.

- `roomId`: RoomId for which the participant recording is to be stopped
- `participantId`: participantId for which the recording is to be stopped.

```js
import Foundation

func stopParticipantRecording(roomId: String, participantId: String) {
    let url = URL(string: "https://api.videosdk.live/v2/recordings/participant/stop")!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.setValue("$YOUR_TOKEN", forHTTPHeaderField: "Authorization")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")

    let body: [String: Any] = ["roomId": roomId, "participantId": participantId]
    request.httpBody = try? JSONSerialization.data(withJSONObject: body)

    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        guard let data = data, error == nil else {
            print("Failed to stop participant recording")
            return
        }

        if let jsonResponse = try? JSONSerialization.jsonObject(with: data, options: []) {
            print(jsonResponse)
        } else {
            print("Failed to parse response")
        }
    }

    task.resume()
}
```

## Webhook associated with Participant Recording

### participant-recording-starting

- A "Participant Recording Starting" webhook is triggered when the participant recording process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-started

- Participant Recording started webhook will be received when successfully participant recording is started in meeting

###### Example

```javascript
{
    "webhookType": "participant-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopping

- A "Participant Recording Stopping" webhook is triggered when the participant recording end process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopped

- Participant Recording stopped webhook will be received when participant recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "participant-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-recording-failed

- A "Participant Recording Failed" webhook is generated when the participant recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "participant-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
    },
}
```

---

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Participant Recording API](/api-reference/realtime-communication/start-participant-recording)
- [Stop Participant Recording API](/api-reference/realtime-communication/stop-participant-recording)



---

VideoSDK provides participant track recording, creating separate audio or video files for participant.

New files are generated when a participant starts their audio or video again after turning it off (e.g., unmuting the microphone or restarting the camera). This ensures that each file represents a continuous segment of audio or video content.

Once track recording is complete, all audio files for a participant are consolidated into a single directory, as are the video files.


## Start Participant Track Recording

To start a participant track recording, you will have to call `/v2/recordings/participant/track/start` API with following body parameters.

- `roomId`: RoomId for which the participant track recording is to be started
- `participantId`: participantId of the participant to be recorder.
- `kind`: The kind of tracks you want to record.
  - You can pass following values: _`audio`_ | _`video`_ | _`screen_audio`_ | _`screen_video`_
- `fileFormat`: Currently only `webm` is supported as file format. We will add the support for other formats in future.
- `webhookUrl`: The webhook URL where you would like to get the status updates of the recording. To learn more about webhooks refer [here](#participant-track-recording-starting).
- `bucketDirPath`: If you are using your own storage, you can provide the directory path where you want to store the recording. To configure the storage please [refere this quide](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config).

The usual recording path would look like `${sessionId}/${participantId}/${kind}/${filename}`.

```js
import Foundation

func startTrackRecording() {
    let roomId = "<YOUR ROOM ID>"
    let participantId = "<PARTICIPANT ID>"
    let kind = "<YOUR STREAM KIND>"
    let fileFormat = "<YOUR FILE FORMAT>"
    let bucketDirPath = "<YOUR CLOUD STORAGE BUCKET PATH>"
    let webhookUrl = "<YOUR WEBHOOK URL>"

    let json: [String: Any] = [
        "roomId": roomId,
        "participantId": participantId,
        "kind": kind,
        "fileFormat": fileFormat,
        "bucketDirPath": bucketDirPath,
        "webhookUrl": webhookUrl
    ]

    let jsonData = try? JSONSerialization.data(withJSONObject: json)

    var request = URLRequest(url: URL(string: "https://api.videosdk.live/v2/recordings/participant/track/start")!)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.setValue("$YOUR_TOKEN", forHTTPHeaderField: "Authorization")
    request.httpBody = jsonData

    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        if let error = error {
            print("Error: \(error)")
            return
        }

        if let data = data, let responseString = String(data: data, encoding: .utf8) {
            print("Response: \(responseString)")
        }
    }

    task.resume()
}
```

## Stop Participant Track Recording

To stop a participant track recording, you will have to call `/v2/recordings/participant/track/stop` API with following body parameters.

- `roomId`: RoomId for which the participant track recording is to be stopped
- `participantId`: participantId for which the recording is to be stopped.
- `kind`: The kind of track recording you want to stop for the given participant.
  - You can pass following values: _`audio`_ | _`video`_ | _`screen_audio`_ | _`screen_video`_

```js
import Foundation

func stopTrackRecording() {
    let roomId = "<YOUR ROOM ID>"
    let participantId = "<PARTICIPANT ID>"
    let kind = "<YOUR STREAM KIND>"

    let json: [String: Any] = [
        "roomId": roomId,
        "participantId": participantId,
        "kind": kind
    ]

    let jsonData = try? JSONSerialization.data(withJSONObject: json)

    var request = URLRequest(url: URL(string: "https://api.videosdk.live/v2/recordings/participant/track/stop")!)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.setValue("$YOUR_TOKEN", forHTTPHeaderField: "Authorization")
    request.httpBody = jsonData

    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        if let error = error {
            print("Error: \(error)")
            return
        }

        if let data = data, let responseString = String(data: data, encoding: .utf8) {
            print("Response: \(responseString)")
        }
    }

    task.resume()
}
```

## Webhook associated with Participant Track Recording

### participant-track-recording-starting

- A "Participant Track Recording Starting" webhook is triggered when the track recording process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-started

- Participant Track Recording started webhook will be received when successfully track recording is started in meeting

###### Example

```javascript
{
    "webhookType": "participant-track-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopping

- A "Participant Track Recording Stopping" webhook is triggered when the track recording end process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopped

- Participant Track Recording stopped webhook will be received when track recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-track-recording-failed

- A "Participant Track Recording Failed" webhook is generated when the track recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Track Recording API](/api-reference/realtime-communication/start-track-recording)
- [Stop Track Recording API](/api-reference/realtime-communication/stop-track-recording)



---

### Storage Configuration

While recording your meetings, you have the flexibility to store them either on VideoSDK's storage or configure your own storage solution such as **`AWS S3 Storage, Azure Blob or GCP Cloud Storage`**. To set up your own storage, you can navigate to the [API section](https://app.videosdk.live/api-keys) in the VideoSDK Dashboard.

- This feature allows you to configure storage provider for your meeting recordings.

- You can configure multiple storage provider with multiple API Keys.

- Currently, we support `AWS S3`, `Azure Blob` and `GCP Cloud Storage`. We will add support for other storage provider soon !!

## Prerequisites

- An active [VideoSDK Developer Account](https://app.videosdk.live)
- `Aws S3`, `Azure Blob Storage` or `GCP Cloud Storage` Credentials

## How to setup ?

### Step 1 : Select Api Key

<div style={{textAlign: 'center'}}>

![Dashboard](/img/tutorial/dashboard/api-key-dashboard.png)

</div>

- Go to [VideoSDK Dashboard](https://app.videosdk.live/api-keys).
- Select API Key for which, you want to set storage configuration.
- Then click on `Storage Config` Icon in Actions.

### Step 2 : Choose Cloud Storage Provider

![Dashboard](/img/tutorial/dashboard/storage-config.png)

- As you can see in the image, there are 3 Cloud Storage Provider (`Aws`, `Azure`, `GCP`).
- You can select a Cloud Storage Provider as per your requirements.

### Step 3 : Configure Bucket or Container

<h4> For Aws S3 Storage </h4>

![Aws S3](/img/tutorial/dashboard/s3.png)

- You will need AWS S3 Bucket. [Learn to create S3 Bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html).

- As you can see in the image, you will need enter `accessKeyId`, `secretAccessKey`, `region`, `bucket`, and `ACL` to setup for Aws S3 Storage.

- Click on `Save` button.

<hr />

<h4> For Azure Blob Storage: </h4>

![Azure Blob](/img/tutorial/dashboard/blob.png)

- You will need Azure Blob Container. [Learn to create Blob Container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal#create-a-container).

- As you can see in the image, you will need to enter `connectionString` and `containerName` to setup for Azure Blob.

- Click on `Save` button.

<hr />

<h4> For Google Cloud Storage: </h4>

<img src="/img/tutorial/dashboard/gcp.png" alt="GCP Cloud Storage" width="436" height="632"/>

1. You will need Google Cloud Storage Bucket. [Learn to create Google Cloud Storage Bucket](https://cloud.google.com/storage/docs/creating-buckets).

2. After creation, click on the <b> &#xFE19; </b>button in the upper right corner and select **`Project settings`**.

3. Under **`IAM and Admin`**, select **`Service Accounts`**. In the service account list, click on the <b> &#xFE19; </b> button for the account just added or created before, and select **`Manage keys`**.

4. Click **`ADD KEY > Create new key`**. Select **`JSON`** in the pop-up box and click **`CREATE`**. A json file is downloaded with the name format `projectId-xxxxxxxx.json`.

5. Open the downloaded json file, which looks like the following example:

```
{
  "type": "service_account",
  "project_id": "videosdk-12345",
  "private_key_id": "yourprivateidkeyyourprivateidkeyyourprivateidkey",
  "private_key": "-----BEGIN PRIVATE KEY-----\nThisisYourPrivateKeyThisisYourPrivateKeyThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\n-----END PRIVATE KEY-----\n",
  "client_email": "xxxx-xxxx@videosdk-12345.iam.gserviceaccount.com",
  "client_id": "123456789012345678901",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/videosdk%40videosdk-404307.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}
```

- As you can see in the image, you will need to enter `Project Id`, `Client Email`, `Bucket`, `Private Key` to setup for Google Cloud Storage Bucket. You can retrieve these details from the json file.

- Click on `Save` button.

### Step 4 : Test

- It's time to test !!
- [Create Room](https://docs.videosdk.live/api-reference/realtime-communication/create-room) with token generated with the API Key, you have configured for.
- Start meeting with the roomId created and Start Recording !!
- Then, you can see that recording will be available in your Bucket or Container.

:::note

- Only a single Recording Storage Config can be possible for a particular Api Key at a time.
- In order to add new Recording Configuration, first you need to delete current configuration.

:::


---

# Recording in Live Stream - iOS

This guide will provide an overview of how to implement start and stop Recording during a live stream.

### `startRecording()`

The `startRecording()` method, accessible from the `useMeeting` hook, is used to initiate the recording of a live stream. This method accepts the following four parameters:

- `1. webhookUrl (optional)`: This is the webhook URL where you can listen to events related to the recording, such as the start and stop of recording. It triggers when the recording is completed and stored on the server. You can learn more about webhooks [here](https://en.wikipedia.org/wiki/Webhook)

- `2. awsDirPath (optional)`: This parameter specifies the path to your S3 bucket where you intend to store the recordings. To enable the storage of recordings in your S3 bucket with VideoSDK, follow this guide ([VideoSDK Cloud (AWS S3, Azure Blob or GCP ) Integration](/react/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config))

- `3. config (optional)`: This parameter defines how the recording should be conducted

- `4. transcription (optional)`: This parameter lets you start post transcription for the recording.

  :::caution

  If you don't have a value for `webhookUrl` or `awsDirPath` and wish to utilize the `config` property, you should pass `null` in place of the missing values. Failing to do so may result in the configuration not being applied to the recording.
  :::


**Swift:**

```js
class LiveStreamViewController {
// button to start recording the meeting
@IBAction func recordMeetingButtonTapped(_ sender: Any) {

     let transcription: PostTranscriptionConfig =  PostTranscriptionConfig(
        enabled: true,
        summary: SummaryConfig(
                enabled: true,
                prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
            )
        )
    //highlight-start
     self.meeting?.startRecording(webhookUrl: "<your webhook-url>",
                                awsDirPath: "<your awsDirPath>",
                                config: RecordingConfig(layout: ConfigLayout(type: .GRIDpriority: .SPEAKER, gridSize: 4),
                                theme: .DARK, mode: .video_and_audio,
                                quality: .high,
                                orientation: .portrait),
                                transcription: transcription)
    //highlight-end
}
}
```

### `stopRecording()`

The `stopRecording()` method, accessible from the `useMeeting` hook, is used to stop the recording of a live stream.

#### Example

**Swift:**

```js
class LiveStreamViewController {

// button to stop recording the meeting
@IBAction func stopRecordingButtonTapped(_ sender: Any) {
     self.meeting?.stopRecording()
}
}
```

:::important

To initiate automatic recording at the beginning of a `session`, simply provide the `autoStartConfig` feature `recording` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.

:::

### Events associated with recording

- **onRecordingStateChanged** - Whenever meeting recording state changes, then `onRecordingStateChanged` event will trigger.


**Swift:**

```js
extension LiveStreamViewController : MeetingEventListner {
//recording event
//highlight-start
func onRecordingStateChanged(state: RecordingState) {
    switch(state) {
        case .RECORDING_STARTING:
            print("recording starting")

        case .RECORDING_STARTED:
            print("recording started")

        case .RECORDING_STOPPING:
            print("recording stopping")

        case .RECORDING_STOPPED:
            print("recording stopped")
    }
}
//highlight-end
}
```

### API Reference

The API references for all the methods utilised in this guide are provided below.

- [startRecording()](/ios/api/sdk-reference/meeting-class/methods#startrecording)
- [stopRecording()](/ios/api/sdk-reference/meeting-class/methods#stoprecording)
- [onRecordingStateChanged](/ios/api/sdk-reference/meeting-class/events#onrecordingstatechanged)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

# Webhooks and Events - iOS

### Event associated with Recording

- **onRecordingStateChanged** - The `onRecordingStateChanged()` event is triggered whenever the state of meeting recording changes.

```js
extension LiveStreamViewController: MeetingEventListener {
    //recording event
    func onRecordingStateChanged(state: RecordingState) {
        switch(state) {
            case .RECORDING_STARTING:
                print("recording starting")

            case .RECORDING_STARTED:
                print("recording started")

            case .RECORDING_STOPPING:
                print("recording stopping")

            case .RECORDING_STOPPED:
                print("recording stopped")
        }
    }
}
```

:::important

You can access your recordings on our **[<u>Dashboard</u>](https://app.videosdk.live/meetings/recordings)**. Additionally, you can access your recordings using our **[<u>Recording API</u>](/api-reference/realtime-communication/fetch-recordings)**.

You can access your post transcriptions using our **[<u>Post Transcription API</u>](/api-reference/realtime-communication/fetch-post-transcriptions-summary)**

:::

## Webhook associated with Recording

### recording-starting

- A "Recording Starting" webhook is triggered when the recording process for a meeting is initiated.

###### Example

```javascript
{
    "webhookType": "recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-started

- Recording started webhook will be received when successfully recording is started in meeting

###### Example

```javascript
{
    "webhookType": "recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopping

- A "Recording Stopping" webhook is triggered when the recording end process for a meeting is initiated.

###### Example

```javascript
{
    "webhookType": "recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopped

- Recording stopped webhook will be received when recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
        "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",

    },
}
```

---

### recording-failed

- A "Recording Failed" webhook is generated when the recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```


---

# Relay Media(PK Host) - iOS

## Overview

The Relay Media feature enables hosts to relay their media (audio, video, screen share) to one or multiple other live streams. This creates cross-stream interactions similar to "PK battles" or collaborative broadcasts.

This feature allows audiences in one live stream to view and hear hosts from another live stream without changing rooms, creating powerful interactive experiences.

## Key Concepts

- **Media Relay**: The process of transmitting a host's audio/video from one live stream to another
- **Source Meeting**: The original live stream where the host is broadcasting
- **Destination Meeting**: The target live stream(s) where the host's media will be relayed
- **Relay Kinds**: The types of media that can be relayed (video, audio, screen share, etc.)

## Sequence Diagram



## Implementation Guide

### 1. Requesting Media Relay

### `requestMediaRelay()`

**Parameters:**

- `destinationMeetingId`: ID of the target liveStream
- `token`: Authentication token for the destination liveStream
- `kinds` : Optional array of media types to relay. Supported values:
  - `"video"`: Camera video
  - `"audio"`: Microphone audio
  - `"share"`: Screen share video
  - `"share_audio"`: Screen share audio

```swift
@IBAction func requestRelayBtn(_ sender: UIButton) {
    Task {
        meeting.requestMediaRelay(destinationMeetingId: "abc123", token: "YOUR_TOKEN_HERE", kinds: ["audio", "video"])
    }
}
```

### 2. Handling Relay Requests (Destination Meeting)

In the destination liveStream, hosts (participants with `SEND_AND_RECV` mode) will receive relay requests:

```swift
func liveStreamController : MeetingEventListener { 

    func onMediaRelayRequestReceived(participantId: String, meetingId: String, displayName: String, accept: @escaping () -> Void, reject: @escaping () -> Void) {
        
        guard let viewController = getTopViewController() else {
            return
        }

        let alert = UIAlertController(
            title: "Entry Request",
            message: "\(displayName) Reaquest MediaRelayRequest for \(meetingId). Allow?",
            preferredStyle: .alert
        )

        let acceptAction = UIAlertAction(title: "Accept", style: .default) { _ in
            accept()
        }

        let declineAction = UIAlertAction(title: "Decline", style: .destructive) { _ in
            reject()
        }

        alert.addAction(acceptAction)
        alert.addAction(declineAction)

        DispatchQueue.main.async {
            viewController.present(alert, animated: true)
        }
        
    }
}    
```

### 3. Handling Request Responses (Source Meeting)

In the source liveStream, track the response to your relay requests:

```swift

func liveStreamController : MeetingEventListener { 

    func onMediaRelayRequestResponse(decision: String, decidedBy: String, meetingId: String) {
        print("onMediaRelayRequestResponse: \(decision), \(decidedBy), \(meetingId)")
    }

}

```

### 4. Tracking Active Relays

When a relay successfully starts:

```swift
func liveStreamController : MeetingEventListener { 

    func onMediaRelayStarted(meetingId: String) {
       print("onMediaRelayStarted: \(meetingId)")
    }

}
```

### 5. Stopping Media Relay

To stop an ongoing relay:

### `stopMediaRelay()`

**Parameters:**

- `liveStreamId` (string): ID of the liveStream where the relay should stop

```swift
@IBAction func stopMediaRelayBtn(_ sender: UIButton) {
    Task {
        meeting?.stopMediaRelay(liveStreamId: "abc123")
    }
}
```

### 6. Handling Relay Stop Events

When a relay stops for any reason:

```swift

func liveStreamController: MeetingEventListener { 

    func onMediaRelayStopped(liveStreamId, reason) {
       print("onMediaRelayStopped: \(liveStreamId) \ (reason)")
    }
    
}
```

### 7. Handling Relay Errors

To handle errors that may occur during relay:

```swift
func liveStreamController: MeetingEventListener { 

    func onMediaRealyError(liveStreamId: String, error: String) {
        print("onMediaRealyError: \(liveStreamId), \(error)")
    }
    
}
```

## Use Cases

1.  **Guest Appearances:** Allow popular hosts to make guest appearances in other streams without leaving their audience
2.  **Cross-Stream Competitions:** Create "battles" or competitions between hosts in different streams
3.  **Multi-Location Broadcasting:** Connect hosts from different physical locations into a shared experience
4.  **Expert Commentary:** Bring in subject matter experts to comment on events in another stream

## Troubleshooting

### Common Issues

1.  **Relay Request Not Received**

    - Verify both meetings are active
    - Check that destination liveStream ID is correct
    - Ensure the token has proper permissions

2.  **Media Not Visible After Acceptance**

    - Verify network connectivity
    - Check that appropriate media kinds were specified
    - Ensure the host has enabled their camera/microphone

3.  **Unexpected Relay Termination**

    - Check for network connectivity issues
    - Verify that both meetings remain active
    - Look for error events with specific reasons

## API Reference

- [requestMediaRelay](/ios/api/sdk-reference/meeting-class/methods#requestmediarelay)
- [stopMediaRelay](/ios/api/sdk-reference/meeting-class/methods#stopmediarelay)
- [onMediaRelayRequestReceived](/ios/api/sdk-reference/meeting-class/events#mediarelayreceived)
- [onMediaRelayRequestResponse](/ios/api/sdk-reference/meeting-class/events#mediarelayresponse)
- [onMediaRelayStarted](/ios/api/sdk-reference/meeting-class/events#mediarelaystarted)
- [onMediaRelayStopped](/ios/api/sdk-reference/meeting-class/events#mediarelaystopped)
- [onMediaRelayError](/ios/api/sdk-reference/meeting-class/events#mediarelayerror)



---

# Release Notes - iOS




---

---
title: RTMP Livestream - Video SDK Docs
hide_title: false
hide_table_of_contents: false
description: RTMP Livestream features quick integrate in Javascript, React JS, Android, IOS, React Native, Flutter with Video SDK to add live video & audio conferencing to your applications.
sidebar_label: RTMP Livestream
pagination_label: RTMP Livestream
keywords:
  - Start Livestream meeting
  - Stop Livestream meeting
  - audio calling
  - video calling
  - real-time communication
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: rtmp-livestream
--- 

# RTMP Livestream - iOS


RTMP is a widely used protocol for live streaming video content from VideoSDK to platforms like YouTube, Twitch, Facebook, and others.

To initiate live streaming from VideoSDK to platforms supporting RTMP ingestion, you simply need to provide the platform-specific stream key and stream URL. This enables VideoSDK to connect to the platform's RTMP server and transmit the live video stream.

Furthermore, VideoSDK offers flexibility in configuring livestream layouts. You can achieve this by either selecting different prebuilt layouts in the configuration or by providing your custom template for livestreaming, catering to your specific layout preferences.

This guide will provide an overview of how to implement starting and stopping RTMP livestreaming with VideoSDK.

### `startLivestream()`

`startLivestream()` can be used to start a RTMP livestream of the meeting which can be accessed from the `Meeting` class. This method accepts two parameters:

- `outputs`: This parameter accepts a list of `LivestreamOutput` objects which contains the RTMP `url` and `streamKey` of the platforms you want to start the livestream.



**Swift:**

```js
class MeetingViewController {

private let platformUrl = "<url-of-the-platform>"
private let privateKey = "<private-key>"

// button to start livestream
@IBAction func startLiveStreamButtonTapped(_ sender: Any) {
    //highlight-start
     self.meeting?.startLivestream(outputs: LivestreamOutput(url: platformUrl, streamKey: privateKey))
    //highlight-end
}
}
```

### `stopLivestream()`

- `stopLivestream()` is used to stop the meeting livestream which can be accessed from the `Meeting` class.

#### Example

**Swift:**

```js
class MeetingViewController {
// button to stop livestream
@IBAction func startLiveStreamButtonTapped(_ sender: Any) {
    //highlight-start
     self.meeting?.stopLivestream()
    //highlight-end
}
}
```

### Event associated with Livestream

- **onLivestreamStateChanged** - Whenever meeting livestream state changes, then `onLivestreamStateChanged` event will trigger.

**Swift:**

```js
extension MeetingViewController: MeetingEventListener {
// rtmp-event
//highlight-start
func onLivestreamStateChanged(state: LiveStreamState) {
    switch(state) {
        case .LIVESTREAM_STARTING:
            print("livestream starting")

        case .LIVESTREAM_STARTED:
            print("livestream started")

        case .LIVESTREAM_STOPPING:
            print("livestream stoping")

        case .LIVESTREAM_STOPPED:
            print("livestream stopped")
    }
}
//highlight-end
}
```


### Custom Template

With VideoSDK, you have the option to employ your own custom-designed layout template for RRTMP livestreaming. To use a custom template, [follow this guide](/react/guide/interactive-live-streaming/custom-template) to create and set up the template. Once the template is configured, you can initiate recording using the [REST API](/api-reference/realtime-communication/start-livestream), specifying the `templateURL` parameter.


## API Reference

The API references for all the methods utilised in this guide are provided below.

- [startLivestream()](/ios/api/sdk-reference/meeting-class/methods#startlivestream)
- [stopLivestream()](/ios/api/sdk-reference/meeting-class/methods#stoplivestream)
- [onLivestreamStateChanged](/ios/api/sdk-reference/meeting-class/events#onlivestreamstatechanged)


---

# Sending Virtual Gifts - iOS

Virtual gifting is a powerful monetization and engagement feature that allows viewers to support hosts or speakers during a livestream by sending them digital tokens or "gifts." These gifts can be visually animated and even linked to leaderboards or reward systems.

This guide explains how to implement a secure and real-time virtual gifting experience using your backend server in combination with VideoSDK PubSub.

### How It Works
1. User Action: A viewer taps on a gift button to send a virtual gift to the host.

2. Server Verification:
   - A request is made to your business backend to process the gift.
    - The server authenticates the user, checks their wallet balance, deducts the gift value, and returns a success response.

3. Event Broadcast: Upon success, the client publishes a PubSub message to inform everyone in the meeting (host + other viewers) that a gift has been sent. Clients can then visually show an animation or notification.

### Backend Responsibility

Your backend plays a central role in verifying, validating, and processing gift transactions. It should:
  - Authenticate the request (token/session)
  - Verify if the user has sufficient balance
  - Deduct the gift cost
  - Store the transaction in a database (optional but recommended)
  - Respond with success or failure

### Frontend Implementation

- Sending a Gift (Client to Backend + PubSub)

```swift
import UIKit
import VideoSDKRTC

class GiftSenderViewController: UIViewController {
    var meeting: Meeting!

    func sendGift(giftType: String, senderId: String, hostId: String) {
        let url = URL(string: "https://your-api.com/send-gift")!
        var request = URLRequest(url: url)
        request.httpMethod = "POST"
        let body: [String: Any] = [
            "senderId": senderId,
            "hostId": hostId,
            "giftType": giftType
        ]
        request.httpBody = try? JSONSerialization.data(withJSONObject: body)
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")

        let task = URLSession.shared.dataTask(with: request) { data, response, error in
            guard
                let data = data,
                let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
                let success = json["success"] as? Bool,
                success
            else {
                DispatchQueue.main.async {
                    self.showAlert(message: "Gift could not be sent.")
                }
                return
            }

            // Publish the gift event
            let message: [String: Any] = [
                "giftType": giftType,
                "from": senderId,
                "to": hostId
            ]
            self.meeting.pubSub.publish(topic: "GIFT", message: message, options: ["persist": true])
        }
        task.resume()
    }

    func showAlert(message: String) {
        let alert = UIAlertController(title: "Gift", message: message, preferredStyle: .alert)
        alert.addAction(UIAlertAction(title: "OK", style: .default))
        present(alert, animated: true)
    }
}
```
- Displaying the Gift (All Clients)

```swift
import UIKit
import VideoSDKRTC

class GiftReceiverViewController: UIViewController, PubSubMessageListener {
    var meeting: Meeting! // Assume this is your current meeting instance
    var gifts: [[String: Any]] = []

    override func viewDidLoad() {
        super.viewDidLoad()
        meeting.pubSub.subscribe(topic: "GIFT", forListener: self)
    }

    func onMessageReceived(message: PubSubMessage) {
        guard let giftData = message.message as? [String: Any] else { return }
        gifts.append(giftData)
        DispatchQueue.main.async {
            self.displayGiftToast(giftData: giftData)
        }
    }

    func displayGiftToast(giftData: [String: Any]) {
        guard
            let from = giftData["from"] as? String,
            let to = giftData["to"] as? String,
            let giftType = giftData["giftType"] as? String
        else { return }

        let toast = UILabel()
        toast.text = "🎁 \(from) sent a \(giftType) to \(to)"
        toast.backgroundColor = UIColor.black.withAlphaComponent(0.6)
        toast.textColor = .white
        toast.textAlignment = .center
        toast.frame = CGRect(x: 20, y: self.view.frame.height - 100, width: self.view.frame.width - 40, height: 50)
        toast.alpha = 0
        self.view.addSubview(toast)

        UIView.animate(withDuration: 0.5, animations: {
            toast.alpha = 1
        }) { _ in
            UIView.animate(withDuration: 0.5, delay: 2, options: [], animations: {
                toast.alpha = 0
            }) { _ in
                toast.removeFromSuperview()
            }
        }
    }
}
```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [PubSub()](/ios/api/sdk-reference/meeting-class/pubsub)


---

# Initialize Live Stream - iOS

To configure livestreaming with VideoSDK you require two things, first the `token` which will be used for **Authentication** purpose and a `streamId` which will be used to specify where the hosts and audience will join.

### Generating Token

You can generate a `token` in two ways:

1. **`Temporary Token`** : You can visit [Dashboard's API Key section](https://app.videosdk.live/api-keys) and generate a temporary token from there.

2. **`Server`** : You can setup **JWT** in backend and make an API call to get the token from your server.

To learn more about **Authentication** and token in detail you can follow [this guide](/react/guide/video-and-audio-calling-api-sdk/authentication-and-token).



**Swift:**

```js
// Update server url here.
let LOCAL_SERVER_URL = "http://192.168.0.101:9000"

class APIService {

class func getToken(completion: @escaping (Result<String, Error>) -> Void) {
    var url = URL("string: LOCAL_SERVER_URL")!
    url = url.appendingPathComponent("get-token")

    URLSession.shared.dataTask(with: url) { data, response, error in
        if let data = data, let token = data.toJSON()["token"] as? String {
          //highlight-next-line
            completion(.success(token))
        } else if let err = error {
            completion(.failure(err))
        }
    }
    .resume()
}
}
```


### Generating Stream Id

With the token ready, you can now get the `streamId` from the [VideoSDK's rooms API](/api-reference/realtime-communication/create-room).
**Swift:**

```js
// Update server url here.
let LOCAL_SERVER_URL = "http://192.168.0.101:9000"

class APIService {

class func createStreamId(token: String, completion: @escaping (Result<String, Error>) -> Void) {
    var url = URL(string: LOCAL_SERVER_URL)!
    url = url.appendingPathComponent("create-meeting")

    let params = ["token": token]

    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.httpBody = try? JSONSerialization.data(withJSONObject: params, options: [])

    URLSession.shared.dataTask(with: request) { data, response, error in
        if let data = data, let meetingId = data.toJSON()["meetingId"] as? String {
          //highlight-next-line
            completion(.success(meetingId))
        } else if let err = error {
            completion(.failure(err))
        }
    }
    .resume()
}
}
```

### Initialization of Live Stream

1. To initialize the live stream, first we have to set the token of VideoSDK class.
   By using `config()` method, you can set the token property of VideoSDK class.

```js title="config"
VideoSDK.config("<your token>");
```

2. Now, we can initialize the live stream using a factory method provided by the SDK called `initMeeting()`. By passing the parameters according to the need, it will generate a new Meeting class and the initiated meeting will be returned.

`initMeeting()` is responsible for initializing the meeting with the provided configuration, which includes the `meetingId`, `name`, `participantId` and many more.

Let's take a deeper look at the available configuration options first.

```js title="initMeeting"
    let meeting = VideoSDK.initMeeting(
            meetingId: "abcd-efgh-hijk",
            participantId: "JD", //optional
            participantName: "John Doe",
            micEnabled: true,
            webcamEnabled: true,
            customCameraVideoStream: customVideoStream, //optional
            customAudioTrack: customAudioStream, //optional
            mode: .SEND_AND_RECV, //optional (default mode is conference)
        )
```

- **`meetingId`** :

  - This is a unique identifier that allows participants to join a specific live stream.
  - It will be in the format of `xxx-yyy-zzz` and will be generated using the [VideoSDK's Room API](/api-reference/realtime-communication/create-room).

- **`mode`** :

  - This paramter defines the mode the participant will enter the live stream with.
  - `SEND_AND_RECV`: For hosts/co-hosts who can send and receive media.
  - `RECV_ONLY`: For audience members who can only receive media.​


- **`name`**:

  - This represents the name of the participant in the live streams.
  - It will accept `String` type value.

- **`micEnabled`**:

  - This is a `boolean` flag, indicating whether a participant's microphone will be automatically enabled when they join the live stream. This property will be completely ignored for Audience participants, as they are not allowed to publish their audio.

- **`webcamEnabled`**:

  - This is a `boolean` flag, indicating whether a participant's webcam will be automatically enabled when they join the live stream. This property will be completely ignored for Audience participants, as they are not allowed to publish their video.

- **`metaData`**:

  - If you want to provide additional details about the participants joining the live stream, such as their profile image, you can pass that information in this parameter.
  - It has to be of `Object` type.
  - This is an `OPTIONAL` parameter.

- **`participantId`**:

  - This is a unique identifier for the participant's inside the live stream.

    - It can be used to specify the **unique identifier** which can be linked with **your own database** service.
    - It has to be of `String` type.
    - This is an `OPTIONAL` parameter. By default VideoSDK will generate unique id for each participant.

- **`multistream`**:

  - This is a `boolean` flag, indicating whether the host's media stream should send multiple resolution layers or a single resolution layer.

:::caution
You must ensure that the `participantId` is not repeated in the same livestream. This will enable VideoSDK to eliminate any participant associated with that `participantId`.
:::

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [initMeeting](/ios/api/sdk-reference/initMeeting)


---

---
title: Join/Leave Live Stream | Video SDK
hide_title: true
hide_table_of_contents: false
description: Easily integrate join and leave functionalities for interactive live streams using Video SDK’s ReactSDK with event handling for participant management.
sidebar_label: Join/Leave Live Stream
pagination_label: Join/Leave Live Stream
keywords:
  - audio calling
  - video calling
  - real-time communication
  - collaboration
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: join-leave-livestream
--- 

# Join Live Stream - iOS

Once, the live stream is configured, the next step is to join it. With our iOS SDK, you can choose to manually call the `join()` method. If you have not initialized the live stream yet, you can [follow the guide here.](/ios/guide/interactive-live-streaming/setup-livestream/initialize-livestream)

### `join()`

- To join the meeting you can call the `join()` method of `Meeting` class.
- This method can be called after the meeting is initialized using `VideoSDK` class.

### Events associated with the join() method

Following events are received when a participant successfully joins the livestream.

- [Local Participant](../concept-and-architecture#2-participant) will receive a [`onMeetingJoined`](/ios/api/sdk-reference/meeting-class/events#onmeetingjoined) event, when successfully joined.
- [Remote Participant](../concept-and-architecture#2-participant) will receive a [`onParticipantJoined`](/ios/api/sdk-reference/meeting-class/events#onparticipantjoined) event with the newly joined `Participant` object from the event callback.



**Swift:**

```js

func handleJoinStream(){
//highlight-start
meeting?.join()
//highlight-end
}

extension LiveStreamViewController: MeetingEventListener {

// Event to know meeting is joined
//highlight-start
func onMeetingJoined() { 
    print("You just joined the livestream")
}
//highlight-end

// Event to know some other participant joined
//highlight-start
func onParticipantJoined(_ participant: Participant) {
    print("A new remote participant", \(participant.displayName) + "just joined the livestream")
}
//highlight-end
}
```



### `leave()`

- To leave the live stream you can call the `leave()` method which is the part of the `useMeeting` hook of React SDK.

:::note
This method can be called only after the live stream is joined successfully.
:::

### Events associated with the leave() method

Following callbacks are received when a participant leaves the live stream.

- The [Local Participant](/react/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive the [`onMeetingLeft`](/react/api/sdk-reference/use-meeting/events#onmeetingleft) event, once they have successfully left the livestream.
- All the [Remote Participants](/react/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant)—including all the hosts and audience members—will receive the [`onParticipantLeft`](/react/api/sdk-reference/use-meeting/events#onparticipantjoined) event with the `Participant` object of the user who left the livestream.

**Swift:**

```js

func handleLeaveStream(){
//highlight-start
meeting?.leave()
//highlight-end
}

extension LiveStreamViewController: MeetingEventListener {
  //highlight-start
func onMeetingLeft() {
    
    // remove listeners
    meeting?.localParticipant.removeEventListener(self)
    meeting?.removeEventListener(self)
    
    print("You left the livestream")
}

func onParticipantLeft(_ participant: Participant) {
    
    // remove listener
    participant.removeEventListener(self)
    
    print(participant.displayName, "just left the livestream")
}
  //highlight-end
}
```

:::tip
You should call the `leave()` method on the unmount of your main live stream component so that live stream is left once the view is unmounted.
:::

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [initMeeting](/ios/api/sdk-reference/initMeeting)
- [join()](/ios/api/sdk-reference/meeting-class/methods#join)
- [onMeetingJoined()](/ios/api/sdk-reference/meeting-class/events#onmeetingjoined)
- [onParticipantJoined()](/ios/api/sdk-reference/meeting-class/events#onparticipantjoined)
- [leave()](/ios/api/sdk-reference/meeting-class/methods#leave)
- [onMeetingLeft()](/ios/api/sdk-reference/meeting-class/events#onmeetingleft)
- [onParticipantLeft()](/ios/api/sdk-reference/meeting-class/events#onparticipantleft)


---

# Waiting Screen - iOS

To create a smoother and more polished entry experience for audience members, it's important not to immediately render the meeting room when they join. Instead, show a waiting screen until at least one host is present in the room.

### Why This Matters?

- Hosts are typically responsible for driving the meeting, and their presence is essential before audience members should be able to view or interact in the room.

- Allowing audience members (in RECV_ONLY mode) to enter a meeting with no active hosts (in SEND_AND_RECV mode) can result in confusion and a poor user experience.

### Participant Modes

- Hosts must join the meeting with the SEND_AND_RECV mode.
- Audience members should join with the RECV_ONLY mode.

### Implementation Guide

You can achieve this behavior by using the participants list and onParticipantJoined event from the useMeeting hook.

1. Check if a Host is Present
   On initial render, use the participants object to determine if there's already a host in the room:

```js
func hasHost(participants: [String: Participant]) -> Bool {
    return participants.values.contains { $0.mode == "SEND_AND_RECV" }
}
```

If hasHost is true, render the meeting view. Otherwise, show the waiting screen.

2. Listen for Host Join
   Always listen for the onParticipantJoined event in case a host joins after the audience participant:

```js

extension LiveStreamViewController: MeetingEventListener {
    
    func onParticipantJoined(_ participant: Participant) {
        if participant.mode == "SEND_AND_RECV" {
            // Update your UI or state to show the meeting view
            DispatchQueue.main.async {
                self.showMeetingView()
            }
        }
    }
}
```

This ensures that as soon as a host joins, the waiting audience members are transitioned smoothly into the meeting view.

<div style={{ textAlign: 'center' }}>
    <img
        src="https://cdn.videosdk.live/docs/images/flutter/ils/waiting_screen_flutter.jpg"
        alt="Waiting Screen"
         style={{height: '450px'}}
    />
</div>


---

# Supported Device OS

:::note
The following device OS version represent the minimum required version to ensure full support for the listed features.
:::




##### SDK Size - 18 MB


---

# Switch Live Stream - iOS

## Overview

The **Switch Live Stream** feature enables users to **seamlessly transition** between live streams without needing to manually disconnect and reconnect. This drastically improves user experience by reducing latency and preserving media and socket connections.

### Previously

1.  Users had to **disconnect** from the current liveStream.
2.  Then **manually connect** to a new liveStream:
    - New socket connection created.
    - New media transports initialized.
    - Delays due to re-connection and media setup.

This led to:

- **Higher latency**
- **Socket transport downtime**
- **Poor experience** for users switching frequently between rooms

### New Behavior with `switchTo`

- Keeps the existing **socket connection** alive
- Reuses or reconfigures existing **media**
- Switches the server-side context to the **new liveStream**

### `switchTo()`

#### **Parameters**

- **liveStreamId** (`string`, required): ID of the new liveStream to join
- **token** (`string`, optional): VideoSDK token for authentication

```swift

@IBAction func switchToMeeting(_ sender: UIButton) {
    Task {
        meeting?.switchTo(meetingId: "MEETING_ID", token: "YOUR_TOKEN")
    }
}

```

## Important Considerations

### Meeting Status

- **The destination liveStream must be active** before attempting to switch.
- If the destination liveStream is inactive or doesn't exist, the switch will fail.

### Token Management

- **Token Expiry**: Be careful with short-lived tokens when using the switch feature.
  - If you're using short-lived tokens for security reasons, always provide a new token in the `switchTo` method.
  - Tokens that expire during a liveStream can cause unexpected disconnections.
- **Best Practice**: For frequent switches, use tokens with reasonable expiry times or implement a token refresh mechanism.

## API Reference

- [switchTo](/ios/api/sdk-reference/meeting-class/methods#switchto)


---

# Virtual Background - iOS

Virtual backgrounds enhance your **live stream experience** by allowing you to replace your physical background with a digital image or apply a blur effect. This is ideal for creators and streamers who want to maintain privacy, reduce distractions, or add a personal touch to their broadcast. You can use a preloaded background image or supply your own via a CDN.

<center>
<img src='https://cdn.videosdk.live/website-resources/docs-resources/virtual-background-ios.jpg' style={{height: '400px'}}/>
</center>

## Virtual Background using `VideoSDKBackgroundProcessor`

This is the easiest way to enable virtual backgrounds in your app. VideoSDK provides a handy class called VideoSDKBackgroundProcessor that takes care of replacing your background for you. Here's a step-by-step guide:

### Toggle Virtual Background

- Virtual background can be enabled by setting VideoSDK's `VideoSDKBackgroundProcessor`'s instance using the `setVideoProcessor` method of `Meeting` class.

- To disbale the virtual background, simply pass `nil` in `setVideoProcessor` and virtual background will be replaced with the normal camera stream.

**Example Code:**



**Swift:**

```js
class MeetingViewController {
  //variable for keeping track of Virtual Background
  var isVirtualBackground: Bool = false

// source url for the background image (make sure background is in portrait, else might get undesired output).
 let backgroundSource = URL(string: "https://cdn.videosdk.live/virtual-background/cloud.jpeg")!
  //create an inctance of VideoSDKBackgroundProcessor
  let processor = VideoSDKBackgroundProcessor(backgroundSource: backgroundSource)
  
// Button when tapped will toggle the virtual background for local participant
  @IBAction func toggleVirtualBackground(_ sender: Any) {

   if isVirtualBackground {
  // Turn off virtual background
  meeting.setVideoProcessor(processor: nil)
  isVirtualBackground = false
} else {
  // Turn on virtual background
  meeting.setVideoProcessor(processor: processor)
  isVirtualBackground = true
}
}
}
```

### Changing Background Image

You can also change the background image dynamically using the `changeBackground` method of the `VideoSDKBackgroundProcessor` class.

**Swift:**

```js
class MeetingViewController {
  // processor instance
  // let processor = VideoSDKBackgroundProcessor()

  // Button when tapped will toggle the virtual background for local participant
  @IBAction func changeBackgroundTapped(_ sender: Any) {
// URL of new background image
let backgroundSource = URL(string: "https://cdn.videosdk.live/virtual-background/san-fran.jpeg")!

// Call changeBackground method of VideoSDKBackgroundProcessor
self.processor.changeBackground(backgroundSource: backgroundSource)
  }
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [setVideoProcessor()](/ios/api/sdk-reference/meeting-class/methods#setvideoprocessor)


---



---

# Overview of SIP with VideoSDK - iOS


SIP (Session Initiation Protocol) is extensively employed for setting up and controlling IP-based calls. It facilitates the initiation and termination of user sessions over IP networks, enabling SIP-based systems to connect and exchange voice communications over the internet.

With VideoSDK's SIP Connect feature, you can enable your users to join VideoSDK meetings via VOIP using third-party service providers. This allows for establishing a bridge between participants using our client SDKs and those joining via SIP, enhancing the accessibility and connectivity of your video meetings.

![SIP Architecture](https://cdn.videosdk.live/website-resources/docs-resources/sip-architechture.png)

### Getting SIP Credentials

To use SIP Connect, you will first need to generate the credentials for the SIP. Go to the [VideoSDK dashboard](https://app.videosdk.live) and under the [API Keys](https://app.videosdk.live/api-keys) sections, first enable the SIP for the desired API key after which you will be presented with the SIP `username` and `password` you can use to establish connection with our SIP servers.

![SIP Credentials](https://cdn.videosdk.live/website-resources/docs-resources/sip-get-credentials.gif)

### How to use SIP to join a particular meeting?

Once you have the credentials, you can use any of the softphones like Linphone, Zoiper etc. or use a third party service provider like twilio to connect with a VideoSDK meeting by initiating a SIP call to `sip:<meeting-id>@sip.videosdk.live`

For example if you want to connect to `abcd-abcd-abcd` meeting then the SIP address will look like `sip:abcd-abcd-abcd@sip.videosdk.live`

### Example of Twilio PSTN

To utilize third-party PSTN (Public Switched Telephone Network) providers like Twilio for making calls via SIP (Session Initiation Protocol), follow these steps:

1. Log in to your Twilio account and navigate to the Phone Numbers section.
2. Purchase a phone number and access its configuration settings.
3. Set up a Webhook handler that will initiate a call to the VideoSDK SIP endpoint whenever an incoming call is received on the selected phone number.

![SIP Configuration for Twilio](https://cdn.videosdk.live/website-resources/docs-resources/sip-twilio-config.png)

##### Example for creating Webhook using Express

```js
const express = require("express");
const VoiceResponse = require("twilio").twiml.VoiceResponse;
const urlencoded = require("body-parser").urlencoded;

const app = express();

// Parse incoming POST params with Express middleware
app.use(urlencoded({ extended: false }));

// Webhook route which will be called by twilio when a call is received
app.post("/incoming-call-handler", (request, response) => {
  console.log({ request });
  // Use the Twilio Node.js SDK to build an XML response
  const twiml = new VoiceResponse();

  const dial = twiml.dial();
  dial.sip(
    {
      username: "<User name generated for dashboard>",
      password: "<Password generated from dashboard>",
    },
    "sip:<meetingId>@sip.videosdk.live"
  );

  // Render the response as XML in reply to the webhook request
  response.type("text/xml");
  response.send(twiml.toString());
});

//Start the express app on port 8000
app.listen(8000, () => {
  console.log(`Server listening on port ${8000}.`);
});
```



---

# Build a SIP Integration: VideoSDK & Twilio for Inbound Outbound Calls! Step-by-Step


Imagine joining an online meeting using just your phone—no apps, no browsers, no internet. This powerful option allows participants to connect via traditional telephony, by creating a bridge between phone systems and modern video conferencing platforms. In this post, we’ll explore how to build a SIP integration using VideoSDK and Twilio for both inbound and outbound VoIP calls.



We’ll break down the flow of calls, set up the project, and show you how to bring this functionality to life using Next.js.

## What Is a SIP Integration?

SIP, or Session Initiation Protocol, enables voice and video communications over internet-based networks. With SIP integrations, traditional phone systems can connect to online platforms .

By integrating SIP with VideoSDK’s SIP address and Twilio, you can handle both inbound and outbound calls while linking them to video meetings. This integration is particularly helpful for situations where participants lack internet access, allowing them to simply dial in to join a meeting or receive phone calls initiated by meeting participants.

## Understanding Inbound and Outbound Call Flows

### Inbound Calls

![Inboud Call Flow](https://assets.videosdk.live/images/inbound.png)

Inbound calls are initiated by a user or customer dialing a phone number, such as a Twilio-provisioned number. Here’s how the process works:

1. **User Dialing**: A participant dials the Twilio number tied to the SIP integration.
2. **Call Routing**: Twilio receives the call and notifies your server with call details.
3. **Server Processing**: Your server processes the request and sends an invite SIP request to the VideoSDK SIP address.
4. **Connection Established**: Once validated, the caller is connected to the specific video meeting through VideoSDK.

For example, if a customer wants to join a video conference using their phone, they can call a designated number. Following this process, the integration connects them to the meeting.

### Outbound Calls

![Outbound Call Flow](https://assets.videosdk.live/images/outbound.png)

Outbound calls begin with a participant or agent in an online meeting initiating a call to a customer’s phone. The process involves the following steps:

1. **Call Request Initiated**: A participant requests your server to call a specific phone number.
2. **Server Action**: The server notifies Twilio to establish the call.
3. **User Accepts Call**: When the user accepts, the connection is forwarded to the video meeting through VideoSDK.

This two-way communication ensures smooth interaction between online participants and phone users.

## Step-by-Step Guide to Setting Up the Project

### Prepare the Project Files

1. Create a workspace for the SIP integration project (or open your existing project if you already have one).

```bash
mkdir videosdk-sip-integration && cd videosdk-sip-integration
```

1. Navigate to project directory

```javascript
cd videosdk-sip-integration
```

1. Install dependencies that are required for you application to work

```javascript
npm install
```

### Configure the Environment

1. **Set Up the `.env` File**: Copy the `.env.example` file in the repository and rename it to `.env`.
2. **Add VideoSDK Details**: Obtain the SIP username, password, and authentication token from the [VideoSDK dashboard](https://app.videosdk.live/).
   - Generate an authentication token under “API Keys.”
   - Get your SIP username and password from the “SIP Config” section.
   - Add these details to the `.env` file.
3. **Configure Twilio**: Sign in to your [Twilio console](https://console.twilio.com/).
   - Copy your Twilio phone number, Account SID, and Auth Token.
   - Paste these values into the `.env` file.

```javascript
TWILIO_ACCOUNT_SID=your-twilio-account-sid
TWILIO_AUTH_TOKEN=your-twilio-auth-token
VIDEOSDK_SIP_USERNAME=your-videosdk-sip-username
VIDEOSDK_SIP_PASSWORD=your-videosdk-sip-password
NEXT_PUBLIC_TWILIO_PHONE_NUMBER=your-twilio-phone-number
NEXT_APP_URL=http://localhost:3000 # Replace with your production URL
```

Your `.env` file should now contain all necessary credentials.

### Running the Application

Once the configurations are complete, start the project using the following command:

```bash
npm run dev
```

![demo home page](https://assets.videosdk.live/images/demo.png)

The application will run locally on port 3000.



## Setting Up Call Routing

### Inbound Call Setup

**Define the API URL**: In Twilio’s Active Numbers section, specify your API endpoint (e.g., `/api/webhook/inbound`). Twilio will send incoming call details to this URL.

If hosting locally, tools like `ngrok` or `pinggy` can expose your server to the internet for testing purposes. Replace the localhost URL with the public domain generated by these tools in the Twilio configuration.

![Twilio Dashboard](https://assets.videosdk.live/images/twilio-dashboard.png)

**Handle Calls with VideoSDK**: Once Twilio routes the call, your code forwards the meeting ID to VideoSDK’s SIP address. This connects the caller to the online meeting.

```javascript

// Environment variables
const accountSid = process.env.TWILIO_ACCOUNT_SID || "";
const authToken = process.env.TWILIO_AUTH_TOKEN || "";
const videosdkSipUsername = process.env.VIDEOSDK_SIP_USERNAME || "";
const videosdkSipPassword = process.env.VIDEOSDK_SIP_PASSWORD || "";

const client = twilio(accountSid, authToken);

export async function POST(request: Request): Promise<Response> {
  try {
    const url = new URL(request.url);
    const meetingId = url.searchParams.get("meetingId");

    const twiml = new twilio.twiml.VoiceResponse();
    twiml.say("Welcome to the Video sdk conference. Connecting you now.");
    twiml.dial().sip(
      {
        username: videosdkSipUsername,
        password: videosdkSipPassword,
      },
      `sip:${meetingId}@sip.videosdk.live`
    );

    return new Response(twiml.toString(), {
      headers: {
        "Content-Type": "text/xml",
      },
    });
  } catch (error) {
    console.error("Error processing Twilio webhook:", error);

    // Return TwiML error response
    const twiml = new twilio.twiml.VoiceResponse();
    twiml.say("Sorry, there was an error connecting your call.");

    return new Response(twiml.toString(), {
      headers: {
        "Content-Type": "text/xml",
      },
    });
  }
}
```

### Outbound Call Setup

For outbound calls, the meeting participant in the web app interacts with an API endpoint that sends a request to Twilio. Twilio establishes the call with the provided number, connecting the phone user back to the meeting through VideoSDK.

```javascript

// Environment variables
const accountSid = process.env.TWILIO_ACCOUNT_SID || "";
const authToken = process.env.TWILIO_AUTH_TOKEN || "";
const twilioPhoneNumber = process.env.NEXT_PUBLIC_TWILIO_PHONE_NUMBER || "";

const client = twilio(accountSid, authToken);

export const dynamic = "force-dynamic";

export async function POST(request: Request): Promise<Response> {
  try {
    const { phoneNumber, meetingId } = await request.json();

    if (!phoneNumber) {
      throw new Error("phone number is required!");
    }

    // Make the outbound call
    const call = await client.calls.create({
      to: phoneNumber,
      from: twilioPhoneNumber,
      url: `${process.env.NEXT_APP_URL}/api/webhook/inbound?meetingId=${meetingId}`,
      method: "POST",
    });

    return new Response(JSON.stringify({ success: true, callSid: call.sid }), {
      headers: {
        "Content-Type": "application/json",
      },
    });
  } catch (error) {
    console.error("Error making outbound call:", error);

    return new Response(
      JSON.stringify({
        success: false,
        error: "Failed to initiate call",
      }),
      {
        status: 500,
        headers: {
          "Content-Type": "application/json",
        },
      }
    );
  }
}
```

**Create an Outbound API**: Write an API function to trigger calls using Twilio’s client instancee.g., `/api/webhook/outbound`)

**Trigger Outbound Calls**: Use this API in your application to handle requests for dialing specific numbers.

When the call is accepted, the system routes it to the VideoSDK SIP address, establishing a connection to the meeting.

## Testing the Integration

To test the setup:

1. Make a call to the Twilio number for inbound calls.
   - Ensure the meeting ID and SIP configurations are correctly passed.
2. Initiate an outbound call from a meeting participant to a phone number.
   - Validate that the phone user is successfully connected to the meeting.

Both inbound and outbound calls should work smoothly, demonstrating the bridged connection between telephony and video conferencing.

## Conclusion

Integrating SIP functionality into your project using VideoSDK and Twilio unlocks new possibilities for communication. By enabling inbound and outbound VoIP calls, you can connect traditional phone systems with modern video conferencing platforms.

This guide covered the basics of setting up the integration, routing calls, and ensuring smooth connectivity. If you encounter any issues or need further help, join the VideoSDK Discord community.

Simplify your users’ communication experience—embrace the power of SIP integration.



---

# Authentication and Token - iOS

VideoSDK uses access tokens for authentication. Using our dashboard ([app.videosdk.live](https://app.videosdk.live/)), anyone can generate access tokens tokens with an API key and secret pair.

- Your backend server will generate access tokens using API Key and secret.
- Your client obtains token from your backend server.
- Your client will pass the token to VideoSDK server.
- VideoSDK client sdk will conncts to the VideoSDK server with available token.
- VideoSDK server will validate the token and accpets your incoming connection.

Here is the simple sequence diagram represents the authentication.


## Generate API Key and Secret

Visit, [app.videosdk.live](https://app.videosdk.live/) to gererate API Key and secret.

![Generate API Key from Dashboard](/img/tutorial/generate-api-key.jpg)

## Generate Access Token

For security, every participant that connects to meeting needs a access token. By substituting `apikey` and `permissions` in it.



**node:**

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

// Need to generate from app.videosdk.live
const API_KEY = "API_KEY_GENERATED";
const SECRET_KEY = "API_SECRET_KEY_GENERATED";

jwt.sign(
  {
apikey: API_KEY,
permissions: ["allow_join"], // Permission to join the meeting
  },
  SECRET_KEY,
  {
algorithm: "HS256",
expiresIn: "24h",
jwtid: uuid4(),
  },
  function (err, token) {
console.log(token);
  }
);
```

---

**python:**

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

api_key = 'api_key_generated'
secret_key = 'secret_key_generated'


def generateToken():
expires = 24 * 3600
now = datetime.datetime.utcnow()
exp = now + datetime.timedelta(seconds=expires)
return jwt.encode(payload={
      'apikey': api_key,
      permissions: ["allow_join"]
    }, key=secret_key).decode('utf-8')

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

---

**java:**

```js
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("apikey", "<api_key_generated>");
payload.put("permissions", ["allow_join"]);
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, "<secret_key_generated>".getBytes()).compact();
  }
```

---

**ruby:**

```js
require 'jwt'
require 'securerandom'

$api_key = "api_key_generated"
$secret_key = "secret_key_generated"

def generateToken()
payload = {
  apikey: $api_key,
  permissions: ["allow_join"]
}
token = JWT.encode(payload, $secret_key, 'HS256')
return token
end

puts generateToken
```

---

**php:**

```js
<?php

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

$api_key = "api_key_generated";
$secret_key = "secret_key_generated"

$payload = [
'apikey' => api_key,
'permissions': ["allow_join"],
];

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

Available permissions are:

- **allow_join**: The participant will be permitted entry without request.
- **ask_join**: The participant will not be permitted entry without request.
- **allow_mod**: Allow participant to enable/disable other participant's mic/webcam.


---

# Chat using PubSub - iOS

For the communication or any kind of messaging in between the participants, VideoSDK provides `pubSub` class which use Publish-Subscribe mechanism and can be used to develope wide varitey of functionalities. For example, participants could use it to send chat messages to each other, share files or other media, or even trigger actions like muting or unmuting audio or video.

Now we will see, how we can use PubSub to implement Chat functionality. If you are not familiar with the PubSub mechanism and `pubSub` class, you can [follow this guide](./pubsub).

## Implementing Chat

### `Group Chat`

1. First step in creating a group chat is choosing the topic which all the participants will publish and subscribe to send and receive the messages. We will be using `CHAT` as the topic for this one.
2. On the send button, publish the message that the sender typed in the `Text` field.

:::note
It is assumed that you have created a user interface along with the implementation of the meeting class and its event listeners.
For reference checkout our iOS [example app](https://github.com/videosdk-live/videosdk-rtc-ios-sdk-example) on how can you setup your app.
:::



**Swift:**

```js
class MeetingViewController {
//Button that will send the message when tapped
@IBAction func sendMessageTapped(_ sender: Any) {
    let options = ["persist" : true]
    // publish message
    //highlight-next-line
    self.meeting?.pubsub.publish(topic: "CHAT", message: "How are you?", options: options)
}
}
```

3. Next step would be to display the messages others send. For this we have to `subscribe` to that topic i.e `CHAT` and display all the messages. When a message is received, the `onMessageReceived` event of the `PubSubMessageListener` is triggered.

**Swift:**

```js
extension MeetingViewController: MeetingEventListener {
func onMeetingJoined() {
//subscribe to the topic 'CHAT' when onMeetingJoined is triggered
 //highlight-next-line
meeting?.pubsub.subscribe(topic: "CHAT", forListener: self)
}
}
//highlight-start
extension MeetingViewController: PubSubMessageListener {
// read message when it is received
func onMessageReceived(_ message: PubSubMessage) {
    print("Message Received: " + message.message)
}
}
//highlight-end
```

4. Final step in the group chat would be `unsubscribe` to that topic, which you had previously subscribed but no longer needed. Here we are `unsubscribe` to `CHAT` topic on activity destroy.

**Swift:**

```js
extension MeetingViewController: MeetingEventListener {
func onMeetingLeft() {
//unsubscribe to the topic 'CHAT' when onMeetingLeft is triggered
////highlight-next-line
meeting?.pubsub.unsubscribe(topic: "CHAT", forListener: self)
}
}
```

### `Private Chat`

In the above example, if you want to convert into the private chat between two participants, then all you have to do is pass the participantID of the participant in the `sendOnly` option as `["sendOnly" : ["ABCD"]]`. Here sendOnly accepts array of participant IDs you wish to send message to.

**Swift:**

```js
class MeetingViewController {
//Button that will send the private message when tapped
@IBAction func sendPrivateMessageTapped(_ sender: Any) {
    //adding sendOnly option
    let options = ["sendOnly" : ["ABCD"]]
    // publish message
    //highlight-next-line
    self.meeting?.pubsub.publish(topic: "CHAT", message: "How are you?", options: options)
}
}
```

### Downloading Chat Messages

All the messages from the PubSub which where published with `persist : true` and can be downloaded as an `.csv` file. This file will be available in the VideoSDK dashboard as well as throught the [Sessions API](/api-reference/realtime-communication/fetch-session-using-sessionid).

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub()](/ios/api/sdk-reference/meeting-class/pubsub)


---

# Realtime Store - iOS

The **Realtime Store** allows you to store, update, retrieve, and observe custom key-value data within a meeting — in real time. It acts as a shared data layer across all connected participants, ensuring synchronized states throughout the session.

This is particularly useful for collaborative or stateful meeting experiences such as:

- Pinned messages and flags
- Moderation data (e.g., blocked users)
- Collaborative notes or polls

## `set()`

The `set()` method is used to store or update data in the RealtimeStore. If a key already exists, it will be overwritten with the new value. Passing `nil` as the value deletes the key.

### Key Notes

- Supports **String** values only.
- Each key can store up to **1 KB** of data.
- A maximum of **100 keys** are allowed per session.
- Deletion is performed by setting the value to `nil`.
- Throws an error if:
  - The key is missing or not of type **String**.
  - The request fails.
  - The session exceeds the 100-key limit.

### Parameters

- **`key`** (`String`)  
  The unique key to store the data under.

- **`value`** (`String?`)  
  The string value to be stored. Pass `nil` to delete the key.

### Example

```swift
let REALTIME_STORE_KEY = "Blocked_Students"
Task {
    do {
        try await meeting.realtimeStore.set(key: REALTIME_STORE_KEY, value: "[Deep,Lily]")
        print("Data set successfully!")
    } catch {
        print("Failed to set data: \(error.localizedDescription)")
    }
}
```

---

## `get()`

The `get()` method retrieves the current value associated with a given key.

### Key Notes

- Returns the current string value for the given key.
- Useful for fetching shared state when joining a meeting or reloading a view.
- Throws an error if the key is missing or if the request fails.

### Parameters

- **`key`** (`String`)
  The key whose value you want to retrieve.

### Returns

- **`String?`** — The stored value or `nil` if the key does not exist. The method throws an error on failure.

### Example

```swift
let REALTIME_STORE_KEY = "Blocked_Students"
Task {
    do {
        let value = try await meeting.realtimeStore.get(key: REALTIME_STORE_KEY)
        let displayValue = value ?? "nil (key not found)"
        print("Current value: \(displayValue)")
    } catch {
        print("Failed to get data: \(error.localizedDescription)")
    }
}
```

---

## `observe()`

The `observe()` method subscribes to real-time updates for a given key. When the key’s value changes, a delegate method on your listener is automatically triggered for all connected participants.

### Key Notes

- You register a listener object that conforms to the `RealtimeStoreListener` protocol.
- The delegate method receives the new value and information about who updated it.
- Ideal for syncing live data like timers, shared notes, or agendas.

### Parameters

- **`key`** (`String`)
  The key to observe.

- **`forListener`** (`RealtimeStoreListener`)
  An object that conforms to the `RealtimeStoreListener` protocol to receive updates.

### Example

First, conform to the `RealtimeStoreListener` protocol:
```swift
extension MeetingViewController: RealtimeStoreListener {
    func onValueChanged(key: String, value: String?, updatedBy: String) {
        print("RealtimeStore Value Changed - Key: \(key), Value: \(value ?? "nil"), UpdatedBy: \(updatedBy)")
    }
}
```

Then, start observing:
```swift
let REALTIME_STORE_KEY = "Blocked_Students"
Task {
    do {
        try await meeting.realtimeStore.observe(key: REALTIME_STORE_KEY, forListener: self)
        print("Started observing key successfully!")
    } catch {
        print("Failed to observe key: \(error.localizedDescription)")
    }
}
```

---

## `stopObserving()`

Stops receiving updates for a specific key and listener combination.

### Key Notes

- Should be called when the listener is no longer needed (e.g., when the view controller is deallocated).

### Parameters

- **`key`** (`String`)
  The key you want to stop observing.

- **`forListener`** (`RealtimeStoreListener`)
  The listener that should stop receiving updates.

### Example

```swift
let REALTIME_STORE_KEY = "Blocked_Students"
Task {
    do {
        try await meeting.realtimeStore.stopObserving(key: REALTIME_STORE_KEY, forListener: self)
        print("Stopped observing successfully!")
    } catch {
        print("Failed to stop observing: \(error.localizedDescription)")
    }
}
```

---

### Error Handling & Constraints

| Property           | Description                                                           |
| ------------------ | --------------------------------------------------------------------- |
| **Error Handling** | All RealtimeStore methods are `async throws`; wrap them in `do-try-catch`. |
| **Payload Size**   | Maximum **1 KB per key**.                                             |
| **Supported Type** | Only `String` values are supported. Use `nil` to delete key.         |
| **Concurrency**    | The latest write overwrites previous values (last write wins)         |
| **Key Limit**      | A maximum of 100 keys are allowed in a single session.        |

## API Reference

The API references for all the methods utilized in this guide are provided below:

- [set()](/ios/api/sdk-reference/meeting-class/realtimeStore#set)
- [get()](/ios/api/sdk-reference/meeting-class/realtimeStore#get)
- [observe()](/ios/api/sdk-reference/meeting-class/realtimeStore#observe)
- [stopObserving()](/ios/api/sdk-reference/meeting-class/realtimeStore#stopobserving)


---

# PubSub - iOS

PubSub is a short acronym for Publish-Subscribe mechanism. This mechanism is used to send and recieve messages from a particular topic. As the name suggests, for someone to send a message, they have to specify the topic and the message which should be published and for someone to receive a message, they should be subscribed to that topic.

Here is a visual to better understand publish-subscribe mechanism.

![pubsub](/img/pubsub.png)

## pubSub

In order to use PubSub in meeting, VideoSDK provides a class `pubSub` which allows you to subscribe to any topic and publish to any topic allowing to pass on messages and instructions during the meeting easily.

### `publish()`

- This method is used for publishing message of specific topic.
- This method can be accessed from the `pubSub` class, which is subclass of `Meeting` class.
- This method will accept following parameters as input:
  - `topic`: This will be the topic for which you are publishing a message.
  - `message`: This will be the actual message to be published. It has to be in `String` format.
  - `options`: This is an object of `PubSubPublishOptions` which specifies the options for publish. `PubSubPublishOptions` has 2 properties.
    - `persist` : `persist` offered the option of keeping the message around for the duration of the session. When `persist` is set to `true`, that message will be retained for upcoming participants and will be available in [VideoSDK Session Dashboard](https://app.videosdk.live/meetings/sessions) with `.CSV` format after completion of session.
    - `sendOnly`: If you want to send a message to specific participants, you can pass their respective `participantId` in form of `String[]`. If you don't provide any IDs or pass a `null` value, the message will be sent to all participants by default. This is optional parameter.



**Swift:**

```js
  //Button that will send the message when tapped
  @IBAction func sendMessageTapped(_ sender: Any) {
  let options = ["persist" : true]
  // publish message
  //highlight-next-line
  self.meeting?.pubsub.publish(topic: "CHAT", message: "How are you?", options: options)
  }
```

### `subscribe()`

- This method is used to subscribe for particular topic.
- This method will accept two parameters as input:

  - `topic`: This will be the topic to be subscribed.
  - `listener`: This is an object of `PubSubMessageListener`, which listens for upcoming messages and calls `onMessageReceived` function, when new message is received.

- This method will return `List<PubSubMessage>` which is a list of messages which were sent earlier.

The object of `PubSubMessage` contains following properties:

- `senderId`: This represents the `participantId` of the participant who send the message.
- `senderName`: This represents the `displayName` of the participant who send the message.
- `message`: This will be the actual message that was send.
- `timestamp`: This wil the timestamp for when the message was published.
- `topic`: This will be the name of the topic message was published to.

**Swift:**

```js
extension MeetingViewController: MeetingEventListener {

/// Meeting started
func onMeetingJoined() {
    
    // listen/subscribe for chat topic
    //highlight-next-line
    meeting?.pubsub.subscribe(topic: "CHAT", forListener: self)
}
}
```

### `unsubscribe()`

- This method is used to unsubscribe for particular topic.
- This method will accept two parameters as input:

  - `topic`: This will be the topic to be unsubscribed.
  - `listener`: This is an object of `PubSubMessageListener`, which was passed in `subscribe()`.

**Swift:**

```js
func unsubscribe() {
  // Unsubscribe 'CHAT' topic
  //highlight-next-line
  meeting?.pubSub.unsubscribe("CHAT", pubSubMessageListener)
}
```

## Applications of usePubSub

PubSub is a very powerful mechanism which can be used to do alot of things which can make your meeting experience much more interactive. Some of the most common usecase that we have come across for the PubSub during a meeting are listed below:

1. [`Chat`](./chat-using-pubsub): You can utilise this to develop various Chat features, such as Private Chat and Group Chat. You can follow our chat [integration guide here](./chat-using-pubsub).
2. `Raise Hand`: You can allow attendees to raise their hands at any time during the meeting, informing everyone else that someone has done so.
3. `Poll`: You may make polls, let users respond to them, and display the results at the end of a poll.
4. `Question Answer Session`: You can also design interactive functionality that is question-and-answer based.

### Downloading PubSub Messages

All the messages from the PubSub which were published with `persist : true` and can be downloaded as an `.csv` file. This file will be available in the VideoSDK dashboard as well as throught the [Sessions API](/api-reference/realtime-communication/fetch-session-using-sessionid).

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub()](/ios/api/sdk-reference/meeting-class/pubsub)


---

# Raise Hand using PubSub - iOS

Let us see, how we can use PubSub to implement Raise Hand functionality. If you are not familiar with the PubSub mechanism and `pubSub` class, you can [follow this guide](./pubsub).

## Implementing Raise Hand

1. First step in raise hand is choosing the topic which all the participants will publish and subscribe to know some participant raise their hand. We will be using `RAISE_HAND` as the topic for this one.
2. On the raiseHand button, publish any message to that specific topic.



**Swift:**

```js
class MeetingViewController {
//Button that will send the Raise Hand message when tapped
@IBAction func raiseHandTapped(_ sender: Any) {
    // publish message
    //highlight-next-line
    self.meeting?.pubsub.publish(topic: "RAISE_HAND", message: "raise hand")
}
}
```

3. Now let us show an alert to all the participants showing who raised the hand.

**Swift:**

```js
extension MeetingViewController: MeetingEventListener {
func onMeetingJoined() {
//subscribe to the topic 'CHAT' when onMeetingJoined is triggered
 //highlight-next-line
meeting?.pubsub.subscribe(topic: "RAISE_HAND", forListener: self)
}
}
//highlight-start
extension MeetingViewController: PubSubMessageListener {
// read message when it is received
func onMessageReceived(_ message: PubSubMessage) {
    print(message.senderName, "just Raised the hand")
}
}
//highlight-end
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub()](/ios/api/sdk-reference/meeting-class/pubsub)


---

# Upload and Retrieve the Temporary File - iOS

This guide demonstrates how to upload and retrieve files from VideoSDK's temporary file storage system.

### `uploadBase64File()`

- By using the `uploadBase64File()` function of the `Meeting` class, you can upload your file to Videosdk's Temporary storage.

- The `uploadBase64File()` function only works with `base64` String. Therefore, it is necessary to convert your file into `base64` String format.

- You have to pass `base64Data`,`token`,`fileName` as parameter in `uploadBase64File()` function.

- The function will return the corresponding `url`, which you can then use to retrieve the file.

- If the upload fails, it will return `nil`.



**Swift:**

```js
func uploadFile() {
  let base64Data: String = "<Your-base64-File>"
  let token: String = "<Your-Token>"
  let fileName: String = "name.jpeg" // Provide file name with extension

  meeting.uploadBase64File(base64Data: base64Data, token: token, fileName: fileName) { url in
    //checking for successful upload
    guard let url = url else {
      print("upload failed")
      return
    }
    print("url: ", url)
}
}
```

### `fetchBase64File()`

- By using the `fetchBase64File()` function of the `Meeting` class, you can retrieve your file from Videosdk's Temporary storage.

- You have to pass the `url` which is returned by `uploadBase64File()` function, and the `token` as parameters to retrieve a file.

- This method will return the image in the form of `base64` String.

- If the retrieval fails, it will return `nil`.

**Swift:**

```js
func fetchFile() {

  let url: String = "<Your FileUrl>"; // Provide fileUrl which is returned by uploadBase64File()
  let token: String = "<Your-Token>"

 meeting.fetchBase64File(url: url, token: token) { base64Data in
      //checking for successful retrieval
      guard let base64Data = base64Data else {
        print("retrieval failed")
        return
      }
    print("base64: ", base64Data)
  }
}
```

:::note

The file stored in the system will be automatically deleted once the current room/meeting comes to an end.

:::


---

# Whiteboard - iOS

A whiteboard is a digital canvas that allows users to collaborate in real-time by drawing, writing, and sharing ideas visually, making it ideal for brainstorming, presentations, and teamwork.

Before initiating a whiteboard session, it is essential to have an active **VideoSDK Meeting** in progress.

## Starting the Whiteboard

To start the whiteboard during a meeting, invoke the `startWhiteboard()` method of the `meeting` class.

Upon successful execution, the `onWhiteboardStarted` event will return a `url`.

You can embed the `url` into a `WKWebView` to display the whiteboard session within your iOS app.

## Stopping the Whiteboard

To stop the whiteboard session, call the `stopWhiteboard()` method of the `meeting` class. This will trigger the `onWhiteboardStopped` event, halting the whiteboard for all participants.

## Example



**Swift:**

```javascript
class MeetingViewController: UIViewController {
  let meeting;
  let isWhiteboardStarted = false;

  private var webView: WKWebView?

  override func viewDidLoad() {
super.viewDidLoad()
//setup ui
//setup actions
setupWebView()
  }

meeting = VideoSDK.initMeeting({
//... Initialization parameters
  });

  //setup webview
  private func setupWebView() {
   // Create WKWebView
   webView = WKWebView(frame: .zero)
   guard let webView = webView else { return }

   webView.translatesAutoresizingMaskIntoConstraints = false

   // Add WKWebView to the view hierarchy
   view.addSubview(webView)

   // Set up constraints
   NSLayoutConstraint.activate([
       webView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
       webView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
       webView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
       webView.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor)
   ])
   // Initially hide the WebView
   webView.isHidden = true
   }
  // show webview
  func showWebView(with url: URL) {
  guard let webView = webView else { return }

  let request = URLRequest(url: url)
  webView.load(request)
  webView.isHidden = false
  }
  // hide webview
  func hideWebView() {
  webView?.isHidden = true
  }
}

extension MeetingViewController {
  // Start Whiteboard
  @IBAction func toggleWhiteboardTapped(_ sender: Any) {
  guard !isWhiteboardStarted else {
    //highlight-next-line
      meeting.stopWhiteboard();
      isWhiteboardStarted = false;
      return;
  }
  //highlight-next-line
  meeting.startWhiteboard();
  isWhiteboardStarted = true;
}
}

// Handle Whiteboard State Changed Event
extension MeetingViewController: MeetingEventListener {
  func onWhiteboardStarted(url: URL) {
    DispatchQueue.main.async {
      self.showWebView(with: url)
    }
}

  func onWhiteboardStopped() {
    DispatchQueue.main.async {
      self.hideWebView()
    }
}
}

```

#### Events Associated with `startWhiteboard()` and `stopWhiteboard()`

- **`onWhiteboardStarted`**: Fired when the whiteboard is successfully started and it will return the url.

- **`onWhiteboardStopped`**: Fired when the whiteboard session is stopped for all participants.

**Swift:**

```js
extension MeetingViewController: MeetingEventListener {
  func onWhiteboardStarted(url: URL) {
  print("Whiteboard Started Successfully with url:", url)
}

  func onWhiteboardStopped() {
   print("Whiteboard Stopped Successfully")
}
}
```

## API Reference

- [startWhiteboard()](../../../api/sdk-reference/meeting-class/methods.md#startwhiteboard)
- [stopWhiteboard()](../../../api/sdk-reference/meeting-class/methods.md#stopwhiteboard)
- [onWhiteboardStarted()](../../../api/sdk-reference/meeting-class/events.md#onwhiteboardstarted)
- [onWhiteboardStopped()](../../../api/sdk-reference/meeting-class/events.md#onwhiteboardstopped)


---

# Concept and Architecture - iOS

Before diving into the concept, let's understand the VideoSDK, VideoSDK is a software development kit that offers tools and APIs for creating apps that are based on video and audio. It typically includes features such as video and audio calls, chat, cloud recording, simulcasting (RTMP), interactive live streaming (HLS), and many more across a wide range of platforms and devices.

## Concepts

![img.png](../../../../static/img/room-concept.png)

### `1. Meeting / Room`

- Meeting or Room object in the VideoSDK provide a virtual place for participants to interact and engage in real-time voice, video, and screen-sharing sessions. The object is in charge of handling media streams and participant communication.

- Meeting or Room can be uniquely identified by `meetingId` or `roomId`.

### `2. Participant`

- Participant is a VideoSDK object that represents each user/client in the meeting or room and allows them to share audio/video assets.

- `2.1 Local Participant` :
  The local participant is the one that runs on the user's device. The local participant has control over their own media streams, including the ability to start and stop audio and video.

  - The local participant in a meeting/room can also connect with other participants by transmitting and receiving audio and video streams, exchanging chat messages, and more.

- `2.2 Remote Participant` :
  The remote participant receives audio and video streams from the local participant and other remote participants and also has the ability to exchange audio, video, and chat messages with the local participant.

- Each participant in VideoSDK can be uniquely identified by `participantId`.

### `3. MediaStream & Track`

- A mediastream is a collection of audio & video tracks that can be transmitted between participants in real-time.

- A track is a continuous flow of audio or video data and can be thought of as a stream of media frames.

- A mediastream can contain multiple tracks. One video track for the video feed from the camera and one audio track for the audio feed from the microphone. These tracks can be transmitted between participants in VideoSDK Meeting / Room.

### `4. Events / Notifications`

- Events / Notifications can be used to inform users about various activities happening in a Meeting / Room, including participant join/leave and new messages. They can also be used to alert users about any SDK-level errors that occur during a call.

### `5. Session`

- A Session is the instance of an ongoing meeting/room which has one or more participants in it. A single room or meeting can have multiple sessions.
- Each session can be uniquely identified by `sessionId`.

![img.png](../../../../static/img/meeting-session.jpg)

---

![img.png](../../../../static/img/recording-hls-rtmp.png)

### `6. Cloud Recording`

- Cloud recording in VideoSDK refers to the process of recording audio or video content and storing it on a remote server or VideoSDK server.

### `7. Simulcasting (RTMP)`

- RTMP is a popular protocol for live streaming video content from a VideoSDK to platforms such as YouTube, Twitch, Facebook, and others.
- By providing the platform-specific `stream key` and `stream URL`, the VideoSDK can connect to the platform's RTMP server and transmit the live video stream.

### `8. Http Live Streaming (HLS)`

- Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

- In an interactive live stream (HLS), viewers can take part in a variety of activities like live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

## Architecture

This diagram demonstrates end-to-end flow to implement video & audio calls, record calls, and go live on social media.

![Video-sdk-architecture!](/img/video-sdk-archietecture.svg)


---

# Mute All Participants - iOS

If you are the host or moderator of a video conference, you may want to mute all the participants at once. This can be useful in various scenarios, such as when you want to deliver a presentation or when there is background noise that is causing distractions.

- To achieve this, you have to iterate over the list of participants from the `Meeting` class and call `disableMic` method from `Participant` class.



**Swift:**

```js
class MeetingViewController {
//Button when tapped will turn off mic of all participants
//highlight-start
@IBAction func muteAllButtonTapped(_ sender: Any) {
    participants.forEach { $0.disableMic() }
}
//highlight-end
```

:::note
Participant who will be muting other participants should have permission **`allow_mod`** passed in the token. To know more about permissions [**visit here**](/android/guide/video-and-audio-calling-api-sdk/authentication-and-token).
:::

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [disableMic()](/ios/api/sdk-reference/participant-class/methods#disablemic)


---

# Toggle Remote Participant Media - iOS

When hosting a meeting, it's important that the host of the meeting should be able to request someone's Mic or Camera to be turned on or should be able to turn them off.

:::note
Participant who will be controlling other participant's mic and camera should have permission **`allow_mod`** passed in the token. To know more about permissions [**visit here**](/ios/guide/video-and-audio-calling-api-sdk/server-setup).
:::

Before we discuss the methods and events associated with this functionality, here is how the flow would look like.

![img1](../../../../../static/img/toggle-remote-media.png)

## Methods

### `enableMic()`

- If you wish to turn **on** the microphone of a participant, you will be calling the `enableMic()` from the `Participant` class.

- When this method is called, the participant whose microphone is requested will receive the `onMicRequested` event with the `participantId` of the participant who requested it and two callback functions `accept` and `reject` which should be called based on decision made by the user.

- **Example:** Meeting is running with **Participant A** and **Participant B**. Now **Participant A** wants to Enable Mic of **Participant B**, so **Participant A** will use `enableMic()` function to request **Participant B**, after that **Participant B** recieve the `onMicRequested` event, from there user can either accept or reject the incoming request.

### `enableWebcam()`

- If you wish to turn **on** the camera of a participant, you will be calling the `enableWebcam()` from the `Participant` class.

- When this method is called, the participant whose camera is requested will receive the `onWebcamRequested` event with the `participantId` of the participant who requested it and two callback functions `accept` and `reject` which should be called based on decision made by the user.

- **Example:** Meeting is running with **Participant A** and **Participant B**. Now **Participant A** wants to Enable Webcam of **Participant B**, so **Participant A** will use `enableWebcam()` function to request **Participant B**, after that **Participant B** recieve the `onWebcamRequested` event, from there user can either accept or reject the incoming request.

### `disableMic()`

- If you wish to turn **off** the microphone of a participant, you will be calling the `disableMic()` from the `Participant` class.
- This will disable the microphone of the participant.

### `disableWebcam()`

- If you wish to turn **off** the camera of a participant, you will be calling the `disableWebcam()` from the `Participant` class.
- This will disable the camera of the participant.

#### Example



**Swift:**

```js
class MeetingViewController {
//Button when tapped will toggle participant's mic
@IBAction func micButtonTapped(_ sender: Any) {
    let participant = meeting?.participants.first(where: { $0.id == <participantId> })
  //micenabled is a user defined status for participant's mic
  if !micenabled {
     //highlight-next-line
     participant?.enableMic()
  } else {
     //highlight-next-line
     participant?.disableMic()
  }
}
   //Button when tapped will toggle participant's video
@IBAction func micButtonTapped(_ sender: Any) {
    let participant = meeting?.participants.first(where: { $0.id == <participantId> })
  //videoenabled is a user defined status for participant's video
  if !videoenabled {
     //highlight-next-line
     participant?.enableWebcam()
  } else {
     //highlight-next-line
     participant?.disableWebcam()
  }
}
}
```

## Events

### `onWebcamRequested`

This event will be emitted to the `Participant B` when any other `Participant A` requests to enable webcam of that participant (`Participant B`). This event handler will receieve following two arguments:

- `participantId` - ParticipantId of the requesting participant
- `listener`: MicRequestListener \{ accept: Method; reject: Method }

### `onMicRequested`

This event will be emitted to the `Participant B` when any other `Participant A` requests to enable mic of that participant (`Participant B`). This event handler will receieve following two arguments:

- `participantId` - ParticipantId of the requesting participant
- `listener`: MicRequestListener \{ accept: Method; reject: Method }

###### Usage

**Swift:**

```javascript
extension MeetingViewController: MeetingEventListener {
/// Called when host requests to turn on the mic/audio
//highlight-start
func onMicRequested(participantId: String?, accept: @escaping () -> Void, reject: @escaping () -> Void) {
  
        // callback to accept the request
        accept()

        // callback to reject the request
        reject()
}
/// Called when host requests to turn on the camera/video
func onWebcamRequested(participantId: String?, accept: @escaping () -> Void, reject: @escaping () -> Void) {
    
        // callback to accept the request
        accept()

        // callback to reject the request
        reject()
}
//highlight-end
}
```

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [enableMic()](/ios/api/sdk-reference/participant-class/methods#enablemic)
- [disableMic()](/ios/api/sdk-reference/participant-class/methods#disablemic)
- [enableWebcam()](/ios/api/sdk-reference/participant-class/methods#enablewebcam)
- [disableWebcam()](/ios/api/sdk-reference/participant-class/methods#disablewebcam)
- [onMicRequested()](/ios/api/sdk-reference/meeting-class/events#onmicrequested)
- [onWebcamRequested()](/ios/api/sdk-reference/meeting-class/events#onwebcamrequested)



---

# Remove Participant - iOS

This feature in a meeting allows the meeting host or organizer to remove a participant from the meeting. This can be helpful in situations where a participant is causing a disturbance, is behaving inappropriately, or is not following meeting guidelines.

VideoSDK provide three ways to remove participant from meeting.

1. [Using SDK](#1-using-sdk)
2. [Using VideoSDK Dashboard](#2-using-videosdk-dashboard)
3. [Using Rest API](#3-using-rest-api)

## 1. Using SDK

### `remove()`

Remove participant allows removing participant while session is on-going. This can be helpful when moderation in particular meeting is required.



**Swift:**

```js
class MeetingViewController {
//Button when tapped will remove the participant with given participantID
@IBAction func removeParticipant(_ sender: Any) {
    var participantID = "ABCD"

    guard let index = self.participants.firstIndex(where: { $0.id == participantID }) else {
        return
    }
    // remove participant from list
    //highlight-next-line
    participants.remove(at: index)
}
```

### Events associated with remove

Following callbacks are received when a participant is removed from the meeting.

- Participant who was removed from the meeting will receive a callback on[`onMeetingLeft`](/ios/api/sdk-reference/meeting-class/events#onmeetingleft).
- All other [remote participants](../concept-and-architecture#2-participant) will receive a callback [`onParticipantLeft`](/ios/api/sdk-reference/meeting-class/events#onparticipantleft) with Participant object.

## 2. Using VideoSDK Dashboard

- You can go the session page on [VideoSDK Dashboard](https://app.videosdk.live/meetings/sessions) and select the meeting you can to remove a participant from.
- And then from the participants list you can remove any participant you want.


<div style={{textAlign: 'center'}}>



</div>

## 3. Using Rest API

- You can also remove the particular participant from the meeting [using the REST API](/api-reference/realtime-communication/remove-participant).
- To use this method, you should have the `sessionId` of the meeting and `participantId` of the participant who is supposed to be removed.

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [remove()](/ios/api/sdk-reference/participant-class/methods#remove)
- [onMeetingLeft()](/ios/api/sdk-reference/meeting-class/events#onmeetingleft)
- [onParticipantLeft()](/ios/api/sdk-reference/meeting-class/events#onparticipantleft)


---

# Camera Controls - iOS

Whenever any participant wants to start/stop broadcasting their video to other participant in a meeting, they can simply do it with VideoSDK Meeting.

This guide will provide an overview of how to implement enable, disable and switch webcam features in a meeting.

1. **Enable Camera** - By using `enableWebcam()` function, a participant can publish camera stream to other participants.
2. **Disable Camera** - By using `disableWebcam()` function, a participant can stop publishing camera stream to other participants.
3. **Switch Camera** - By using `changeWebcam()` function, a participant can stream from front / rear camera during the meeting.This function is only applicable for Mobile devices.

### Enable, Disable And Switch Webcam

```js
@IBAction func videoButtonTapped(_ sender: Any) {
    if !videoEnabled {
        // enable webcam/camera
        self.meeting?.enableWebcam()
    } else {
        // disable webcam/camera
        self.meeting?.disableWebcam()
    }
}

/// keep track of camera position
private var cameraPosition = CameraPosition.front

@IBAction func cameraButtonTapped(_ sender: Any) {
    cameraPosition.toggle()

    // switch camera to front/back
    // Values: .front, .back
    self.meeting?.switchWebcam(position: cameraPosition)
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [enableWebcam()](/ios/api/sdk-reference/meeting-class/methods#enablewebcam)
- [disableWebcam()](/ios/api/sdk-reference/meeting-class/methods#disablewebcam)
- [onStreamEnabled()](/ios/api/sdk-reference/participant-class/events#onstreamenabled)
- [onStreamDisabled()](/ios/api/sdk-reference/participant-class/events#onstreamdisabled)

---

# Error Event - iOS

This event is helpful for development level troubleshooting while integrating SDK.

Whenever any invalid configuration provided or server/network errors arise, this event will trigger with a specific error code and message.

This event can ease your development process.

We have depicted a specific constant with code and message in the below table.

| Constant                                    | Code | Message                                                                                                               |
| ------------------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------- |
| **INVALID_API_KEY**                         | 4001 | `apikey` provided in the token is empty or invalid, please verify it on the dashboard.                                |
| **INVALID_TOKEN**                           | 4002 | `token` is empty or invalid or might have expired.                                                                    |
| **INVALID_MEETING_ID**                      | 4003 | `meetingId` is empty or invalid, please verify it or generate new meetingId using the API.                            |
| **INVALID_PARTICIPANT_ID**                  | 4004 | `participantId` is empty or invalid, it shouldn't contain any whitespaces.                                            |
| **DUPLICATE_PARTICIPANT**                   | 4005 | Leaving meeting, since this `participantId` joined from another device.                                               |
| **ACCOUNT_DEACTIVATED**                     | 4006 | It seems your account is deactivated by VideoSDK for some reason, you can reach out to us at `support@videosdk.live`. |
| **ACCOUNT_DISCONTINUED**                    | 4007 | _Server will respond you with specific message._                                                                      |
| **INVALID_PERMISSIONS**                     | 4008 | `permissions` provided in the token are invalid, please don't use `allow_join` or `allow_mod` with `ask_join`.        |
| **MAX_PARTICIPANT_REACHED**                  | 4009 | You have reached max participant limit in a meeting.                                                                   |
| **MAX_SPEAKER_REACHED**                     | 4010 | You have reached max speaker limit in a meeting.                                                                      |
| **START_RECORDING_FAILED**                  | 4011 | Recording start request failed due to an unknown error.                                                               |
| **STOP_RECORDING_FAILED**                   | 4012 | Recording stop request failed due to an unknown error.                                                                |
| **START_LIVESTREAM_FAILED**                 | 4013 | Livestream start request failed due to an unknown error.                                                              |
| **STOP_LIVESTREAM_FAILED**                  | 4014 | Livestream stop request failed due to an unknown error.                                                               |
| **INVALID_LIVESTREAM_CONFIG**               | 4015 | Livestream 'outputs' configuration provided was invalid.                                                              |
| **START_HLS_FAILED**                        | 4016 | HLS start request failed due to an unknown error.                                                                     |
| **STOP_HLS_FAILED**                         | 4017 | HLS stop request failed due to an unknown error.                                                                      |
| **MAX_SPEAKER_LIMIT_REACHED_ON_ORGANIZATION**    | 4026 | You have reached max speaker limit on organization. To increase contact at support@videosdk.live".                                                               |
| **MAX_VIEWER_LIMIT_REACHED_ON_ORGANIZATION**    | 4027 | You have reached max viewer limit on organization. To increase contact at support@videosdk.live".                                                               |
| **MAX_RECORDING_LIMIT_REACHED_ON_ORGANIZATION**    | 4028 | You have reached max limit of recording on organization. To increase contact at support@videosdk.live.                                                               |
| **MAX_HLS_LIMIT_REACHED_ON_ORGANIZATION**    | 4029 | You have reached max limit of hls on organization. To increase contact at support@videosdk.live.                                                               |
| **MAX_LIVESTREAM_LIMIT_REACHED_ON_ORGANIZATION**    | 4030 | You have reached max limit of livestream on organization. To increase contact at support@videosdk.live.                                                               |
| **RECORDING_FAILED**                        | 5001 | Recording stopped due to an unknown error.                                                                            |
| **LIVESTREAM_FAILED**                       | 5002 | Livestream stopped due to an unknown error.                                                                           |
| **HLS_FAILED**                              | 5003 | HLS stopped due to an unknown error.                                                                                  |
| **ERROR_GET_VIDEO_MEDIA**                   | 3011 | Your browser/Device does not support Video.                                                                           |
| **ERROR_GET_AUDIO_MEDIA**                   | 3012 | Your browser/Device does not support Audio.                                                                           |
| **ERROR_GET_DISPLAY_MEDIA**                 | 3013 | Your browser/Device does not support Screen Sharing.                                                                  |
| **ERROR_GET_VIDEO_MEDIA_PERMISSION_DENIED** | 3014 | Video capture permission denied.                                                                                      |
| **ERROR_GET_AUDIO_MEDIA_PERMISSION_DENIED** | 3015 | Audio capture permission denied.                                                                                      |

### Event Code

```js
import VideoSDKRTC

func onError(error: VideoSDKError) {
        switch error {
            case .INVALID_TOKEN: print("Invalid Token")

            case .INVALID_MEETING_ID: print("Invalid Meeting Id")

            case .INVALID_API_KEY: print("Invalid API Key")

            case .INVALID_PERMISSIONS: print("Invalid Permissions")

            case .INVALID_PARTICIPANT_ID: print("Invalid Participant ID")

            ...
        }
    }
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [Error codes](/ios/api/sdk-reference/error-codes)

---

# Go Live On Social Media - iOS

This feature allows participant to broadcast meeting on various social media platforms such as Facebook or Youtube.
This guide will provide an overview of how participant can start and stop broadcasting meeting.

1. **Start LiveStream** - By using `startLivestream()` function, a participant can start broadcasting meeting on various platforms by provding url and stream keys as an argument.
2. **Stop LiveStream** - By using `stopLivestream()` function, a participant can stop broadcasting on all platforms.

### Start And Stop Live Stream

```js
/// keep track of livestream
private var livestreamStarted = false

@IBAction func livestreamButtonTapped(_ sender: Any) {
    if !livestreamStarted {
        // prepare output
        // specify social-media-url and stream-key
        let output = LivestreamOutput(url: "<rtmp://a.rtmp.youtube.com/live2>", streamKey: "<stream-key>")

        // start livestream
        self.meeting?.startLivestream(outputs: [output])
    }
    else {
        // stop livestream
        self.meeting?.stopLivestream()
    }
}
```

### Events

1. **livestream-started** - Whenever broadcasting of meeting started, `livestream-started` event will trigger.

2. **livestream-stopped** - Whenever broadcasting of meeting stopped, `livestream-stopped` event will trigger.

```js
/// Called after livestream starts
func onLivestreamStarted() {
    liveStreamStarted = true

    // show indication that livestream is started
}

/// Called after livestream stops
func onLivestreamStopped() {
    liveStreamStarted = false

    // hide livestream indication
}
```


---

# Interactive Livestream (HLS) - iOS

Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

In an interactive live stream (HLS), viewers can take part in a variety of activities like live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

<center>

![VideoSDK-HLS](/img/VideoSDK-HLS.png)

</center>

VideoSDK also allows you to configure the interactive livestream layouts in numerous ways like by simply setting different prebuilt layouts in the configuration or by providing your own custom template to do the livestream according to your layout choice.

This guide will provide an overview of how to implement start and stop Interactive live streaming (HLS).

:::important

To initiate automatic Interactive live streaming (HLS) at the beginning of a `session`, simply provide the `autoStartConfig` feature `hls` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.

:::

### `startHLS()`

`startHLS()` can be used to start a interactive livestream of the meeting which can be accessed from the `useMeeting` hook. This method accepts one parameter:

- `config (optional)`: This parameter will define how the interactive livestream layout should look like.

  ```js
  let config: HLSConfig = HLSConfig(

    // highlight-next-line
    // Layout Configuration
    layout: HLSLayout(
      type: .GRID, // .SPOTLIGHT | .SIDEBAR,  Default : .GRID
      priority: .SPEAKER, // .PIN, Default : .SPEAKER
      gridSize: 4 // MAX : 25
    ),

    // highlight-next-line
    // Theme of livestream
    theme: .DARK, //  .LIGHT | .DEFAULT

    // highlight-next-line
    // `mode` is used to either interactive livestream video & audio both or only audio.
    mode: .video_and_audio, // .audio, Default : .video_and_audio

    // highlight-next-line
    // Quality of livestream and is only applicable to `video-and-audio` type mode.
    quality: .high,  // .low | .med,  Default : .med

    //highlight-start
    // This mode refers to orientation of recording.
    // landscape : Livestream the meeting in horizontally
    // portrait : Livestream the meeting in vertically (Best for mobile view)
    //highlight-end
    orientation: .portrait  // .portrait,  Default : .landscape
  )
  startHLS(config: config)
  ```

### `stopHLS()`

- `stopHLS()` is used to stop interactive livestream of the meeting which can be accessed from the `meeting` object.

#### Example

```js
stopHLS();
```

### Event associated with HLS

- **onHlsStateChanged** - Whenever meeting HLS state changes, then `onHlsStateChanged` event will trigger.

- You can get the `playbackHlsUrl` and `livestreamUrl` of the HLS to play it on the Viewer side when the state changes to `HLSState.HLS_STARTED`

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

```js
func onHlsStateChanged(state: HLSState, hlsUrl: HLSUrl?) {
    switch(state) {
        case .HLS_STARTING:
            print("HLS Starting")

        case .HLS_STARTED:
            self.hlsStreamStarted = true
            print("HLS Started")

        case .HLS_PLAYABLE:
            print("HLS Playable")

        case .HLS_STOPPING:
            print("HLS Stopping")

        case .HLS_STOPPED:
            self.hlsStreamStarted = false
            print("HLS Stopped")
        }
}
```

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [startHLS](/ios/api/sdk-reference/meeting-class/methods#starthls)
- [stopHLS](/ios/api/sdk-reference/meeting-class/methods#stophls)
- [onHlsStateChanged](/ios/api/sdk-reference/meeting-class/events#onhlsstatechanged)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

# Leave or End Meeting - iOS

Whenever participant wishes to end their communication in the meeting, they can simply leave the meeting.

This guide will provide an overview of how to implement leave or end feature in VideoSDK meetings.

1. **Leave** - By using `leave()` function, only a participant will leave/exit the meeting, the rest of the meeting will continue with other participants.
2. **End** - By using `end()` function, meeting will end for each and every participant. So, use this function according to your use cases.

### Leave And End Meeting

```js
@IBAction func leaveMeetingButtonTapped(_ sender: Any) {
    // leave meeting
    self.meeting?.leave()

    // end meeting for everyone
    self.meeting?.end()
}

/// Events:
// called after user leaves the meeting
func onMeetingLeft() {
    // cleanup: remove listeners
    meeting?.localParticipant.removeEventListener(self)
    meeting?.removeEventListener(self)

    // dismiss meeting controller
}
```

### API Reference
The API references for all the methods and events utilised in this guide are provided below.

- [leave()](/ios/api/sdk-reference/meeting-class/methods#leave)
- [end()](/ios/api/sdk-reference/meeting-class/methods#end)
- [onMeetingLeft()](/ios/api/sdk-reference/meeting-class/events#onmeetingleft)
- [onParticipantLeft()](/ios/api/sdk-reference/meeting-class/events#onparticipantleft)



---

# Manage Participants - iOS

## 1. Local Participant (self)

Local participant is used to consume your video & audio streams.
it contains information about local participant such as displayName, id, quality and streams Map.

You can acces localParticipant from the [meeting object](/ios/guide/video-and-audio-calling-api-sdk/features/start-join-meeting#2-initialization).

### Participant object properties

| Property Name | Type          | Description                                            |
| ------------- | ------------- | ------------------------------------------------------ |
| id            | string        | Unique id of the participant.                          |
| displayName   | string        | The name you define during the meeting initialization. |
| local         | boolean       | Indicates the participant is local or not.             |
| quality       | string        | Indicates the participant streams quality.             |
| Streams       | Map of Stream | Returns Video & Audio Streams.                         |

### Stream Object properties

| Property Name | Type   | Description        |
| ------------- | ------ | ------------------ |
| id            | string | Unique id          |
| codec         | string | Video/Audio codec. |
| kind          | string | Stream Kind.       |
| track         | string | MediaStreamTrack   |

## 2. Other Participants (Except You)

Other participants Map is used to get all the participants (except you) in the meeting at any given time.

Other participants Map contains same properties as [LocalParticipant](/ios/guide/video-and-audio-calling-api-sdk/features/manage-participants#participant-object-properties).

### Local And Other Participants

```js
// get local participant
let localParticipant = self.meeting?.localParticipant;

// get other participants
let otherParticipants = self.meeting?.participants;
```

## 3. Participant Related Events

1. **participant-joined** - Whenever any new participant join the meeting, `participant-joined` event will trigger. For example, the meeting is running with **Alice** and **Bob**, then **Eve** join that meeting, after that `participant-joined` event trigger and return the [participant object](/ios/guide/video-and-audio-calling-api-sdk/features/manage-participants#participant-object-properties).

2. **participant-left** - Whenever any participant leave/exit the meeting, `participant-left` event will trigger.For example, the meeting is running with **Alice** and **Bob**, then **Bob** leave that meeting, after that `participant-left` event trigger and return the [participant object](/ios/guide/video-and-audio-calling-api-sdk/features/manage-participants#participant-object-properties)

3. **presenter-changed** - Whenever any participant present/screenshare their screen/window in meeting, `presenter-changed` event will trigger and return the presenter `participantId`.

4. **stream-enabled** - Whenever any participant enabled mic/webcam in meeting, `stream-enabled` event will trigger and return [Stream Map](/ios/guide/video-and-audio-calling-api-sdk/features/manage-participants#stream-object-properties).

5. **stream-disabled** - Whenever any participant disabled mic/webcam in meeting, `stream-disabled` event will trigger and return [Stream Map](/ios/guide/video-and-audio-calling-api-sdk/features/manage-participants#stream-object-properties).

```js
/// keep track of video participants including self to show in UI
// ex. we can show participants as grid in collectionView.
private var participants: [Participant] = []

/// keep track of mic
private var micEnabled = true

/// keep track of video
private var videoEnabled = true

/// keep track of screenshare
private var screenShareEnabled = false


// MARK: - MeetingEventListener

extension MeetingViewController: MeetingEventListener {

    /// Meeting started
    func onMeetingJoined() {

        // handle for local participant
        if let localParticipant = self.meeting?.localParticipant {
            // event listener for self
            localParticipant.addEventListener(self)

            // add to list
            participants.append(localParticipant)

            // show in ui
            // ex. add to collecionView
            // addParticipantToGridView()
        }
    }

    /// A new participant joined
    func onParticipantJoined(_ participant: Participant) {
        // add new participant to list
        participants.append(participant)

        // add listener
        participant.addEventListener(self)

        // show in ui
        // ex. add to collectionView
        // addParticipantToGridView()
    }

    /// A participant left from the meeting
    /// - Parameter participant: participant object
    func onParticipantLeft(_ participant: Participant) {
        // remove listener
        participant.removeEventListener(self)

        // remove from list and update ui
        guard let index = self.participants.firstIndex(where: { $0.id == participant.id }) else {
            return
        }

        // remove participant from list
        participants.remove(at: index)

        // hide from ui
        // ex. remove from collectionview
        // removeParticipantFromGridView(at: index)
    }
}

// MARK: - ParticipantEventListener

extension MeetingViewController: ParticipantEventListener {

    /// Participant has enabled mic, video or screenshare
    /// - Parameters:
    ///   - stream: enabled stream object
    ///   - participant: participant object
    func onStreamEnabled(_ stream: MediaStream, forParticipant participant: Participant) {

        switch stream.kind {
        case .audio:
            // update ui to show that participant's mic is enabled
            // ex. update collectionView cell

            if participant.isLocal {
                // update mic flag for local participant
                micEnabled = true
            }

        case .video:
            // show track in videoView: RTCMTLVideoView
            if let track = stream.track as? RTCVideoTrack {
                track.add(videoView)
            }

            if participant.isLocal {
                // update video flag for local participant
                videoEnabled = true
            }

        case .share:
            // show track in screenShareView: RTCMTLVideoView
            if let track = stream.track as? RTCVideoTrack {
                track.add(screenShareView)
            }

            if participant.isLocal {
                // update screenShare flag for local participant
                screenShareEnabled = true
            }
        }
    }

    /// Participant has disabled mic, video or screenshare
    /// - Parameters:
    ///   - stream: disabled stream object
    ///   - participant: participant object
    func onStreamDisabled(_ stream: MediaStream, forParticipant participant: Participant) {

        switch stream.kind {
        case .audio:
            // update ui to show that participant's mic is disabled
            // ex. update collectionView cell

            if participant.isLocal {
                // update mic flag for local participant
                micEnabled = false
            }

        case .video:
            // remove track from videoView: RTCMTLVideoView
            if let track = stream.track as? RTCVideoTrack {
                track.remove(videoView)
            }

            if participant.isLocal {
                // update video flag for local participant
                videoEnabled = false
            }

        case .share:
            // remove track from screenShareView: RTCMTLVideoView
            if let track = stream.track as? RTCVideoTrack {
                track.remove(screenShareView)
            }

            if participant.isLocal {
                // update screenShare flag for local participant
                screenShareEnabled = false
            }
        }
    }
}

```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onParticipantJoined()](/ios/api/sdk-reference/meeting-class/events#onparticipantjoined)
- [onParticipantLeft()](/ios/api/sdk-reference/meeting-class/events#onparticipantleft)
- [onWebcamRequested()](/ios/api/sdk-reference/meeting-class/events#onwebcamrequested)
- [onMicRequested()](/ios/api/sdk-reference/meeting-class/events#onmicrequested)

---

# Mic Controls - iOS

Whenever any participant wants to start / stop broadcasting their audio to other participant in meeting, they can simply do it with VideoSDK Meeting.

This guide will provide an overview of how to use enable and disable Mic in a meeting.

1. **Enable Mic** - By using `unmuteMic()` function, a participant can publish audio to other participants.
2. **Disable Mic** - By using `muteMic()` function, a participant can stop publishing audio to other participants.
3. **Change Mic** - By using `changeMic()` function, a participant can change mic.

### Enable, Disable, Change Mic

```js
@IBAction func micButtonTapped(_ sender: Any) {
    if !micEnabled {
        // enable/unmute mic
        self.meeting?.unmuteMic()
    } else {
        // disable/mute mic
        self.meeting?.muteMic()
    }
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [unmuteMic()](/ios/api/sdk-reference/meeting-class/methods#unmutemic)
- [muteMic()](/ios/api/sdk-reference/meeting-class/methods#mutemic)
- [onStreamEnabled()](/ios/api/sdk-reference/participant-class/events#onstreamenabled)
- [onStreamDisabled()](/ios/api/sdk-reference/participant-class/events#onstreamdisabled)

---

# Optimize Video Track - iOS

While optimizing for the best viewing experience, it is necessary to fine-tune the video tracks that are being used during the calls.

For the best fine-tuning experience, we have introduced the ability to pass a custom video track for the participant's media before and during the meeting.

## Custom Video Track

This feature can be used to add custom video encoder configurations and background removal & video filter from external libraries and send it to other participants.

### `How to Create a Custom Video Track ?`

- You can create a Video Track using `createCameraVideoTrack()` method of `VideoSDK` class.

- This method can be used to create video track using different encoding parameters and camera facing mode, it return `RTCVideoTrack?`.

#### Example

```javascript
import WebRTC
guard let videoMediaTrack = try? VideoSDK.createCameraVideoTrack(
  // highlight-next-line
  // This will accept the enum value of CustomVideoTrackConfig which contains resolution (height x width) of video you want to capture.
  encoderConfig: .h720p_w1280p, // .h540p_w960p | .h720p_w1280p ... // Default : .h360p_w640p

  // highlight-next-line
  // It will specify whether to use front or back camera for the video track.
  facingMode: .front, // .back,  Default : .front

  // highlight-next-line
  // We will discuss this parameter in next step.
  multiStream:true // false,  Default : true

  // highlight-next-line
  // A video codec for compresses video data for efficient transmission over the internet, balancing quality and bandwidth usage.
   codec: .H264 // Default: .VP8

) else { return}
```

:::caution
The capabilities of the device have a significant impact on how custom track configurations behave. Assuming a case where you set encoder configuration to 1080p but the webcam only supports 720p, then encoder configuration will automatically switch to the highest resolution that the device can handle, which is 720p.
:::

##### What is `multiStream`?

- It will specify if the stream should send multiple resolution layers or single resolution layer.

**`multiStream : true`** By default, VideoSDK sends multiple resolution video streams to the server (whether you are using custom video track or not), For instance, user device capabilty is 720p, so VideoSDK sends 720p along with 640p and 480p streams. This allows VideoSDK to deliver the appropriate stream to each participant based on their network bandwidth.

<center>

![Multi Stream False](/img/multistream_true.png)

</center>

**`multiStream : false`** If you want to restrict the VideoSDK to send only one stream to maintain quality, you can set `multiStream` to `false`.

<center>

![Multi Stream False](/img/multistream_false.png)

</center>

:::danger
`setQuality` would not have any effect if multiStream is set to `false`.
:::

### `How to Setup a Custom Video Track ?`

The custom track can be set up both before and after the initialization of the meeting.

1. [Setting up a Custom Track during the initialization of a meeting](#1-setting-up-a-custom-track-during-the-initialization-of-a-meeting)
2. [Setting up a Custom Track with methods](#2-setting-up-a-custom-track-with-methods)

##### 1. Setting up a Custom Track during the initialization of a meeting

If you are passing `webcamEnabled: true` in the `createRoom` and want to use custom tracks from start of the meeting, you can pass custom track in the `customCameraVideoTrack` as shown below.

:::caution
Custom Track will not apply on `webcamEnabled: false` configuration.
:::

##### Example

```javascript
import VideoSDKRTC

guard let videoMediaTrack = try? VideoSDK.createCameraVideoTrack(
 		encoderConfig: .h720p_w1280p,
		facingMode: .front,
		multiStream:true,
    codec: .H264
) else { return}

let meeting = VideoSDK.initMeeting(
      meetingId: meetingId,
      participantName: name,
      micEnabled: micEnabled, // optional, default: true
      webcamEnabled: cameraEnabled, // optional, default: true

      // Pass the custom track here which will be used to when webcam is auto started
      customCameraVideoStream: customVideoStream,
)

```

#### 2. Setting up a Custom Track with methods

In order to switch tracks during the meeting, you have to pass the `CustomTrack` in the **`enableWebCam()`** method of `Room`.

:::tip
Make sure to call `disableCam()` before you create a new track as it may lead to unexpected behavior.
:::

##### Example

```javascript
import VideoSDKRTC

@IBAction func videoButtonTapped(_ sender: Any) {
if !on {
  guard let videoMediaTrack = try? VideoSDK.createCameraVideoTrack(encoderConfig: .h360p_w480p, facingMode: .front, multiStream: false) else { return}
  self.meeting?.enableWebcam(customVideoStream: videoMediaTrack)
      } else {
  self.meeting?.disableWebcam()
      }
}

```

### `Which Configuration is suitable for Device ?`

In this section, we will understand participant size wise `encoder(Resolution)` and `multiStream` configuration.

<center>
<img src='https://cdn.videosdk.live/website-resources/docs-resources/mobile_device_config.png' />
</center>

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [Custom Video Track](/ios/api/sdk-reference/custom-tracks)


---

# PubSub - iOS

PubSub is a short acronym for Publish-Subscribe mechanism. This mechanism is used to send and recieve messages from a particular topic. As the name suggests, for someone to send a message, they have to specify the topic and the message which should be published and for someone to receive a message, they should be subscribed to that topic.

Here is a visual to better understand publish-subscribe mechanism.

![pubsub](/img/pubsub.png)

## Methods

### publish()

This method is use for publishing message of specific topic.

#### Syntax

```js
func publish(topic: String, message: String, options: [String : Any] = [:])
```

| Parameter Name | Type   | Description                                                                                                               |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| topic          | String | This should be the topic for which you are publishing a message.                                                          |
| message        | String | This is the actual message, which will be published to participants, who had subscribed to a particular topic.            |
| options        | Object | This is the object which provides an option, such as `persist`, which persists message history for upcoming participants. |

#### Example

```js
func sendMessage() {
  meeting.pubsub.publish(topic: "CHAT", message: "Hello Everyone!", options: ["persist": true])
}
```

<br />

### subscribe()

This method is used to subscribe for particular topic. This method returns a list of messages which were sent earlier.

#### Syntax

```js
func subscribe(topic: String, forListener listener: PubSubMessageListener)
```

| Parameter Name | Type                  | Description                                                                                                                                      |
| -------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| topic          | String                | This should be the topic to be subscribed.                                                                                                       |
| forListener    | PubSubMessageListener | This is an object of PubSubMessageListener, which listens for upcoming messages and calls onMessageReceived function, when new message received. |

#### Example

```js
class ChatMessageListener: PubSubMessageListener {
    func onMessageReceived(_ message: PubSubMessage) {
        // Print new message
        print("Message Received:= " + message.message)
    }
}
const listener = ChatMessageListener()

func subscribe() {
  // Subscribe 'CHAT' topic
  meeting?.pubsub.subscribe(topic: "CHAT", forListener: listener)
}
```

### unsubscribe()

This method is used to unsubscribe the message topic.

#### Syntax

```js
func unsubscribe(topic: String, forListener listener: PubSubMessageListener)
```

| Parameter Name | Type                  | Description                                                                    |
| -------------- | --------------------- | ------------------------------------------------------------------------------ |
| topic          | String                | This should be the topic to be unsubscribed.                                   |
| forListener    | PubSubMessageListener | This is an object of PubSubMessageListener, which was passed in `subscribe()`. |

#### Example

```js
func unsubscribe() {
  // Unsubscribe 'CHAT' topic
  meeting?.pubsub.unsubscribe(topic: "CHAT", forListener: listener)
}
```

## Sample Code

```js
import UIKit
import VideoSDKRTC

class ChatViewController: UIViewController {

  // Meeting
  public var meeting: Meeting

  // Chat Topic
  var topic: String = "CHAT"

  var chatMessageListener: ChatMessageListener = ChatMessageListener()

  init(meeting: Meeting) {
    self.meeting = meeting;

    // Subscribe 'CHAT' topic
    meeting.pubsub.subscribe(topic: topic, forListener: chatMessageListener)

    // Get persisted chat messages
    let pubsubMessages = meeting.pubsub.getMessagesForTopic(topic)

    for msg in pubsubMessages! {
      print("Message: " + msg.message)
    }

    super.init(nibName: nil, bundle: nil)
  }

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

  required init?(coder: NSCoder) {
    fatalError("Fatal Error")
  }


  // Lifecycle
  override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    meeting.pubsub.publish(topic: topic, message: "Hii from iOS", options: ["persist": true])
    print("Chat Message Published")
  }

  override func viewDidDisappear(_ animated: Bool) {
    super.viewDidDisappear(animated)
    meeting.pubsub.unsubscribe(topic: topic, forListener: chatMessageListener)
    print("Unsubscribed 'CHAT' topic")
  }
}

class ChatMessageListener: PubSubMessageListener{
 func onMessageReceived(_ message: PubSubMessage){
  print("Message Received: " + message.message)
 }
}

```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [pubSub()](/ios/api/sdk-reference/meeting-class/pubsub)

---

# Record Meeting - iOS

Record meeting allows participants to record video & audio during the meeting. The recording files are available in developer dashboard.
Any participant can start / stop recording any time during the meeting.

This guide will provide an overview of how to implement start and stop Meeting Recording.

1. **Start Recording** - By using `startRecording()` function, a participant can start meeting recording.
2. **Stop Recording** - By using `stopRecording()` function, a participant can stop meeting recording.

### Start And Stop Recording

```js
/// webhook url
private let recordingWebhookUrl = "<webhook-url-here>"

/// aws directory path
private let recordAwsDirPath = "<aws-dir-path>"

/// custom configuration for recording
private let recordConfig = RecordingConfig(
                            layout: ConfigLayout(
                                type: .GRID, 
                                priority: .PIN, 
                                gridSize: 4
                            ), theme: .DARK, 
                            mode: .video_and_audio, 
                            quality: .med, 
                            orientation: .landscape
                           )

/// keep track of recording
private var recordingStarted = false

@IBAction func recordButtonTapped(_ sender: Any) {
    if !recordingStarted {
        // start recording
        self.meeting?.startRecording(webhookUrl: recordingWebhookUrlrecordingWebhookUrl,
                                     awsDirPath: recordAwsDirPath, 
                                     config: recordConfig)
    } else {
        // stop recording
        meeting?.stopRecording()
    }
}
```

### Events

1. **recording-started** - Whenever any participant start meeting recording, then `recording-started` event will trigger.

2. **recording-stopped** - Whenever any participant stop meeting recording, then `recording-stopped` event will trigger.

```js
/// Called after recording starts
func onRecordingStarted() {
    recordingStarted = true

    // show indication that meeting recording is started.
}

/// Caled after recording stops
func onRecordingStopped() {
    recordingStarted = false

    // hide meeting recording indication.
}
```

### API Reference

The API references for all the methods utilised in this guide are provided below.

- [startRecording()](/ios/api/sdk-reference/meeting-class/methods#startrecording)
- [stopRecording()](/ios/api/sdk-reference/meeting-class/methods#stoprecording)
- [onRecordingStateChanged](/ios/api/sdk-reference/meeting-class/events#onrecordingstatechanged)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)

---

# Remove Participant - iOS

Remove participant allows removing participant while session is on-going. This can be helpful when moderation in particular meeting is required.



```js
let participant = meeting?.participants.first(where: { $0.id == <participantId> })

// Remove participant from active session
// This will emit an event called "onParticipantLeft" to that particular participant
participant?.remove()
```

### Events

**onParticipantLeft** - Removing participant will trigger `onParticipantLeft` event.

```js
// MARK: - MeetingEventListener

extension MeetingViewController: MeetingEventListener {

    /// A participant left from the meeting
    /// - Parameter participant: participant object
    func onParticipantLeft(_ participant: Participant) {
        // remove listener
        participant.removeEventListener(self)

        // remove from list and update ui
        guard let index = self.participants.firstIndex(where: { $0.id == participant.id }) else {
            return
        }

        // remove participant from list
        participants.remove(at: index)

        // hide from ui
        // ex. remove from collectionview
        // removeParticipantFromGridView(at: index)
    }
}
```

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [remove()](/ios/api/sdk-reference/participant-class/methods#remove)
- [onMeetingLeft()](/ios/api/sdk-reference/meeting-class/events#onmeetingleft)
- [onParticipantLeft()](/ios/api/sdk-reference/meeting-class/events#onparticipantleft)

---

# Speaker Indication - iOS

Speaker indication feature in VideoSDK let you know, which participant in a meeting is active speaker.

Whenever any participant speaks in meeting, `speaker-changed` event will trigger.

For example, the meeting is running with **Alice** and **Bob**. Whenever any of them speaks, `speaker-changed` event will trigger and return the speaker `participantId`.

We can access `speaker-changed` event through [meeting object](/ios/guide/video-and-audio-calling-api-sdk/features/start-join-meeting#2-initialization).

### Speaker-Changed Event

```js
/// Called when speaker is changed
/// - Parameter participantId: participant id of the speaker, nil when no one is speaking.
func onSpeakerChanged(participantId: String?) {

    // show indicator for active speaker
    if let participant = participants.first(where: { $0.id == participantId }),

        // show indication for active speaker
        // ex. show border color
        // cell.contentView.layer.borderColor = UIColor.blue.cgColor : UIColor.clear.cgColor
    }

    // hide indicator for others participants
    let otherParticipants = participants.filter { $0.id != participantId }
    for participant in otherParticipants {

        // ex. remove border color
        //cell.contentView.layer.borderColor = UIColor.clear.cgColor
    }
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onSpeakerChanged()](/ios/api/sdk-reference/meeting-class/events#onspeakerchanged)

---

# Start or Join Meeting - iOS

<div style={{display:'flex',flexDirection:'row',alignItems:'stretch',}}>
<div style={{}}>
<p>After the successful installation of VideoSDK, the next step is to integrate VideoSDK features with your webApp/MobileApp.</p>

<p>To Communicate with other participant's audio or video call, you will need to join the meeting.</p>

<p>This guide will provide an overview of how to configure, initialize and join a VideoSDK meeting.</p>

</div>
<div>
<img src="/img/gif/new-meeting.gif"/>
</div>

</div>

## 1. Configuration

To configure a meeting, you will need [generated token](/ios/guide/video-and-audio-calling-api-sdk/server-setup) and [meetingId](/api-reference/realtime-communication/create-room), we had discussed in [Server Setup](/ios/guide/video-and-audio-calling-api-sdk/server-setup).
This code snippet calls API from local server

**Scenario 1** - Suppose you **don't have** any meetingId, you can simply generate meetingId by invoking `create-meeting` API.

**Scenario 2** - Suppose you **have** meetingId, now you don't have to call `create-meeting` API to generate meetingId, instead you can call `validate-meeting` API to validate meetingId.

**Token generation API is necessary for both scenario.**

```js
// Update server url here.
let LOCAL_SERVER_URL = "http://192.168.0.101:9000"

class APIService {

    class func getToken(completion: @escaping (Result
</div>

</div>

```js
// import sdk
import VideoSDKRTC

class MeetingViewController: UIViewController {

    // meeting
    private var meeting: Meeting?

    override func viewDidLoad() {
        super.viewDidLoad()

        // Configure authentication token got earlier
        VideoSDK.config(token: 
</div>

</div>

```js
// join
meeting?.join();
```

### API Reference
The API references for all the methods and events utilised in this guide are provided below.

- [initMeeting](/ios/api/sdk-reference/initMeeting)
- [join](/ios/api/sdk-reference/meeting-class/methods#join)
- [onMeetingJoined()](/ios/api/sdk-reference/meeting-class/events#onmeetingjoined)
- [onParticipantJoined()](/ios/api/sdk-reference/meeting-class/events#onparticipantjoined)


---

# Toggle Participant Media - iOS

Control other participant's webcam and mic.
For better idea, let's understand this with a real case scenario

**Scenario 1 (Online Class)** - In this scenario, the lecturer(Local Participant) will control the student's(Other Participant) webcam and mic as per his/her needs.

**Scenario 2 (Online Events)** - In this scenario, the event hosts will control the audience webcam and mic when someone wants to speak.

This guide will provide an overview of how to control other participant webcam and mic in a meeting.

1. **Enable Webcam of Participant** - By using `enableWebcam()` function, a `webcam-requested` event will trigger on requested participant side.

   **Example** : Meeting is running with **User A** and **User B**. Now **User A** wants to Enable Webcam of **User B**, so **User A** will use `enableWebcam()` function to request **User B**, after that **User B** recieve the `webcam-requested` event, from there user can either accept or reject the incoming request.

2. **Disable Webcam of Participant** - By using `disableWebcam()` function, webcam of that participant will be turned off.

   **Example** : **User A** wants to Disable Webcam of **User B**, so **User A** will use `disableWebcam()` function to Disable it without any request.

3. **Enable Mic of Participant** - By using `enableMic()` function, a `mic-requested` event will trigger on requested participant side.

   **Example** : Meeting is running with **User A** and **User B**. Now **User A** wants to Enable Mic of **User B**, so **User A** will use `enableMic()` function to request **User B**, after that **User B** will receive the `Mic-requested` event, from there user can either accept or reject the incoming request.

4. **Disable Mic of Participant** - By using `disableMic()` function, Mic of that participant will disable.

   **Example** : **User A** wants to Disable Mic of **User B**, so **User A** will use `disableMic()` function to Disable it without any request.

:::note

To achieve this feature, you need to pass `allow_join` persmission while genearting token for meeting initialization. After that you will be able to access participant media methods.

[How to apply permission while generating token?](/ios/guide/video-and-audio-calling-api-sdk/server-setup)

:::

### Request Media Methods

```js
let participant = meeting?.participants.first(where: { $0.id == <participantId> })

/// Enable/Unmute mic for this participant
participant?.enableMic()

/// Disable/Mute mic for this participant
participant?.disableMic()

/// Enable/Turn on camera for this participant
participant?.enableWebcam()

/// Disable/Turn off camera for this participant
participant?.disableWebcam()
```

### Manage Requested Media Events

1. **webcam-requested** - This event will be emitted to the participant `B` when any other participant `A` requests to enable webcam of that participant `B`. This event handler will receieve following three arguments:

   - `accept()` - Callback function to accept the request.
   - `reject()` - Callback function to reject the request.

<div style={{height: "10px"}}></div>

2. **mic-requested** - This event will be emitted to the participant `B` when any other participant `A` requests to enable mic of that participant `B`. This event handler will receieve following three arguments:

   - `accept()` - Callback function to accept the request.
   - `reject()` - Callback function to reject the request.

```js
/// Called when host requests to turn on the mic/audio
func onMicRequested(participantId: String?, accept: @escaping () -> Void, reject: @escaping () -> Void) {

    // callback to accept the request
    accept()

    // callback to reject the request
    reject()
}

/// Called when host requests to turn on the camera/video
func onWebcamRequested(participantId: String?, accept: @escaping () -> Void, reject: @escaping () -> Void) {
    // callback to accept the request
    accept()

    // callback to reject the request
    reject()
}

```

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [enableMic()](/ios/api/sdk-reference/participant-class/methods#enablemic)
- [disableMic()](/ios/api/sdk-reference/participant-class/methods#disablemic)
- [enableWebcam()](/ios/api/sdk-reference/participant-class/methods#enablewebcam)
- [disableWebcam()](/ios/api/sdk-reference/participant-class/methods#disablewebcam)
- [onMicRequested()](/ios/api/sdk-reference/meeting-class/events#onmicrequested)
- [onWebcamRequested()](/ios/api/sdk-reference/meeting-class/events#onwebcamrequested)


---

# Understanding Analytics Dashboard - Android

Welcome to the world of actionable insights and empowered decision-making. VideoSDK's session analytics dashboard is your gateway to understanding, optimizing, and elevating every aspect of your sessions.

## Accessing Analytics Made Easy

Navigating through session data is a breeze with VideoSDK. Simply head to your session page at https://app.videosdk.live/meetings/sessions, where a treasure trove of session information awaits.

### How to Access Analytics?

Open Session Analytics effortlessly by following these steps:

1. **Click on Meeting-ID:**
    - Directly access analytics by clicking on the meeting-ID within the session table.
2. **Hover and Click View Analytics:**
    - Hover over a specific meeting row to reveal the **View Analytics** button in the Actions Column.
    - Click on **View Analytics** to open the Session Overview sidebar, unlocking a wealth of insights.

![Access Analytics](https://cdn.videosdk.live/website-resources/docs-resources/access_analytics.png)

---

There are three tabs available within the session analytics view:

## **1. Session Overview**

This tab provides an overview of the session, including its duration and participant details. You can explore individual participant statistics to understand their session performance better.

## **2. Errors**

In this tab, you can find information about any errors encountered during the session. It helps you identify and address issues like network problems or technical glitches promptly.

:::note

Session errors are visible with JS SDK v0.0.82 or higher, React SDK v0.1.85 or higher, and React Native v0.1.6 or newer versions.

:::

## **3. Session Stats**

Explore data and metrics sent and received by participants to measure performance of the session in this tab. It offers insights into data exchange among participants, including metrics on jitter, RTT, and packet loss, resolutions, and fps aiding in assessing communication efficiency.

Let's dive deeper into each of these tabs to gain a better understanding of session analytics.

# Session Overview

The session overview page is your compass in the sea of data. Here's what you'll uncover:

- **Meeting ID:** Unique identifier for the meeting in the format of `abcd-efgh-ijkl`.
- **Session ID:** Unique identifier for each session, uniquely identified by its `sessionId`.
- **Session Status:** Indicates if the session is ongoing or ended.
- **Session Initiating Time:** Time taken by the first participant to establish the connection.
- **Start and End Time:** Marks the start and end of the session.
- **Total Unique Participants Joined:** Total number of unique participants in the session.
- **Total Session Duration:** Overall duration of the session from start to end.
- **Total Participant Minutes:** A sum of all participant duration.
- **Recording, HLS, RTMP:** Additional services used in the session.

### Participant Table List

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for each participant.
- **Join Time:** Time taken by the participant to establish connection.
- **Duration:** Total time spent by this participant in the session.

### Efficient Session Management with Actions

Enhance your session management with streamlined actions:

- **Kick Out Participants:** Effortlessly remove/kickout participants from ongoing sessions.
- **Detailed Participant Analytics:**
- Hover over a specific participant row to reveal the `View Stats` button at the end of the row.
- Click on `View Stats` to open the Participant Overview sidebar.


![View Stats](https://cdn.videosdk.live/website-resources/docs-resources/view_stats.png)


## Explore Participant Insights

Discover valuable participant data that provides a clear view of engagement and experience:

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for better interaction.
- **Joined At:** Indicates the precise moment when participant connects to the session.
- **Left At:** Indicates the precise moment when participant left the session.
- **Total Duration:** Total duration of participant within that session.
- **Joining Time:** Time taken by the this participant to establish the connection.
- **Location:** Approx. geographic location from where the participant joined.
- **Platform:** Specifies whether participants are using a desktop or mobile device.
- **Device Info:** Offers details regarding the participant's device.
- **OS:** Provides information about the participant's OS.
- **Browser:** Provides specifics about the participant's browser
- **SDK Version:** Indicates the version of the SDK used by participants.

### Understanding Participant Call Health

We've developed call health to offer a rapid assessment of participant performance during calls. This feature highlights the performance of audio, video, and screen sharing audio-video separately. We've utilized color theory, with green indicating good performance, orange for moderate, and red for poor performance, to enhance clarity. For detailed insights, simply hover over the bars

![Participant Call Health](https://cdn.videosdk.live/website-resources/docs-resources/participant_call_health.png)

## Participant Session Stats

Dive into Participant Session Stats for valuable insights into your session experience! With just a click on `View Session Stats` at the bottom of the page, unlock a treasure trove of data crucial for understanding audio and video experiences.

Within this section, you can observe quality metrics for the selected participant, comparing them to others. Additionally, the `Sessions Stats` covers quality stats comparison for every participant. Keep reading to explore more about Session Stats.

**Visualizing Session Performance from Both Sides**

This section provides a two-sided view of your session's metrics.

- **Left Side: Sender Participant Graph** This section displays graphs representing the metrics sent by the sender participant.. Here, you can see how the various factors impacted the data you transmitted.
- **Right Side: Receiver Participant Graph** On the right side, you'll find a dropdown menu where you can select a specific participant. Choosing a receiver will display graphs showcasing the metrics **received by that participant**. This allows you to compare the sending experience (left side) with the receiving experience (right side) for different participants.

![VideoSDK Jitter Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_jitter_graph.png)

**See How Your Session Performed**

These metrics give you a clear picture of your session's quality. Understanding them helps you spot any issues and keep things running smoothly. Let's dive into what each metric means!

**Jitter:** Imagine your internet connection like a bumpy road. Jitter is how much those bumps cause your signal to bounce around. Less jitter means a smoother ride for your data (audio and video, threshold ≤ 30ms).

**RTT (Latency):** This is how long it takes for data to travel between you and the server you're connected to. Think of it like the time it takes for a message to get delivered – a lower RTT means a faster delivery (affects both audio and video, threshold ≤ 300ms).

**Bitrate:** This measures the amount of data flowing through your connection per second. Imagine it like the width of a water pipe – a higher bitrate allows for more data to flow, which can be good for high-quality audio/video or fast downloads.

**Packet Loss:** Think of data traveling in tiny packets. Packet loss is when some of those packets get dropped along the way. More packet loss means information might be missing, affecting things like audio/video quality or lag in games (threshold ≤ 5%).

**Resolution:** This refers to the sharpness and detail of an image or video. Think of it like the number of pixels on your screen – a higher resolution means a crisper picture (**Video Only**).

**FPS (Frames Per Second):** This measures how many images (frames) are displayed on your screen every second. Imagine it like a flipbook – a higher FPS creates a smoother and more fluid animation or video experience (**Video Only**).

![VideoSDK FPS Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_fps_graph.png)

![VideoSDK Resolution Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_resolution_graph.png)

---

# **Analyse Session Stats**

Similar to `Participant Session Stats`, this tab covers quality statistics sent by individual participants. You can select any participant to compare effectively with others.

Choose a sender participant from the dropdown menu on the left and select a recipient on the right to compare data over different time frames. This allows you to identify and explore issues within specific durations.

This tab covers the same metrics as covered in the `participant session stats`: Jitter, RTT (Latency), Bitrate, Packet-loss, Resolution (Video only), and FPS (Video only).

![VideoSDK Session Stats](https://cdn.videosdk.live/website-resources/docs-resources/session_stats.png)

---

# Cloud Proxy - iOS


Our SDK features a Cloud Proxy that allows you to manage how your streaming content is routed through different network paths. This feature ensures compliance with various regional internet regulations by restricting traffic to specified proxy servers, based on your needs and the geographical location of users.

This capability is crucial for adhering to local data protection laws and optimizes the streaming experience by overcoming geographical network constraints. By directing user connections to appropriate regional servers, Cloud Proxy enhances overall service performance and reliability.

Cloud Proxy offers three straightforward operating modes to fit different business and firewall requirements:

- **UDP_OVER_TCP (Default)**: In this mode, the connection starts by attempting to establish a UDP connection for media transmission. If that fails, it will automatically shifts to a secure TCP connection, which is compatible with most firewalls.

- **Force UDP**: This mode uses only UDP to send media, ensuring high-quality streams. It's ideal for environments where media quality is critical and the firewall can be configured accordingly.

- **Force TCP**: Only uses TCP for secure media transmission, suitable for strict firewall settings that only permit TCP traffic over centain ports. This might require additional firewall configuration and could affect media quality under poor network conditions.




### In this sequence diagram:
- Client to Proxy Server: The client sends a request to the proxy server, which processes and forwards it based on predefined rules.
- Proxy Server to Destination Server: The proxy server sends the request to the destination server, receives the response, and relays it back to the client.

:::info

Cloud Proxy is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Implementation

```js
  let meeting = VideoSDK.initMeeting(
            meetingId: "abcd-efgh-hijk",
            participantId: "JD", //optional
            participantName: "John Doe",
            micEnabled: true,
            webcamEnabled: true,
            customCameraVideoStream: customVideoStream, //optional
            customAudioTrack: customAudioStream, //optional
            mode: .SEND_AND_RECV, //optional (default mode is conference)
            //highlight-start
            preferredProtocol: .UDP_ONLY, //optional(default is .UDP_OVER_TCP),
            signalingBaseUrl: "proxy.yourwebsite.com" //optional
            //highlight-end
        )
```

### Parameters

- preferredProtocol:
  - UDP_OVER_TCP (default): Initially the server attempts to establish a connection using UDP, if that fails it automatically switches to TCP protocol.
  - UDP_ONLY: Force UDP protocol
  - TCP_ONLY: Force TCP protocol
- signalingBaseUrl: Proxy URL to origin signaling and media.

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [initMeeting](/ios/api/sdk-reference/initMeeting)


---

# Geo Fencing - iOS


Our SDK includes a region geofencing feature to comply with local laws and regulations worldwide. It restricts connections to servers within specified regions, ensuring users connect only to designated areas, regardless of their location. 

This helps meet regional data protection requirements and enhances user experience by addressing geographical network limitations.




### In this sequence diagram:
- User 1 (India) tries to connect to a meeting. In a regular scenario, the meeting would connect to the India region, but due to the geofence configuration, the meeting will connect to North America.

## Considerations
- If the user’s location differs from the chosen region, the network quality between these locations may be poor, affecting audio and video quality.
- Avoid using geofencing unless your scenario requires regional compliance.

:::info

Geo Fencing is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Available Regions
- INDIA
- USA
- UAE
- EUROPE
- SINGAPORE
- AUSTRALIA


---

# Geo IP Restrictions - iOS


Our SDK features Geo IP Restriction to ensure adherence to location-based access controls. It determines the user's location using their IP address and allows or restricts content based on geographic rules. This is essential for businesses needing to comply with international content distribution laws or provide localized services.

By implementing Geo IP Restriction, you can control who accesses your services based on where they are, ensuring compliance with legal regulations and enhancing security. This feature also improves the user experience by ensuring content relevance and availability is tailored to the user's location.




### In this sequence diagram:
- User 1 (India) attempts to connect to a meeting that is geo-restricted to only allow connections from North America. The server denies the connection due to the geographic restrictions.
- User 2 (North America) successfully connects because their location complies with the geo-restricted rules set on the meeting.


## Considerations
- Avoid using geo ip restriction unless your scenario requires regional or VPN/Proxy restrictions.

:::info

Geo IP Restriction is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Available Regions
- INDIA
- USA
- UAE
- EUROPE
- SINGAPORE
- AUSTRALIA


---

# Error Events - iOS

VideoSDK provides `onError` event which will notify you of any error happening during the meeting.

### onError

- This event will be triggered whenever any invalid configuration provided or server/network errors arise, this event will trigger with a specific error code and message.
- This event is helpful for development level troubleshooting while integrating SDK.
- You can implement this method of the abstract Class `MeetingEventListener` and add the listener to `Meeting` class using the `addEventListener()` method of `Meeting` Class.

### Example



**Swift:**

```js
import VideoSDKRTC

extension MeetingViewController: MeetingEventListener {
func onError(error: VideoSDKError) {
    switch error {
        case .INVALID_TOKEN: print("Invalid Token")

        case .INVALID_MEETING_ID: print("Invalid Meeting Id")

        case .INVALID_API_KEY: print("Invalid API Key")

        case .INVALID_PERMISSIONS: print("Invalid Permissions")

        case .INVALID_PARTICIPANT_ID: print("Invalid Participant ID")

        ...
    }
}
}
```

### Error Codes

We have depicted a specific constant with code and message in the below table.



### 1. Errors associated with Organization 

This table lists errors that occur due to the configuration and limitations within your organization’s account. These include account status, participant limits, and add-on service availability.

| Type                                   | Code  | Message                                             |
|----------------------------------------|-------|-----------------------------------------------------|
| ACCOUNT_DEACTIVATED                   | 4006  | Your account has been deactivated. Please contact VideoSDK support. |
| ACCOUNT_DISCONTINUED                  | 4007  | Your account has been discontinued. Please reach out to support for more details. |
| MAX_PARTICIPANT_REACHED               | 4009  | You have reached the maximum participant limit for this meeting. |
| MAX_SPEAKER_REACHED                   | 4010  | The maximum number of speakers for this meeting has been reached. |
| MAX_SPEAKER_LIMIT_REACHED_ON_ORGANIZATION | 4026  | Your organization has reached the maximum number of speakers allowed. |
| MAX_VIEWER_LIMIT_REACHED_ON_ORGANIZATION | 4027  | Your organization has reached the maximum number of viewers allowed. |
| ADD_ON_SERVICES_DISABLED              | 4021  | Add-On services have been disabled. Please contact support to enable them. |
| MAX_RECORDING_LIMIT_REACHED_ON_ORGANIZATION              | 4028  | You have reached max limit of recording on organization. To increase contact at support@videosdk.live |
| MAX_HLS_LIMIT_REACHED_ON_ORGANIZATION  | 4029  | You have reached max limit of hls on organization. To increase contact at support@videosdk.live |
| MAX_LIVESTREAM_LIMIT_REACHED_ON_ORGANIZATION  | 4030  | You have reached max limit of livestream on organization. To increase contact at support@videosdk.live |

### 2. Errors associated with Token

Errors listed here are related to issues with the API key, authentication tokens, or permissions assigned to users. These errors can occur when tokens are missing, expired, or improperly configured.

| Type                                    | Code  | Message                                                |
|-----------------------------------------|-------|--------------------------------------------------------|
| INVALID_API_KEY                        | 4001  | The provided API key is either missing or invalid. |
| INVALID_TOKEN                          | 4002  | The provided token is empty, invalid, or has expired. |
| INVALID_PERMISSIONS                    | 4008  | The permissions in the token are incorrect. Please verify them. |
| UNAUTHORIZED_MEETING_ID                | 4022  | The provided token is not authorized for this meeting ID. |
| UNAUTHORIZED_PARTICIPANT_ID            | 4023  | The provided token is not authorized for this participant ID. |
| UNAUTHORIZED_ROLE                      | 4024  | The role specified in the token is not valid for joining this meeting. |
| UNAUTHORIZED_REQUEST                      | 4025 | Your request does not match the security configuration. |

### 3. Errors associated with Meeting and Participant

This table lists errors resulting from invalid or missing meeting or participant details, including cases where a participant attempts to join with a duplicate ID.

| Type                    | Code  | Message                                         |
|-------------------------|-------|-------------------------------------------------|
| INVALID_MEETING_ID      | 4003  | The meeting ID provided is either invalid or missing. |
| INVALID_PARTICIPANT_ID  | 4004  | The participant ID is either invalid or missing. |
| DUPLICATE_PARTICIPANT   | 4005  | This participant has joined from another device. |

### 4. Errors associated with Add-on Service

This section addresses errors that occur while using VideoSDK's add-on services such as recording, livestreaming, HLS streaming, and transcription.

### Recording-related errors

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_RECORDING_FAILED      | 4011  | Failed to start recording. Please try again.   |
| STOP_RECORDING_FAILED       | 4012  | Failed to stop recording. Please try again.    |
| RECORDING_FAILED            | 5001  | Recording was stopped due to an error.         |
| START_PARTICIPANT_RECORDING_FAILED | 4035 | Failed to start participant recording. Please check the request. |
| STOP_PARTICIPANT_RECORDING_FAILED  | 4036 | Failed to stop participant recording. |
| PARTICIPANT_RECORDING_FAILED       | 5012 | Participant recording has stopped due to an error. |
| START_TRACK_RECORDING_FAILED | 4037 | Failed to start track recording.                |
| STOP_TRACK_RECORDING_FAILED  | 4038 | Failed to stop track recording.                 |
| TRACK_RECORDING_FAILED  | 5013 | Track recording stopped due to an unknown error.                 |
| PREV_RECORDING_PROCESSING  | 4018 | Previous recording session is being processed, please try again after few seconds.                 |
| RECORDING_DURATION_LIMIT_REACHED | 5004 | Recording stopped due to maximum duration being reached. |

### Livestream-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| INVALID_LIVESTREAM_CONFIG           | 4015  | Livestream 'outputs' configuration provided was invalid            |
| START_LIVESTREAM_FAILED     | 4013  | Failed to start livestream. Please try again.  |
| STOP_LIVESTREAM_FAILED      | 4014  | Failed to stop livestream. Please try again.   |
| LIVESTREAM_FAILED           | 5002  | Livestream stopped due to an error.            |
| PREV_RTMP_RECORDING_PROCESSING | 4019 | Previous RTMP recording session is being processed, please try again after few seconds! |
| LIVESTREAM_DURATION_LIMIT_REACHED | 5005 | Livestream stopped due to maximum duration being reached. |

### HLS-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_HLS_FAILED            | 4016  | Failed to start HLS stream.                    |
| STOP_HLS_FAILED             | 4017  | Failed to stop HLS stream.                     |
| HLS_FAILED                  | 5003  | HLS streaming stopped due to an error.         |
| PREV_HLS_STREAMING_PROCESSING | 4020 | Previous HLS streaming session is still being processed. |
| HLS_DURATION_LIMIT_REACHED  | 5006  | HLS stream stopped due to maximum duration being reached. |

### Transcription-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_TRANSCRIPTION_FAILED  | 4031  | Failed to start transcription. Please try again. |
| STOP_TRANSCRIPTION_FAILED   | 4032  | Failed to stop transcription.                  |
| TRANSCRIPTION_FAILED        | 5007  | Transcription stopped due to an error.         |

### 5.Errors associated with Media

These errors involve media access, device availability, or permission-related issues affecting camera, microphone, and screen sharing.

### Device permission-related errors
| Type                                      | Code  | Message                                          |
|-------------------------------------------|-------|--------------------------------------------------|
| ERROR_GET_VIDEO_MEDIA_PERMISSION_DENIED  | 3014  | Video capture permission denied. |
| ERROR_GET_AUDIO_MEDIA_PERMISSION_DENIED  | 3015  | Audio capture permission denied. |
| ERROR_GET_DISPLAY_MEDIA_PERMISSION_DENIED | 3016 | Screen sharing permission denied. |

### Device-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| ERROR_GET_VIDEO_MEDIA      | 3011  | Your browser/Device does not support Video. |
| ERROR_GET_AUDIO_MEDIA      | 3012  | Your browser/Device does not support Audio. |
| ERROR_GET_DISPLAY_MEDIA      | 3013  | Your browser/Device does not support Screen Sharing. |

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onError()](/ios/api/sdk-reference/error-codes)


---

### External Call Detection Events - iOS

VideoSDK provides external call detection events that notify you when a participant is on another call while in a meeting. These events help track call states and handle UI changes accordingly.

### onExternalCallRinging 

- Triggered when the participant receives an incoming call or starts dialing an outgoing call, and the call is ringing but not yet answered.

### onExternalCallAnswered 

- Triggered when the participant answers an incoming call or when an outgoing call is picked up by the other party.

### onExternalCallRejected 

- Triggered when the participant rejects an incoming call or ends the call while it is still ringing.

### onExternalCallHangup

- Triggered when the participant ends an answered call or when the other party hangs up the call.

All of the above methods can be implemented in the abstract class `MeetingEventListener` and added as listeners to the `Meeting` class using the `addEventListener()` method.

For example, suppose a meeting is running with **Alice** and **Bob**. If Alice receives a call or makes a call, only Alice will receive the `onExternalCallRinging` event.


### Example



**Swift:**

```js
extension MeetingViewController: MeetingEventListener {
 func onExternalCallRinging(callType: String) {
    print("\(callType.capitalized) call is ringing...")
}

func onExternalCallAnswered(callType: String) {
    print("\(callType.capitalized) call answered!")
}

func onExternalCallRejected(callType: String) {
    print(" \(callType.capitalized) call rejected before answering!")
}

func onExternalCallHangup(callType: String) {
    print("\(callType.capitalized) call ended after being answered.")
}
}
```



---

# HLS Events - iOS

VideoSDK provides `onHlsStateChanged` event which will notify you of the current state of HLS for the meeting.

### onHlsStateChanged

- This event will be triggered when the meeting's HLS status changed.
- You can implement this method of the abstract Class `MeetingEventListener` and add the listener to `Meeting` class using the `addEventListener()` method of `Meeting` Class.

### Example

Here is the usage of the event mentioned in this page.



**Swift:**

```js
extension MeetingViewController: MeetingEventListener {
func onHlsStateChanged(state: HLSState, hlsUrl: HLSUrl?) {
    switch(state) {
        case .HLS_STARTING:
            print("HLS Starting")
            
        case .HLS_STARTED:
            self.hlsStreamStarted = true
            print("HLS Started")
            
        case .HLS_PLAYABLE:
            print("HLS Playable")
            
        case .HLS_STOPPING:
            print("HLS Stopping")
            
        case .HLS_STOPPED:
            self.hlsStreamStarted = false
            print("HLS Stopped")
        }
}
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onHlsStateChanged()](/ios/api/sdk-reference/meeting-class/events#onhlsstatechanged)


---

# Media Events - iOS

VideoSDK provides multiple types of events which can be listened to know the about the participant's media status in the meeting.

You can implement all the methods of `ParticipantEventListener` abstract Class and add the listener to `Participant` class using the `addEventListener()` method of `Participant` Class.

Here are the events which specifically relate to the stream.

### onStreamEnabled

- This event is triggered whenever a participant's video, audio or screen share stream is enabled.

### onStreamDisabled

- This event is triggered whenever a participant's video, audio or screen share stream is disabled.

### Example

Here is the usage of all the events mentioned in this page.



**Swift:**

```js
extension MeetingViewController: ParticipantEventListener {

func onStreamEnabled(_ stream: MediaStream, forParticipant participant: Participant) {
    print("Media Stream enabled for :", participant.displayName)
}

func onStreamDisabled(_ stream: MediaStream, forParticipant participant: Participant) {
    print("Media Stream disabled for :", participant.displayName)
}
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onStreamEnabled()](/ios/api/sdk-reference/participant-class/events#onstreamenabled)
- [onStreamDisabled()](/ios/api/sdk-reference/participant-class/events#onstreamdisabled)


---

# Meeting Connection Events - iOS

VideoSDK provides `onMeetingStateChanged` event which will notify you of the current connection state of the meeting.

### onMeetingStateChanged

- This event will be triggered when state of meeting changes.
- It will pass **`state`** as an event callback parameter which will indicate current state of the meeting.     
  *All available states are* :
  - `CONNECTING`: The meeting is in the process of establishing a connection.
  - `CONNECTED`: The meeting has successfully connected.
  - `RECONNECTING`: The meeting is trying to reconnect after the connection was lost.
  - `DISCONNECTED`: The meeting has been disconnected.
- You can implement this method of the abstract Class `MeetingEventListener` and add the listener to `Meeting` class using the `addEventListener()` method of `Meeting` Class.

### Example

Here is the usage of the event mentioned in this page.



**Swift:**

```javascript
extension MeetingViewController: MeetingEventListener {
meeting.listeners.onMeetingStateChanged(meetingState: MeetingState) {
    switch meetingState {
        case .CONNECTING:
            print("Meeting is connecting")

        case .CONNECTED:
            print("Meeting is connected")

        case .CLOSING:
            print("Meeting is closing")

        case .CLOSED:
            print("Meeting connection closed")

        case .CANCELLED:
            print("Meeting is cancelled")
    }
}
}
```


### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onMeetingStateChanged()](/ios/api/sdk-reference/meeting-class/events#onmeetingstatechanged)


---

# Meeting Events - iOS

VideoSDK provides multiple types of events which can be listened to know the current state of the meeting.

You can implement all the methods of `MeetingEventListener` abstract Class and add the listener to `Meeting` class using the `addEventListener()` method of `Meeting` Class.

Here are the events which specifically relate to the meeting.

### onMeetingJoined

- This event is triggered when the meeting is successfully joined.

### onMeetingLeft

- This event is triggered when the meeting is left.

### onSpeakerChanged

- This event is triggered when the active speaker in the meeting gets changed.

### Example

Here is the usage of all the events mentioned in this page.



**Swift:**

```js
extension MeetingViewController: MeetingEventListener {
/// Meeting started
func onMeetingJoined() {
    print("Meeting Joined")
}
/// Meeting ended
func onMeetingLeft() {
    print("Meeting Left")
}
///Speaker Changed
func onSpeakerChanged(participantId: String?) {
    print("Speaker changer for:", participantID)
}
}
```


## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onMeetingJoined()](/ios/api/sdk-reference/meeting-class/events#onmeetingjoined)
- [onMeetingLeft()](/ios/api/sdk-reference/meeting-class/events#onmeetingleft)
- [onSpeakerChanged()](/ios/api/sdk-reference/meeting-class/events#onspeakerchanged)


---

# Participant Events - iOS

VideoSDK provides multiple types of events which can be listened to know the about the participants in the meeting.

You can implement all the methods of `MeetingEventListener` abstract Class and add the listener to `Meeting` class using the `addEventListener()` method of `Meeting` Class.

Here are the events which specifically relate to the participants.

### onParticipantJoined

- This event is triggered when someone joins the meeting and return the `Participant` object as parameter.

### onParticipantLeft

- This event is triggered when the someone leaves the meeting.

### onWebcamRequested

- This event will be triggered to the participant `B` when any other participant `A` requests to enable webcam of participant `B`.
- On accepting the request, webcam of participant `B` will be enabled.

### onMicRequested

- This event will be triggered to the participant `B` when any other participant `A` requests to enable mic of participant `B`.
- On accepting the request, mic of participant `B` will be enabled.
- This event can be subscribed from the `useMeeting` hook.

### Example

Here is the usage of all the events mentioned in this page.



**Swift:**

```javascript
extension MeetingViewController: MeetingEventListener {
/// Meeting started
func onParticipantJoined(_ participant: Participant) {
    print("ParticipantJoined", participant.displayName)
}
/// Meeting ended
func onParticipantLeft(_ participant: Participant) {
    print("onParticipantLeft", participant.displayName)
}
/// Called when host requests to turn on the mic/audio
func onMicRequested(participantId: String?, accept: @escaping () -> Void, reject: @escaping () -> Void) {
  
        // callback to accept the request
        accept()

        // callback to reject the request
        reject()
}
/// Called when host requests to turn on the camera/video
func onWebcamRequested(participantId: String?, accept: @escaping () -> Void, reject: @escaping () -> Void) {
    
        // callback to accept the request
        accept()

        // callback to reject the request
        reject()
}
}
```


### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onParticipantJoined()](/ios/api/sdk-reference/meeting-class/events#onparticipantjoined)
- [onParticipantLeft()](/ios/api/sdk-reference/meeting-class/events#onparticipantleft)
- [onWebcamRequested()](/ios/api/sdk-reference/meeting-class/events#onwebcamrequested)
- [onMicRequested()](/ios/api/sdk-reference/meeting-class/events#onmicrequested)


---

# Recording Events - iOS

VideoSDK provides `onRecordingStateChanged` event which will notify you of the current state of recording for the meeting.

### onRecordingStateChanged

- This event will be triggered when the meeting's recording status changed.
- You can implement this method of the abstract Class `MeetingEventListener` and add the listener to `Meeting` class using the `addEventListener()` method of `Meeting` Class.

### Example

Here is the usage of the event mentioned in this page.



**Swift:**

```js
extension MeetingViewController: MeetingEventListener {
func onRecordingStateChanged(state: RecordingState) {
    switch(state) {
        case .RECORDING_STARTING:
            print("recording starting")
        
        case .RECORDING_STARTED:
            print("recording started")
            
        case .RECORDING_STOPPING:
            print("recording stopping")
    
        case .RECORDING_STOPPED:
            print("recording stopped")
    }
}
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onRecordingStateChanged()](/ios/api/sdk-reference/meeting-class/events#onrecordingstatechanged)


---

# RTMP Events - iOS

VideoSDK provides `onLivestreamStateChanged` event which will notify you of the current state of livestream for the meeting.

### onLivestreamStateChanged

- This event will be triggered when the meeting's livestream status changed.
- You can implement this method of the abstract Class `MeetingEventListener` and add the listener to `Meeting` class using the `addEventListener()` method of `Meeting` Class.

### Example

Here is the usage of the event mentioned in this page.



**Swift:**

```js
extension MeetingViewController: MeetingEventListener {
func onLivestreamStateChanged(state: LiveStreamState) {
    switch(state) {
        case .LIVESTREAM_STARTING:
            print("livestream starting")
        
        case .LIVESTREAM_STARTED:
            print("livestream started")
            
        case .LIVESTREAM_STOPPING:
            print("livestream stoping")
    
        case .LIVESTREAM_STOPPED:
            print("livestream stopped")
    }
}
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onLivestreamStateChanged()](/ios/api/sdk-reference/meeting-class/events#onlivestreamstatechanged)


---

## Steps


<div class="container guide-steps-block">
  <div class="row ">
    <div class="col col--6">
    
    </div>
     <div class="col col--6">
     
    </div>
  </div>
  <div class="row ">
   <div class="col col--6" >
    
    </div>
    <div class="col col--6">
      
    </div>
  </div>

</div>

## Architecture

This diagram demonstrates end-to-end flow to implement video & audio calling, record calls and go-live on social media.

![Video-sdk-architecture!](/img/video-sdk-archietecture.svg)


---

# Active Speaker Indication - iOS

Active Speaker indication feature in VideoSDK let you know, which participant in a meeting is active speaker. This feature can be particularly useful in larger meetings or webinars, where there may be many participants and it can be difficult to tell who is speaking.

Whenever any participant speaks in meeting, `onSpeakerChanged` event will trigger with the participant id of the active speaker.

For example, the meeting is running with **Alice** and **Bob**. Whenever any of them speaks, `onSpeakerChanged` event will trigger and return the speaker `participantId`.

### Event



**Swift:**

```js
extension MeetingViewController: MeetingEventListener {
/// Called when speaker is changed
/// - Parameter participantId: participant id of the speaker, nil when no one is speaking.
func onSpeakerChanged(participantId: String?) {

// show indicator for active speaker
if let participant = participants.first(where: { $0.id == participantId }),
    // show indication for active speaker
    // ex. show border color
    // cell.contentView.layer.borderColor = UIColor.blue.cgColor : UIColor.clear.cgColor
}

// hide indicator for others participants
let otherParticipants = participants.filter { $0.id != participantId }
for participant in otherParticipants {
    // ex. remove border color
    //cell.contentView.layer.borderColor = UIColor.clear.cgColor
}
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [onSpeakerChanged()](/ios/api/sdk-reference/meeting-class/events#onspeakerchanged)

---

# Change Input/Output Audio Device - iOS

During the meeting at any point a participant wishes to switch his/her audio device, it can be done using the below mentioned methods.

## Changing Input/Output Audio Device

### `getMics()`

- The `getMics()` method will return an array of tuples, where each tuple consists of two elements deviceName and deviceType.

- returns `[deviceName: String, deviceType: String]`

### Example


**Swift:**

```js
//highlight-next-line
let devices = meeting.getMics()
for device in devices {
print(device.deviceName)  //sample output [("Speaker","Speaker"), ("iPhone Microphone", "Receiver")]
}
```

### `changeMic()`

- Participant can change the audio device using `changeMic(selectedDevice: String)` method of `Meeting` classs

### Example

**Swift:**

```swift
func changeAudioDevice(device: String) {
changeMic(selectedDevice: "Speaker") //output will be changed to speaker
}
```

:::caution
 selectedDevice string should only be from the deviceName that you get from the returned array of `getMics()`.
:::

### Events

**onMicChanged** - Changing Mic will trigger `onMicChanged` event.

**Swift:**

```js
extension MeetingViewController: MeetingEventListener {

/// Mic is Changed
/// - Parameter selectedDevice: String
 func onMicChanged(selectedDevice: String) {

    print("Mic Changed to: \(selectedDevice)") //example: Mic changed to Speaker

    print("Available Devices:")

    let devices = self.meeting?.getMics() ?? []
    for device in devices {
        print(device.deviceName)
    }
}
}
```

 **Sample output**
```
Mic changed to Speaker
Available Devices:
Speaker
iPhone Microphone
Headphones
```

## Changing Camera Input Device

### `switchWebcam()`

- By using `switchWebcam()` function, a participant can stream from front / rear camera during the meeting.

#### Example

**Swift:**

```js
/// keep track of camera position
private var cameraPosition = CameraPosition.front

@IBAction func cameraButtonTapped(_ sender: Any) {
cameraPosition.toggle()

// switch camera to front/back
// Values: .front, .back
//highlight-next-line
self.meeting?.switchWebcam(position: cameraPosition)
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [switchWebcam()](/ios/api/sdk-reference/meeting-class/methods#switchwebcam)
- [getMics()](/ios/api/sdk-reference/meeting-class/methods#getmics)
- [changeMic()](/ios/api/sdk-reference/meeting-class/methods#changemic)
- [onMicChanged()](/ios/api/sdk-reference/meeting-class/events#onmicchanged)

---

# Image Capturer - iOS

This guide provides instructions on capturing images of participants from a video stream.

This capability proves particularly valuable in Video KYC scenarios, enabling the capture of images where users can hold up their identity for verification.

### `captureImage()`

- By using the `captureImage()` function of the `Participant` class, you can capture image of a local participant from their video stream.
- You have the option to specify the desired height and width in the `captureImage()` function; however, these parameters are optional. If not provided, the VideoSDK will automatically use the dimensions of the local participant's webcamStream.
- The `captureImage()` function returns the image in the form of a `base64` string.
- If the image was not captured, `nil` will be returned.



**Swift:**

```js
class MeetingViewController {
// Button when tapped will capture image
@IBAction func captureImageTapped(_ sender: Any) {

    guard let participant = meeting.participants.first(where: { $0.isLocal}) else { return }

    participant.captureImage(height: 200, width: 200) { base64Data in
        // make sure that image was captured
        guard let base64Data = base64Data else {
            print("Image was not captured")
            return
        }

        print("base64: ", base64Data)
    }
}
}
```

:::note

You can only capture an image of local participant. If you called `captureImage()` function on a remote participant, you will receive an error. If you want to capture an image of a remote participant, check the documentation below.

:::

### How to capture image of remote participant ?

- Before proceeding, it's crucial to understand [VideoSDK's temporary file storage system](../collaboration-in-meeting/upload-fetch-temporary-file.md) and the underlying [pubsub mechanism](../collaboration-in-meeting/pubsub.md).

- Here's a break down of the steps, using the names Participant A and Participant B for clarity:

#### Step 1 : Initiate Image Capture Request

- In this step, you have to first send a request to Participant B, whose image you want to capture, using pubsub.
- In order to do that, you have to subscribe to topic called `IMAGE_CAPTURE` to ParticipantB.
- Here, we will be using `sendOnly` option inside the `options` field of the `publish()` method. Therefore, the request will be sent to that participant only.

**Swift:**

```js
class MeetingViewController {
// Button when tapped will initiate capture request
@IBAction func requestCapture(_ sender: Any, _ participant: Participant) {

     let options = ["persist" : false, "sendOnly" : [participant.id]]
      meeting.pubsub.publish(topic: "IMAGE_CAPTURE", message: "Sending Request to capture image", options: options)
}
​}
```

#### Step 2 : Capture and Upload File

- To capture image from remote participant [Participant B], we will filter out request from the `onMessageReceived` event of the `PubSubMessageListener`. When a participant receives an image capture request, we will capture image using `captureImage` function of the `Participant` class.

- The captured image is then stored in the VideoSDK's temporary file storage system using the `uploadBase64File()` function of the `Meeting` class. This operation returns a unique `url` of the stored image.

- Next, the `url` is sent back to the participant who initiated the request using the `IMAGE_TRANSFER` topic. For this, Participant A must be subscribed to the topic `IMAGE_TRANSFER`.

**Swift:**

```js
extension MeetingViewController: PubSubMessageListener {

func onMessageReceived(_ message: PubSubMessage) {

    if message.topic == "IMAGE_CAPTURE" {
        print("received image request")
        handleImageCapture(senderId: message.senderId)
        return
    }
}
}
extension MeetingViewController {

func handleImageCapture(senderId: String) {
    // Ensure that caller is the local participant (i.e. Participant B).
    guard let participant = self.participants.first(where: {$0.isLocal})  else {
        return
    }
        // capture the image.
        participant.captureImage(height: 100, width: 100) { image in

            // make sure that image was captured
            guard let image = image else {
                print("Image was not captured)
                return
            }

            // upload it to the VideoSDK's temporary storage.
            meeting.uploadBase64File(base64Data: image, token: "<Your-Token>", fileName: "screenshot.jpeg") { url in

                //checking for successful upload
                guard let url = url else {
                    print("upload failed")
                    return
                }
                let options = ["persist" : false, "sendOnly" : senderId]
                // send url using pubsub back to Participant A.
                meeting.pubsub.publish(topic: "IMAGE_TRANSFER", message: url ?? "", options: options)
            }
        }
}
}
```

#### Step 3 : Fetch and Display Image

- To fetch the image, you need to be subscribed to the `IMAGE_TRANSFER` topic, receiving the `url` associated with the captured image. Once obtained, leverage the `fetchBase64File()` function from the `Meeting` class to retrieve the file in `base64` String format from VideoSDK's temporary storage.

**Swift:**

```js
extension MeetingViewController: PubSubMessageListener {

func onMessageReceived(_ message: PubSubMessage) {

    if message.topic == "IMAGE_CAPTURE" {
        print("received image request")
        handleImageCapture(senderId: message.senderId)
        return
    }
    // listen for IMAGE_TRANSFER topic
    if message.topic == "IMAGE_TRANSFER" {

        print("received image response")
        // fetch image from the VideoSDK's temporary storage.
        meeting.fetchBase64File(url: message.message, token: "<Your-Token>", completion: { base64Data in

                //checking for successful retrieval
                guard let base64Data = base64Data else {
                    print("retrieval failed")
                    return
                }
            print("base64Data: ", base64Data!)
            let data = Data(base64Encoded: base64Data ?? "", options: .ignoreUnknownCharacters)
            let image = UIImage(data: data!)
            //<Display this image or upload to your cloud storage>
        })
        return
    }
}
}
```

:::note

The file stored in the [VideoSDK's temporary file storage system](../collaboration-in-meeting/upload-fetch-temporary-file.md) will be automatically deleted once the current room/meeting comes to an end.

:::

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [captureImage()](/ios/api/sdk-reference/participant-class/methods#captureimage)
- [pubSub()](/ios/api/sdk-reference/meeting-class/pubsub)
- [uploadBase64File()](/ios/api/sdk-reference/meeting-class/methods#uploadbase64file)
- [fetchBase64File()](/ios/api/sdk-reference/meeting-class/methods#fetchbase64file)


---

# Mute / Unmute Mic - iOS

Muting and Unmuting your microphone refers to turning your microphone off and on, respectively.

When you mute your microphone, you prevent any sound from your microphone from being transmitted to other meeting participants, while unmuting it allows others to hear you.

### `unmuteMic()`

- By using `unmuteMic()` function of `Meeting` class, local participant can publish audio to other participants.

  - You can call this method when the local participant is not broadcasting any audio to others.

- Audio stream of the participant can be accessed from the `onStreamEnabled` event of `ParticipantEventListener`.

### `muteMic()`

- By using `muteMic()` function of `Meeting` class, local participant can stop publish audio to other participants.

- You can call this method when the local participant is broadcasting any audio to others.

### Example


**Swift:**

```js
@IBAction func micButtonTapped(_ sender: Any) {
if !micEnabled {
    // enable/unmute mic
    //highlight-next-line
    self.meeting?.unmuteMic()
} else {
    // disable/mute mic
    //highlight-next-line
    self.meeting?.muteMic()
}
}
```


### Events associated with `unmuteMic`

- Every Participant will receive a callback on [`onStreamEnabled()`](/ios/api/sdk-reference/participant-class/events#onstreamenabled) of the [`Participant`](/ios/api/sdk-reference/participant-class/introduction) with `Stream` object.

### Events associated with `muteMic`

- Every Participant will receive a callback on [`onStreamDisabled()`](/ios/api/sdk-reference/participant-class/events#onstreamdisabled) of the [`Participant`](/ios/api/sdk-reference/participant-class/introduction) with `Stream` object.

**Swift:**

```js
extension MeetingViewController: ParticipantEventListener {
//highlight-start
//Callback for when the participant starts a stream
func onStreamEnabled(_ stream: MediaStream, forParticipant participant: Participant) {
    if stream.kind = .state(value: .audio) {
        print("new audio stream enabled")
    }
}
 //highlight-end 
//Callback for when the participant stops a stream
    //highlight-start
func onStreamDisabled(_ stream: MediaStream, forParticipant participant: Participant) {
    if stream.kind = .state(value: .audio) {
        print("new audio stream disabled")
    }
}
//highlight-end
}
```


## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [unmuteMic()](/ios/api/sdk-reference/meeting-class/methods#unmutemic)
- [muteMic()](/ios/api/sdk-reference/meeting-class/methods#mutemic)
- [onStreamEnabled()](/ios/api/sdk-reference/participant-class/events#onstreamenabled)
- [onStreamDisabled()](/ios/api/sdk-reference/participant-class/events#onstreamdisabled)


---

# Screen Share - iOS

Follow the below listed steps to add the screensharing capability in your iOS App.

## Create Broadcast Upload Extension in iOS

### Step 1 : Open Target

Open your project with xcode, the select **File > New > Target** in menu bar.

![IOS Screen Share](/img/ios-screenshare/step1-xcode.png)

### Step 2 : Select Target

Select **Broadcast Upload Extension** and click next.

![IOS Screen Share](/img/ios-screenshare/step2-xcode.png)

### Step 3 : Configure Broadcast Upload Extension

Enter the extension's name in the **Product Name** field, choose the team from the dropdown, uncheck the "Include UI extension" field, and click "Finish."

![IOS Screen Share](/img/ios-screenshare/step3-xcode.png)

### Step 4 : Activate Extension scheme

You will be prompted with a popup : **Activate "Your-Extension-name" scheme?**, click on activate.

![IOS Screen Share](/img/ios-screenshare/step4-xcode.png)
 
Now, the "Broadcast" folder will appear in the Xcode left side bar.

![IOS Screen Share](/img/ios-screenshare/step5-xcode.png)

### Step 5 : Add External file in Created Extension

Open the [videosdk-rtc-ios-sdk-example](https://github.com/videosdk-live/videosdk-rtc-ios-sdk-example/tree/main/VideoSDKScreenShare) repository, and copy the following files: `SampleUploader.swift`, `SocketConnection.swift`, `DarwinNotificationCenter.swift`, and `Atomic.swift` to your extension's folder. Ensure that these files are added to the target.

### Step 6 : Update `SampleHandler.swift` file

Open [SampleHandler.swift](https://github.com/videosdk-live/videosdk-rtc-ios-sdk-example/blob/main/VideoSDKScreenShare/SampleHandler.swift), and copy the content of the file. Paste this content into your extension's SampleHandler.swift file.

### Step 7 : Add Capability in App

In Xcode, navigate to **YourappName > Signing & Capabilities**, and click on **+Capability** to configure the app group.

![IOS Screen Share](/img/ios-screenshare/step8-xcode.png)

Choose **App Groups** from the list.

![IOS Screen Share](/img/ios-screenshare/step9-xcode.png)
 
After that, select or add the generated App Group ID that you have created before.

![IOS Screen Share](/img/ios-screenshare/step10-xcode.png)

### Step 8 : Add Capability in Extension

Go to **Your-Extension-Name > Signing & Capabilities** and configure **App Group** functionality which we had perform in previous steps. (Group id should be same for both targets).

![IOS Screen Share](/img/ios-screenshare/step11-xcode.png)

### Step 9 : Add App Group Id in Extension File

Go to the extension's `SampleHandler.swift` file and paste your group ID in the `appGroupIdentifier` constant.

![IOS Screen Share](/img/ios-screenshare/step12-xcode.png)

### Step 10 : Update App level info.plist file

1.  Add a new key **RTCScreenSharingExtension** in Info.plist with the extension's Bundle Identifier as the value.
2.  Add a new key **RTCAppGroupIdentifier** in Info.plist with the extension's App groups Id as the value.

**Note** : For the extension's Bundle Identifier, go to **TARGETS > Your-Extension-Name > Signing & Capabilities** .

![IOS Screen Share](/img/ios-screenshare/step13-xcode.png)

:::note

You can also check out the extension's [example code](https://github.com/videosdk-live/videosdk-rtc-ios-sdk-example/tree/main/VideoSDKScreenShare) on github.
:::

## Integrate ScreenShare in your App

After successfully creating Broadcast Upload Extension using the above listed steps, we can start using the `enableScreenShare` and `disableScreenShare` functions of the `Meeting` class.

### How to use the ScreenShare functions



**Swift:**

```js
@IBAction func ScreenShareButtonTapped(_ sender: Any) {
Task {
  self.meeting?.enableScreenShare()
}
}

@IBAction func StopScreenShareButtonTapped(_ sender: Any) {
Task {
  self.meeting?.disableScreenShare()
}
}
```

:::caution
  The function `enableScreenShare` and `disableScreenShare` are async functions; therefore use above syntax to call the screenshare functions.
:::

Calling the `enableScreenShare()` will prompt a `RPBroadcastPickerView` with the extension that was created using the above steps.

![IOS Screen Share](/img/ios-screenshare/step23-xcode.png)

After clicking the **Start Broadcast** button, you will be able to get the screen share stream in the session.

- When the broadcast is started, it creates a Stream that has `MediaStream.kind = .share`. Using the stream kind, you can prompt a ScreenShare view for remote peer when ScreenShare is started by the local peer.

- Similarly, you can use the same kind to dismiss the screenshare view on the remote peer when the screenshare was stopped.

### Example

**Swift:**

```js
extension MeetingViewController: ParticipantEventListener {
/// Participant has enabled mic, video or screenshare
/// - Parameters:
///   - stream: enabled stream object
///   - participant: participant object
func onStreamEnabled(_ stream: MediaStream, forParticipant participant: Participant) {
    
    if stream.kind == .share {
    // show screen share
        showScreenSharingView(true)
        screenSharingView.showMediastream(stream)
        return
    }
    
    // show stream in cell
    if let cell = self.cellForParticipant(participant) {
        cell.updateView(forStream: stream, enabled: true)
    }
    
    if participant.isLocal {
    // turn on controls for local participant
        self.buttonControlsView.updateButtons(forStream: stream, enabled: true)
    }
}

/// Participant has disabled mic, video or screenshare
/// - Parameters:
/// - stream: disabled stream object
/// - participant: participant object
func onStreamDisabled(_ stream: MediaStream, forParticipant participant: Participant) {
    
    if stream.kind == .share {
    // remove screen share
        showScreenSharingView(false)
        screenSharingView.hideMediastream(stream)
        return
    }
    
    // hide stream in cell
    if let cell = self.cellForParticipant(participant) {
        cell.updateView(forStream: stream, enabled: false)
    }
    
    if participant.isLocal {
    // turn off controls for local participant
        self.buttonControlsView.updateButtons(forStream: stream, enabled: false)
    }
}
}
```

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [enableScreenShare()](/ios/api/sdk-reference/meeting-class/methods#enablescreenshare)
- [disableScreenShare()](/ios/api/sdk-reference/meeting-class/methods#disablescreenshare)
- [onStreamEnabled()](/ios/api/sdk-reference/participant-class/events#onstreamenabled)
- [onStreamDisabled()](/ios/api/sdk-reference/participant-class/events#onstreamdisabled)



---

# On / Off Camera - iOS

Any participant can turn their camera on or off in the meeting using below methods.

### `enableWebcam()`

- By using `enableWebcam()` function of `Meeting` class, local participant can publish video to other participants.

- You can call this method when the local participant is not broadcasting any video to others.

- You can pass customised video track in `enableWebcam()` by using [Custom Video Track](/ios/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track#custom-video-track).

- Video stream of the participant can be accessed from the `onStreamEnabled` event of `ParticipantEventListener`.

### `disableWebcam()`

- By using `disableWebcam()` function of `Meeting` class, local participant can stop publish video to other participants.

- You can call this method when the local participant is broadcasting any video to others.

:::info
From version 2.1.5 of the SDK, you can now use the hardware-accelerated codec (H.264) with [VideoSDK.createCameraVideoTrack()](../render-media/optimize-video-track.md), which can enhance compresses video data for efficient transmission over the internet, balancing quality and bandwidth usage.
:::



**Swift:**

```js
@IBAction func videoButtonTapped(_ sender: Any) {
if !videoEnabled {
    // enable webcam/camera
    //highlight-next-line
    self.meeting?.enableWebcam()
} else {
    // disable webcam/camera
    //highlight-next-line
    self.meeting?.disableWebcam()
}
}
```

### Events associated with `enableWebcam`

- Every Participant will receive a callback on [`onStreamEnabled()`](/ios/api/sdk-reference/participant-class/events#onstreamenabled) of the [`Participant`](/ios/api/sdk-reference/participant-class/introduction) with `Stream` object.

### Events associated with `disableWebcam`

- Every Participant will receive a callback on [`onStreamDisabled()`](/ios/api/sdk-reference/participant-class/events#onstreamdisabled) of the [`Participant`](/ios/api/sdk-reference/participant-class/introduction) with `Stream` object.

**Swift:**

```js
extension MeetingViewController: ParticipantEventListener {
//highlight-start
//Callback for when the participant starts a stream
func onStreamEnabled(_ stream: MediaStream, forParticipant participant: Participant) {
    if stream.kind = .state(value: .video) {
        print("new audio stream enabled")
    }
}
 //highlight-end
//Callback for when the participant stops a stream
    //highlight-start
func onStreamDisabled(_ stream: MediaStream, forParticipant participant: Participant) {
    if stream.kind = .state(value: .video) {
        print("new audio stream disabled")
    }
}
//highlight-end
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [enableWebcam()](/ios/api/sdk-reference/meeting-class/methods#enablewebcam)
- [disableWebcam()](/ios/api/sdk-reference/meeting-class/methods#disablewebcam)
- [onStreamEnabled()](/ios/api/sdk-reference/participant-class/events#onstreamenabled)
- [onStreamDisabled()](/ios/api/sdk-reference/participant-class/events#onstreamdisabled)


---

# Integrate VideoSDK Using Swift Package Manager (SPM) - iOS




---

# Client Setup using Pods - iOS




---

# Known Issues - iOS




---

https://sdk.videosdk.live/js-sdk/0.2.6/videosdk.jsVideoSDK offers a range of video streaming tools and solutions for content creators, publishers, and developers.

- A custom template is a specialized layout for a live stream that allows users to integrate real-time graphics into their broadcasts.

- With custom templates, users can enhance their video content by overlaying graphics, text, images, and animations onto their live streams. These elements can be customized to align with specific branding requirements.

- By leveraging custom templates, users can craft dynamic and engaging video experiences. Whether incorporating live scoreboards, social media feeds, or other personalized elements, users have the flexibility to create visually appealing streams that stand out and capture audience attention.

:::note

Custom templates can also be used with recordings and RTMP service provided by VideoSDK.

:::

### What you can do with Custom Template

By utilizing a custom template, you have the flexibility to create various modes for your live stream. Here are some popular modes that you can design:

- **`PK Host:`** The host can organize a player vs. player battle, as illustrated in the example of a gaming battle shown below.

![pk host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_pk_battle.png)

- **`Watermark:`** The host has the ability to add and update watermarks anywhere in the template; for instance, the image below features a VideoSDK watermark on the top right side of the screen.

![watermark host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_water_mark.png)

- **`News Mode:`** Additionally, the host can incorporate dynamic text in the lower third banner, as demonstrated by the sample text in the bottom left of the screen.

![news mode](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_news_live.png)

### Custom template with VideoSDK

In this section, we will discuss how Custom Templates work with VideoSDK.

- **`Host`**: The host initiates live streaming by providing the `templateURL`. The `templateURL` is the URL of the hosted template webpage. The host is also responsible for managing the template, including tasks such as altering text, logos, and switching template layouts.

- **`VideoSDK Template Engine`** : The VideoSDK Template Engine accepts and opens the templateURL in the browser, actively listening to all events initiated by the Host. It facilitates the customization of the template in accordance with the host's preferences.

- **`Viewer`**: Viewers can stream the content, experiencing the live stream with added real-time graphics. This feature contributes to a distinctive and engaging viewing experience.

![custom template](https://cdn.videosdk.live/website-resources/docs-resources/custom_template.png)

### Understanding Template URL

The template URL is a webpage that VideoSDK Template Engine will open while composing the live stream.

It will appear as shown below.

![template url](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_url.png)

The Template URL comprises of two essential parts:

- Your actual page URL, resembling something like `https://example.com/videosdk-template`.
- Query parameters, designed to enable the VideoSDK Template Engine to seamlessly join the meeting upon opening the URL. There are three key query parameters in total:
  - `token`: Your token, serving as the authentication key to join the meeting.
  - `meetingId`: The meeting Id of the meeting that the VideoSDK Template Engine will join.
  - `participantId`: The participant ID of the VideoSDK Template Engine. This should be included when joining the template engine in your template, ensuring that the template engine participant remains invisible to other participants. **This parameter is automatically added by the VideoSDK**.

:::info

Above mentioned query parameters are mandatory. Apart from these parameters, you can pass any other extra parameters which are required according to your use-case.

:::

### **Creating Template**

**`Step 1:`** Import VideoSDK using `<script>` tag or install it using the below-mentioned npm command.
Make sure you are in your app directory before you run this command.



**Tab:**

" label="<script>" default>

```html
<html>
  <head></head>
  <body>
// highlight-next-line
<script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
  </body>
</html>
```

---

**npm:**

```bash
npm install @videosdk.live/js-sdk
```

---

**yarn:**

```bash
yarn add @videosdk.live/js-sdk
```

:::note

You can use VideoSDK's React or JavaScript SDK to create custom template. Following is the example of building custom template with JavaScript SDK.

:::

###### Structure of the Project

```jsx title="Project Structure"
  root
   ├── index.html
   ├── index.js
```

**`Step 2:`** Craft a user interface (UI) tailored for your live stream presentation.

```html title="index.html"
<!DOCTYPE html>
<html>
  <head> </head>

  <body>
    <div id="textDiv">Starting live stream...</div>

    
    <div class="row" id="videoContainer"></div>

    <script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
    <script src="index.js"></script>
  </body>
</html>
```

**`Step 3:`** Next, fetch the query parameters, from the URL which will be later used to initialize the meeting and get the elements from DOM.

```js title=index.js
const url = window.location;
const urlParams = new URLSearchParams(url.search);

const meetingId = urlParams.get("meetingId");
const token = urlParams.get("token");
const participantId = urlParams.get("participantId");

const videoContainer = document.getElementById("videoContainer");
const textDiv = document.getElementById("textDiv");
```

**`Step 4:`** Subsequently, initialize the meeting with the parameters that were extracted from the URL. Ensure direct initialization so that the template engine seamlessly joins the meeting upon page load.

```js title=index.js
window.VideoSDK.config(token);

const meeting = window.VideoSDK.initMeeting({
  meetingId: meetingId, // required
  name: "recorder", // required
  micEnabled: false,
  webcamEnabled: false,
  participantId: participantId,
});

meeting.join();

meeting.on("meeting-joined", () => {
  textDiv.style.display = "none";
});
```

**`Step 5:`** Next step is to create the container that will render the meeting view on the `participant-joined` event.

```js title=index.js
//  participant joined
meeting.on("participant-joined", (participant) => {
  let videoElement = createVideoElement(
    participant.id,
    participant.displayName
  );
  let audioElement = createAudioElement(participant.id);

  participant.on("stream-enabled", (stream) => {
    setTrack(stream, audioElement, participant, false);
  });
  videoContainer.appendChild(videoElement);
  videoContainer.appendChild(audioElement);
});

// participants left
meeting.on("participant-left", (participant) => {
  let vElement = document.getElementById(`f-${participant.id}`);
  vElement.remove(vElement);

  let aElement = document.getElementById(`a-${participant.id}`);
  aElement.remove(aElement);
});

// creating video element
function createVideoElement(pId, name) {
  let videoFrame = document.createElement("div");
  videoFrame.setAttribute("id", `f-${pId}`);

  //create video
  let videoElement = document.createElement("video");
  videoElement.classList.add("video-frame");
  videoElement.setAttribute("id", `v-${pId}`);
  videoElement.setAttribute("playsinline", true);
  videoElement.setAttribute("width", "300");
  videoElement.muted = true;
  videoFrame.appendChild(videoElement);

  let displayName = document.createElement("div");
  displayName.innerHTML = `Name : ${name}`;
  videoFrame.appendChild(displayName);

  return videoFrame;
}

// creating audio element
function createAudioElement(pId) {
  let audioElement = document.createElement("audio");
  audioElement.setAttribute("autoPlay", "false");
  audioElement.setAttribute("playsInline", "true");
  audioElement.setAttribute("controls", "false");
  audioElement.setAttribute("id", `a-${pId}`);
  audioElement.style.display = "none";
  return audioElement;
}

// setting media track
function setTrack(stream, audioElement, participant, isLocal) {
  if (stream.kind == "video") {
    isWebCamOn = true;
    const mediaStream = new MediaStream();
    mediaStream.addTrack(stream.track);
    let videoElm = document.getElementById(`v-${participant.id}`);
    videoElm.srcObject = mediaStream;
    videoElm
      .play()
      .catch((error) =>
        console.error("videoElem.current.play() failed", error)
      );
  }
  if (stream.kind == "audio") {
    if (isLocal) {
      isMicOn = true;
    } else {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(stream.track);
      audioElement.srcObject = mediaStream;
      audioElement
        .play()
        .catch((error) => console.error("audioElem.play() failed", error));
    }
  }
}
```

**`Step 6:`** Now, listen to PubSub messages from the `CHANGE_BACKGROUND` topic, triggering a change in the meeting's background color accordingly.

:::note

The PubSub mechanism is utilized to communicate with the template. You can learn more about [PubSub from here](/javascript/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

:::

```js title=index.js
meeting.on("meeting-joined", () => {
  //  ...

  meeting.pubSub.subscribe("CHANGE_BACKGROUND", (data) => {
    let { message } = data;
    document.body.style.backgroundColor = message;
  });
});
```

**`Step 7:`** Once tested, you can deploy it using your backend or host it on services like [firebase](https://www.geeksforgeeks.org/how-to-deploy-react-project-on-firebase/) or vercel.

:::tip

You can checkout the github repository for sample custom template [created here](https://github.com/videosdk-live/videosdk-custom-recording-template-js-example).

:::

### Setup Livestream Using Custom Template

- To utilize Custom Templates with Livestream, you need to establish both the Host and Viewer setups. The Host initiates the livestream, while Viewers can watch the broadcast.

![template manager](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_manager.png)

- To understand custom templates, clone this example and run it on your system.

```bash
git clone https://github.com/videosdk-live/videosdk-custom-recording-template-js-example.git
```

- You can utilize this custom template in [Start Recording API](/api-reference/realtime-communication/start-recording), [Start HLS API](/api-reference/realtime-communication/start-hlsStream) and [Start Livestream API](/api-reference/realtime-communication/start-livestream). Here is the example of HLS.
- To utilize the custom template that has been deployed, invoke the [Start HLS API](https://docs.videosdk.live/api-reference/realtime-communication/start-hlsStream) instead of the `startHls` method from the `Meeting` class. The necessary code has already been incorporated in the cloned example above.

:::important

You can create your own custom template manager in JavaScript. In this example, we are using one for better understanding.

:::

```js
<button
  onClick={async () => {
    const url = `https://api.videosdk.live/v2/hls/start`;
    //Update your Custom Template URL here if you have deployed your own, if not deployed you can use this template from our URL.
    //highlight-next-line
    const templateUrl = `https://lab.videosdk.live/js-template-demo/?meetingId=${meetingId}&token=${authToken}`;
    const options = {
      method: "POST",
      headers: {
        Authorization: authToken,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        roomId: meetingId,
        templateUrl: templateUrl,
      }),
    };

    const result = await fetch(url, options)
      .then((response) => response.json()) // result will have playbackHlsUrl and livestreamUrl
      .catch((error) => console.error("error", error));
  }}
>
  Start HLS
</button>
```

- In this example, the host has two options on their side, enabling them to change the background and send messages to the viewers.

- Given below is a test run of the example.


<div style={{textAlign: 'center'}}>



</div>

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)
- [Start HLS API](/api-reference/realtime-communication/start-hlsStream)
- [Start Livestream API](/api-reference/realtime-communication/start-livestream)
- [recordingState](/react/api/sdk-reference/use-meeting/properties#recordingstate)
- [hlsState](/react/api/sdk-reference/use-meeting/properties#hlsstate)
- [livestreamState](/react/api/sdk-reference/use-meeting/properties#livestreamstate)
- [hlsUrls](/react/api/sdk-reference/use-meeting/properties#hlsurls)
- [onRecordingStateChanged](/react/api/sdk-reference/use-meeting/events#onrecordingstatechanged)
- [onHlsStateChanged](/react/api/sdk-reference/use-meeting/events#onhlsstatechanged)
- [onLivestreamStateChanged](/react/api/sdk-reference/use-meeting/events#onlivestreamstatechanged)



---

# Go Live On Social Media - iOS

This feature allows participant to broadcast meeting on various social media platforms such as Facebook or Youtube.
This guide will provide an overview of how participant can start and stop broadcasting meeting.

1. **Start LiveStream** - By using `startLivestream()` function, a participant can start broadcasting meeting on various platforms by provding url and stream keys as an argument.
2. **Stop LiveStream** - By using `stopLivestream()` function, a participant can stop broadcasting on all platforms.

### Start And Stop Live Stream



**Swift:**

```js
/// keep track of livestream
private var livestreamStarted = false

@IBAction func livestreamButtonTapped(_ sender: Any) {
if !livestreamStarted {
    // prepare output
    // specify social-media-url and stream-key
    let output = LivestreamOutput(url: "<rtmp://a.rtmp.youtube.com/live2>", streamKey: "<stream-key>")

    // start livestream
    self.meeting?.startLivestream(outputs: [output])
}
else {
    // stop livestream
    self.meeting?.stopLivestream()
}
}
```

### Events

1. **livestream-started** - Whenever broadcasting of meeting started, `livestream-started` event will trigger.

2. **livestream-stopped** - Whenever broadcasting of meeting stopped, `livestream-stopped` event will trigger.

**Swift:**

```js
/// Called after livestream starts
func onLivestreamStarted() {
liveStreamStarted = true

// show indication that livestream is started
}

/// Called after livestream stops
func onLivestreamStopped() {
liveStreamStarted = false

// hide livestream indication
}
```

---

# Interactive Livestream (HLS) - iOS

Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

In an interactive live stream (HLS), viewers can take part in a variety of activities like live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

<center>

![VideoSDK-HLS](/img/VideoSDK-HLS.png)

</center>

VideoSDK also allows you to configure the interactive livestream layouts in numerous ways like by simply setting different prebuilt layouts in the configuration or by providing your own custom template to do the livestream according to your layout choice.

This guide will provide an overview of how to implement start and stop Interactive live streaming (HLS).

:::important

To initiate automatic Interactive live streaming (HLS) at the beginning of a `session`, simply provide the `autoStartConfig` feature `hls` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.

:::

### `startHLS()`

`startHLS()` can be used to start a interactive livestream of the meeting which can be accessed from the `useMeeting` hook. This method accepts two optional parameter:

- `config (optional)`: This parameter will define how the interactive livestream layout should look like.

- `transcription(optional)`: This parameter will be used to enable post transcription for the recording with the given config.



**Swift:**

```js
let config: HLSConfig = HLSConfig(

  // highlight-next-line
  // Layout Configuration
  layout: HLSLayout(
type: .GRID, // .SPOTLIGHT | .SIDEBAR,  Default : .GRID
priority: .SPEAKER, // .PIN, Default : .SPEAKER
gridSize: 4 // MAX : 25
  ),

  // highlight-next-line
  // Theme of livestream
  theme: .DARK, //  .LIGHT | .DEFAULT

  // highlight-next-line
  // `mode` is used to either interactive livestream video & audio both or only audio.
  mode: .video_and_audio, // .audio, Default : .video_and_audio

  // highlight-next-line
  // Quality of livestream and is only applicable to `video-and-audio` type mode.
  quality: .high,  // .low | .med,  Default : .med

  //highlight-start
  // This mode refers to orientation of recording.
  // landscape : Livestream the meeting in horizontally
  // portrait : Livestream the meeting in vertically (Best for mobile view)
  //highlight-end
  orientation: .portrait  // .portrait,  Default : .landscape
)

 let transcription: PostTranscriptionConfig =  PostTranscriptionConfig(
        enabled: true,
        summary: SummaryConfig(
                enabled: true,
                prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
            )
        )

startHLS(config: config, transcription: transcription)
```

### `stopHLS()`

- `stopHLS()` is used to stop interactive livestream of the meeting which can be accessed from the `meeting` object.

#### Example

**Swift:**

```js
stopHLS();
```

### Event associated with HLS

- **onHlsStateChanged** - Whenever meeting HLS state changes, then `onHlsStateChanged` event will trigger.

- You can get the `downstreamUrl` of the HLS to play it on the Viewer side when the state changes to `HLSState.HLS_STARTED`

**Swift:**

```js
func onHlsStateChanged(state: HLSState, hlsUrl: HLSUrl?) {
switch(state) {
    case .HLS_STARTING:
        print("HLS Starting")

    case .HLS_STARTED:
        self.hlsStreamStarted = true
        print("HLS Started")

    case .HLS_PLAYABLE:
        print("HLS Playable")

    case .HLS_STOPPING:
        print("HLS Stopping")

    case .HLS_STOPPED:
        self.hlsStreamStarted = false
        print("HLS Stopped")
    }
}
```

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [startHLS](/ios/api/sdk-reference/meeting-class/methods#starthls)
- [stopHLS](/ios/api/sdk-reference/meeting-class/methods#stophls)
- [onHlsStateChanged](/ios/api/sdk-reference/meeting-class/events#onhlsstatechanged)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

# RTMP Livestream - iOS

RTMP is a popular protocol for live streaming video content from a VideoSDK to platforms such as YouTube, Twitch, Facebook, and others.

By providing the platform-specific stream key and stream URL, the VideoSDK can connect to the platform's RTMP server and transmit the live video stream.

VideoSDK allows you to livestream your meeting to platform which support RTMP ingestion just by providing the platform-specific stream key and stream URL, we can connect to the platform's RTMP server and transmit the live video stream.

VideoSDK also allows you to configure the livestream layouts in numerous ways like by simply setting different prebuilt layouts in the configuration or by providing your own custom template to do the livestream according to your layout choice.

This guide will provide an overview of how to implement start and stop RTMP Livestreaming.

### `startLivestream()`

`startLivestream()` can be used to start a RTMP livestream of the meeting which can be accessed from the `Meeting` class. This method accepts two parameters:

- `outputs`: This parameter accepts a list of `LivestreamOutput` objects which contains the RTMP `url` and `streamKey` of the platforms you want to start the livestream.



**Swift:**

```js
class MeetingViewController {

private let platformUrl = "<url-of-the-platform>"
private let privateKey = "<private-key>"

// button to start livestream
@IBAction func startLiveStreamButtonTapped(_ sender: Any) {
    //highlight-start
     self.meeting?.startLivestream(outputs: LivestreamOutput(url: platformUrl, streamKey: privateKey))
    //highlight-end
}
}
```

### `stopLivestream()`

- `stopLivestream()` is used to stop the meeting livestream which can be accessed from the `Meeting` class.

#### Example

**Swift:**

```js
class MeetingViewController {
// button to stop livestream
@IBAction func startLiveStreamButtonTapped(_ sender: Any) {
    //highlight-start
     self.meeting?.stopLivestream()
    //highlight-end
}
}
```

### Event associated with Livestream

- **onLivestreamStateChanged** - Whenever meeting livestream state changes, then `onLivestreamStateChanged` event will trigger.

**Swift:**

```js
extension MeetingViewController: MeetingEventListener {
// rtmp-event
//highlight-start
func onLivestreamStateChanged(state: LiveStreamState) {
    switch(state) {
        case .LIVESTREAM_STARTING:
            print("livestream starting")

        case .LIVESTREAM_STARTED:
            print("livestream started")

        case .LIVESTREAM_STOPPING:
            print("livestream stoping")

        case .LIVESTREAM_STOPPED:
            print("livestream stopped")
    }
}
//highlight-end
}
```

## API Reference

The API references for all the methods utilised in this guide are provided below.

- [startLivestream()](/ios/api/sdk-reference/meeting-class/methods#startlivestream)
- [stopLivestream()](/ios/api/sdk-reference/meeting-class/methods#stoplivestream)
- [onLivestreamStateChanged](/ios/api/sdk-reference/meeting-class/events#onlivestreamstatechanged)


---

# Quick Start for Http Live Streaming(HLS) in iOS

**VideoSDK** empowers you to seamlessly integrate the **Http Live Streaming(HLS)** feature into your iOS application within minutes.

In this quickstart, you'll explore this feature of VideoSDK. Follow the step-by-step guide to integrate it within your application.

:::info

For low-latency interactive live streaming (under 100ms), follow this [documentation](./quick-start-ios-ils.md).
:::

### Prerequisites

- iOS 13.0+
- Xcode 15.0+
- Swift 5.0+

:::important

One should have a VideoSDK account to generate token.
Visit VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate token

:::

### App Architecture

The application consists of two primary interfaces:

1. `Start Meeting View`

- Allows users to create a new meeting or join an existing one by selecting their mode (Host or Viewer/Audience)

2. `Meeting View`

- Provides Http Live Stream controls and adapts the UI dynamically based on the user's mode (Host or Viewer/Audience).

### Getting Started With the Code!

Follow the steps to create the environment necessary to add video calls into your app. Also you can find the code sample for [quickstart here](https://github.com/videosdk-live/quickstart/tree/main/ios-hls).




### Step 1: Create New iOS Application


`Step 1:` Create a new application by selecting `Create a new Xcode project`

`Step 2:` Add **Product Name** and Save the project.

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/hls_qs_ios_project_creation.png' style={{height: '600px'}}/>

</center>


### Step 2: VideoSDK Installation


There are two ways to install VideoSDK: Using Swift Package Manager (SPM) or Using CocoaPods.

**1. Install Using Swift Package Manager (SPM)**

To install VideoSDK via Swift Package Manager, follow these steps:

1. Open your Xcode project and go to File > Add Packages.
2. Enter the repository URL:

```js
  https://github.com/videosdk-live/videosdk-rtc-ios-spm
```

3. Choose the version rule (e.g., "Up to Next Major") and add the package to your target.
4. Import the library in Swift files:

```js
import VideoSDKRTC
```

For more details, refer to the official guide on [SPM installation](/ios/guide/video-and-audio-calling-api-sdk/ios-sdk-spm).

**2. Install Using CocoaPods**

To install VideoSDK using CocoaPods, follow these steps:

1. Initialize CocoaPods: Run the following command in your project directory:

```js
pod init
```

2. Update the Podfile: Open the Podfile and add the VideoSDK dependency:

```js
pod 'VideoSDKRTC', :git => 'https://github.com/videosdk-live/videosdk-rtc-ios-sdk.git'
```

3. Install the Pod: Run the following command to install the pod:

```js
pod install
```

For more details, refer to the official guide on [CocoaPods installation](/ios/guide/video-and-audio-calling-api-sdk/ios-sdk).

then declare the permissions in Info.plist :

```js
<key>NSCameraUsageDescription</key>
<string>Camera permission description</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone permission description</string>
```


### Step 3: Project Structure


```js
quick_start_ios_hls
   ├── quick_start_ios_hls.swift // Default
   ├── Screens
		├── StartMeetingView.swift
        └── Meeting
            ├── Controller
                └── MeetingViewController.swift
            └── MeetingView.swift
   ├── Views
        ├── HLSPlayer.swift
        └── ParticipantViewItem.swift
   ├── Model
        └── RoomStruct.swift
   └── Info.plist // Default
 Pods
	 └── Podfile
```


### Step 4: Create Start Meeting View


The `StartMeetingView` acts as the entry point for users to initiate or participate in Http Live Streams with the following functionalities:

- **Create Meeting as Host**: Start a new Http Live Stream in `SEND_AND_RECV` mode, providing full host privileges.

- **Join as Host**: Enter an existing Http Live Stream with `SEND_AND_RECV` mode, granting full host controls.

- **Join as Viewer**: Join an existing Http Live Stream with `SIGNALLING_ONLY` mode, without receiving & producing audio & video.



**Swift:**

```js title="StartMeetingView.swift"
import SwiftUI

// MARK: - Meeting Role Enum
enum UserRole: String { case host = "Host", case viewer = "Viewer" }

struct StartMeetingView: View {
//MARK: - Properties
@State private var meetingId: String = "

</center>

Also add the `StartMeetingView` in main app as shown below

**Swift:**

```js title="quick_start_ios_hls.swift"
import SwiftUI

@main
struct quick_start_ios_hls: App {
var body: some Scene {
    WindowGroup {
        //highlight-start
        StartMeetingView()
        //highlight-end
    }
}
}
```

Before proceeding, let's understand the two modes of a HTTP Live Stream:

###### 1. SEND_AND_RECV (For Host or Co-host):

- Designed primarily for the Host or Co-host.
- Allows sending and receiving media.
- Hosts can broadcast their audio/video and interact directly with the audience.

###### 2. SIGNALLING_ONLY (For Viewer/Audience):

- Tailored for the Viewer/Audience.
- Doesn't enabled receiving media shared by the Host also.
- Audience members can not view or listen, also cannot share their own media.



### Step 5: Initialize and Join the Http Live Stream


In this step, Inside `MeetingViewController` we will setup `initializeMeeting` and related functions for it. You will require **Auth token**, you can generate it using either using [videosdk-server-api-example](https://github.com/videosdk-live/videosdk-rtc-api-server-examples) or generate it from the [Video SDK Dashboard](https://app.videosdk.live/api-keys) for developer.

`MeetingViewController` will implement various event listeners such as `MeetingEventListener`, `ParticipantEventListener`.

**Swift:**

```js title="MeetingViewController.swift"

import Foundation
import SwiftUI
import Combine
import VideoSDKRTC
internal import Mediasoup

// MARK: - MeetingViewController
class MeetingViewController: ObservableObject {

@Published var participants: [Participant] = []
@Published var hlsState: HLSState = .HLS_STOPPED

@Published var isMicOn: Bool = true
@Published var isWebcamOn: Bool = true
@Published var meeting: Meeting? = nil
@Published var participantVideoTracks: [String: RTCVideoTrack] = [:]
@Published var participantMicStatus: [String: Bool] = [:]
@Published var playbackURL: String? = nil
private var cancellables = Set

</center>


### Step 7: Implementing Media Toggles and Start/Stop HLS


**Host Controls**: Include buttons to toggle the microphone, webcam and HLS, allowing users to mute/unmute their microphone and enable/disable their camera and start/stop the HLS entirely.

**Header UI**: Includes button for leave the meeting and meetingId also displayed in the Header UI.

**Swift:**

```js title="MeetingView.swift"

import SwiftUI
import VideoSDKRTC

struct MeetingView: View {

@StateObject private var controller: MeetingViewController
@Environment(\.dismiss) var dismiss

init(meetingId: String, role: UserRole) {
    _controller = StateObject(
        wrappedValue: MeetingViewController(meetingId: meetingId, role: role)
    )
}

// Grid layout
private let columns = [
    GridItem(.flexible(), spacing: 10),
    GridItem(.flexible(), spacing: 10),
]

var body: some View {
    ZStack {
        Color.black.ignoresSafeArea()
        
        VStack(spacing: 20) {
            
            // HEADER
            header
            
            if controller.role == .host {
                // HLS State
                Text("Current HLS State : \(controller.hlsState.rawValue)")
                    .foregroundColor(.white)
                    .font(.headline)
                
                // Participants Grid
                ScrollView {
                    LazyVGrid(columns: columns) {
                        ForEach(controller.participants, id: \.id) { participant in
                            ParticipantContainerView(
                                participant: participant,
                                controller: controller
                            )
                            .frame(height: 200, alignment: .center)
                            
                        }
                    }
                }
                
                Spacer()
            } else {
                if ((controller.hlsState == .HLS_STARTED || controller.hlsState == .HLS_PLAYABLE) && controller.playbackURL != nil) {
                    HLSVideoPlayer(
                        url: URL(string: controller.playbackURL ?? "")!,
                        width: .infinity,
                        height: .infinity
                    )
                    .cornerRadius(12)
                    .padding()
                   
                    Spacer()
                } else {
                    Spacer()
                    Text("Waiting for host\nto start the live streaming")
                        .font(.title)
                        .foregroundStyle(.white)
                        .bold(true)
                        .multilineTextAlignment(.center)
                    Spacer()
                }
            }
            
            // Host Controls
            if controller.role == .host {
                hostControls
            }
        }
    }
    .navigationBarBackButtonHidden(true)
    .navigationBarHidden(true)
}

// highlight-start
// MARK: Header UI
private var header: some View {
    HStack {
        Text("Meeting : \(controller.meetingId)")
            .foregroundColor(.white)
            .font(.title3.bold())
        
        Spacer()
        
        Button {
            controller.leaveMeeting()
            dismiss()
        } label: {
            Text("Leave")
                .font(.headline)
                .padding(.horizontal, 18)
                .padding(.vertical, 10)
                .background(Color.blue)
                .foregroundColor(.white)
                .cornerRadius(10)
        }
    }
    .padding(.horizontal)
    .padding(.top)
}
// highlight-end

// highlight-start
// MARK: Host bottom controls
private var hostControls: some View {
    HStack(spacing: 14) {
        
        if (controller.hlsState == .HLS_STARTING || controller.hlsState == .HLS_STARTED || controller.hlsState == .HLS_PLAYABLE) {
                controlButton(title: "Stop HLS") {
                    controller.stopHLS()
                }
        } else {
            controlButton(title: "Start HLS") {
                controller.startHLS()
            }
        }
        
        controlButton(title: "Toggle Webcam") {
            controller.toggleWebcam()
        }
        
        controlButton(title: "Toggle Mic") {
            controller.toggleMic()
        }
    }
    .padding(.bottom, 20)
}
// highlight-end

// MARK: Reusable UI Elements
func controlButton(title: String, action: @escaping () -> Void) -> some View {
    Button(action: action) {
        Text(title)
            .font(.headline)
            .padding(.horizontal, 14)
            .padding(.vertical, 12)
            .background(Color.blue)
            .foregroundColor(.white)
            .cornerRadius(10)
    }
}
}

```

#### Output

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/hls_qs_ios_meeting_view_with_controls_1.png' style={{height: '500px'}}/>

</center>


### Step 8: Extending Meeting Event Listeners


In this step, we extend the `MeetingEventListener` implementation in `MeetingViewController` by adding additional event listeners for enhanced meeting functionality.
These include `onParticipantJoined` and `onParticipantLeft` to handle participant updates, `onMeetingStateChanged` to manage meeting state transitions, and `onHlsStateChanged` to track HLS state, allowing us to utilize them as needed.

**Swift:**

```js title="MeetingViewController.swift"

class MeetingViewController: ObservableObject {
//...
 extension MeetingViewController: MeetingEventListener {
//...
//highlight-start
func onParticipantJoined(_ participant: Participant) {
    let isExist = participants.first { $0.id == participant.id } != nil
    if (!isExist && (participant.mode != .SIGNALLING_ONLY && participant.mode != .VIEWER)) {
        participants.append(participant)
    }
    // add listener
    participant.addEventListener(self)
}

func onParticipantLeft(_ participant: Participant) {
    participants = participants.filter({ $0.id != participant.id })
}

func onMeetingStateChanged(meetingState: MeetingState) {
    switch meetingState {
    case .DISCONNECTED:
            participants.removeAll()
        default:
        print("meeting state: \(meetingState.rawValue)")
    }
}

func onHlsStateChanged(state: HLSState, hlsUrl: HLSUrl?) {
    hlsState = state
    switch (state) {
    case .HLS_PLAYABLE:
        playbackURL = hlsUrl?.playbackHlsUrl ?? ""
    default:
        print("HLS State: \(state.rawValue)")
    }
}
//highlight-end
 }
//...
}

```

#### Output

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/hls_qs_ios_meeting_view_with_controls_2.png' style={{height: '500px'}}/>

</center>


## Final Output

We are done with implementation of HLS Live Streaming in iOS Appplication using Video SDK. To explore more features go through Basic and Advanced features.


<div style={{textAlign: 'center'}}>



</div>

:::tip

Stuck anywhere? Check out this [example code](https://github.com/videosdk-live/quickstart/tree/main/ios-hls) on GitHub

:::


---

# Quick Start for Interactive Live Streaming in iOS

**VideoSDK** empowers you to seamlessly integrate **interactive live streaming** features into your iOS application in minutes. While built for meetings, the SDK is easily adaptable for live streaming with support for up to **100 hosts/co-hosts** and **2,000 viewers** in **real-time**. Perfect for social use cases, this guide will walk you through integrating live streaming into your app.

### Prerequisites

- iOS 13.0+
- Xcode 15.0+
- Swift 5.0+

### App Architecture

The application consists of two primary interfaces:

1. `Join Stream View`

- Allows users to create a new Live Stream or join an existing one with a stream ID and select their mode (Host or Audience)

2. `Live Stream View`

- Provides Live Stream controls and adapts the UI dynamically based on the user's mode (Host or Audience).

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ils_qs_ios_app_architecture.png' />

</center>

### Getting Started With the Code!

### Step 1: Create New iOS Application


`Step 1:` Create a new application by selecting `Create a new Xcode project`

`Step 2:` Add **Product Name** and Save the project.

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ils_qs_ios_project_creation.png' style={{height: '600px'}}/>

</center>


### Step 2: VideoSDK Installation


There are two ways to install VideoSDK: Using Swift Package Manager (SPM) or Using CocoaPods.

**1. Install Using Swift Package Manager (SPM)**

To install VideoSDK via Swift Package Manager, follow these steps:

1. Open your Xcode project and go to File > Add Packages.
2. Enter the repository URL:

```js
  https://github.com/videosdk-live/videosdk-rtc-ios-spm
```

3. Choose the version rule (e.g., "Up to Next Major") and add the package to your target.
4. Import the library in Swift files:

```js
import VideoSDKRTC
```

For more details, refer to the official guide on [SPM installation](/ios/guide/video-and-audio-calling-api-sdk/ios-sdk-spm).

**2. Install Using CocoaPods**

To install VideoSDK using CocoaPods, follow these steps:

1. Initialize CocoaPods: Run the following command in your project directory:

```js
pod init
```

2. Update the Podfile: Open the Podfile and add the VideoSDK dependency:

```js
pod 'VideoSDKRTC', :git => 'https://github.com/videosdk-live/videosdk-rtc-ios-sdk.git'
```

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ils_qs_pod_ios.png' style={{height: '500px'}}/>

</center>

3. Install the Pod: Run the following command to install the pod:

```js
pod install
```

For more details, refer to the official guide on [CocoaPods installation](/ios/guide/video-and-audio-calling-api-sdk/ios-sdk).

then declare the permissions in Info.plist :

```js
<key>NSCameraUsageDescription</key>
<string>Camera permission description</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone permission description</string>
```


### Step 3: Project Structure


```js
quick-start-videosdk-lis
   ├── quick-start-videosdk-lis.swift // Default
   ├── Screens
		├── JoinStreamView
	            └── JoinStreamView.swift
        ├── LiveStreamView
	            └── LiveStreamView.swift
                └── LiveStreamViewController.swift
   └── Info.plist // Default
 Pods
	 └── Podfile
```


### Step 4: Create JoinStream View


The `JoinStreamView` acts as the entry point for users to initiate or participate in Live Streams with the following functionalities:

- **Create Live Stream as Host**: Start a new Live Stream in `SEND_AND_RECV` mode, providing full host privileges.

- **Join as Host**: Enter an existing Live Stream using a stream ID with `SEND_AND_RECV` mode, granting full host controls.

- **Join as Audience**: Join an existing Live Stream using a stream ID with `RECV_ONLY` mode, offering view-only access.



**Swift:**

```js title="JoinStreamView.swift"
import SwiftUI

struct JoinStreamView: View {
@State var streamId: String
@State var name: String

var body: some View {
    NavigationView {
        ZStack {
            // Background gradient
            LinearGradient(colors: [.blue.opacity(0.1), .white],
                         startPoint: .topLeading,
                         endPoint: .bottomTrailing)
                .ignoresSafeArea()

            VStack(spacing: 24) {
                Text("VideoSDK")
                    .font(.largeTitle)
                    .fontWeight(.bold)
                    .padding(.top,80)

                Text("ILS - QuickStart")
                    .font(.title)
                    .fontWeight(.semibold)
                    .padding(.bottom,50)

                // Create Room Button
                HStack {
                    NavigationLink(
                        destination: LiveStreamView(userName: name ?? "Gust", mode: .SEND_AND_RECV)
                            .navigationBarBackButtonHidden(true)
                    ) {
                        ActionButton(title: "Create Live Stream", icon: "plus.circle.fill")
                    }
                    .padding(.horizontal)
                }

                // Stream ID input
                HStack {

                    TextField("Enter StreamId", text: $streamId)
                        .textFieldStyle(.plain)
                        .autocorrectionDisabled()

                    if !streamId.isEmpty {
                        Button(action: { streamId = "" }) {
                            Image(systemName: "xmark.circle.fill")
                                .foregroundColor(.gray)
                        }
                    }
                }
                .padding()
                .background(
                    RoundedRectangle(cornerRadius: 12)
                        .fill(.white)
                        .shadow(color: .black.opacity(0.1), radius: 5)
                )
                .padding(.horizontal)

                // Buttons Stack
                VStack(spacing: 16) {

                    HStack(spacing: 16) {
                        NavigationLink(destination: {
                            if !streamId.isEmpty {
                                LiveStreamView(streamId: streamId,
                                          userName: name ?? "Guest",
                                                 mode: mode)
                                    .navigationBarBackButtonHidden(true)
                            }
                        }) {
                            ActionButton(title: "Join As Host", icon: "person.fill")
                                .opacity(streamId.isEmpty ? 0.6 : 1)
                        }
                        .disabled(streamId.isEmpty)

                        NavigationLink(
                            destination: LiveStreamView(
                                streamId: streamId,
                                userName: name.isEmpty ? "Guest" : name,
                                mode: .RECV_ONLY
                            )
                            .navigationBarBackButtonHidden(true)
                        ) {
                            ActionButton(title: "Join As Audience", icon: "person.2.fill")
                                .opacity(streamId.isEmpty ? 0.6 : 1)
                        }
                        .disabled(streamId.isEmpty)
                    }
                }
                .padding(.horizontal)

                Spacer()
            }
        }
    }
}
}

struct ActionButton: View {
let title: String
let icon: String

var body: some View {
    HStack {
        Image(systemName: icon)
            .frame(width: 24, height: 24)
        Text(title)
            .font(.system(size: 16))
            .fontWeight(.medium)
            .multilineTextAlignment(.center)
            .lineLimit(2)
    }
    .frame(maxWidth: .infinity, minHeight: 60)
    .padding(.horizontal)
    .background(
        RoundedRectangle(cornerRadius: 12)
            .fill(Color.blue)
    )
    .foregroundColor(.white)
}
}
```

#### Output

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ils_qs_ios_join_stream_view.jpg' style={{height: '500px'}}/>

</center>

Also add the `JoinStreamView` in main app as shown below

**Swift:**

```js title="quick_start_videosdk_lis.swift"
import SwiftUI

@main
struct quick_start_videosdk_lis: App {
var body: some Scene {
    WindowGroup {
        JoinStreamView(streamId: "", name: "")
    }
}
}
```

Before proceeding, let's understand the two modes of a Live Stream:

###### 1. SEND_AND_RECV (For Host or Co-host):

- Designed primarily for the Host or Co-host.
- Allows sending and receiving media.
- Hosts can broadcast their audio/video and interact directly with the audience.

###### 2. RECV_ONLY (For Audience):

- Tailored for the Audience.
- Enables receiving media shared by the Host.
- Audience members can view and listen but cannot share their own media.

<div style={{textAlign: 'center'}}>
<img
  src="https://cdn.videosdk.live/website-resources/docs-resources/ils_mode_demonstration-compressed.jpg"
  alt="ILS Mode Demonstration"
  width="550"
  height="450"
/>
</div>


### Step 5: Initialize and Join the Live Stream


In this step, Inside `LiveStreamViewController` we will setup `initializeStream` and related functions for it. You will require **Auth token**, you can generate it using either using [videosdk-server-api-example](https://github.com/videosdk-live/videosdk-rtc-api-server-examples) or generate it from the [Video SDK Dashboard](https://app.videosdk.live/api-keys) for developer.

`LiveStreamViewController` will implement various event listeners such as `MeetingEventListener`, `ParticipantEventListener`.

**Swift:**

```js title="LiveStreamViewController.swift"

import Foundation
import VideoSDKRTC

struct RoomStruct: Codable {
let roomID: String?

enum CodingKeys: String, CodingKey {
    case roomID = "roomId"
}
}

class LiveStreamViewController: ObservableObject {

var token = "YOUR_TOKEN"
var streamId: String = ""
var name: String = ""

@Published var meeting: Meeting? = nil
@Published var localParticipantView: VideoView? = nil
@Published var videoTrack: RTCVideoTrack?
@Published var participants: [Participant] = []
@Published var streamID: String = ""

func initializeStream(streamId: String, userName: String, mode: Mode) {
    meeting = VideoSDK.initMeeting(
        meetingId: streamId,
        participantName: userName,
        micEnabled: true,
        webcamEnabled: true,
        mode: mode // Pass the mode here
    )
    // Join the stream
    meeting?.join()
    // Add event listeners
    meeting?.addEventListener(self)
}
}

extension LiveStreamViewController: MeetingEventListener {

func onMeetingJoined() {
    guard let localParticipant = self.meeting?.localParticipant else { return }
    // add to list
    participants.append(localParticipant)
    // add event listener
    localParticipant.addEventListener(self)
}

func onMeetingLeft() {
    meeting?.localParticipant.removeEventListener(self)
    meeting?.removeEventListener(self)
}

}
extension LiveStreamViewController: ParticipantEventListener {
func onStreamEnabled(_ stream: MediaStream, forParticipant participant: Participant) {
    if participant.isLocal   {
        if let track = stream.track as? RTCVideoTrack {
            DispatchQueue.main.async {
                self.videoTrack = track
            }
        }
    } else {
        if let track = stream.track as? RTCVideoTrack {
            DispatchQueue.main.async {
                self.videoTrack = track
            }
        }
    }
}

func onStreamDisabled(_ stream: MediaStream, forParticipant participant: Participant) {

    if participant.isLocal {
        if let _ = stream.track as? RTCVideoTrack {
            DispatchQueue.main.async {
                self.videoTrack = nil
            }
        }
    } else {
        self.videoTrack = nil
    }
}
}
extension LiveStreamViewController {
// create a new stream id
func joinRoom(userName: String, mode: Mode) {

    let urlString = "https://api.videosdk.live/v2/rooms"
    let session = URLSession.shared
    let url = URL(string: urlString)!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.addValue(self.token, forHTTPHeaderField: "Authorization")

    session.dataTask(with: request, completionHandler: { (data: Data?, response: URLResponse?, error: Error?) in

        if let data = data, let utf8Text = String(data: data, encoding: .utf8)
        {
            print("UTF =>=>\(utf8Text)") // original server data as UTF8 string
            do{
                let dataArray = try JSONDecoder().decode(RoomStruct.self,from: data)
                DispatchQueue.main.async {
                    print(dataArray.roomID)
                    self.streamID = dataArray.roomID!
                    self.joinStream(streamId: dataArray.roomID!, userName: userName,mode: mode)
                }
                print(dataArray)
            } catch {
                print(error)
            }
        }
    }
    ).resume()
}

// initialise a stream with give stream id (either new or existing)
func joinStream(streamId: String, userName: String, mode: Mode) {

    if !token.isEmpty {
        // use provided token for the stream
        self.streamID = streamId
        self.initializeStream(streamId: streamId, userName: userName, mode: mode)
    }
    else {
        print("Auth token required")
    }
}
}
```


### Step 6: Create LiveStream View


The `LiveStreamView` file manages the live streaming interface and adapts to the user's role.

**Swift:**

```js title="LiveStreamView.swift"

import SwiftUI
import VideoSDKRTC
import WebRTC

struct LiveStreamView: View {
@Environment(\.presentationMode) var presentationMode
@ObservedObject var liveStreamViewController = LiveStreamViewController()

@State var streamId: String?
@State var userName: String?
@State var isUnMute: Bool = true
@State var camEnabled: Bool = true
@State private var currentMode: Mode

init(streamId: String? = nil, userName: String? = nil, mode: Mode) {
    self.streamId = streamId
    self.userName = userName
    self._currentMode = State(initialValue: mode)
}

 private var isAudienceMode: Bool {
    // Derive audience mode from the current participant's mode
    if let localParticipant = liveStreamViewController.participants.first(where: { $0.isLocal }) {
        return localParticipant.mode == .RECV_ONLY
    }
    return currentMode == .RECV_ONLY
}

var body: some View {
    VStack {
        if liveStreamViewController.participants.isEmpty {
            Text("Stream Initializing")
        } else {
            VStack {
                // Stream ID Tile
                HStack {
                    Text("Stream ID: \(liveStreamViewController.streamID)")
                        .padding(.vertical)

                    Button(action: {
                        UIPasteboard.general.string = liveStreamViewController.streamID
                    }) {
                        Image(systemName: "doc.on.doc")
                            .foregroundColor(.blue)
                    }
                }

                // Participant List
                List {
                    ForEach(liveStreamViewController.participants.indices, id: \.self) { index in
                        let participant = liveStreamViewController.participants[index]
                        if participant.mode != .RECV_ONLY {
                            Text("Participant Name: \(participant.displayName)")
                            ZStack {
                                ParticipantView(track: participant.streams.first(where: { $1.kind == .state(value: .video) })?.value.track as? RTCVideoTrack)
                                    .frame(height: 250)
                                if participant.streams.first(where: { $1.kind == .state(value: .video) }) == nil {
                                    Color.white.opacity(1.0)
                                        .frame(width: UIScreen.main.bounds.width, height: 250)
                                    Text("No media")
                                }
                            }
                        }
                    }
                }
            }
        }
    }
    .onAppear {
        VideoSDK.config(token: liveStreamViewController.token)
        if let streamId = streamId, !streamId.isEmpty {
            liveStreamViewController.joinStream(streamId: streamId, userName: userName ?? "Guest", mode: currentMode)
        } else {
            liveStreamViewController.joinRoom(userName: userName ?? "Guest")
        }
    }
}
}

/// VideoView for participant's video
class VideoView: UIView {

var videoView: RTCMTLVideoView = {
    let view = RTCMTLVideoView()
    view.videoContentMode = .scaleAspectFill
    view.backgroundColor = UIColor.black
    view.clipsToBounds = true
    view.frame = CGRect(x: 0, y: 0, width: UIScreen.main.bounds.width, height: 250)

    return view
}()

init(track: RTCVideoTrack?) {
    super.init(frame: CGRect(x: 0, y: 0, width: UIScreen.main.bounds.width, height: 250))
    backgroundColor = .clear
    DispatchQueue.main.async {
        self.addSubview(self.videoView)
        self.bringSubviewToFront(self.videoView)
        track?.add(self.videoView)
    }
}

required init?(coder: NSCoder) {
    fatalError("init(coder:) has not been implemented")
}
}

/// ParticipantView for showing and hiding VideoView
struct ParticipantView: UIViewRepresentable {
var track: RTCVideoTrack?

func makeUIView(context: Context) -> VideoView {
    let view = VideoView(track: track)
    view.frame = CGRect(x: 0, y: 0, width: 250, height: 250)
    return view
}

func updateUIView(_ uiView: VideoView, context: Context) {
    if track != nil {
        track?.add(uiView.videoView)
    } else {
        track?.remove(uiView.videoView)
    }
}
}
```

#### Output

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ils_qs_ios_live_stream_view-3.jpg' style={{height: '500px'}}/>

</center>


### Step 7: Implementing Media Toggles and Mode Switch


**Media Control Buttons**: Include buttons to toggle the microphone and webcam, allowing users to mute/unmute their microphone and enable/disable their camera or leave the session entirely.

**Mode Switching**: User can switch between "Host" and "Audience" modes.

**Swift:**

```js title="LiveStreamViewController.swift"

struct LiveStreamView: View {

var body: some View {
    VStack {
        if liveStreamViewController.participants.isEmpty {
            Text("Stream Initializing")
        } else {
            VStack {
                // ... other code for displaying participants
                //highlight-start
                // Media Control Buttons
                if !isAudienceMode {
                    HStack(spacing: 15) {
                        // Button to toggle microphone mute/unmute
                        Button {
                            isUnMute.toggle()
                            if isUnMute {
                                liveStreamViewController.meeting?.unmuteMic()
                            } else {
                                liveStreamViewController.meeting?.muteMic()
                            }
                        } label: {
                            ModeButton(
                                text: isUnMute ? "Mute Mic" : "Unmute Mic",
                                color: .blue
                            )
                        }

                        // Button to enable/disable webcam
                        Button {
                            camEnabled.toggle()
                            if camEnabled {
                                liveStreamViewController.meeting?.enableWebcam()
                            } else {
                                liveStreamViewController.meeting?.disableWebcam()
                            }
                        } label: {
                            ModeButton(
                                text: camEnabled ? "Disable Webcam" : "Enable Webcam",
                                color: .blue
                            )
                        }
                    }
                }

                // Mode Control Buttons for switching modes
                HStack(spacing: 15) {
                    // Button to leave the call
                    Button {
                        liveStreamViewController.meeting?.leave()
                        presentationMode.wrappedValue.dismiss()
                    } label: {
                        ModeButton(text: "Leave Call", color: .red)
                    }

                    // Button to switch between audience and host modes
                    Button {
                        let newMode: Mode = isAudienceMode ? .SEND_AND_RECV : .RECV_ONLY
                        liveStreamViewController.meeting?.changeMode(newMode)
                        currentMode = newMode
                    } label: {
                        ModeButton(
                            text: isAudienceMode ? "Switch to Host" : "Switch to Audience",
                            color: .indigo
                        )
                    }
                }
                //highlight-end
            }
        }
    }
    .onAppear {
        // code to handle view appearing
    }
}
}

// Helper View for consistent button styling
struct ModeButton: View {
let text: String
let color: Color

var body: some View {
    Text(text)
        .foregroundStyle(Color.white)
        .font(.caption)
        .padding()
        .background(
            RoundedRectangle(cornerRadius: 25)
                .fill(color)
        )
}
}

```

#### Output

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ils_qs_ios_live_stream_view-4.jpeg' style={{height: '500px'}}/>

</center>


### Step 8: Extending Meeting Event Listeners


In this step, we extend the `MeetingEventListener` implementation in `LiveStreamViewController` by adding additional event listeners for enhanced meeting functionality.
These include `onParticipantJoined` and `onParticipantLeft` to handle participant updates, `onMeetingStateChanged` to manage meeting state transitions, and `onParticipantModeChanged` to track participant modes, allowing us to utilize them as needed.

**Swift:**

```js title="LiveStreamViewController.swift"

class LiveStreamViewController: ObservableObject {
//...
 //highlight-start
  private var needsRefresh = false
  //highlight-end
//..
 extension LiveStreamViewController: MeetingEventListener {
//...
//highlight-start
func onParticipantJoined(_ participant: Participant) {

    participants.append(participant)

    // add listener
    participant.addEventListener(self)

    participant.setQuality(.high)
}

func onParticipantLeft(_ participant: Participant) {
    participants = participants.filter({ $0.id != participant.id })
}

func onMeetingStateChanged(meetingState: MeetingState) {
    switch meetingState {

    case .CLOSED:
        participants.removeAll()

    default:
        print("")
    }
}
func onParticipantModeChanged(participantId: String, mode: Mode) {
    DispatchQueue.main.async { [weak self] in
        if var currentParticipants = self?.participants {
            // Find and update the participant whose mode changed
            if let index = currentParticipants.firstIndex(where: { $0.id == participantId }) {
                currentParticipants[index].mode = mode
                // Update the published array to trigger refresh
                self?.participants = currentParticipants
            }
        }
    }
}
//highlight-end
 }
//...
}

```

#### Output

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ils_qs_ios_live_stream_view-2.jpg' style={{height: '500px'}}/>

</center>


## Final Output

We are done with implementation of Interactive Live Streaming in iOS Appplication using Video SDK. To explore more features go through Basic and Advanced features.


<div style={{textAlign: 'center'}}>



</div>

:::tip

Stuck anywhere? Check out this [example code](https://github.com/videosdk-live/quickstart/tree/main/interactive-live-streaming/ios-ils) on GitHub

:::


---

# Quick Start for Conference in iOS using SwiftUI

VideoSDK enables the opportunity to integrate video & audio calling to Web, Android, iOS applications. It provides Programmable SDKs and REST APIs to build scalable video conferencing applications.

This guide will get you running with the VideoSDK video & audio calling in minutes.

### Prerequisites

- iOS 11.0+
- Xcode 12.0+
- Swift 5.0+

### App Architecture

This App will contain two screen :

1. `Join Screen` : This screen allows user to either create meeting or join predefined meeting.

2. `Meeting Screen` : This screen basically contain local and remote participant view and some meeting controls such as Enable / Disable Mic & Camera, Screen Sharing and Leave meeting.

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/swiftui-quickstart.png' />

</center>

## Getting Started With the Code!

### Step 1: Create App


`Step 1:` Create a new application by selecting `Create a new Xcode project`

`Step 2:` Choose **App** then click Next

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ios_quickstart_app_selection.png' style={{height: '600px'}}/>

</center>

`Step 3:` Add **Product Name** and Save the project.

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/swiftui-quickstart2.png' style={{height: '600px'}}/>

</center>


### Step 2: VideoSDK Installation


To install VideoSDK, you must initialise the pod on the project by running the following command.

```js
pod init
```

It will create the Podfile in your project folder, open that file and add the dependency for the VideoSDK like below:

```js
pod 'VideoSDKRTC', :git => 'https://github.com/videosdk-live/videosdk-rtc-ios-sdk.git'
```

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ios_quickstart_podfile.png' style={{height: '500px'}}/>

</center>

then run the below code to install the pod:

```js
pod install
```

then declare the permissions in Info.plist :

```js
<key>NSCameraUsageDescription</key>
<string>Camera permission description</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone permission description</string>
```


### Step 3: Project Structure


```js
iOSQuickStartDemo
   ├── iOSQuickStartDemo.swift // Default
   ├── Screens
		├── JoinScreenView
	            └── JoinScreenView.swift
        ├── MeetingView
	            └── MeetingView.swift
                └── MeetingViewController.swift
   ├── RoomStruct.swift
   └── Info.plist // Default
 Pods
	 └── Podfile
```


### Step 4: Create Models


Create swift file for `RoomStruct` class model for setting data in object pattern.



**Swift:**

```js title="RoomStruct.swift"
struct RoomsStruct: Codable {
let createdAt, updatedAt, roomID: String?
let links: Links?
let id: String?

enum CodingKeys: String, CodingKey {
    case createdAt, updatedAt
    case roomID = "roomId"
    case links, id
}
}

struct Links: Codable {
let getRoom, getSession: String?

enum CodingKeys: String, CodingKey {
    case getRoom = "get_room"
    case getSession = "get_session"
}
}
```


### Step 5: Create JoinScreen View


We will create a joining screen that will act as our main screen. Create a new Swift UI file and paste the following code.

**Swift:**

```js title="JoinScreenView.swift"
import SwiftUI

struct JoinScreenView: View {

// State variables for
@State var meetingId: String
@State var name: String

var body: some View {

        NavigationView {

            VStack {

                Text("VideoSDK")
                    .font(.largeTitle)
                    .fontWeight(.bold)
                Text("Swift UI Quickstart")
                    .font(.largeTitle)
                    .fontWeight(.semibold)
                    .padding(.bottom)

                TextField("Enter MeetingId", text: $meetingId)
                    .foregroundColor(Color.black)
                    .autocorrectionDisabled()
                    .font(.headline)
                    .overlay(
                    Image(systemName: "xmark.circle.fill")
                        .padding()
                        .offset(x: 10)
                        .foregroundColor(Color.gray)
                        .opacity(meetingId.isEmpty ? 0.0 : 1.0)
                        .onTapGesture {
                            UIApplication.shared.endEditing()
                            meetingId = ""
                        }
                    , alignment: .trailing)
                    .padding()
                    .background(
                        RoundedRectangle(cornerRadius: 25)
                            .fill(Color.secondary.opacity(0.5))
                            .shadow(color: Color.gray.opacity(0.10), radius: 10))
                    .padding(.leading)
                    .padding(.trailing)

                Text("Enter Meeting Id to join an existing meeting")

                TextField("Enter Your Name", text: $name)
                    .foregroundColor(Color.black)
                    .autocorrectionDisabled()
                    .font(.headline)
                    .overlay(
                    Image(systemName: "xmark.circle.fill")
                        .padding()
                        .offset(x: 10)
                        .foregroundColor(Color.gray)
                        .opacity(name.isEmpty ? 0.0 : 1.0)
                        .onTapGesture {
                            UIApplication.shared.endEditing()
                            name = ""
                        }
                    , alignment: .trailing)
                    .padding()
                    .background(
                        RoundedRectangle(cornerRadius: 25)
                            .fill(Color.secondary.opacity(0.5))
                            .shadow(color: Color.gray.opacity(0.10), radius: 10))
                    .padding()

                if meetingId.isEmpty == false {
                    NavigationLink(destination:{
                        if meetingId.isEmpty == false {
                            MeetingView(meetingId: self.meetingId, userName: name ?? "Guest")
                                .navigationBarBackButtonHidden(true)
                        } else {
                        }
                    }) {
                        Text("Join Meeting")
                            .foregroundColor(Color.white)
                            .padding()
                            .background(
                                RoundedRectangle(cornerRadius: 25.0)
                                    .fill(Color.blue))                    }
                }

                NavigationLink(destination: MeetingView(userName: name ?? "Guest")
                    .navigationBarBackButtonHidden(true)) {
                    Text("Start Meeting")
                        .foregroundColor(Color.white)
                        .padding()
                        .background(
                            RoundedRectangle(cornerRadius: 25.0)
                                .fill(Color.blue))                    }
            }
        }
    }
}

// preview to show screen into your canvas
#Preview {
JoinScreenView(meetingId: "", name: "")
}

extension UIApplication {

func endEditing() {
    sendAction(#selector(UIResponder.resignFirstResponder), to: nil, from: nil, for: nil)
}
}
```

Also add the `JoinScreenView` in main app as shown below

**Swift:**

```js title="iOSQuickStartDemo.swift"
import SwiftUI

@main
struct iOSQuickStartDemo: App {
var body: some Scene {
    WindowGroup {
        JoinScreenView(meetingId: "", name: "")
    }
}
}
```


### Step 6: Create Meeting View


Create a view for the meeting screen.

`MeetingView` will implement the main meeting screen and the control buttons for the local participant.

**Swift:**

```js title="MeetingView.swift"
import SwiftUI
import VideoSDKRTC
import WebRTC

struct MeetingView: View{

@Environment(\.presentationMode) var presentationMode

// instance of MeetingViewController which we will implement in next step
@ObservedObject var meetingViewController = MeetingViewController()
// Variables for keeping the state of various controls
 @State var meetingId: String?
 @State var userName: String?
 @State var isUnMute: Bool = true
 @State var camEnabled: Bool = true
 @State var isScreenShare: Bool = false

var body: some View {

    VStack {
        if meetingViewController.participants.count == 0 {
            Text("Meeting Initializing")
        } else {
            VStack {
                VStack(spacing: 20) {
                    Text("Meeting ID: \(meetingViewController.meetingID)")
                        .padding(.vertical)

                        List {
                            ForEach(meetingViewController.participants.indices, id: \.self) { index in
                                Text("Participant Name: \(meetingViewController.participants[index].displayName)")
                                ZStack {
                                    ParticipantView(track: meetingViewController.participants[index].streams.first(where: { $1.kind == .state(value: .video) })?.value.track as? RTCVideoTrack).frame(height: 250)
                                    if meetingViewController.participants[index].streams.first(where: { $1.kind == .state(value: .video) }) == nil {
                                        Color.white.opacity(1.0).frame(width: UIScreen.main.bounds.width, height: 250)
                                        Text("No media")
                                    }
                                }
                            }
                        }
                }

                VStack {
                    HStack(spacing: 15) {
                        // mic button
                        Button {
                            if isUnMute {
                                isUnMute = false
                                meetingViewController.meeting?.muteMic()
                            }
                            else {
                                isUnMute = true
                                meetingViewController.meeting?.unmuteMic()
                            }
                        } label: {
                            Text("Toggle Mic")
                                .foregroundStyle(Color.white)
                                .font(.caption)
                                .padding()
                                .background(
                                    RoundedRectangle(cornerRadius: 25)
                                        .fill(Color.blue))
                        }
                        // camera button
                        Button {
                            if camEnabled {
                                camEnabled = false
                                meetingViewController.meeting?.disableWebcam()
                            }
                            else {
                                camEnabled = true
                                meetingViewController.meeting?.enableWebcam()
                            }
                        } label: {
                            Text("Toggle WebCam")
                                .foregroundStyle(Color.white)
                                .font(.caption)
                                .padding()
                                .background(
                                    RoundedRectangle(cornerRadius: 25)
                                        .fill(Color.blue))
                        }
                    }
                    HStack{
                        // screenshare button (OPTIONAL)
                        Button {
                            if isScreenShare {
                                isScreenShare = false
                                Task {
                                    await meetingViewController.meeting?.disableScreenShare()
                                }
                            }
                            else {
                                isScreenShare = true
                                Task {
                                    await meetingViewController.meeting?.enableScreenShare()
                                }
                            }
                        } label: {
                            Text("Toggle ScreenShare")
                                .foregroundStyle(Color.white)
                                .font(.caption)
                                .padding()
                                .background(
                                    RoundedRectangle(cornerRadius: 25)
                                        .fill(Color.blue))
                        }

                        // end meeting button
                        Button {
                            meetingViewController.meeting?.end()
                            presentationMode.wrappedValue.dismiss()
                        } label: {
                            Text("End Call")
                                .foregroundStyle(Color.white)
                                .font(.caption)
                                .padding()
                                .background(
                                    RoundedRectangle(cornerRadius: 25)
                                        .fill(Color.red))
                        }
                    }
                    .padding(.bottom)
                }
            }
        }
    }.onAppear() {
        /// MARK :- configuring the videoSDK
        VideoSDK.config(token: meetingViewController.token)
        if meetingId?.isEmpty == false {
            // join an existing meeting with provided meeting Id
            meetingViewController.joinMeeting(meetingId: meetingId!, userName: userName!)
        }
        else {
            // create a new meeting
            meetingViewController.joinRoom(userName: userName!)
        }
    }
}
}

/// VideoView for participant's video
class VideoView: UIView {

var videoView: RTCMTLVideoView = {
    let view = RTCMTLVideoView()
    view.videoContentMode = .scaleAspectFill
    view.backgroundColor = UIColor.black
    view.clipsToBounds = true
    view.frame = CGRect(x: 0, y: 0, width: UIScreen.main.bounds.width, height: 250)

    return view
}()

init(track: RTCVideoTrack?) {
    super.init(frame: CGRect(x: 0, y: 0, width: UIScreen.main.bounds.width, height: 250))
    backgroundColor = .clear
    DispatchQueue.main.async {
        self.addSubview(self.videoView)
        self.bringSubviewToFront(self.videoView)
        track?.add(self.videoView)
    }
}

required init?(coder: NSCoder) {
    fatalError("init(coder:) has not been implemented")
}
}

/// ParticipantView for showing and hiding VideoView
struct ParticipantView: UIViewRepresentable {
var track: RTCVideoTrack?

func makeUIView(context: Context) -> VideoView {
    let view = VideoView(track: track)
    view.frame = CGRect(x: 0, y: 0, width: 250, height: 250)
    return view
}

func updateUIView(_ uiView: VideoView, context: Context) {
    print("ui updated")
    if track != nil {
        track?.add(uiView.videoView)
    } else {
        track?.remove(uiView.videoView)
    }
}
}
```


### Step 7: Implement MeetingViewController


Here, we will write the code for initialising meeting and controls for the same. You will require **Auth token**, you can generate it using either using [videosdk-server-api-example](https://github.com/videosdk-live/videosdk-rtc-api-server-examples) or generate it from the [Video SDK Dashboard](https://app.videosdk.live/api-keys) for developer.

`MeetingViewController` will implement various event listeners such as `MeetingEventListener`, `ParticipantEventListener`.

**Swift:**

```js title="MeetingViewController.swift"
import Foundation
import VideoSDKRTC
import WebRTC

class MeetingViewController: ObservableObject {

var token = "Your_Token"
var meetingId: String = ""
var name: String = ""

@Published var meeting: Meeting? = nil
@Published var localParticipantView: VideoView? = nil
@Published var videoTrack: RTCVideoTrack?
@Published var participants: [Participant] = []
@Published var meetingID: String = ""

func initializeMeeting(meetingId: String, userName: String) {
    meeting = VideoSDK.initMeeting(
        meetingId: meetingId,
        participantName: userName,
        micEnabled: true,
        webcamEnabled: true
    )

    meeting?.addEventListener(self)
    meeting?.join()
}
}

extension MeetingViewController: MeetingEventListener {

func onMeetingJoined() {

    guard let localParticipant = self.meeting?.localParticipant else { return }

    // add to list
    participants.append(localParticipant)

    // add event listener
    localParticipant.addEventListener(self)

    localParticipant.setQuality(.high)
}

func onParticipantJoined(_ participant: Participant) {

    participants.append(participant)

    // add listener
    participant.addEventListener(self)

    participant.setQuality(.high)
}

func onParticipantLeft(_ participant: Participant) {
    participants = participants.filter({ $0.id != participant.id })
}

func onMeetingLeft() {

    meeting?.localParticipant.removeEventListener(self)
    meeting?.removeEventListener(self)
}

func onMeetingStateChanged(meetingState: MeetingState) {
    switch meetingState {

    case .DISCONNECTED:
        participants.removeAll()

    default:
        print("")
    }
}
}

extension MeetingViewController: ParticipantEventListener {
func onStreamEnabled(_ stream: MediaStream, forParticipant participant: Participant) {

    if participant.isLocal {
        if let track = stream.track as? RTCVideoTrack {
            DispatchQueue.main.async {
                self.videoTrack = track
            }
        }
    } else {
        if let track = stream.track as? RTCVideoTrack {
            DispatchQueue.main.async {
                self.videoTrack = track
            }
        }
    }
}

func onStreamDisabled(_ stream: MediaStream, forParticipant participant: Participant) {

    if participant.isLocal {
        if let _ = stream.track as? RTCVideoTrack {
            DispatchQueue.main.async {
                self.videoTrack = nil
            }
        }
    } else {
        self.videoTrack = nil
    }
}
}

extension MeetingViewController {
// create a new meeting id
func joinRoom(userName: String) {

    let urlString = "https://api.videosdk.live/v2/rooms"
    let session = URLSession.shared
    let url = URL(string: urlString)!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.addValue(self.token, forHTTPHeaderField: "Authorization")

    session.dataTask(with: request, completionHandler: { (data: Data?, response: URLResponse?, error: Error?) in

        if let data = data, let utf8Text = String(data: data, encoding: .utf8)
        {
            print("UTF =>=>\(utf8Text)") // original server data as UTF8 string
            do{
                let dataArray = try JSONDecoder().decode(RoomsStruct.self,from: data)
                DispatchQueue.main.async {
                    print(dataArray.roomID)
                    self.meetingID = dataArray.roomID!
                    self.joinMeeting(meetingId: dataArray.roomID!, userName: userName)
                }
                print(dataArray)
            } catch {
                print(error)
            }
        }
    }
    ).resume()
}

// initialise a meeting with give meeting id (either new or existing)
func joinMeeting(meetingId: String, userName: String) {

    if !token.isEmpty {
        // use provided token for the meeting
        self.meetingID = meetingId
        self.initializeMeeting(meetingId: meetingId, userName: userName)
    }
    else {
        print("Auth token required")
    }
}
}
```


### Step 8: Adding Broadcast Extension


To make your app capable of sharing screen, you will need to add broadcast upload extension into you app. Head over to the ScreenShare [guide](/ios/guide/video-and-audio-calling-api-sdk/handling-media/native-ios-screen-share) and follow the given steps to add the screen sharing capability in your app.

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/swiftui-quickstart-output.png' style={{height: '500px'}}/>

</center>


:::tip

Stuck anywhere? Check out this [example code](https://github.com/videosdk-live/videosdk-rtc-ios-sdk-swiftui-example) on GitHub

:::


---

# Quick Start for Conference in iOS

VideoSDK enables the opportunity to integrate video & audio calling to Web, Android, iOS applications. It provides Programmable SDKs and REST APIs to build scalable video conferencing applications.

This guide will get you running with the VideoSDK video & audio calling in minutes.

## Prerequisites

- iOS 11.0+
- Xcode 12.0+
- Swift 5.0+

### App Architecture

This App will contain two screen :

1. `Join Screen` : This screen allows user to either create meeting or join predefined meeting.

2. `Meeting Screen` : This screen basically contain local and remote participant view and some meeting controls such as Enable / Disable Mic & Camera and Leave meeting.

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ios_quickstart_architecture.png' />

</center>

## Getting Started With the Code!

### Step 1: Create App


`Step 1:` Create a new application by selecting `Create a new Xcode project`

`Step 2:` Choose **App** then click Next

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ios_quickstart_app_selection.png' style={{height: '600px'}}/>

</center>

`Step 3:` Add **Product Name** and Save the project.

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ios_quickstart_add_product_name.png' style={{height: '600px'}}/>

</center>


### Step 2: VideoSDK Installation


To install VideoSDK, you must initialise the pod on the project by running the following command.

```js
pod init
```

It will create the Podfile in your project folder, open that file and add the dependency for the VideoSDK like below:

```js
pod 'VideoSDKRTC', :git => 'https://github.com/videosdk-live/videosdk-rtc-ios-sdk.git'
```

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ios_quickstart_podfile.png' style={{height: '500px'}}/>

</center>

then run the below code to install the pod:

```js
pod install
```

then declare the permissions in Info.plist :

```js
<key>NSCameraUsageDescription</key>
<string>Camera permission description</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone permission description</string>
```


### Step 3: Project Structure


```js
iOSQuickStartDemo
   ├── Models
		├── RoomStruct.swift
	    └── MeetingData.swift
   ├── ViewControllers
		├── StartMeetingViewController.swift
	    └── MeetingViewController.swift
   ├── AppDelegate.swift // Default
   ├── SceneDelegate.swift // Default
   └── APIService
		   └── APIService.swift
   ├── Main.storyboard // Default
   ├── LaunchScreen.storyboard // Default
   └── Info.plist // Default
 Pods
	 └── Podfile
```

**Main.storyboard Design**

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ios_quickstart_storyboard.png' style={{height: '600px'}}/>

</center>


### Step 4: Create Models


Create swift file for `MeetingData` and `RoomStruct` class model for setting data in object pattern.



**Swift:**

```js title="MeetingData.swift"
import Foundation
struct MeetingData {
let token: String
let name: String
let meetingId: String
let micEnabled: Bool
let cameraEnabled: Bool
}
```

**Swift:**

```js title="RoomStruct.swift"
import Foundation
struct RoomsStruct: Codable {
let createdAt, updatedAt, roomID: String?
let links: Links?
let id: String?
enum CodingKeys: String, CodingKey {
    case createdAt, updatedAt
    case roomID = "roomId"
    case links, id
}
}
// MARK: - Links
struct Links: Codable {
let getRoom, getSession: String?
enum CodingKeys: String, CodingKey {
    case getRoom = "get_room"
    case getSession = "get_session"
}
}
```


### Step 5: Get Started with APIClient


Before jumping to anything else, we have to write API to generate unique
meetingId. You will require **Auth token**, you can generate it using either
using [videosdk-server-api-example](https://github.com/videosdk-live/videosdk-rtc-api-server-examples) or generate it from the [Video SDK Dashboard](https://app.videosdk.live/api-keys) for developer.

**Swift:**

```js title="APIService.swift"
import Foundation

let TOKEN_STRING: String = "

</center>


### Step 7: Initialize and Join Meeting


Using the provided `token` and `meetingId`, we will configure and initialise the meeting in `viewDidLoad()`.

Then, we'll add **@IBOutlet** for `localParticipantVideoView` and `remoteParticipantVideoView`, which can render local and remote participant media respectively.

**Swift:**

```js title="MeetingViewController.swift"

class MeetingViewController: UIViewController {

import UIKit
import VideoSDKRTC
import WebRTC
import AVFoundation

class MeetingViewController: UIViewController {

// MARK: - Properties
// outlet for local participant container view
@IBOutlet weak var localParticipantViewContainer: UIView!

// outlet for label for meeting Id
@IBOutlet weak var lblMeetingId: UILabel!

// outlet for local participant video view
@IBOutlet weak var localParticipantVideoView: RTCMTLVideoView!

// outlet for remote participant video view
@IBOutlet weak var remoteParticipantVideoView: RTCMTLVideoView!

// outlet for remote participant no media label
@IBOutlet weak var lblRemoteParticipantNoMedia: UILabel!

// outlet for remote participant container view
@IBOutlet weak var remoteParticipantViewContainer: UIView!

// outlet for local participant no media label
@IBOutlet weak var lblLocalParticipantNoMedia: UILabel!

/// Meeting data - required to start
var meetingData: MeetingData!

/// current meeting reference
private var meeting: Meeting?

// MARK: - video participants including self to show in UI
private var participants: [Participant] = []

		// MARK: - Lifecycle Events

		override func viewDidLoad() {
    super.viewDidLoad()
    // configure the VideoSDK with token
    VideoSDK.config(token: meetingData.token)

    // init meeting
    initializeMeeting()

    // set meeting id in button text
    lblMeetingId.text = "Meeting Id: \(meetingData.meetingId)"
	  }

	  override func viewWillAppear(_ animated: Bool) {
   super.viewWillAppear(animated)
   navigationController?.navigationBar.isHidden = true
	  }

override func viewWillDisappear(_ animated: Bool) {
    super.viewWillDisappear(animated)
    navigationController?.navigationBar.isHidden = false
    NotificationCenter.default.removeObserver(self)
}

		// MARK: - Meeting

		private func initializeMeeting() {

  // Initialize the VideoSDK
  meeting = VideoSDK.initMeeting(
      meetingId: meetingData.meetingId,
      participantName: meetingData.name,
      micEnabled: meetingData.micEnabled,
      webcamEnabled: meetingData.cameraEnabled
  )

  // Adding the listener to meeting
  meeting?.addEventListener(self)

  // joining the meeting
  meeting?.join()
		}
}
```


### Step 8: Implement Controls


After initialising the meeting in previous step. We will now add **@IBOutlet** for `btnLeave`, `btnToggleVideo` and `btnToggleMic` which can controls the media in meeting.

**Swift:**

```js title="MeetingViewController.swift"

class MeetingViewController: UIViewController {

//highlight-next-line
...

// outlet for leave button
@IBOutlet weak var btnLeave: UIButton!

// outlet for toggle video button
@IBOutlet weak var btnToggleVideo: UIButton!

// outlet for toggle audio button
@IBOutlet weak var btnToggleMic: UIButton!

// bool for mic
var micEnabled = true
// bool for video
var videoEnabled = true


// outlet for leave button click event
@IBAction func btnLeaveTapped(_ sender: Any) {
        DispatchQueue.main.async {
            self.meeting?.leave()
            self.dismiss(animated: true)
        }
    }

// outlet for toggle mic button click event
@IBAction func btnToggleMicTapped(_ sender: Any) {
    if micEnabled {
        micEnabled = !micEnabled // false
        self.meeting?.muteMic()
    } else {
        micEnabled = !micEnabled // true
        self.meeting?.unmuteMic()
    }
}

// outlet for toggle video button click event
@IBAction func btnToggleVideoTapped(_ sender: Any) {
    if videoEnabled {
        videoEnabled = !videoEnabled // false
        self.meeting?.disableWebcam()
    } else {
        videoEnabled = !videoEnabled // true
        self.meeting?.enableWebcam()
    }
}

  //highlight-next-line
...

}
```

#### Output

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ios_quickstart_loading.png' style={{height: '500px'}}/>

</center>


### Step 9: Implementing MeetingEventListener


In this step, we'll create an extension for the `MeetingViewController` that implements the MeetingEventListener, which implements the `onMeetingJoined`, `onMeetingLeft`, `onParticipantJoined`, `onParticipantLeft`, `onParticipantChanged`, `onSpeakerChanged`, etc. methods.

**Swift:**

```js title="MeetingViewController.swift"

class MeetingViewController: UIViewController {

//highlight-next-line
...

extension MeetingViewController: MeetingEventListener {

		/// Meeting started
		func onMeetingJoined() {

  // handle local participant on start
  guard let localParticipant = self.meeting?.localParticipant else { return }
  // add to list
  participants.append(localParticipant)

  // add event listener
  localParticipant.addEventListener(self)

  localParticipant.setQuality(.high)

  if(localParticipant.isLocal){
      self.localParticipantViewContainer.isHidden = false
  } else {
      self.remoteParticipantViewContainer.isHidden = false
  }
		}

		/// Meeting ended
		func onMeetingLeft() {
  // remove listeners
  meeting?.localParticipant.removeEventListener(self)
  meeting?.removeEventListener(self)
		}

		/// A new participant joined
		func onParticipantJoined(_ participant: Participant) {
  participants.append(participant)

  // add listener
  participant.addEventListener(self)

  participant.setQuality(.high)

  if(participant.isLocal){
      self.localParticipantViewContainer.isHidden = false
  } else {
      self.remoteParticipantViewContainer.isHidden = false
  }
		}

		/// A participant left from the meeting
		/// - Parameter participant: participant object
		func onParticipantLeft(_ participant: Participant) {
  participant.removeEventListener(self)
  guard let index = self.participants.firstIndex(where: { $0.id == participant.id }) else {
      return
  }
  // remove participant from list
  participants.remove(at: index)
  // hide from ui
  UIView.animate(withDuration: 0.5){
      if(!participant.isLocal){
          self.remoteParticipantViewContainer.isHidden = true
      }
  }
		}

		/// Called when speaker is changed
		/// - Parameter participantId: participant id of the speaker, nil when no one is speaking.
		func onSpeakerChanged(participantId: String?) {

  // show indication for active speaker
  if let participant = participants.first(where: { $0.id == participantId }) {
      self.showActiveSpeakerIndicator(participant.isLocal ? localParticipantViewContainer : remoteParticipantViewContainer, true)
  }

  // hide indication for others participants
  let otherParticipants = participants.filter { $0.id != participantId }
  for participant in otherParticipants {
      if participants.count > 1 && participant.isLocal {
          showActiveSpeakerIndicator(localParticipantViewContainer, false)
      } else {
          showActiveSpeakerIndicator(remoteParticipantViewContainer, false)
      }
  }
		}

		func showActiveSpeakerIndicator(_ view: UIView, _ show: Bool) {
  view.layer.borderWidth = 4.0
  view.layer.borderColor = show ? UIColor.blue.cgColor : UIColor.clear.cgColor
		}

}

//highlight-next-line
...

```


### Step 10: Implementing ParticipantEventListener


In this stage, we'll add an extension for the `MeetingViewController` that implements the ParticipantEventListener, which implements the `onStreamEnabled` and `onStreamDisabled` methods for the audio and video of MediaStreams enabled or disabled.

The function `updateUI` is frequently used to control or modify the user interface (enable / disable camera & mic) in accordance with MediaStream state.

**Swift:**

```js title="MeetingViewController.swift"
class MeetingViewController: UIViewController {

//highlight-next-line
...

extension MeetingViewController: ParticipantEventListener {

		/// Participant has enabled mic, video or screenshare
		/// - Parameters:
		///   - stream: enabled stream object
		///   - participant: participant object
		func onStreamEnabled(_ stream: MediaStream, forParticipant participant: Participant) {
  updateUI(participant: participant, forStream: stream, enabled: true)
		}

		/// Participant has disabled mic, video or screenshare
		/// - Parameters:
		///   - stream: disabled stream object
		///   - participant: participant object
		func onStreamDisabled(_ stream: MediaStream, forParticipant participant: Participant) {
  updateUI(participant: participant, forStream: stream, enabled: false)
		}
}

private extension MeetingViewController {

func updateUI(participant: Participant, forStream stream: MediaStream, enabled: Bool) { // true
    switch stream.kind {
    case .state(value: .video):
        if let videotrack = stream.track as? RTCVideoTrack {
            if enabled {
                DispatchQueue.main.async {
                    UIView.animate(withDuration: 0.5){
                        if(participant.isLocal){
                            self.localParticipantViewContainer.isHidden =   false
                            self.localParticipantVideoView.isHidden = false
                            self.localParticipantVideoView.videoContentMode = .scaleAspectFill
                            self.localParticipantViewContainer.bringSubviewToFront(self.localParticipantVideoView)
                            videotrack.add(self.localParticipantVideoView)
                            self.lblLocalParticipantNoMedia.isHidden = true
                        } else {
                            self.remoteParticipantViewContainer.isHidden = false
                            self.remoteParticipantVideoView.isHidden = false
                            self.remoteParticipantVideoView.videoContentMode = .scaleAspectFill
                            self.remoteParticipantViewContainer.bringSubviewToFront(self.remoteParticipantVideoView)
                            videotrack.add(self.remoteParticipantVideoView)
                            self.lblRemoteParticipantNoMedia.isHidden = true
                        }
                    }
                }
            } else {
                UIView.animate(withDuration: 0.5){
                    if(participant.isLocal){
                        self.localParticipantViewContainer.isHidden = false
                        self.localParticipantVideoView.isHidden = true
                        self.lblLocalParticipantNoMedia.isHidden = false
                        videotrack.remove(self.localParticipantVideoView)
                    } else {
                        self.remoteParticipantViewContainer.isHidden = false
                        self.remoteParticipantVideoView.isHidden = true
                        self.lblRemoteParticipantNoMedia.isHidden = false
                        videotrack.remove(self.remoteParticipantVideoView)
                    }
                }
            }
        }

    case .state(value: .audio):
        if participant.isLocal {
            localParticipantViewContainer.layer.borderWidth = 4.0
            localParticipantViewContainer.layer.borderColor = enabled ? UIColor.clear.cgColor : UIColor.red.cgColor
        } else {
            remoteParticipantViewContainer.layer.borderWidth = 4.0
            remoteParticipantViewContainer.layer.borderColor = enabled ? UIColor.clear.cgColor : UIColor.red.cgColor
        }
    default:
        break
    }
}
}

//highlight-next-line
...

```

#### Output

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ios_quickstart_meeting_screen.png' style={{height: '500px'}}/>

</center>


## Known Issue

Please add the following line in the `MeetingViewController.swift` file's `viewDidLoad` method If you get your video out of the container view like below image.

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ios_quickstart_known_issue.png' style={{height: '400px'}}/>

</center>

**Swift:**

```js title="MeetingViewController.swift"
override func viewDidLoad() {

localParticipantVideoView.frame = CGRect(x: 10, y: 0, width: localParticipantViewContainer.frame.width, height: localParticipantViewContainer.frame.height)

localParticipantVideoView.bounds = CGRect(x: 10, y: 0, width: localParticipantViewContainer.frame.width, height: localParticipantViewContainer.frame.height)

localParticipantVideoView.clipsToBounds = true

remoteParticipantVideoView.frame = CGRect(x: 10, y: 0, width: remoteParticipantViewContainer.frame.width, height: remoteParticipantViewContainer.frame.height)
remoteParticipantVideoView.bounds = CGRect(x: 10, y: 0, width: remoteParticipantViewContainer.frame.width, height: remoteParticipantViewContainer.frame.height)
remoteParticipantVideoView.clipsToBounds = true
}

```

:::tip

Stuck anywhere? Check out this [example code](https://github.com/videosdk-live/videosdk-rtc-ios-sdk-example) on GitHub

:::


---

## Understanding Usage Quota Limits - iOS

In this documentation, you will find detailed information about the quotas associated with each plan, including usage limits for various features and functionalities. Understanding these quotas will help you optimize your usage, selecting the best pricing plan and make the most of your VideoSDK experience.

## How VideoSDK limits concurrent usage quota

VideoSDK's approach to limiting usage focuses on concurrent usage rather than overall usage. Concurrent usage refers to the number of participants or requests that can be hosted or processed simultaneously. 

For example, if there's a limit of 50 concurrent participants per organization, users can run multiple calls (sessions) simultaneously, with a maximum of 50 participants across all sessions combined.

## How to view my current plan’s quota limits?

To view the current quota limits on your organization, simply navigate to the [VideoSDK Dashboard](https://app.videosdk.live/), go to your Profile section, and click on the Billing tab.

## Free Plan

Since, we’ve designed Free Plan for developers who are just exploring, we’ve kept the limits that would get you started without a hitch.

Organisations on Free Plan have the following limits on concurrent usage:

| Feature | Concurrent Limit |
| --- | --- |
| Participants in Video Calls | 50 concurrent participants |
| Viewers in Live Streams | 100 concurrent viewers |
| Recording Request | 1 concurrent request at a time |
| HLS Encoding Request | 1 concurrent request at a time |
| RTMP-Out Request | 1 concurrent request at a time |

 
### How to increase my limits?

To increase your limits, simply upgrade your plan by providing billing details and credit card information.

## Pay-as-you-Go Plan

We've increased participant limits for this paid plan. This way, it won't significantly impact users heavily involved in production or integration.

Organisations on Pay-as-you-Go have the following limits on concurrent usage:

| Feature | Concurrent Limit |
| --- | --- |
| Participants in Video Calls | 100 concurrent participants |
| Viewers in Live Streams | 500 concurrent viewers |
| Recording Request | 5 concurrent request at a time |
| HLS Encoding Request | 5 concurrent request at a time |
| RTMP-Out Request | 5 concurrent request at a time |

### How to increase my limits?

To increase your limits further more, simply get in touch with us. [Contact us](https://www.videosdk.live/contact) directly or reach out via email at [support@videosdk.live](mailto:support@videosdk.live), and we'll handle the rest gladly.

## Enterprise Plan

For Enterprise users, all limits are tailored to the specific needs. Customised limits ensure optimal performance for your unique requirements.

To get started as an Enterprise user, simply get in touch with us, explain your requirements and use case, and we’ll customise the quota and limits according to your needs.

## Examples to understand concurrent limits

**Example #1**

Let's say you're using video callings (RTC) in your organization on the Free Plan. In this scenario, you can concurrently host up to 50 participants. However, the number of calls (sessions) you initiate is unrestricted.

To simplify, you can run multiple sessions simultaneously, but concurrently, you can only accommodate a maximum of 50 participants across all sessions. If a 51st participant attempts to join, they won't be able to access the session until you upgrade your plan to increase your participant limits.

**Example #2**

Let’s say you're using live streaming in your organization on the Free Plan. In this setup, you can concurrently host up to 100 viewers joining the sessions. While you have the flexibility to host multiple live streaming sessions, the number of viewers joining session concurrently is restricted.

**Example #3**

Lets say you’re using video callings (RTC) in your organization on the Pay-as-you-Go Plan and you're hosting 5 concurrent calls (sessions), all of which are being recorded. Now, when you initiate the 6th call (session) and request recording, VideoSDK will not process your recording request. Instead, it will throw an error because you've reached your recording request limit.

If you have any questions regarding quota limits and pricing plan, post in our [Discord community](https://discord.com/invite/Qfm8j4YAUJ), [contact us](https://www.videosdk.live/contact) directly, or reach out to us on [support@videosdk.live](mailto:support@videosdk.live).

---

Recording meetings is an essential feature that ensures all important discussions, decisions, and interactions are documented for future reference. VideoSDK offers three types of recordings: Meeting Recording, Participant Recording, and Participant Track Recording. Each type serves a specific purpose to cater to different recording needs during a meeting.

## Meeting Recording

Meeting Recording captures the entire meeting, including all participants, audio, video, and shared content. This comprehensive recording is ideal for reviewing the entire meeting, ensuring that nothing is missed. It provides a holistic view of the meeting, capturing every interaction and piece of information shared during the session.

![Meeting Recording](https://cdn.videosdk.live/website-resources/docs-resources/MeetingRecording.png)

## Participant Recording

Participant Recording focuses on individual participants, capturing both their audio and video into a single file. This type of recording is particularly useful for tracking the contributions of specific participants or for scenarios where detailed analysis of an individual’s participation is needed. When a participant mutes their audio or turns off their video, the recording continues but with silenced audio or a black screen, respectively. This ensures a continuous recording without interruptions, reflecting the participant's involvement throughout the meeting.

![Participant Recording](https://cdn.videosdk.live/website-resources/docs-resources/ParticipantRecording.png)

## Participant Track Recording

Participant Track Recording allows you to record specific tracks of a participant, either audio or video, based on user input. This targeted approach is perfect for capturing particular aspects of a participant’s contribution, such as only their audio or only their video. Multiple files are generated whenever there is a change in the track's status (e.g., starting after being muted ), ensuring focused documentation of each continuous segment. This method is especially useful in scenarios where detailed analysis of specific media (audio or video) is required.

![Participant Track Recording](https://cdn.videosdk.live/website-resources/docs-resources/TrackRecording.png)



---

https://sdk.videosdk.live/js-sdk/0.2.6/videosdk.jsVideoSDK offers a range of video streaming tools and solutions for content creators, publishers, and developers.

- A custom template is a specialized layout for a live stream that allows users to integrate real-time graphics into their broadcasts.

- With custom templates, users can enhance their video content by overlaying graphics, text, images, and animations onto their live streams. These elements can be customized to align with specific branding requirements.

- By leveraging custom templates, users can craft dynamic and engaging video experiences. Whether incorporating live scoreboards, social media feeds, or other personalized elements, users have the flexibility to create visually appealing streams that stand out and capture audience attention.

:::note

Custom templates can also be used with recordings and RTMP service provided by VideoSDK.

:::

### What you can do with Custom Template

By utilizing a custom template, you have the flexibility to create various modes for your live stream. Here are some popular modes that you can design:

- **`PK Host:`** The host can organize a player vs. player battle, as illustrated in the example of a gaming battle shown below.

![pk host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_pk_battle.png)

- **`Watermark:`** The host has the ability to add and update watermarks anywhere in the template; for instance, the image below features a VideoSDK watermark on the top right side of the screen.

![watermark host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_water_mark.png)

- **`News Mode:`** Additionally, the host can incorporate dynamic text in the lower third banner, as demonstrated by the sample text in the bottom left of the screen.

![news mode](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_news_live.png)

### Custom template with VideoSDK

In this section, we will discuss how Custom Templates work with VideoSDK.

- **`Host`**: The host initiates live streaming by providing the `templateURL`. The `templateURL` is the URL of the hosted template webpage. The host is also responsible for managing the template, including tasks such as altering text, logos, and switching template layouts.

- **`VideoSDK Template Engine`** : The VideoSDK Template Engine accepts and opens the templateURL in the browser, actively listening to all events initiated by the Host. It facilitates the customization of the template in accordance with the host's preferences.

- **`Viewer`**: Viewers can stream the content, experiencing the live stream with added real-time graphics. This feature contributes to a distinctive and engaging viewing experience.

![custom template](https://cdn.videosdk.live/website-resources/docs-resources/custom_template.png)

### Understanding Template URL

The template URL is a webpage that VideoSDK Template Engine will open while composing the live stream.

It will appear as shown below.

![template url](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_url.png)

The Template URL comprises of two essential parts:

- Your actual page URL, resembling something like `https://example.com/videosdk-template`.
- Query parameters, designed to enable the VideoSDK Template Engine to seamlessly join the meeting upon opening the URL. There are three key query parameters in total:
  - `token`: Your token, serving as the authentication key to join the meeting.
  - `meetingId`: The meeting Id of the meeting that the VideoSDK Template Engine will join.
  - `participantId`: The participant ID of the VideoSDK Template Engine. This should be included when joining the template engine in your template, ensuring that the template engine participant remains invisible to other participants. **This parameter is automatically added by the VideoSDK**.

:::info

Above mentioned query parameters are mandatory. Apart from these parameters, you can pass any other extra parameters which are required according to your use-case.

:::

### **Creating Template**

**`Step 1:`** Import VideoSDK using `<script>` tag or install it using the below-mentioned npm command.
Make sure you are in your app directory before you run this command.



**Tab:**

" label="<script>" default>

```html
<html>
  <head></head>
  <body>
// highlight-next-line
<script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
  </body>
</html>
```

---

**npm:**

```bash
npm install @videosdk.live/js-sdk
```

---

**yarn:**

```bash
yarn add @videosdk.live/js-sdk
```

:::note

You can use VideoSDK's React or JavaScript SDK to create custom template. Following is the example of building custom template with JavaScript SDK.

:::

###### Structure of the Project

```jsx title="Project Structure"
  root
   ├── index.html
   ├── index.js
```

**`Step 2:`** Craft a user interface (UI) tailored for your live stream presentation.

```html title="index.html"
<!DOCTYPE html>
<html>
  <head> </head>

  <body>
    <div id="textDiv">Starting live stream...</div>

    
    <div class="row" id="videoContainer"></div>

    <script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
    <script src="index.js"></script>
  </body>
</html>
```

**`Step 3:`** Next, fetch the query parameters, from the URL which will be later used to initialize the meeting and get the elements from DOM.

```js title=index.js
const url = window.location;
const urlParams = new URLSearchParams(url.search);

const meetingId = urlParams.get("meetingId");
const token = urlParams.get("token");
const participantId = urlParams.get("participantId");

const videoContainer = document.getElementById("videoContainer");
const textDiv = document.getElementById("textDiv");
```

**`Step 4:`** Subsequently, initialize the meeting with the parameters that were extracted from the URL. Ensure direct initialization so that the template engine seamlessly joins the meeting upon page load.

```js title=index.js
window.VideoSDK.config(token);

const meeting = window.VideoSDK.initMeeting({
  meetingId: meetingId, // required
  name: "recorder", // required
  micEnabled: false,
  webcamEnabled: false,
  participantId: participantId,
});

meeting.join();

meeting.on("meeting-joined", () => {
  textDiv.style.display = "none";
});
```

**`Step 5:`** Next step is to create the container that will render the meeting view on the `participant-joined` event.

```js title=index.js
//  participant joined
meeting.on("participant-joined", (participant) => {
  let videoElement = createVideoElement(
    participant.id,
    participant.displayName
  );
  let audioElement = createAudioElement(participant.id);

  participant.on("stream-enabled", (stream) => {
    setTrack(stream, audioElement, participant, false);
  });
  videoContainer.appendChild(videoElement);
  videoContainer.appendChild(audioElement);
});

// participants left
meeting.on("participant-left", (participant) => {
  let vElement = document.getElementById(`f-${participant.id}`);
  vElement.remove(vElement);

  let aElement = document.getElementById(`a-${participant.id}`);
  aElement.remove(aElement);
});

// creating video element
function createVideoElement(pId, name) {
  let videoFrame = document.createElement("div");
  videoFrame.setAttribute("id", `f-${pId}`);

  //create video
  let videoElement = document.createElement("video");
  videoElement.classList.add("video-frame");
  videoElement.setAttribute("id", `v-${pId}`);
  videoElement.setAttribute("playsinline", true);
  videoElement.setAttribute("width", "300");
  videoElement.muted = true;
  videoFrame.appendChild(videoElement);

  let displayName = document.createElement("div");
  displayName.innerHTML = `Name : ${name}`;
  videoFrame.appendChild(displayName);

  return videoFrame;
}

// creating audio element
function createAudioElement(pId) {
  let audioElement = document.createElement("audio");
  audioElement.setAttribute("autoPlay", "false");
  audioElement.setAttribute("playsInline", "true");
  audioElement.setAttribute("controls", "false");
  audioElement.setAttribute("id", `a-${pId}`);
  audioElement.style.display = "none";
  return audioElement;
}

// setting media track
function setTrack(stream, audioElement, participant, isLocal) {
  if (stream.kind == "video") {
    isWebCamOn = true;
    const mediaStream = new MediaStream();
    mediaStream.addTrack(stream.track);
    let videoElm = document.getElementById(`v-${participant.id}`);
    videoElm.srcObject = mediaStream;
    videoElm
      .play()
      .catch((error) =>
        console.error("videoElem.current.play() failed", error)
      );
  }
  if (stream.kind == "audio") {
    if (isLocal) {
      isMicOn = true;
    } else {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(stream.track);
      audioElement.srcObject = mediaStream;
      audioElement
        .play()
        .catch((error) => console.error("audioElem.play() failed", error));
    }
  }
}
```

**`Step 6:`** Now, listen to PubSub messages from the `CHANGE_BACKGROUND` topic, triggering a change in the meeting's background color accordingly.

:::note

The PubSub mechanism is utilized to communicate with the template. You can learn more about [PubSub from here](/javascript/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

:::

```js title=index.js
meeting.on("meeting-joined", () => {
  //  ...

  meeting.pubSub.subscribe("CHANGE_BACKGROUND", (data) => {
    let { message } = data;
    document.body.style.backgroundColor = message;
  });
});
```

**`Step 7:`** Once tested, you can deploy it using your backend or host it on services like [firebase](https://www.geeksforgeeks.org/how-to-deploy-react-project-on-firebase/) or vercel.

:::tip

You can checkout the github repository for sample custom template [created here](https://github.com/videosdk-live/videosdk-custom-recording-template-js-example).

:::

### Setup Livestream Using Custom Template

- To utilize Custom Templates with Livestream, you need to establish both the Host and Viewer setups. The Host initiates the livestream, while Viewers can watch the broadcast.

![template manager](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_manager.png)

- To understand custom templates, clone this example and run it on your system.

```bash
git clone https://github.com/videosdk-live/videosdk-custom-recording-template-js-example.git
```

- You can utilize this custom template in [Start Recording API](/api-reference/realtime-communication/start-recording), [Start HLS API](/api-reference/realtime-communication/start-hlsStream) and [Start Livestream API](/api-reference/realtime-communication/start-livestream). Here is the example of HLS.
- To utilize the custom template that has been deployed, invoke the [Start HLS API](https://docs.videosdk.live/api-reference/realtime-communication/start-hlsStream) instead of the `startHls` method from the `Meeting` class. The necessary code has already been incorporated in the cloned example above.

:::important

You can create your own custom template manager in JavaScript. In this example, we are using one for better understanding.

:::

```js
<button
  onClick={async () => {
    const url = `https://api.videosdk.live/v2/hls/start`;
    //Update your Custom Template URL here if you have deployed your own, if not deployed you can use this template from our URL.
    //highlight-next-line
    const templateUrl = `https://lab.videosdk.live/js-template-demo/?meetingId=${meetingId}&token=${authToken}`;
    const options = {
      method: "POST",
      headers: {
        Authorization: authToken,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        roomId: meetingId,
        templateUrl: templateUrl,
      }),
    };

    const result = await fetch(url, options)
      .then((response) => response.json()) // result will have playbackHlsUrl and livestreamUrl
      .catch((error) => console.error("error", error));
  }}
>
  Start HLS
</button>
```

- In this example, the host has two options on their side, enabling them to change the background and send messages to the viewers.

- Given below is a test run of the example.


<div style={{textAlign: 'center'}}>



</div>

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)
- [Start HLS API](/api-reference/realtime-communication/start-hlsStream)
- [Start Livestream API](/api-reference/realtime-communication/start-livestream)
- [recordingState](/react/api/sdk-reference/use-meeting/properties#recordingstate)
- [hlsState](/react/api/sdk-reference/use-meeting/properties#hlsstate)
- [livestreamState](/react/api/sdk-reference/use-meeting/properties#livestreamstate)
- [hlsUrls](/react/api/sdk-reference/use-meeting/properties#hlsurls)
- [onRecordingStateChanged](/react/api/sdk-reference/use-meeting/events#onrecordingstatechanged)
- [onHlsStateChanged](/react/api/sdk-reference/use-meeting/events#onhlsstatechanged)
- [onLivestreamStateChanged](/react/api/sdk-reference/use-meeting/events#onlivestreamstatechanged)



---

You have the option to create presigned URL, allowing you to upload your recordings to AWS, Azure, or GCP securely.
presigned URL provide a secure and temporary way to upload objects to your cloud storage. Instead of sharing your entire credentials, you can create a special URL that allows uploading a specific file for a limited time.

:::important

While presigned URL offer a convenient way to upload files securely, each cloud provider (AWS, Azure, and GCP) might have different restrictions on how they work. It's advisable to refer the respective documentation for **[<u>AWS</u>](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)**, **[<u>Azure</u>](https://learn.microsoft.com/en-us/rest/api/storageservices/delegate-access-with-shared-access-signature)**, and **[<u>GCP</u>](https://cloud.google.com/cdn/docs/using-signed-urls)** to gain a clearer understanding of presigned URL.

:::

### Code Sample

This guide will walk you through the process of generating a presigned URL for uploading recordings to your cloud storage of choice. You can use this generated presigned URL in [Start Recording API](/api-reference/realtime-communication/start-recording#preSignedUrl).



**AWS:**

```js
const { S3Client, PutObjectCommand } = require("@aws-sdk/client-s3");
const { getSignedUrl } = require("@aws-sdk/s3-request-presigner");

const region = <YOUR S3 REGION>;
const bucket = <YOUR S3 BUCKET NAME>;
const key = <YOUR FILE NAME>; // test/abc.mp4
const accessKeyId = <YOUR S3 ACCESS KEY ID>;
const secretAccessKey = <YOUR S3 SECRET ACCESS KEY>;
const expiresIn = <URL EXPIRY IN SECONDS>; // this number should be higher than duraion of recording

const s3Client = new S3Client({
credentials: {
    accessKeyId: accessKeyId,
    secretAccessKey: secretAccessKey,
},
region: region,
});

const createPresignedUrlWithClient = async () => {
const command = new PutObjectCommand({ Bucket: bucket, Key: key });
const preSignedUrl = await getSignedUrl(s3Client, command, { expiresIn: expiresIn });
return preSignedUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await createPresignedUrlWithClient();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

---

**AZURE:**

```js
const { BlobServiceClient, BlobSASPermissions } = require("@azure/storage-blob");

const connectionString = <YOUR AZURE STORAGE CONNECTION STRING>;
const containerName = <YOUR AZURE CONTAINER NAME>;
const blobName = <YOUR AZURE BLOB NAME>;
const startsOn = <YOUR SASURL START TIME>; // (optional, defaults to now)
const expiresOn = <YOUR SASURL EXPIRY TIME>; // expiry time should be higher than duration of recording

const generateSASUrl = async () => {
let blobServiceClient = BlobServiceClient.fromConnectionString(connectionString);
let containerClient = blobServiceClient.getContainerClient(containerName);

await containerClient.createIfNotExists({
    access: "container",
});

const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const sasUrl = await blockBlobClient.generateSasUrl({
    startsOn: startsOn, // sasUrl start time
    expiresOn: expiresOn, // sasUrl expiration time
    permissions: BlobSASPermissions.parse("write"),
});
return sasUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await generateSASUrl();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

---

**GCP:**

```js
const { Storage } = require("@google-cloud/storage");

const projectId = <YOUR GCP PROJECT ID>;
const clientEmail = <YOUR GCP CLIENT EMAIL>;
const privateKey = <YOUR GCP PRIVATE KEY>;
const expires =<URL EXPIRY IN SECONDS>; // this number should be higher than duraion of recording
const bucketName = <YOUR GCP BUCKET NAME>;
const fileName = <YOUR FILE NAME>; // test/abc.mp4

const storage = new Storage({
projectId: projectId,
credentials: {
    client_email: clientEmail,
    private_key: privateKey,
},
});

const generateSignedUrl = async () => {
const options = {
    version: "v4",
    action: "write",
    expires: expires,
    contentType: "video/mp4",
};

const [signedUrl] = storage.bucket(bucketName).file(fileName).getSignedUrl(options);
return signedUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await generateSignedUrl();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)



---

# Start and Stop - iOS

This guide will provide an overview of how to implement start and stop Meeting Recording.

### `startRecording()`

`startRecording()` can be used to start a recording of the meeting which can be accessed from the `Meeting` class. This method accepts three parameters:

- `1. webhookUrl`: This would the webhook URL where you would like to listen to event happening for the recording like starting and stopping of recording. It will be triggered when the recording is completed and stored into server. Read more about webhooks [here](https://en.wikipedia.org/wiki/Webhook)

- `2. awsDirPath`: This parameter accepts the path for the your S3 bucket where you want to store recordings to. To allow us to store recording in your S3 bucket, you will need to fill this form by providing the required values. ([VideoSDK Cloud (AWS S3, Azure Blob or GCP ) Integration](/ios/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config))

- `3. config`: This parameter will define how the meeting should be recorded.

- `4. transcription(optional)`: This parameter will be used to enable post transcription for the recording with the given config.

:::note

If you don't have a value for `webhookUrl`,`awsDirPath` or `config`, you should pass `null` in place of the missing value. If you pass `null` in `awsDirPath` parameter then by default recordings will be store on the VideoSDK's storage.
:::



**Swift:**

```js
class MeetingViewController {
// button to start recording the meeting
@IBAction func recordMeetingButtonTapped(_ sender: Any) {

     let transcription: PostTranscriptionConfig =  PostTranscriptionConfig(
        enabled: true,
        summary: SummaryConfig(
                enabled: true,
                prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
            )
        )
    //highlight-start
     self.meeting?.startRecording(webhookUrl: "<your webhook-url>",
                                awsDirPath: "<your awsDirPath>",
                                config: RecordingConfig(layout: ConfigLayout(type: .GRIDpriority: .SPEAKER, gridSize: 4),
                                theme: .DARK, mode: .video_and_audio,
                                quality: .high,
                                orientation: .portrait),
                                transcription: transcription)
    //highlight-end
}
}
```

### `stopRecording()`

- `stopRecording()` is used to stop the meeting recording which can be accessed from the `Meeting` class.

#### Example

**Swift:**

```js
class MeetingViewController {
// button to stop recording the meeting
@IBAction func stopRecordingButtonTapped(_ sender: Any) {
    //highlight-next-line
     self.meeting?.stopRecording()
}
}
```

:::important

To initiate automatic recording at the beginning of a `session`, simply provide the `autoStartConfig` feature `recording` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.

:::

### API Reference

The API references for all the methods utilised in this guide are provided below.

- [startRecording()](/ios/api/sdk-reference/meeting-class/methods#startrecording)
- [stopRecording()](/ios/api/sdk-reference/meeting-class/methods#stoprecording)
- [onRecordingStateChanged](/ios/api/sdk-reference/meeting-class/events#onrecordingstatechanged)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

VideoSDK offers individual participant recording, generating a single, continuous file for a participant.

This recording captures the participant's audio and video streams throughout the meeting, regardless of whether they are muted or have their camera turned off. During periods of audio muting or video disengagement, the respective tracks will be silent or display a black screen, respectively.

You can access the recorded files in the developer dashboard or opt to store them in your own cloud storage.

This guide provides an overview of the start and stop functionality for individual participant recording through APIs.


## Start Individual Participant Recording

To start a participant recording, you will have to call `/v2/recordings/participant/start` API with following body parameters.

- `roomId`: RoomId for which the participant recording is to be started
- `participantId`: participantId of the participant to be recorder.
- `fileFormat`: Currently only `webm` is supported as file format. We will add the support for other formats in future.
- `webhookUrl`: The webhook URL where you would like to get the status updates of the recording. To learn more about webhooks refer [here](#participant-track-recording-starting).
- `bucketDirPath`: If you are using your own storage, you can provide the directory path where you want to store the recording. To configure the storage please [refere this quide](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config).

The usual recording path would look like `${sessionId}/${participantId}/${filename}`.

```swift
import Foundation

func startParticipantRecording() {
    let roomId = "<YOUR ROOM ID>"
    let participantId = "<PARTICIPANT ID>"
    let fileFormat = "<YOUR FILE FORMAT>" // (Optional) default: webm
    let bucketDirPath = "<YOUR CLOUD STORAGE BUCKET PATH>" // (Optional) test/abc
    let webhookUrl = "<YOUR WEBHOOK URL>" // (Optional)

    let url = URL(string: "https://api.videosdk.live/v2/recordings/participant/start")!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.addValue("$YOUR_TOKEN", forHTTPHeaderField: "Authorization")
    request.addValue("application/json", forHTTPHeaderField: "Content-Type")

    let json: [String: Any] = [
        "roomId": roomId,
        "participantId": participantId,
        "fileFormat": fileFormat,
        "bucketDirPath": bucketDirPath,
        "webhookUrl": webhookUrl
    ]

    let jsonData = try! JSONSerialization.data(withJSONObject: json)

    request.httpBody = jsonData

    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        guard let data = data, error == nil else {
            print("Error: \(error?.localizedDescription ?? "Unknown error")")
            return
        }
        let responseData = try? JSONSerialization.jsonObject(with: data, options: [])
        print(responseData)
    }

    task.resume()
}


```

## Stop Individual Participant Recording

To stop a participant recording, you will have to call `/v2/recordings/participant/stop` API with following body parameters.

- `roomId`: RoomId for which the participant recording is to be stopped
- `participantId`: participantId for which the recording is to be stopped.

```swift
import Foundation

func stopParticipantRecording(roomId: String, participantId: String) {
    let url = URL(string: "https://api.videosdk.live/v2/recordings/participant/stop")!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.setValue("$YOUR_TOKEN", forHTTPHeaderField: "Authorization")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")

    let body: [String: Any] = ["roomId": roomId, "participantId": participantId]
    request.httpBody = try? JSONSerialization.data(withJSONObject: body)

    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        guard let data = data, error == nil else {
            print("Failed to stop participant recording")
            return
        }

        if let jsonResponse = try? JSONSerialization.jsonObject(with: data, options: []) {
            print(jsonResponse)
        } else {
            print("Failed to parse response")
        }
    }

    task.resume()
}

```

## Webhook associated with Participant Recording

### participant-recording-starting

- A "Participant Recording Starting" webhook is triggered when the participant recording process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-started

- Participant Recording started webhook will be received when successfully participant recording is started in meeting

###### Example

```javascript
{
    "webhookType": "participant-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopping

- A "Participant Recording Stopping" webhook is triggered when the participant recording end process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopped

- Participant Recording stopped webhook will be received when participant recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "participant-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-recording-failed

- A "Participant Recording Failed" webhook is generated when the participant recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "participant-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
    },
}
```

---

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Participant Recording API](/api-reference/realtime-communication/start-participant-recording)
- [Stop Participant Recording API](/api-reference/realtime-communication/stop-participant-recording)



---

VideoSDK provides participant track recording, creating separate audio or video files for participant.

New files are generated when a participant starts their audio or video again after turning it off (e.g., unmuting the microphone or restarting the camera). This ensures that each file represents a continuous segment of audio or video content.

Once track recording is complete, all audio files for a participant are consolidated into a single directory, as are the video files.


## Start Participant Track Recording

To start a participant track recording, you will have to call `/v2/recordings/participant/track/start` API with following body parameters.

- `roomId`: RoomId for which the participant track recording is to be started
- `participantId`: participantId of the participant to be recorder.
- `kind`: The kind of tracks you want to record.
  - You can pass following values: _`audio`_ | _`video`_ | _`screen_audio`_ | _`screen_video`_
- `fileFormat`: Currently only `webm` is supported as file format. We will add the support for other formats in future.
- `webhookUrl`: The webhook URL where you would like to get the status updates of the recording. To learn more about webhooks refer [here](#participant-track-recording-starting).
- `bucketDirPath`: If you are using your own storage, you can provide the directory path where you want to store the recording. To configure the storage please [refere this quide](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config).

The usual recording path would look like `${sessionId}/${participantId}/${kind}/${filename}`.

```swift
import Foundation

func startTrackRecording() {
    let roomId = "<YOUR ROOM ID>"
    let participantId = "<PARTICIPANT ID>"
    let kind = "<YOUR STREAM KIND>"
    let fileFormat = "<YOUR FILE FORMAT>"
    let bucketDirPath = "<YOUR CLOUD STORAGE BUCKET PATH>"
    let webhookUrl = "<YOUR WEBHOOK URL>"

    let json: [String: Any] = [
        "roomId": roomId,
        "participantId": participantId,
        "kind": kind,
        "fileFormat": fileFormat,
        "bucketDirPath": bucketDirPath,
        "webhookUrl": webhookUrl
    ]

    let jsonData = try? JSONSerialization.data(withJSONObject: json)

    var request = URLRequest(url: URL(string: "https://api.videosdk.live/v2/recordings/participant/track/start")!)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.setValue("$YOUR_TOKEN", forHTTPHeaderField: "Authorization")
    request.httpBody = jsonData

    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        if let error = error {
            print("Error: \(error)")
            return
        }

        if let data = data, let responseString = String(data: data, encoding: .utf8) {
            print("Response: \(responseString)")
        }
    }

    task.resume()
}

```

## Stop Participant Track Recording

To stop a participant track recording, you will have to call `/v2/recordings/participant/track/stop` API with following body parameters.

- `roomId`: RoomId for which the participant track recording is to be stopped
- `participantId`: participantId for which the recording is to be stopped.
- `kind`: The kind of track recording you want to stop for the given participant.
  - You can pass following values: _`audio`_ | _`video`_ | _`screen_audio`_ | _`screen_video`_

```swift
import Foundation

func stopTrackRecording() {
    let roomId = "<YOUR ROOM ID>"
    let participantId = "<PARTICIPANT ID>"
    let kind = "<YOUR STREAM KIND>"

    let json: [String: Any] = [
        "roomId": roomId,
        "participantId": participantId,
        "kind": kind
    ]

    let jsonData = try? JSONSerialization.data(withJSONObject: json)

    var request = URLRequest(url: URL(string: "https://api.videosdk.live/v2/recordings/participant/track/stop")!)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.setValue("$YOUR_TOKEN", forHTTPHeaderField: "Authorization")
    request.httpBody = jsonData

    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        if let error = error {
            print("Error: \(error)")
            return
        }

        if let data = data, let responseString = String(data: data, encoding: .utf8) {
            print("Response: \(responseString)")
        }
    }

    task.resume()
}

```

## Webhook associated with Participant Track Recording

### participant-track-recording-starting

- A "Participant Track Recording Starting" webhook is triggered when the track recording process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-started

- Participant Track Recording started webhook will be received when successfully track recording is started in meeting

###### Example

```javascript
{
    "webhookType": "participant-track-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopping

- A "Participant Track Recording Stopping" webhook is triggered when the track recording end process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopped

- Participant Track Recording stopped webhook will be received when track recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-track-recording-failed

- A "Participant Track Recording Failed" webhook is generated when the track recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Track Recording API](/api-reference/realtime-communication/start-track-recording)
- [Stop Track Recording API](/api-reference/realtime-communication/stop-track-recording)



---

### Storage Configuration

While recording your meetings, you have the flexibility to store them either on VideoSDK's storage or configure your own storage solution such as **`AWS S3 Storage, Azure Blob or GCP Cloud Storage`**. To set up your own storage, you can navigate to the [API section](https://app.videosdk.live/api-keys) in the VideoSDK Dashboard.

- This feature allows you to configure storage provider for your meeting recordings.

- You can configure multiple storage provider with multiple API Keys.

- Currently, we support `AWS S3`, `Azure Blob` and `GCP Cloud Storage`. We will add support for other storage provider soon !!

## Prerequisites

- An active [VideoSDK Developer Account](https://app.videosdk.live)
- `Aws S3`, `Azure Blob Storage` or `GCP Cloud Storage` Credentials

## How to setup ?

### Step 1 : Select Api Key

![Dashboard](/img/tutorial/dashboard/api-key-dashboard.png)

- Go to [VideoSDK Dashboard](https://app.videosdk.live/api-keys).
- Select API Key for which, you want to set storage configuration.
- Then click on `Storage Config` Icon in Actions.

### Step 2 : Choose Cloud Storage Provider

![Dashboard](/img/tutorial/dashboard/storage-config.png)

- As you can see in the image, there are 3 Cloud Storage Provider (`Aws`, `Azure`, `GCP`).
- You can select a Cloud Storage Provider as per your requirements.

### Step 3 : Configure Bucket or Container

<h4> For Aws S3 Storage </h4>

![Aws S3](/img/tutorial/dashboard/s3.png)

- You will need AWS S3 Bucket. [Learn to create S3 Bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html).

- As you can see in the image, you will need enter `accessKeyId`, `secretAccessKey`, `region`, `bucket`, and `ACL` to setup for Aws S3 Storage.

- Click on `Save` button.

<hr />

<h4> For Azure Blob Storage: </h4>

![Azure Blob](/img/tutorial/dashboard/blob.png)

- You will need Azure Blob Container. [Learn to create Blob Container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal#create-a-container).

- As you can see in the image, you will need to enter `connectionString` and `containerName` to setup for Azure Blob.

- Click on `Save` button.

<hr />

<h4> For Google Cloud Storage: </h4>

<img src="/img/tutorial/dashboard/gcp.png" alt="GCP Cloud Storage" width="436" height="632"/>

1. You will need Google Cloud Storage Bucket. [Learn to create Google Cloud Storage Bucket](https://cloud.google.com/storage/docs/creating-buckets).

2. After creation, click on the <b> &#xFE19; </b>button in the upper right corner and select **`Project settings`**.

3. Under **`IAM and Admin`**, select **`Service Accounts`**. In the service account list, click on the <b> &#xFE19; </b> button for the account just added or created before, and select **`Manage keys`**.

4. Click **`ADD KEY > Create new key`**. Select **`JSON`** in the pop-up box and click **`CREATE`**. A json file is downloaded with the name format `projectId-xxxxxxxx.json`.

5. Open the downloaded json file, which looks like the following example:

```
{
  "type": "service_account",
  "project_id": "videosdk-12345",
  "private_key_id": "yourprivateidkeyyourprivateidkeyyourprivateidkey",
  "private_key": "-----BEGIN PRIVATE KEY-----\nThisisYourPrivateKeyThisisYourPrivateKeyThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\n-----END PRIVATE KEY-----\n",
  "client_email": "xxxx-xxxx@videosdk-12345.iam.gserviceaccount.com",
  "client_id": "123456789012345678901",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/videosdk%40videosdk-404307.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}
```

- As you can see in the image, you will need to enter `Project Id`, `Client Email`, `Bucket`, `Private Key` to setup for Google Cloud Storage Bucket. You can retrieve these details from the json file.

- Click on `Save` button.

### Step 4 : Test

- It's time to test !!
- [Create Room](https://docs.videosdk.live/api-reference/realtime-communication/create-room) with token generated with the API Key, you have configured for.
- Start meeting with the roomId created and Start Recording !!
- Then, you can see that recording will be available in your Bucket or Container.

:::note

- Only a single Recording Storage Config can be possible for a particular Api Key at a time.
- In order to add new Recording Configuration, first you need to delete current configuration.

:::


---

# Webhooks and Events - iOS

### Event associated with Recording

- **onRecordingStateChanged** - Whenever meeting recording state changes, then `onRecordingStateChanged` event will trigger.



**Swift:**

```js
extension MeetingViewController: MeetingEventListener {
//recording event
//highlight-start
func onRecordingStateChanged(state: RecordingState) {
    switch(state) {
        case .RECORDING_STARTING:
            print("recording starting")

        case .RECORDING_STARTED:
            print("recording started")

        case .RECORDING_STOPPING:
            print("recording stopping")

        case .RECORDING_STOPPED:
            print("recording stopped")
    }
}
//highlight-end
}
```

## Webhook associated with Recording

### recording-starting

- A "Recording Starting" webhook is triggered when the recording process for a meeting is initiated.

###### Example

```javascript
{
    "webhookType": "recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-started

- Recording started webhook will be received when successfully recording is started in meeting

###### Example

```javascript
{
    "webhookType": "recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopping

- A "Recording Stopping" webhook is triggered when the recording end process for a meeting is initiated.

###### Example

```javascript
{
    "webhookType": "recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopped

- Recording stopped webhook will be received when recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
        "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",

    },
}
```

---

### recording-failed

- A "Recording Failed" webhook is generated when the recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```


---

# Go Live On Social Media - iOS

This feature allows participant to broadcast meeting on various social media platforms such as Facebook or Youtube.
This guide will provide an overview of how participant can start and stop broadcasting meeting.

1. **Start LiveStream** - By using `startLivestream()` function, a participant can start broadcasting meeting on various platforms by provding url and stream keys as an argument.
2. **Stop LiveStream** - By using `stopLivestream()` function, a participant can stop broadcasting on all platforms.

### Start And Stop Live Stream



**Swift:**

```js
/// keep track of livestream
private var livestreamStarted = false

@IBAction func livestreamButtonTapped(_ sender: Any) {
if !livestreamStarted {
    // prepare output
    // specify social-media-url and stream-key
    let output = LivestreamOutput(url: "<rtmp://a.rtmp.youtube.com/live2>", streamKey: "<stream-key>")

    // start livestream
    self.meeting?.startLivestream(outputs: [output])
}
else {
    // stop livestream
    self.meeting?.stopLivestream()
}
}
```

### Events

1. **livestream-started** - Whenever broadcasting of meeting started, `livestream-started` event will trigger.

2. **livestream-stopped** - Whenever broadcasting of meeting stopped, `livestream-stopped` event will trigger.

**Swift:**

```js
/// Called after livestream starts
func onLivestreamStarted() {
liveStreamStarted = true

// show indication that livestream is started
}

/// Called after livestream stops
func onLivestreamStopped() {
liveStreamStarted = false

// hide livestream indication
}
```

---

# Interactive Livestream (HLS) - iOS

Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

In an interactive live stream (HLS), viewers can take part in a variety of activities like live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

<center>

![VideoSDK-HLS](/img/VideoSDK-HLS.png)

</center>

VideoSDK also allows you to configure the interactive livestream layouts in numerous ways like by simply setting different prebuilt layouts in the configuration or by providing your own custom template to do the livestream according to your layout choice.

This guide will provide an overview of how to implement start and stop Interactive live streaming (HLS).

:::important

To initiate automatic Interactive live streaming (HLS) at the beginning of a `session`, simply provide the `autoStartConfig` feature `hls` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.

:::

### `startHLS()`

`startHLS()` can be used to start a interactive livestream of the meeting which can be accessed from the `useMeeting` hook. This method accepts one parameter:

- `config (optional)`: This parameter will define how the interactive livestream layout should look like.

- `transcription(optional)`: This parameter will be used to enable post transcription for the recording with the given config.



**Swift:**

```js
let config: HLSConfig = HLSConfig(

  // highlight-next-line
  // Layout Configuration
  layout: HLSLayout(
type: .GRID, // .SPOTLIGHT | .SIDEBAR,  Default : .GRID
priority: .SPEAKER, // .PIN, Default : .SPEAKER
gridSize: 4 // MAX : 25
  ),

  // highlight-next-line
  // Theme of livestream
  theme: .DARK, //  .LIGHT | .DEFAULT

  // highlight-next-line
  // `mode` is used to either interactive livestream video & audio both or only audio.
  mode: .video_and_audio, // .audio, Default : .video_and_audio

  // highlight-next-line
  // Quality of livestream and is only applicable to `video-and-audio` type mode.
  quality: .high,  // .low | .med,  Default : .med

  //highlight-start
  // This mode refers to orientation of recording.
  // landscape : Livestream the meeting in horizontally
  // portrait : Livestream the meeting in vertically (Best for mobile view)
  //highlight-end
  orientation: .portrait  // .portrait,  Default : .landscape
)

 let transcription: PostTranscriptionConfig =  PostTranscriptionConfig(
        enabled: true,
        summary: SummaryConfig(
                enabled: true,
                prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
            )
        )

startHLS(config: config, transcription: transcription)
```

### `stopHLS()`

- `stopHLS()` is used to stop interactive livestream of the meeting which can be accessed from the `meeting` object.

#### Example

**Swift:**

```js
stopHLS();
```

### Event associated with HLS

- **onHlsStateChanged** - Whenever meeting HLS state changes, then `onHlsStateChanged` event will trigger.

- You can get the `downstreamUrl` of the HLS to play it on the Viewer side when the state changes to `HLSState.HLS_STARTED`

**Swift:**

```js
func onHlsStateChanged(state: HLSState, hlsUrl: HLSUrl?) {
switch(state) {
    case .HLS_STARTING:
        print("HLS Starting")

    case .HLS_STARTED:
        self.hlsStreamStarted = true
        print("HLS Started")

    case .HLS_PLAYABLE:
        print("HLS Playable")

    case .HLS_STOPPING:
        print("HLS Stopping")

    case .HLS_STOPPED:
        self.hlsStreamStarted = false
        print("HLS Stopped")
    }
}
```

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [startHLS](/ios/api/sdk-reference/meeting-class/methods#starthls)
- [stopHLS](/ios/api/sdk-reference/meeting-class/methods#stophls)
- [onHlsStateChanged](/ios/api/sdk-reference/meeting-class/events#onhlsstatechanged)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

# Record Meeting - iOS

VideoSDK allows you to record video & audio during the meeting. The recording files are available in developer dashboard or you can also choose to store them in your own cloud storage.

VideoSDK also allows you to configure the recording layouts in numerous ways like by simply setting different prebuilt layouts in the configuration or by providing your own custom template to do the recording according to your layout choice.

This guide will provide an overview of how to implement start and stop Meeting Recording.

:::important

To initiate automatic recording at the beginning of a `session`, simply provide the `autoStartConfig` feature `recording` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.

:::

### `startRecording()`

`startRecording()` can be used to start a recording of the meeting which can be accessed from the `Meeting` class. This method accepts three parameters:

- `1. webhookUrl`: This would the webhook URL where you would like to listen to event happening for the recording like starting and stopping of recording. It will be triggered when the recording is completed and stored into server. Read more about webhooks [here](https://en.wikipedia.org/wiki/Webhook)

- `2. awsDirPath`: This parameter accepts the path for the your S3 bucket where you want to store recordings to. To allow us to store recording in your S3 bucket, you will need to fill this form by providing the required values. [VideoSDK AWS S3 Integration](/docs/tutorials/user-dashboard/recording-storage-config)

- `3. config`: This parameter will define how the meeting should be recorded.

- `4. transcription(optional)`: This parameter will be used to enable post transcription for the recording with the given config.

:::note

If you don't have a value for `webhookUrl`,`awsDirPath` or `config`, you should pass `null` in place of the missing value. If you pass `null` in `awsDirPath` parameter then by default recordings will be store on the VideoSDK's storage.
:::



**Swift:**

```js
class MeetingViewController {
// button to start recording the meeting
@IBAction func recordMeetingButtonTapped(_ sender: Any) {

     let transcription: PostTranscriptionConfig =  PostTranscriptionConfig(
        enabled: true,
        summary: SummaryConfig(
                enabled: true,
                prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
            )
        )
    //highlight-start
     self.meeting?.startRecording(webhookUrl: "<your webhook-url>",
                                awsDirPath: "<your awsDirPath>",
                                config: RecordingConfig(layout: ConfigLayout(type: .GRIDpriority: .SPEAKER, gridSize: 4),
                                theme: .DARK, mode: .video_and_audio,
                                quality: .high,
                                orientation: .portrait),
                                transcription: transcription)
    //highlight-end
}
}
```

### `stopRecording()`

- `stopRecording()` is used to stop the meeting recording which can be accessed from the `Meeting` class.

#### Example

**Swift:**

```js
class MeetingViewController {
// button to stop recording the meeting
@IBAction func stopRecordingButtonTapped(_ sender: Any) {
    //highlight-next-line
     self.meeting?.stopRecording()
}
}
```

### Event associated with Recording

- **onRecordingStateChanged** - Whenever meeting recording state changes, then `onRecordingStateChanged` event will trigger.

**Swift:**

```js
extension MeetingViewController: MeetingEventListener {
//recording event
//highlight-start
func onRecordingStateChanged(state: RecordingState) {
    switch(state) {
        case .RECORDING_STARTING:
            print("recording starting")

        case .RECORDING_STARTED:
            print("recording started")

        case .RECORDING_STOPPING:
            print("recording stopping")

        case .RECORDING_STOPPED:
            print("recording stopped")
    }
}
//highlight-end
}
```

### Storage Configuration

While recording your meetings, you can choose to store them on the VideoSDK's storage or you can also configure your own **`AWS S3 Storage, Azure Blob or GCP Cloud Storage`** to store the meeting recordings directly on your storage.

You can configure your own **`AWS S3 Storage, Azure Blob or GCP Cloud Storage`** from the [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).

You can also go through this [guide to setup](/docs/tutorials/user-dashboard/recording-storage-config) the storage or watch this [video to configure](https://www.loom.com/share/23a2617f824a4a5da004d14d1a541a9d) your storage.

### Custom Template

With VideoSDK, you can also use your own custom designed layout template to record the meetings. In order to use the custom template, you need to create a template for which you can [follow this guide](/react/guide/interactive-live-streaming/custom-template). Once you have setup the template, you can use the [REST API to start](/api-reference/realtime-communication/start-recording) the recording with the `templateURL` parameter.

### API Reference

The API references for all the methods utilised in this guide are provided below.

- [startRecording()](/ios/api/sdk-reference/meeting-class/methods#startrecording)
- [stopRecording()](/ios/api/sdk-reference/meeting-class/methods#stoprecording)
- [onRecordingStateChanged](/ios/api/sdk-reference/meeting-class/events#onrecordingstatechanged)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

# RTMP Livestream - iOS

RTMP is a popular protocol for live streaming video content from a VideoSDK to platforms such as YouTube, Twitch, Facebook, and others.

By providing the platform-specific stream key and stream URL, the VideoSDK can connect to the platform's RTMP server and transmit the live video stream.

VideoSDK allows you to livestream your meeting to platform which support RTMP ingestion just by providing the platform-specific stream key and stream URL, we can connect to the platform's RTMP server and transmit the live video stream.

VideoSDK also allows you to configure the livestream layouts in numerous ways like by simply setting different prebuilt layouts in the configuration or by providing your own custom template to do the livestream according to your layout choice.

This guide will provide an overview of how to implement start and stop RTMP Livestreaming.

### `startLivestream()`

`startLivestream()` can be used to start a RTMP livestream of the meeting which can be accessed from the `Meeting` class. This method accepts two parameters:

- `outputs`: This parameter accepts a list of `LivestreamOutput` objects which contains the RTMP `url` and `streamKey` of the platforms you want to start the livestream.



**Swift:**

```js
class MeetingViewController {

private let platformUrl = "<url-of-the-platform>"
private let privateKey = "<private-key>"

// button to start livestream
@IBAction func startLiveStreamButtonTapped(_ sender: Any) {
    //highlight-start
     self.meeting?.startLivestream(outputs: LivestreamOutput(url: platformUrl, streamKey: privateKey))
    //highlight-end
}
}
```

### `stopLivestream()`

- `stopLivestream()` is used to stop the meeting livestream which can be accessed from the `Meeting` class.

#### Example

**Swift:**

```js
class MeetingViewController {
// button to stop livestream
@IBAction func startLiveStreamButtonTapped(_ sender: Any) {
    //highlight-start
     self.meeting?.stopLivestream()
    //highlight-end
}
}
```

### Event associated with Livestream

- **onLivestreamStateChanged** - Whenever meeting livestream state changes, then `onLivestreamStateChanged` event will trigger.

**Swift:**

```js
extension MeetingViewController: MeetingEventListener {
// rtmp-event
//highlight-start
func onLivestreamStateChanged(state: LiveStreamState) {
    switch(state) {
        case .LIVESTREAM_STARTING:
            print("livestream starting")
        
        case .LIVESTREAM_STARTED:
            print("livestream started")
            
        case .LIVESTREAM_STOPPING:
            print("livestream stoping")
    
        case .LIVESTREAM_STOPPED:
            print("livestream stopped")
    }
}
//highlight-end
}
```

### Custom Template

With VideoSDK, you can also use your own custom designed layout template to livestream the meetings. In order to use the custom template, you need to create a template for which you can [follow this guide](/react/guide/interactive-live-streaming/custom-template). Once you have setup the template, you can use the [REST API to start](/api-reference/realtime-communication/start-livestream) the livestream with the `templateURL` parameter.

## API Reference

The API references for all the methods utilised in this guide are provided below.

- [startLivestream()](/ios/api/sdk-reference/meeting-class/methods#startlivestream)
- [stopLivestream()](/ios/api/sdk-reference/meeting-class/methods#stoplivestream)
- [onLivestreamStateChanged](/ios/api/sdk-reference/meeting-class/events#onlivestreamstatechanged)


---

# Release Notes - iOS




---

# Display Video - iOS

In this guide, we will take a look at how to render the participant's video on the screen.

For simplicity purposes, we will render a remote participant and a local participant in our Meeting View.

1. [Creating VideoView](#1-create-videoview)
2. [Setup event Listeners](#2-setup-event-listeners)
3. [Render Video](#3-render-video)
4. [Display Audio Status](#4-display-audio-status)

### 1. Create VideoView

We will create a storyboad for our video view as shown below.





<img src='https://cdn.videosdk.live/website-resources/docs-resources/ios-display-view.png' style={{height: '600px'}}/>
<img src='https://cdn.videosdk.live/website-resources/docs-resources/ios-display-view-hierarchy.png' style={{height: '600px'}}/>



Use the above view hierarchy for faster implementation.

Below is the code for defining the variables for the UIViews that we create in the storyboard



**Swift:**

```js title=MeetingViewController.swift
class MeetingViewController: UIViewController, UNUserNotificationCenterDelegate {
//remote participant view
@IBOutlet weak var participantViewsContainer: UIView!
@IBOutlet weak var remoteParticipantVideoContainer: RTCMTLVideoView!
//local participant view
@IBOutlet weak var localParticipantViewContainer: UIView!
@IBOutlet weak var localParticipantViewVideoContainer: RTCMTLVideoView!

```

### 2. Setup Event Listeners

When a meeting is created or joined by a participant, we add the event listeners that will notify us when participant's video needs to be rendered.

Adding event listeners will enable us to listen the `onStreamEnabled` and `onStreamDisabled` events, using which we can update the view and start rendering the video.

**Swift:**

```js title=MeetingViewController.swift
//adding event listener when local peer joins the meeting
func initializeMeeting() {    
    // initialize
    meeting = VideoSDK.initMeeting(
        meetingId: "abcd-xyzw-efgh",
        participantName: "John Doe",
        micEnabled: true,
        webcamEnabled: true,
    )
    // add listener after creating meeting
    //highlight-next-line
    meeting?.addEventListener(self)
    // join
    meeting?.join(cameraPosition: .front)
}

//adding event listener when remote peer joins the meeting
extension MeetingViewController: MeetingEventListener {
/// Meeting started
func onMeetingJoined() {
    // handle local participant on start
    guard let localParticipant = self.meeting?.localParticipant else { return }
        // add event listener
        //highlight-next-line
        localParticipant.addEventListener(self)
}
func onParticipantJoined(_ participant: Participant) {
        // add event listener
        //highlight-next-line
        participant.addEventListener(self)
}
}
```

After adding event listeners, We can use the [`onStreamEnabled()`](/ios/api/sdk-reference/participant-class/events#onstreamenabled) and [`onStreamDisabled()`](/ios/api/sdk-reference/participant-class/events#onstreamdisabled) of the [`ParticipantEventListener`](/ios/api/sdk-reference/participant-class/events) protocol for rendering purposes.


### 3. Render Video

- When an audio/video stream is enabled by local or remote participant, the `onStreamEnabled` event is triggered. Similarly when an audio/video stream is disabled by the local or remote participant, the `onStreamDisabled` event is triggered. 

- We can render the video using the stream that we get from `onStreamEnabled` as shown below.

:::note
 We will not render audio seperately, it is handled by the RTCMTLVideoView automatically.
:::

**Swift:**

```js title=MeetingViewController.swift
extension MeetingViewController: ParticipantEventListener {

func onStreamEnabled(_ stream: MediaStream, forParticipant participant: Participant) {
    //call updateView function
    updateView(participant: participant, forStream: stream, enabled: true)
}

func onStreamDisabled(_ stream: MediaStream, forParticipant participant: Participant) {
    //call updateView function
    updateView(participant: participant, forStream: stream, enabled: false)
}
}
```

**Swift:**

```js title=MeetingViewController.swift
extension MeetingViewController { 
//update view for stream kind video
func updateView(participant: Participant, forStream stream: MediaStream, enabled: Bool) { // true
    switch stream.kind {
    case .state(value: .video):
        if let videotrack = stream.track as? RTCVideoTrack {
            if enabled {
                showVideoView(participant: participant, stream: videotrack) // show video
            } else {
                hideVideoView(participant: participant, stream: videotrack) // hide video
            }
        }
    default:
        break
    }
}
//show video view
func showVideoView(participant: Participant, stream: RTCVideoTrack){
    DispatchQueue.main.async {
        UIView.animate(withDuration: 0.5){
            //rendering if more than one participants
            if self.participants.count > 1 {
                if let currentVideoTrack = self.participants.first(where: { $0.isLocal })?.streams.first(where: {$1.kind == .state(value: .video)})?.value.track as? RTCVideoTrack {
                    currentVideoTrack.remove(self.remoteParticipantVideoContainer)
                    currentVideoTrack.remove(self.localParticipantViewVideoContainer)
                }
                    //add stream to the respective video view
                    stream.add(participant.isLocal ? self.localParticipantViewVideoContainer : self.remoteParticipantVideoContainer)
                    //show the respective video view
                    if participant.isLocal {
                        self.localParticipantViewVideoContainer.isHidden = false
                    } else {
                        self.remoteParticipantVideoContainer.isHidden = false
                    }
                    //shift local video view to its container
                    if let localParticipantVideoStream = self.participants.first(where: { $0.isLocal })?.streams.first(where: {$1.kind == .state(value: .video )})?.value.track as? RTCVideoTrack {
                    localParticipantVideoStream.add(self.localParticipantViewVideoContainer)
                    self.localParticipantViewVideoContainer.isHidden = false
                    self.localParticipantViewContainer.isHidden = false
                }

            } else {
                //rendering if more than one participants
                stream.add(self.remoteParticipantVideoContainer)
                self.remoteParticipantVideoContainer.isHidden = false
            }
        }
    }
}
//hide video view
func hideVideoView(participant: Participant, stream: RTCVideoTrack){
    UIView.animate(withDuration: 0.5){
        //adjust view when there are more than one participants
        if self.participants.count > 1 {
            //remove stream from the respective view
                stream.remove(participant.isLocal ? self.localParticipantViewVideoContainer : self.remoteParticipantVideoContainer)
                //hide the respective view
                if participant.isLocal {
                    self.localParticipantViewVideoContainer.videoContentMode = .scaleAspectFill
                    self.localParticipantViewVideoContainer.isHidden = true
                } else {
                    self.remoteParticipantVideoContainer.isHidden = true
                }
        } else {
            //render video in remote container when there is only one participant
            stream.remove(self.remoteParticipantVideoContainer)
            self.remoteParticipantVideoContainer.isHidden = true
        }
    }
}
}
```

<center>
<img src='https://cdn.videosdk.live/website-resources/docs-resources/ios-display-view-example.jpg' style={{height: '600px'}}/>
</center>

Above code is the simplified example of how you can render or remove video stream whenever required. Use this as a reference to render your own video inside a RTCMTLVideoView.

Additionally, you can show Participant's initials when their video is off using the `participant.displayName`. Display the initials when `onStreamDisabled` event is triggered when user switch off their camera, by placing another view that would contain the initials over the respective container.

### 4. Display Audio Status

- Unlike Video, we do not need to explicitly render audio. Therefore, you can use the `onStreamEnabled` events for the audio kind to show the mute/unmute mic icon.

Below is the sample on how it can be done.

**Example**

**Swift:**

```js title=MeetingViewController.swift
extension MeetingViewController: ParticipantEventListener {

func onStreamEnabled(_ stream: MediaStream, forParticipant participant: Participant) {
    //call updateView function
    updateView(participant: participant, forStream: stream, enabled: true)
}

func onStreamDisabled(_ stream: MediaStream, forParticipant participant: Participant) {
    //call updateView function
    updateView(participant: participant, forStream: stream, enabled: false)
}
}
```

**Swift:**

```js title=MeetingViewController.swift
extension MeetingViewController { 
//update view for stream kind audio
func updateView(participant: Participant, forStream stream: MediaStream, enabled: Bool) { // true
    switch stream.kind {
    case .state(value: .audio):
        updateMic(participant: participant, enabled)
    default:
        break
    }
}
//update mic according to the status.
func updateMic(participant: Participant, _ enabled: Bool) {
    if !participant.isLocal {
        viewRemoteMicContainer.isHidden = enabled // set mic icon accordingly
    } else if participants.count == 1 {
        participantViewsContainer.bringSubviewToFront(viewRemoteMicContainer)
        viewRemoteMicContainer.isHidden = enabled // set mic icon accordingly
    }
}
```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [Participant](/ios/api/sdk-reference/participant-class/introduction)
- [onStreamEnabled()](/ios/api/sdk-reference/participant-class/events#onstreamenabled)
- [onStreamDisabled()](/ios/api/sdk-reference/participant-class/events#onstreamdisabled)


---

# Layout and Grid Management - iOS

In this guide, we will take a look at how to efficiently manage the participants in different types of layout.

## Grid Layout

The most usual way to showing participants within a grid. There are multiple things you should keep in mind when showing participants in the grid.

This includes the number of participants being shown on the screens, number of participants in the background(in the meeting but not on the grid), quality which is being consumed for each and every participant in the grid.

### Quality of Participant's Video

When there are large number of participants present on the screen, it is best to consume them in lower resolutions. For this we recommend you to call the `setQuality` method on the participants present in the grid with dynamic values based on the number of participants on the screen.

Here is the recommended video quality:

1. Participants less than 3: `setQuality("high")`
2. Participants between 3 to 4: `setQuality("med")`
3. Participants greater than 4: `setQuality("low")`

<center>
<img src='https://cdn.videosdk.live/website-resources/docs-resources/grid_quality_mobile.png' />
</center>

### Grid with Screen Share

When you are rendering a small grid along with the screen share of the presenter or you are showing a simple sidebar video of the participants while the screenshare is on, it is recommended to do `setQuality("low")` for the participants who are present in the sidebar.

## Grid with Pagination

If you are having large video calls where there are multiple speakers with video turned on, it is best to implement a pagination type setup where only a few (4-6) participants are shown on the grid and rest can be seen by changing the page.

To best utilize the resourses, you should pause the streams of the participants who are not present in the grid and resume them when the come in to the grid. You can [follow this guide](#pauseresume-stream) to pause/resume the stream.

<center>
<img src='https://cdn.videosdk.live/website-resources/docs-resources/grid_pagination.png' />
</center>



## Pause/Resume Stream

Whenver you wish to stop/resume download stream(webcam, screenShare and mic) of participant, you can simply do it by using `pause`, `resume` methods.

### Pause stream

- `pause()` method is used for pause stream(webcam, screenShare and mic) of a particular participant.



**Swift:**

```js
let videoStream = participant.streams.first(where: { $1.kind == .state(value: .video) })?.value {
            videoStream.pause()
        }
```

### Resume stream

- `resume()` method is used for pause stream(webcam, screenShare and mic) of a particular participant.

**Swift:**

```js
let videoStream = participant.streams.first(where: { $1.kind == .state(value: .video) })?.value {
            videoStream.resume()
        }
```

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [setQuality](/ios/api/sdk-reference/participant-class/methods#setquality)


---

# Optimize Audio Track - iOS

While optimizing for the best listening experience, it is necessary to fine-tune the audio track that is being used during the calls.

For the best fine-tuning experience, we have introduced the ability to pass a custom audio track for the participant's media before and during the meeting.

## Custom Audio Track

This feature can be used to create a custom Audio track for the Audio of the participants with different encoder configuration and send it to other participants.

### `How to Create Custom Audio Track ?`

- You can create a Audio Track using `createAudioTrack()` method of `VideoSDK` class.

- This method can be used to create audio track using different noise configurations.

#### Example



**Swift:**

```js
guard let audioMediaTrack = try? VideoSDK.createAudioTrack(
 		noiseConfig: noiseConfig(
        //highlight-next-line
        // It is used to improve the quality of audio by removing background noise
        //highlight-next-line
        // that can interfere with the clarity of speech.
        noiseSupression: true, 

        //highlight-next-line
        // It is used to remove unwanted echoes from voice.
        echoCancellation: true, 

        //highlight-next-line
        // It is used to maintain a consistent level of loudness or amplitude in a voice.
        autoGainControl: true, 

        //highlight-next-line
        // It removes low frequency sounds hence making the audio clearer.
        highPassFilter: true
)
) else {return}
```


### `How to Setup Custom Audio Track ?`

The custom track can be set up both before and after the initialization of the meeting.

1. [Setting up a Custom Track during the initialization of a meeting](#1-setting-up-a-custom-track-during-the-initialization-of-a-meeting)
2. [Setting up a Custom Track with methods](#2-setting-up-a-custom-track-with-methods)

##### 1. Setting up a Custom Track during the initialization of a meeting

If you are passing `micEnabled: true` in the `initMeeting` of `VideoSDK` and want to use custom tracks from start of the meeting, you can pass custom track in the `initMeeting` as shown below.

:::caution
Custom Track will not apply on `micEnabled: false` configuration.
:::

##### Example

**Swift:**

```js
//highlight-start
guard let customAudioStream = try? VideoSDK.createAudioTrack(
 		noiseConfig: noiseConfig(
        noiseSupression: true, 
        echoCancellation: true, 
        autoGainControl: true, 
        highPassFilter: true
)
) else {return}
//highlight-end

let meeting = VideoSDK.initMeeting(
  meetingId: meetingId,
  participantName: name,
  micEnabled: true, // when passed true, it creates an audio track with defined configs
  webcamEnabled: cameraEnabled // optional, default: true

  // Pass the custom audio track here which will be used to when mic is auto started
  //highlight-next-line
  customAudioStream: customAudioStream
)
```

#### 2. Setting up a Custom Track with methods

In order to switch tracks during the meeting, you have to pass the `customAudioStream` in the `unmuteMic()` method of `Meeting`.

:::tip
Make sure to call `muteMic()` before you create a new track as it may lead to unexpected behavior.
:::

##### Example

**Swift:**

```js
@IBAction func unmuteButtonTapped(_ sender: Any) {
  if !on {
//highlight-start
guard
  let audioMediaTrack = try? VideoSDK.createAudioTrack(
    noiseConfig: noiseConfig(
        noiseSupression: true,
        echoCancellation: true,
        autoGainControl: true,
        highPassFilter: true
    )
  )
else { return }
//highlight-end

self.meeting?.unmuteMic(customAudioStream: audioMediaTrack)
  } else {
self.meeting?.muteMic()
  }
}
```

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [Custom Audio Track](/ios/api/sdk-reference/custom-tracks#custom-audio-track)


---

# Optimize Video Track - iOS

While optimizing for the best viewing experience, it is necessary to fine-tune the video tracks that are being used during the calls.

For the best fine-tuning experience, we have introduced the ability to pass a custom video track for the participant's media before and during the meeting.

:::info
From version 2.1.5 of the SDK, you can now use the hardware-accelerated codec (H.264) with Video Track, which can enhance compresses video data for efficient transmission over the internet, balancing quality and bandwidth usage.
:::

## Custom Video Track

This feature gives you powerful tools to deliver the best possible video stream for varying network conditions. You can specify a modern video quality profile (`bitrateMode`) and control simulcast behavior (`maxLayer`). 

### `How to Create a Custom Video Track ?`

- You can create a Video Track using `createCameraVideoTrack()` method of `VideoSDK` class.

- This method can be used to create video track by specifying parameters like video resolution, camera facing mode, and the quality controls (`bitrateMode` and `maxLayer`).

- You can choose video resolution from the below mentioned list of values for the encoder config:

| Config | Resolution | Frame Rate |   Optimized (kbps)   |   Balanced (kbps)   |   High Quality (kbps)   |
| -------------- | :--------: | :--------: | :----------: | :----------: | :----------: |
| h90p_w160p     |  160x90    |   30 fps   |  40   |  90   |  120   |
| h180p_w320p    |  320x180   |   30 fps   |  60   |  120  |  180   |
| h360p_w640p    |  640x360   |   30 fps   |  300  |  450  |  600   |
| h540p_w960p    |  960x540   |   30 fps   |  600  |  900  |  1200  |
| h720p_w1280p   |  1280x720  |   30 fps   |  1000  |  1500  |  2000  |
| h1080p_w1920p  | 1920x1080  |   30 fps   |  1500  |  2200  |  2700  |
| h120p_w160p    |  160x120   |   30 fps   |  40  |  90  |  120  |
| h180p_w240p    |  240x180   |   30 fps   |  90  |  120  |  180  |
| h240p_w320p    |  320x240   |   30 fps   |  100  |  150  |  200  |
| h360p_w480p    |  480x360   |   30 fps   |  270  |  360  |  540  |
| h480p_w640p    |  640x480   |   30 fps   |  350  |  600  |  900  |
| h720p_w960p    |  960x720   |   30 fps   |  900  |  1200  |  1600  |
| h1080p_w1440p  | 1440x1080  |   30 fps   |  1500  |  2000  |  2700  |

:::note

Above mentioned encoder configurations are valid for both, landscape as well as portrait mode.

:::

#### Example



**Swift:**

```javascript
import WebRTC
guard let videoMediaTrack = try? VideoSDK.createCameraVideoTrack(
  // highlight-next-line
  // This will accept the enum value of CustomVideoTrackConfig which contains resolution (height x width) of video you want to capture.
  encoderConfig: .h720p_w960p, // .h360p_w640p | .h480p_w640p ... // Default : .h720p_w1280p
  // highlight-next-line
  // It will specify whether to use front or back camera for the video track.
  facingMode: .front, // .back,  Default : .front

  // highlight-next-line
  // We will discuss this parameter in next step.
  multiStream: true, // false,  Default : true

  // highlight-next-line
  // A video codec for compresses video data for efficient transmission over the internet, balancing quality and bandwidth usage.
  codec: .H264, // Default: .VP8

  // highlight-next-line
  // Optional: This controls the video quality and bandwidth usage.
  bitrateMode: BitrateMode.HIGH_QUALITY // .BANDWIDTH_OPTIMIZED | .BALANCED Default: .BALANCED 

  // highlight-next-line
  // Optional: This specifies the maximum number of simulcast layers (maxLayer) to publish.
  maxLayer: EncodingLayer.MAX_LAYER_2, // 2 |  Default: .MAX_LAYER_3

) else { return}
```

:::caution
The capabilities of the device have a significant impact on how custom track configurations behave. Assuming a case where you set encoder configuration to 1080p but the webcam only supports 720p, then encoder configuration will automatically switch to the highest resolution that the device can handle, which is 720p.
:::

##### What is `multiStream`?

- It will specify if the stream should send multiple resolution layers or single resolution layer.

**`multiStream : true`** By default, VideoSDK sends multiple resolution video streams to the server (whether you are using custom video track or not), For instance, user device capabilty is 720p, so VideoSDK sends 720p along with 360p and 180p streams. This allows VideoSDK to deliver the appropriate stream to each participant based on their network bandwidth.

<center>

![Multi Stream False](https://cdn.videosdk.live/website-resources/docs-resources/multistream_true_ios.png)

</center>

**`multiStream : false`** If you want to restrict the VideoSDK to send only one stream to maintain quality, you can set `multiStream` to `false`.

<center>

![Multi Stream False](/img/multistream_false.png)

</center>

:::danger
`setQuality` would not have any effect if multiStream is set to `false`.
:::

##### What is `BitrateMode`?
`BitrateMode` is the key setting for video quality. It lets you decide whether to prioritize sharp details, save internet data, or find a good balance between the two.

You can choose from three distinct modes:
- `.BANDWIDTH_OPTIMIZED`: Prioritizes lower bandwidth usage over video quality. Ideal for users with poor or unstable network conditions.
- `.BALANCED`: The default setting. It provides a smart compromise between clear video and efficient bandwidth consumption, suitable for most use cases.
- `.HIGH_QUALITY`: Prioritizes video quality over bandwidth usage. Use this when high-fidelity video is essential and viewers are expected to have strong network connections.

##### What is `MaxLayer`?
`MaxLayer` is an advanced parameter that gives you direct control over simulcast, which is the process of sending multiple versions (or "layers") of the same video stream at different resolutions and qualities simultaneously.

- `.MAX_LAYER_3` **(Default)**: Publishes all available layers (e.g., high, medium, and low quality). This provides the maximum adaptability for viewers on diverse and unpredictable networks.
- `.MAX_LAYER_2`: Intelligently publishes only the highest and lowest quality layers, skipping any in the middle. This is useful for providing a high-quality option and a low-bandwidth fallback without the overhead of a third stream.
  - If a device is capable of producing a `h720p_w960p` stream, setting `EncodingLayer.MAX_LAYER_2` will result in two streams being sent: the highest quality (`h720p_w960p`) and the lowest quality (e.g. `h180p_w240p`), ensuring a fallback for poor connections.

:::info
To use the `maxLayer` parameter, `multiStream` must be set to `true`. The `multiStream` flag enables simulcasting (sending multiple quality streams), while `maxLayer` specifies how many streams to send.
:::

:::note
- If the video width or height is 960 or higher, it will create 3 layers.
- If it’s 360 or higher and less than 960, it will create 2 layers.
- If it’s below 360, it will create only 1 layer.
  - For example, if you set MaxLayer to `EncodingLayer.MAX_LAYER_3` but your video is 320×180, it will only create 1 layer.
:::

### `How to Setup a Custom Video Track ?`

The custom track can be set up both before and after the initialization of the meeting.

1. [Setting up a Custom Track during the initialization of a meeting](#1-setting-up-a-custom-track-during-the-initialization-of-a-meeting)
2. [Setting up a Custom Track with methods](#2-setting-up-a-custom-track-with-methods)

##### 1. Setting up a Custom Track during the initialization of a meeting

If you are passing `webcamEnabled: true` in the `createRoom` and want to use custom tracks from start of the meeting, you can pass custom track in the `customCameraVideoTrack` as shown below.

:::caution

- Custom Track will not apply on `webcamEnabled: false` configuration.

- Custom video track's `facingMode` takes precedence over the `cameraPosition` specified during the `join` method. Ensure you set `facingMode` appropriately to achieve the desired camera orientation.

:::

##### Example

**Swift:**

```javascript
import VideoSDKRTC

guard let videoMediaTrack = try? VideoSDK.createCameraVideoTrack(
encoderConfig: .h720p_w960p,
facingMode: .front,
multiStream: true,
codec: .H264, // Default: .VP8
bitrateMode: .HIGH_QUALITY, // Default: .BALANCED
maxLayer: .MAX_LAYER_2 // Default: .MAX_LAYER_3
) else {
return
}

let meeting = VideoSDK.initMeeting(
meetingId: meetingId,
participantName: name,
micEnabled: micEnabled, // optional, default: true
webcamEnabled: cameraEnabled, // optional, default: true
// highlight-next-line
// Pass the custom track here which will be used to when webcam is auto started
customCameraVideoStream: videoMediaTrack
)

```

#### 2. Setting up a Custom Track with methods

In order to switch tracks during the meeting, you have to pass the `CustomTrack` in the **`enableWebCam()`** method of `Room`.

:::tip
Make sure to call `disableWebcam()` before you create a new track as it may lead to unexpected behavior.
:::

##### Example

**Swift:**

```javascript
import VideoSDKRTC

@IBAction func videoButtonTapped(_ sender: Any) {
if !on {
    guard let videoMediaTrack = try? VideoSDK.createCameraVideoTrack(
        encoderConfig: .h720p_w960p,
        facingMode: .front,
        multiStream: false,
        codec: .H264, // Default: .VP8
        bitrateMode: .HIGH_QUALITY, // Default: .BALANCED
        maxLayer: .MAX_LAYER_2 // Default: .MAX_LAYER_3
    ) else {
        return
    }
    self.meeting?.enableWebcam(customVideoStream: videoMediaTrack)
} else {
    self.meeting?.disableWebcam()
}
}
```

### `Which Configuration is suitable for Device ?`

In this section, we will understand participant size wise `encoder(Resolution)` and `multiStream` configuration.

<center>
<img src='https://cdn.videosdk.live/website-resources/docs-resources/mobile_device_config.png' />
</center>

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [Custom Video Track](/ios/api/sdk-reference/custom-tracks)


---

---
title: Picture-in-Picture Mode | Video SDK
hide_title: true
hide_table_of_contents: false
description: Picture-in-picture (PiP) is a feature that is commonly used in video conferencing software. It allows you to continue your video conference while also performing other tasks on your device.
sidebar_label: Picture-in-Picture Mode
pagination_label: Picture-in-Picture Mode
keywords:
  - audio calling
  - video calling
  - real-time communication
  - collaboration
  - Picture In Picture Mode 
  - iOS Application 
  - SwiftUI 
  - WebRTC PiP Mode
  - Native iOS Picture In Picture Mode 
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: picture-in-picture
--- 

# Picture-in-Picture Mode - iOS

### Overview

Picture-in-picture (PiP) is a commonly used feature in video conferencing software, enabling users to simultaneously engage in a video conference and perform other tasks on their device. With PiP, you can keep the video conference window open, resize it to a smaller size, and continue working on other tasks while still seeing and hearing the other participants in the conference. This feature proves beneficial when you need to take notes, send an email, or look up information during the conference.
 
This guide explains the steps to implement the Picture-in-Picture (PiP) feature in a SwiftUI iOS application using VideoSDK. without relying on any third-party packages.

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ios_pip_mode_output_image.png' style={{height: '500px'}}/>

</center>


### Prerequisites
To implement this feature, you need to setup your own example with videosdk or you clone this [Quick Start Repository](https://github.com/videosdk-live/videosdk-rtc-ios-sdk-swiftui-example) and run the app. Once the app is running, we will start integrating PiP mode in the iOS app.

### Info.plist Configuration

```js
<key>NSCameraUsageDescription</key>
<string>Camera permission description</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone permission description</string>
```

### Xcode Capabilities

Enable the following capabilities in Xcode:

1. Go to your target settings.
2. Select the "Signing & Capabilities" tab.
3. Click the "+" button to add capabilities.
4. Add  **Background Modes**

For **Background Modes**, ensure the following options are checked:

- Audio, AirPlay, and Picture in Picture
- Voice over IP

<center>
    <img src='https://cdn.videosdk.live/website-resources/docs-resources/pip_flutter_ios_modes.png'/>
</center>


### Adding a PiP Toggle Button and Functions in `MeetingViewController`
Ensure that a button is added to the UI in MeetingViewController to enable and disable the PiP (Picture-in-Picture) feature.



**Swift:**

```js title="MeetingView.swift"
Button {
meetingViewController.checkPiPStatus()

if meetingViewController.isPiPActive {
    meetingViewController.stopPiP()
} else {
    meetingViewController.startPiP()
}
} label: {
Text(meetingViewController.isPiPActive ? "Disable PiP" : "Enable PiP")
    .foregroundStyle(Color.white)
    .font(.caption)
    .padding()
    .background(RoundedRectangle(cornerRadius: 25).fill(Color.indigo))
}
```

Inside the cloned project, in `MeetingViewController.swift`, we need to add functions to handle PiP mode activation and manage foreground/background states.


**Key Functions:**
- `startPiP()`: Initializes and starts PiP mode.
- `stopPiP()`: Stops PiP mode and restores the main UI.
- `handleEnterBackground()`: Ensures PiP remains active when the app goes into the background.
- `handleEnterForeground()`: Reconfigures PiP when the app returns to the foreground.

You can also copy the file from [Here](https://github.com/videosdk-live/videosdk-ios-pip-mode-example/blob/main/videosdk-swiftui-pipmode/MeetingSetup/MeetingViewController.swift)

**Swift:**

```js title="MeetingViewController.swift"
func startPiP() {
if pipVideoCallViewController == nil {
    pipVideoCallViewController = PiPVideoCallViewController(meetingViewController: self)
}
pipVideoCallViewController?.startPiP()
}
func stopPiP() {
pipVideoCallViewController?.stopPiP()
isPiPActive = false
}
```

# Implementing PiP Mode
PiP implementation consists of the following four key files:
- `PiPContainerView.swift` 
- `PiPVideoCallViewController.swift`
- `PiPFrameProcessor.swift`
- `PiPVideoView.swift`

You can copy these files from [github pip mode example](https://github.com/videosdk-live/videosdk-ios-pip-mode-example/tree/main/videosdk-swiftui-pipmode/PiPMode) and add them to your project.

## Architecture Diagram
Below is the which will explaining the PiP workflow:

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/ios_pip_mode_diagram.png' style={{height: '400px'}}/>

</center>

When the user clicks "Start PiP ",(In Our Case Enable PiP) the `PiPVideoCallViewController` fetches video tracks from VideoSDK and sends them to `PiPContainerView`, which manages the local and remote video views. These tracks are processed by `PiPFrameProcessor`, and the frames are rendered using AVSampleBufferDisplayLayer within `PiPVideoView` for real-time video display.


## File Breakdown
Each of the four files serves a specific purpose in enabling PiP mode.

### PiPVideoCallViewController.swift (PiP Video Call Manager)
When the user clicks "Enable PiP". [PiPVideoCallViewController](https://github.com/videosdk-live/videosdk-ios-pip-mode-example/blob/main/videosdk-swiftui-pipmode/PiPMode/PiPVideoCallViewController.swift) fetches the video tracks from the VideoSDK meeting and sends them to the PiPContainerView. And also manages the state of AVPictureInPictureControllerDelegate.
* Key Responsibilities:
    * Initializes a PiPContainerView that contains both local and remote video views.
    * Creates an AVPictureInPictureController to handle PiP behavior.
    * Updates video tracks dynamically based on users activity.
* How It Connects:
* Receives video tracks from Videosdk's meeting and updates PiPContainerView.
* Uses PiPContainerView to display the video.
* Calls updateVideoTracks() whenever video state changes.

### PiPContainerView.swift (Container for PiP Video Views)
* Purpose: Acts as a container for the local and remote video views inside PiP mode.and you can customize the [PiPContainerView.swift](https://github.com/videosdk-live/videosdk-ios-pip-mode-example/blob/main/videosdk-swiftui-pipmode/PiPMode/PiPContainerView.swift). as per you requirement. 
* Key Responsibilities:
    * Manages two PiPVideoView instances: localVideoView and remoteVideoView.
    * Updates video tracks when they change.
    * Arranges views properly using constraints.
* How It Connects:
* Receives video tracks from PiPVideoCallViewController.
* Calls addVideoTrack() on PiPVideoView to render video frames.
* Uses PiPFrameProcessor inside PiPVideoView to process and render frames.

### PiPVideoView.swift (Individual Video View)
* Purpose: [PiPVideoView.swift](https://github.com/videosdk-live/videosdk-ios-pip-mode-example/blob/main/videosdk-swiftui-pipmode/PiPMode/PiPVideoView.swift) Handles rendering of an individual video track (either local or remote).
* Key Responsibilities:
    * Uses AVSampleBufferDisplayLayer to display video frames.
    * Receives an RTCVideoTrack and processes frames using WebRTCFrameProcessor.
    * Ensures real-time rendering of WebRTC video.
* How It Connects:
* Receives an RTCVideoTrack from PiPContainerView.
* Passes the video track to PiPFrameProcessor for frame processing.

### PiPFrameProcessor.swift (Frame Processing)
* Purpose: [PiPFrameProcessor.swift](https://github.com/videosdk-live/videosdk-ios-pip-mode-example/blob/main/videosdk-swiftui-pipmode/PiPMode/PiPFrameProcessor.swift) Converts Videosdk's RTC video frames into a format that can be displayed in AVSampleBufferDisplayLayer.
* Key Responsibilities:
    * Converts RTCVideoFrame into CVPixelBuffer for rendering.
    * Handles frame rate and performance optimizations.
    * Uses a pixel buffer pool for efficient memory management.
* How It Connects:
* Receives video frames from PiPVideoView.
* Converts and renders frames into AVSampleBufferDisplayLayer


## Final Output

We have successfully implemented Picture-in-Picture (PiP) Mode for an iOS application using VideoSDK without any third-party packages. You can customize the view and optimize it as needed.


<div style={{textAlign: 'center'}}>



</div>

:::tip

Stuck anywhere? Check out this [example code](https://github.com/videosdk-live/videosdk-ios-pip-mode-example) on GitHub

:::

---

# Understanding Analytics Dashboard - iOS

Welcome to the world of actionable insights and empowered decision-making. VideoSDK's session analytics dashboard is your gateway to understanding, optimizing, and elevating every aspect of your sessions.

## Accessing Analytics Made Easy

Navigating through session data is a breeze with VideoSDK. Simply head to your session page at https://app.videosdk.live/meetings/sessions, where a treasure trove of session information awaits.

### How to Access Analytics?

Open Session Analytics effortlessly by following these steps:

1. **Click on Meeting-ID:**
    - Directly access analytics by clicking on the meeting-ID within the session table.
2. **Hover and Click View Analytics:**
    - Hover over a specific meeting row to reveal the **View Analytics** button in the Actions Column.
    - Click on **View Analytics** to open the Session Overview sidebar, unlocking a wealth of insights.

![Access Analytics](https://cdn.videosdk.live/website-resources/docs-resources/access_analytics.png)

---

There are three tabs available within the session analytics view:

## **1. Session Overview**

This tab provides an overview of the session, including its duration and participant details. You can explore individual participant statistics to understand their session performance better.

## **2. Errors**

In this tab, you can find information about any errors encountered during the session. It helps you identify and address issues like network problems or technical glitches promptly.

:::note

Session errors are visible with JS SDK v0.0.82 or higher, React SDK v0.1.85 or higher, and React Native v0.1.6 or newer versions.

:::

## **3. Session Stats**

Explore data and metrics sent and received by participants to measure performance of the session in this tab. It offers insights into data exchange among participants, including metrics on jitter, RTT, and packet loss, resolutions, and fps aiding in assessing communication efficiency.

Let's dive deeper into each of these tabs to gain a better understanding of session analytics.

# Session Overview

The session overview page is your compass in the sea of data. Here's what you'll uncover:

- **Meeting ID:** Unique identifier for the meeting in the format of `abcd-efgh-ijkl`.
- **Session ID:** Unique identifier for each session, uniquely identified by its `sessionId`.
- **Session Status:** Indicates if the session is ongoing or ended.
- **Session Initiating Time:** Time taken by the first participant to establish the connection.
- **Start and End Time:** Marks the start and end of the session.
- **Total Unique Participants Joined:** Total number of unique participants in the session.
- **Total Session Duration:** Overall duration of the session from start to end.
- **Total Participant Minutes:** A sum of all participant duration.
- **Recording, HLS, RTMP:** Additional services used in the session.

### Participant Table List

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for each participant.
- **Join Time:** Time taken by the participant to establish connection.
- **Duration:** Total time spent by this participant in the session.

### Efficient Session Management with Actions

Enhance your session management with streamlined actions:

- **Kick Out Participants:** Effortlessly remove/kickout participants from ongoing sessions.
- **Detailed Participant Analytics:**
- Hover over a specific participant row to reveal the `View Stats` button at the end of the row.
- Click on `View Stats` to open the Participant Overview sidebar.


![View Stats](https://cdn.videosdk.live/website-resources/docs-resources/view_stats.png)


## Explore Participant Insights

Discover valuable participant data that provides a clear view of engagement and experience:

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for better interaction.
- **Joined At:** Indicates the precise moment when participant connects to the session.
- **Left At:** Indicates the precise moment when participant left the session.
- **Total Duration:** Total duration of participant within that session.
- **Joining Time:** Time taken by the this participant to establish the connection.
- **Location:** Approx. geographic location from where the participant joined.
- **Platform:** Specifies whether participants are using a desktop or mobile device.
- **Device Info:** Offers details regarding the participant's device.
- **OS:** Provides information about the participant's OS.
- **Browser:** Provides specifics about the participant's browser
- **SDK Version:** Indicates the version of the SDK used by participants.

### Understanding Participant Call Health

We've developed call health to offer a rapid assessment of participant performance during calls. This feature highlights the performance of audio, video, and screen sharing audio-video separately. We've utilized color theory, with green indicating good performance, orange for moderate, and red for poor performance, to enhance clarity. For detailed insights, simply hover over the bars

![Participant Call Health](https://cdn.videosdk.live/website-resources/docs-resources/participant_call_health.png)

## Participant Session Stats

Dive into Participant Session Stats for valuable insights into your session experience! With just a click on `View Session Stats` at the bottom of the page, unlock a treasure trove of data crucial for understanding audio and video experiences.

Within this section, you can observe quality metrics for the selected participant, comparing them to others. Additionally, the `Sessions Stats` covers quality stats comparison for every participant. Keep reading to explore more about Session Stats.

**Visualizing Session Performance from Both Sides**

This section provides a two-sided view of your session's metrics.

- **Left Side: Sender Participant Graph** This section displays graphs representing the metrics sent by the sender participant.. Here, you can see how the various factors impacted the data you transmitted.
- **Right Side: Receiver Participant Graph** On the right side, you'll find a dropdown menu where you can select a specific participant. Choosing a receiver will display graphs showcasing the metrics **received by that participant**. This allows you to compare the sending experience (left side) with the receiving experience (right side) for different participants.

![VideoSDK Jitter Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_jitter_graph.png)

**See How Your Session Performed**

These metrics give you a clear picture of your session's quality. Understanding them helps you spot any issues and keep things running smoothly. Let's dive into what each metric means!

**Jitter:** Imagine your internet connection like a bumpy road. Jitter is how much those bumps cause your signal to bounce around. Less jitter means a smoother ride for your data (audio and video, threshold ≤ 30ms).

**RTT (Latency):** This is how long it takes for data to travel between you and the server you're connected to. Think of it like the time it takes for a message to get delivered – a lower RTT means a faster delivery (affects both audio and video, threshold ≤ 300ms).

**Bitrate:** This measures the amount of data flowing through your connection per second. Imagine it like the width of a water pipe – a higher bitrate allows for more data to flow, which can be good for high-quality audio/video or fast downloads.

**Packet Loss:** Think of data traveling in tiny packets. Packet loss is when some of those packets get dropped along the way. More packet loss means information might be missing, affecting things like audio/video quality or lag in games (threshold ≤ 5%).

**Resolution:** This refers to the sharpness and detail of an image or video. Think of it like the number of pixels on your screen – a higher resolution means a crisper picture (**Video Only**).

**FPS (Frames Per Second):** This measures how many images (frames) are displayed on your screen every second. Imagine it like a flipbook – a higher FPS creates a smoother and more fluid animation or video experience (**Video Only**).

![VideoSDK FPS Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_fps_graph.png)

![VideoSDK Resolution Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_resolution_graph.png)

---

# **Analyse Session Stats**

Similar to `Participant Session Stats`, this tab covers quality statistics sent by individual participants. You can select any participant to compare effectively with others.

Choose a sender participant from the dropdown menu on the left and select a recipient on the right to compare data over different time frames. This allows you to identify and explore issues within specific durations.

This tab covers the same metrics as covered in the `participant session stats`: Jitter, RTT (Latency), Bitrate, Packet-loss, Resolution (Video only), and FPS (Video only).

![VideoSDK Session Stats](https://cdn.videosdk.live/website-resources/docs-resources/session_stats.png)

---

# Understanding Call Quality - iOS

When developing a video call app, customer satisfaction heavily depends on your app's video and audio quality and its fluctuation.

## Call Quality

If we look at the video quality from the user's perspective, a good video quality can be defined as smooth and clear video, along with a crystal clear audio. If the same is viewed from the developer's perspective, a good video quality can be determined as a high resolution, high frame rate video with minimal latency along with a high bitrate audio with minimal audio loss.

## Factors affecting Quality

When it comes to measuring the video and audio quality of a call, there are multiple variables to consider, and the most common factors which affect the video and audio quality are:

### `1. Network Bandwidth`

- Network bandwidth is a measurement of a user's network capability to how large data can be received and send.
- If the bandwidth is low at participant side, he/she is likely to get pixelated or frozen video along with robotic voice or minor breaking in the audio.
- Frequent change in the network providers can also result in high fluctuation of the internet bandwidth, which can also result in poor quality video.

### `2. Latency`

- Latency basically means the time it takes for data to transfer from one machine to another.
- If the meeting is hosted in `Ohio` region, and users are joining from `Singapore` region, so this will create long delay for data to transfer from one machine to another, thus you should pick a server according to your user base.
- In VideoSDK you can set the server during creation of Meeting/Room.

### `3. CPU Usage`

- CPU Usage is an also quite determining factor as all the audio and video streams which are going out and coming in will have to encoded or decoded which will require a significant amount of computation.
- The high the resolution and frame rate of the videos, the larger would be the computation required, which can be a reason for the bottleneck of delivering a good quality video.
- If the CPU is being consumed heavily, it can also result in a choppy or robotic audio.

### `4. Camera and Mic Quality`

- The camera and microphone should capture good quality of streams so that remote user doesn't get low quality stream even if he/she has good network bandwidth

## Identifying the Quality Issues

In order to identify quality issues, VideoSDK collects multiple audio and video related metrics which can help in pinpointing the quality issues. Let's have a look at those metrics and understand what the indicates.

### `1. Resolutions and Framerates`

- Resolution and frame rate are key metrics for video quality in a video call app. Resolution refers to the number of pixels in a video image, while frame rate refers to the number of frames displayed per second.

- Higher resolutions and frame rates can provide better video quality, but they also require more bandwidth and processing power. It's important to optimize this metrics for the devices and network conditions of your users.

- For example, if most of your users are on mobile devices, a lower resolution and frame rate may be more appropriate to ensure smooth playback and minimize bandwidth usage.

- If most of your users are on mobile and desktop devices, having higher resolution for desktop and mid-resolutions for mobile devices can help in improving the performance and quality as we will be saving the bandwidth on the mobile end.

### `2. Bitrate`

- Bitrate is the number of bits per second send or received during the transmission of audio or video streams. Bitrate can be a key parameter to determine the quality of the audio or video streams, as it should be fine-tuned for each resolution to achieve the best match of performance and bandwidth utilization.

- If the users are having excellent network conditions, higher bitrate can result in much better video quality but on the other hand, having very high bitrates on the mobile devices can result in heating issues due to high computation required to encode and decode the videos.

##### Example

We joined using the same phone **(iPhone 14)**, but the resolution and bitrate were different, first participant having resolution **`1280x720`** with bitrate **`1442 kbps`** and second participant having resolution **`960x540`** with bitrate **`642 kbps`**, so as we can see both participants' video appeared to be of equal quality even though resolution and bitrate are different.

![resolution-and-bitrate](/img/resolution-and-bitrate.png)

### `3. Packet Loss`

- Packet loss is a metric that indicates how many data packets are lost during transmission from the sender to the receiver. Packet loss can occur due to network congestion, hardware or software issues, or network latency. Higher packet loss can result in poor video and audio quality, as the missing packets can cause gaps or distortions in the media stream.


<div style={{textAlign: 'center'}}>



</div>

### `4. Jitter`

- The audio and video packets are sent out at random intervals over a specified time frame as they are being sent between the server and client. Nevertheless, jitter is produced when there is a variation in transmitting or receiving this data packets as a result of a faulty network connection.

- When data packets delay while being transmitted to the participant, usually because the network is busy. They'll display as pixelated video on a video call or sound choppy, distorted, or robotic on a voice call as they arrive. They'll arrive at random intervals, creating jitter.

### `5. Round Trip Time (Latency)`

- Round trip time is the amount of time required to transmit the data packets to send or receive from the server. If the servers are located very far from the user's location, they can observe a high latency (delay).

- With VideoSDK, this factor is taken care of as we automatically choose the nearest available server for participants. But if you are geofencing to a certain region, you should make sure that you choose the server which will be nearest to your users.

<center>

![resolution-and-bitrate](/img/rtt.png)

</center>

## Checking Realtime Statistics

VideoSDK provides methods to check the realtime statistics of the audio and video of all the participants.

### `getVideoStats()`

- `getVideoStats()` returns an array of object containing the different quality parameters for video stream which can be accessed through the `Participant` class.

- This objects will have values for the specific participant's video stream resolution, frame rate, bitrate, jitter, round trip time, and packet loss.

<div style={{textAlign: 'center'}}>



</div>

### `getAudioStats()`

- `getAudioStats()` returns an array of object containing the different quality parameters for audio stream which can be accessed through the `Participant` class.

- This objects will have values for the specific participant's audio stream bitrate, jitter, round trip time and packet loss.

### `getShareStats()`

- `getShareStats()` returns an array of object containing the different quality parameters for screen share stream which can be accessed through the `Participant` class.

- This objects will have values for the specific participant's screen share stream resolution, frame rate, bitrate, jitter, round trip time, and packet loss.

## Quality analysis Graphs

For all the sessions taken using the VideoSDK, you can find the quality analysis graphs from the [VideoSDK Dashboard](https://app.videosdk.live/meetings/sessions) which can help you visualize the data you are seeing in realtime and identify the spikes of a few parameters happing during call which can help figure out the reason for the quality issue.

![quality analysis](/img/quality-analysis.png)

## API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [getVideoStats()](/ios/api/sdk-reference/participant-class/methods#getvideostats)
- [getAudioStats()](/ios/api/sdk-reference/participant-class/methods#getaudiostats)
- [getShareStats()](/ios/api/sdk-reference/participant-class/methods#getsharestats)


---

# Virtual Background - iOS

Virtual backgrounds let you replace your real background during video calls or meetings with a digital image or video. This can be useful for:

- Privacy: Hide your messy room or anything you don't want others to see.

- Focus: Minimize distractions and keep the focus on the conversation.

- Fun: Liven up the call with a cool background theme.

<center>
<img src='https://cdn.videosdk.live/website-resources/docs-resources/virtual-background-ios.jpg' style={{height: '400px'}}/>
</center>

## Virtual Background using `VideoSDKBackgroundProcessor`

This is the easiest way to enable virtual backgrounds in your app. VideoSDK provides a handy class called VideoSDKBackgroundProcessor that takes care of replacing your background for you. Here's a step-by-step guide:

### Toggle Virtual Background

- Virtual background can be enabled by setting VideoSDK's `VideoSDKBackgroundProcessor`'s instance using the `setVideoProcessor` method of `Meeting` class.

- To disbale the virtual background, simply pass `nil` in `setVideoProcessor` and virtual background will be replaced with the normal camera stream.

**Example Code:**



**Swift:**

```js
class MeetingViewController {
  //variable for keeping track of Virtual Background
  var isVirtualBackground: Bool = false

// source url for the background image (make sure background is in portrait, else might get undesired output).
 let backgroundSource = URL(string: "https://cdn.videosdk.live/virtual-background/cloud.jpeg")!
  //create an inctance of VideoSDKBackgroundProcessor
  let processor = VideoSDKBackgroundProcessor(backgroundSource: backgroundSource)
  
// Button when tapped will toggle the virtual background for local participant
  @IBAction func toggleVirtualBackground(_ sender: Any) {

   if isVirtualBackground {
  // Turn off virtual background
  meeting.setVideoProcessor(processor: nil)
  isVirtualBackground = false
} else {
  // Turn on virtual background
  meeting.setVideoProcessor(processor: processor)
  isVirtualBackground = true
}
}
}
```

### Changing Background Image

You can also change the background image dynamically using the `changeBackground` method of the `VideoSDKBackgroundProcessor` class.

**Swift:**

```js
class MeetingViewController {
  // processor instance
  // let processor = VideoSDKBackgroundProcessor()

  // Button when tapped will toggle the virtual background for local participant
  @IBAction func changeBackgroundTapped(_ sender: Any) {
// URL of new background image
let backgroundSource = URL(string: "https://cdn.videosdk.live/virtual-background/san-fran.jpeg")!

// Call changeBackground method of VideoSDKBackgroundProcessor
self.processor.changeBackground(backgroundSource: backgroundSource)
  }
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [setVideoProcessor()](/ios/api/sdk-reference/meeting-class/methods#setvideoprocessor)


---

# Run Http Live Streaming Project - iOS

Video SDK provides open-source sample project [videosdk-hls-ios-sdk-example](https://github.com/videosdk-live/quickstart/tree/main/ios-hls) on Github. This document introduces how to run this project.

## Prerequisites

- Xcode 15.0 or later
- An iOS device running iOS 13.0 or later.
- Valid Video SDK [Account](https://app.videosdk.live/)
- Valid developer signature and device permission settings.


### Generate Token

To manage secured communication, every participant that connects to a meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key`, which you can obtain from the [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

**For development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for obtaining a token involves generating it from your backend server which will help in **keeping your credentials safe**.
:::


## Run the Sample Project

### Step 1: Clone the sample project

Clone the repository to your local environment.

```js
$ git clone https://github.com/videosdk-live/quickstart.git
```

After that change directory to the project folder:

```js
cd quickstart -> ios-hls
```


### Step 2: Install the dependencies

Install the SPM dependencies through XCode on loading the project


### Step 3: Modify StartMeetingView.swift

Open your favorite code editor and add VideoSDK `AUTH_TOKEN` in it.

```js title="StartMeetingView.swift"
let AUTH_TOKEN: String = "YOUR_TOKEN"
```


### Step 4: Run the Sample App

Run the iOS app with **⌘ + R.** or the ** ▶ Run ** from toolbar.



---

# Run Interactive Live Streaming Project - iOS

Video SDK provides open-source sample project [videosdk-ils-iOS-sdk-example](https://github.com/videosdk-live/videosdk-ils-iOS-sdk-example) on Github. This document introduces how to run this project.

## Prerequisites

- Xcode 15.0 or later
- An iOS device running iOS 13.0 or later.
- Valid Video SDK [Account](https://app.videosdk.live/)
- Valid developer signature and device permission settings.


### Generate Token

To manage secured communication, every participant that connects to a meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key`, which you can obtain from the [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

**For development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for obtaining a token involves generating it from your backend server which will help in **keeping your credentials safe**.
:::


## Run the Sample Project

### Step 1: Clone the sample project

Clone the repository to your local environment.

```js
$ git clone https://github.com/videosdk-live/videosdk-ils-iOS-sdk-example.git
```

After that change directory to the project folder:

```js
cd VideoSDK-ILS-iOS-Example
```


### Step 2: Install the dependencies

Install the SPM dependencies through XCode on loading the project


### Step 3: Modify LiveStreamViewController.swift

Open your favorite code editor and add VideoSDK `AUTH_TOKEN` in it.

```js title="LiveStreamViewController.swift"
let AUTH_TOKEN: String = "YOUR_TOKEN"
```


### Step 4: Run the Sample App

Run the iOS app with **⌘ + R.** or the ** ▶ Run ** from toolbar.



---

# Run Audio & Video Call Project - iOS

Video SDK provides open-source sample project [videosdk-rtc-ios-sdk-example)](https://github.com/videosdk-live/videosdk-rtc-ios-sdk-example) on Github. This document introduces how to run this project.

## Prerequisites

- Xcode 15.0 or later
- An iOS device running iOS 13.0 or later.
- Valid Video SDK [Account](https://app.videosdk.live/)
- Valid developer signature and device permission settings.


### Generate Token

To manage secured communication, every participant that connects to a meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key`, which you can obtain from the [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

**For development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for obtaining a token involves generating it from your backend server which will help in **keeping your credentials safe**.
:::


## Run the Sample Project

### Step 1: Clone the sample project

Clone the repository to your local environment.

```js
$ git clone https://github.com/videosdk-live/videosdk-rtc-ios-sdk-example.git
```


### Step 2: Install the dependencies

Install all the pod dependencies

```js
pod install
```


### Step 3: Modify Constants.swift

Open your favorite code editor and add `AUTH_TOKEN` in it.

```js title="Constants.swift"
public let AUTH_TOKEN = "TEMPORARY-TOKEN"
```


### Step 4: Run the Sample App

Run the iOS app with **⌘ + R.** or the ** ▶ Run ** from toolbar.



---

# Scalability Guide for Large Participant Meetings

## Overview

This guide explains how to optimize performance when hosting video meetings with 10+ participants by using a key feature:

**Adaptive Subscriptions**: Intelligently prioritizes audio/video streams based on who's speaking

These features help solve common challenges in large meetings, such as excessive bandwidth consumption and poor quality for users with network constraints.

## Common Challenges in Large Meetings

### 1. Ineffective Stream Prioritization

**Problem**: All streams receive equal treatment regardless of importance.

**Impact**:

- Users with limited bandwidth experience poor quality
- Audio quality suffers when competing with video for resources
- Important speakers may not be clearly heard or seen

## Solution Features

### Adaptive Subscriptions

This feature optimizes bandwidth by prioritizing active speakers and managing stream quality.

**Key Benefits**:

- Identifies and prioritizes dominant speakers
- Intelligently manages bandwidth constraints
- Ensures clear audio even under network limitations
- Gives highest priority to pinned participants

**How It Works**:  
The system analyzes speaking patterns to detect active participants and adjusts stream priorities accordingly. For bandwidth-constrained users, it strategically pauses or lowers the quality of non-essential video streams. Pinned participants always receive the highest priority in stream allocation.

_Visual Illustration:_

<div style={{textAlign: 'center'}}>

<img src="https://cdn.videosdk.live/website-resources/docs-resources/adaptive_subscriptions_priority.png" alt="Viewport illustration" height="500px"/>
</div>

If a user experiences bandwidth constraints, Adaptive Subscriptions will pause the video streams in the following priority order:

1. Muted Participants
2. Least Dominant Speakers
3. Dominant Speakers

> If you want to achieve pin/unpin functionality, you can refer to [this documentation](https://docs.videosdk.live/ios/api/sdk-reference/participant-class/methods#pin)

## Implementation Guide

### Prerequisites

- SDK Version: 2.2.3 or later
- iOS Version: 13.0 or later
- Swift Version: 5.0 or later

### Enabling Adaptive Subscriptionss(BETA)

You can toggle this feature using these methods:

```swift
// Enable adaptive subscriptions
meeting?.enableAdaptiveSubscriptions();

// Disable adaptive subscriptions
meeting?.disableAdaptiveSubscriptions();
```

**Recommended Implementation**:

```swift
// Enable on meeting join

extension MeetingViewController: MeetingEventListener {

    onMeetingJoined(){
       meeting?.enableAdaptiveSubscriptions()
    }

}
```

### Stream Pause/Resume Events

When a video stream is paused or resumed, the system triggers events with specific reasons:

```swift
// Listen for video stream pause events

extension MeetingViewController: ParticipantEventListener {

  func onStreamPaused(kind: String, reason: String) {
      print("onStreamPaused reason : \(reason)")
    }
    
  func onStreamResumed(kind: String, reason: String) {
      print("onStreamResumed reason : \(reason)")
  }

}
```

**Pause Reasons**:

- `muted`: Participant has turned off their audio
- `leastDominance`: Participant hasn't spoken much in the meeting

**Resume Reasons**:

- `adaptiveSubscriptionsDisabled`: Feature was disabled
- `networkStable`: Network conditions have improved

> **Developer Tip**: When a stream is paused (e.g., due to network issues), always keep users in the loop by displaying a helpful UI indicator. For instance, render a message such as:
> "Paused: Waiting for stable connection..."

## Best Practices

- Enable adaptive subscriptions at the start of every meeting
- Design your UI to display indicators when a stream is paused
- Pin important participants to ensure they receive the highest streaming priority




---

# End-to-End Encryption (E2EE) - iOS

## Overview

End-to-end encryption (E2EE) ensures that your media content remains private and secure by encrypting it on the sender's device and decrypting it only on the receiver's device. This prevents intermediaries, including VideoSDK servers, from accessing or modifying the content.

E2EE is particularly important for applications in security-critical domains such as telehealth, finance, and legal services.

### How E2EE Works

- E2EE is applied at the room level, where a single shared key encrypts and decrypts all media tracks during a session.
- Participants without the key cannot access the media.
- The entire encryption process is handled client-side. VideoSDK does not access or store any encryption keys.

### Key Management & Distribution

You are **fully responsible** for generating, managing, and securely distributing encryption keys to all participants. VideoSDK **never stores, accesses, or transfers** your encryption keys.

- Common Key Distribution Approaches:
  - Generate the key **on your server** when creating a meeting.
  - Send the key securely along with the **meeting access token**.
  - Use **HTTPS-secured API calls** to fetch the key on the client.

:::important

⚠️ Ensure that all participants have access to the correct encryption key before joining the room.

:::

The table below shows the minimum SDK versions that support E2EE. All subsequent versions also include E2EE support.

| React Native | iOS   | Flutter | React | Android     | JavaScript |
| ------------ | ----- | ------- | ----- | ----------- | ---------- |
| 0.2.1        | 2.2.2 | 2.1.0   | 0.3.5 | 0.5.0 | 0.2.6      |

### Enabling E2EE in VideoSDK iOS

To enable E2EE in VideoSDK for iOS, follow these steps:

```js
  private func initializeMeeting(cameraPosition: AVCaptureDevice.Position? = .front, customVideoStream: CustomRTCMediaStream? = nil, customAudioStream: CustomRTCMediaStream? = nil) {
        // initialize
        meeting = VideoSDK.initMeeting(
            meetingId: meetingData.meetingId,
            participantName: meetingData.name,
            micEnabled: meetingData.micEnabled,
            webcamEnabled: meetingData.cameraEnabled,
            customCameraVideoStream: customVideoStream,
            customAudioTrack: customAudioStream,
        )
        // listener
        meeting?.addEventListener(self)
        //highlight-start
        // keySetup() for enabling E2EE
        keySetup()
        //highlight-end
        // join
        meeting?.join()
    }
    //highlight-start

    func keySetup() async {
        do {
            let customKeyProvider = try await BaseKeyProvider()
            try await customKeyProvider.setSharedKey("<Your Encryption Key>")
            VideoSDK.setKeyProvider(customKeyProvider)
        } catch {
            print("Error setting encryption keys: \(error.localizedDescription)")
        }
    }
    //highlight-end
```

### Additional Configuration Options

You can customize the encryption behavior by passing parameters while creating the BaseKeyProvider instance:

| Parameter                         | Type   | Description                                                                                                 |
| --------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| `discardFrameWhenCryptorNotReady` | `bool` | If `true`, frames will be discarded when the cryptor is not ready, ensuring no unencrypted content is sent. |

:::warning

Make sure to set the encryption key using `setSharedKey` before assigning the key provider with `setKeyProvider`, otherwise it will throw an error.

:::

### Event for E2EE State Changes

To monitor encryption state changes for each participant's media stream:

```js
func e2eeStateChanged(forParticipant participant: Participant, state: E2EEState, _ stream: MediaStream) {
    print("Participant: \(participant.displayName)")
    print("E2EE State: \(state)")
    print("Media Stream Kind: \(stream.kind)")
}
```

The possible values for `state` are:

| State             | Description                               |
| ----------------- | ----------------------------------------- |
| EncryptionSuccess | Media encryption is successfully applied. |
| DecryptionSuccess | Incoming media is successfully decrypted. |
| EncryptionFailed  | Encryption encountered an error.          |
| DecryptionFailed  | Decryption encountered an error.          |
| InternalError     | Internal processing error occurred.       |

### To Check Whether E2EE enable not

You can check whether E2EE is enabled by using `e2eeEnabled` property of `Meeting` class.

```js
let isE2EEEnabled = meeting.e2eeEnabled;
print("Is E2EE Enabled: (isE2EEEnabled)");
```

### Limitations

E2EE only applies to media. It does not apply to:

- Chat messages or metadata
- API calls and signaling data

These communications are still protected by TLS but are not encrypted end-to-end.

:::info

Recording and transcription features are not supported when End-to-End Encryption (E2EE) is enabled.

:::


---

<h1> {props.title} </h1>{" "}

### Why we are using JWT based Token ?

Token based authentication allows users to verify their identity by providing generated API key and secret.

We use JWT token for the authentication purpose because Token-based authentication is **widely used** in modern web applications and APIs because it offers several benefits over traditional authentication. For example, it can **reduce the risk of the credentials being misused**, and it allows for **more fine-grained control** over access to resources. Additionally, tokens can be easily revoked or expired, making it easier to manage access rights.

### How to generate Token ?

To manage secured communication, every participant that connects to the meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key` which you can get from [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

#### 1. Generating token from Dashboard

If you are looking to do **testing or for development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for getting token includes generating it from your backend server which will help in **keeping your credentials safe**.
:::

#### 2. Generating token in your backend

- Your server will generate access token using your API key and secret.
  - While generating a token, you can provide **expiration time, permissions and roles** which are discussed later in this section.
- Your client obtains token from your backend server.
- For token validation, client will pass this token to VideoSDK server.
- VideoSDK server will only allow entry in the meeting if the token is valid.

![img2.png](../../static/img/authentication-and-token.png)




Follow our official example repositories to setup token API [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)

### Payload while generating token

```js
{
 apikey: API_KEY, //MANDATORY
 permissions: [`allow_join`], //`ask_join` || `allow_mod` //MANDATORY
 version: 2, //OPTIONAL
 roomId: ROOM_ID, //OPTIONAL,
 participantId: PARTICIPANT_ID, //OPTIONAL
 roles: ['crawler', 'rtc'], //OPTIONAL
}
```

- **`apikey`(Mandatory)**: This must be the API Key generated from the VideoSDK Dashboard. You can get it from [here](https://app.videosdk.live/api-keys).

- **`permissions`(Mandatory)**: By providing the permissions, you can control what a participant can do in the meeting and whether he can join the meeting directly.

  Available permissions are:

  - **`allow_join`**: The participant is **allowed to join** the meeting directly.
  - **`ask_join`**: The participant is required to **ask for permission to join** the meeting. The participant having the permission `allow_join` can accept or reject a participant whenever someone wants to join.
  - **`allow_mod`**: The participant is **allowed to toggle** webcam & mic of other participants.

- **`version`(optional)**: For accessing the [v2 API](/api-reference/realtime-communication/intro), you need to provide `2` as the version value.

  - For passing `roomId`, `participantId` or `roles` parameters in payload, it is essential to set the version value to `2`.

- **`roomId`(optional)**: To provide customised access control, you can make the token applicable to a particular room by including the `roomId` in the payload.

- **`participantId`(optional)**: You can include the `participantId` in the payload to limit the token's access to a particular participant.

- **`roles`(optional)**:

  - **`crawler`**: This role is only for accessing [v2 API](/api-reference/realtime-communication/intro), you can not use this token for running the `Meeting`/`Room`.
  - **`rtc`**: This role is only allowed for running the `Meeting` / `Room`, with this role you can not use [server-side APIs](/api-reference/realtime-communication/intro).

Then, you have to sign this payload with your **`SECRET KEY`** and `jwt` options using the **`HS256 algorithm`**.

### Expiration time

You can set any expiration time to the token. But in the **production environment**, it is recommended to generate a token with **short expiration time** because by any chance if someone gets hold of the token, it won't be valid for a longer period of time.

### What happens if token is expired?

If your token is expired, the user won't be able to join the meeting and all the API calls will give error with message `Token is invalid or expired`.

:::note
Token is validated only once while joining the meeting, so if a person joins the meeting and the token gets expired after that, there won't be any issue in the current meeting.
:::

## How to check validity of token?

1. After generating the token, visit [jwt.io](https://jwt.io) and paste your token in the given area.
2. You will be able to see the payload you passed while generating the token and also be able to see the expiration time and token creation time.

![img1.png](../../static/img/validate-token.png)

## API Settings & Controls

The VideoSDK Dashboard provides a powerful [API Settings](https://app.videosdk.live/api-keys) section where you can configure various services and controls for your meetings. These settings allow you to customize the behavior of different features directly from the dashboard without requiring code changes.

## Audio/Video Configurations

:::note
Runtime configuration from the dashboard has higher precedence than static SDK configurations.
If a value is modified in the dashboard, it will override any previously defined SDK settings for that session.

Example:
Code: Video = HD → Dashboard: Video = Full HD → Applied: Full HD
:::

### Maximum Send Bitrate Per Participant

Control the maximum total upload bandwidth for all media streams from a single participant.

![Maximum Send Bitrate](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.00.11%E2%80%AFPM.png)

**Available Options:**
- **Auto**: Removes the upload bitrate limit (recommended for best quality)
- **SD (800kbps)**: Standard definition bitrate
- **HD (1500kbps)**: High definition bitrate
- **Full HD (3000kbps)**: Full high definition bitrate

:::tip
Setting this to **Auto** provides the best video quality as it removes upload bitrate constraints, allowing adaptive streaming based on network conditions.
:::

## Recording & Streaming Configuration

:::note
Recording and HLS follow a precedence-based configuration model:

API/SDK configuration → Highest priority
Dashboard configuration → Used only when no API values are defined

Any parameters explicitly set via the API will not be overridden by dashboard changes.
:::

### Recording Configuration

Configure recording settings for your meetings including layout, quality, and auto-start options.

![Recording Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.01.00%E2%80%AFPM.png)

**Recording Controls:**
- **Enabled**: Toggle to enable/disable recording functionality
- **Enabled Modes**: Choose between Video & Audio or Audio Only recording
- **Start Recording Automatically**: Auto-start recording when meeting begins
- **Layout Style**: Select Grid layout for recording composition
- **Maximum Tiles In Grid**: Set the number of participants visible in grid (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme for recordings
- **Video Orientation**: Choose between Landscape or Portrait mode
- **Recording Quality**: Select quality level (e.g., HD Medium)
- **Recording Mode**: Choose between Video & Audio or Audio Only

### HLS Streaming Configuration

Configure HTTP Live Streaming (HLS) settings for broadcasting your meetings.

![HLS Streaming Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.02.18%E2%80%AFPM.png)

**HLS Streaming Controls:**
- **Enabled**: Toggle to enable/disable HLS streaming
- **Enabled Modes**: Choose between Video & Audio or Audio Only streaming
- **Auto Start HLS**: Automatically start HLS when meeting begins
- **Record HLS Stream**: Enable recording of the HLS stream
- **Layout Style**: Select Grid layout for stream composition
- **Maximum Tiles In Grid**: Set the number of participants visible (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme
- **HLS Orientation**: Choose between Landscape or Portrait mode
- **HLS Quality**: Select streaming quality (e.g., HD Medium)
- **HLS Streaming Mode**: Choose between Video & Audio or Audio Only

### Additional Service Controls

Enable or disable additional services for your API key.

![Service Controls](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.08%E2%80%AFPM.png)

**Available Services:**
- **RTMP Output**: Enable RTMP streaming to external platforms
- **SIP Integration**: Enable SIP (Session Initiation Protocol) integration for telephony
- **Realtime Translation**: Enable real-time language translation in meetings

### Transcription & Summary

Configure transcription and domain whitelisting for your API key.

![Transcription Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.50%E2%80%AFPM.png)

**Transcription Controls:**
- **Enabled**: Toggle to enable/disable transcription and summary features
- **Whitelist Domain**: Add domain restrictions for API key usage
  - Enter domain names in the format `https://domain.name`
  - Click "Add Domain" to whitelist specific domains
  - Only whitelisted domains can use this API key
  - When no domains are whitelisted, the API key can be used from any domain


---

# Initialise Meeting - iOS

To configure a VideoSDK meeting you require two things, first the `token` which will be used for **Authentication** purpose and a `meetingId` which will be used to specify where a participant will join. Let's see each of the steps closely.

### Generating Token

You can generate a `token` in two ways:

1. **`Temporary Token`** : You can visit [Dashboard's API Key section](https://app.videosdk.live/api-keys) and generate the temporary token from there.

2. **`Server`** : You can setup **JWT** in backend and make an API call to get the token from your server.

To learn more about **Authentication** and token in detail you can follow [this guide](../server-setup).



**Swift:**

```js
// Update server url here.
let LOCAL_SERVER_URL = "http://192.168.0.101:9000"

class APIService {

class func getToken(completion: @escaping (Result

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [initMeeting](/ios/api/sdk-reference/initMeeting)


---

# Join Meeting - iOS

### Overview

After meeting initialization by `initMeeting()` it returns a new instance of `Meeting`. If you have not initialized a meeting yet, you can [follow the guide here.](./initialize-meeting) However, by default, it will not automatically join the meeting. Hence, to join the meeting you have to call `join()` .

### `join()`

- To join the meeting you can call the `join()` method of `Meeting` class.
- This method can be called after the meeting is initialized using `VideoSDK` class.



**Swift:**

```js
private func initializeMeeting(cameraPosition: AVCaptureDevice.Position? = .front) {
    
    // initialize
    meeting = VideoSDK.initMeeting(
        meetingId: "abcd-wxyz-efgh",
        participantId: "JD",
        participantName: "John Doe",
        micEnabled: true,
        webcamEnabled: true,
    )
    
    // Add event listener for listening upcoming events of meeting 
    // highlight-next-line
    meeting?.addEventListener(self)
    
    // join
    // highlight-next-line
    meeting?.join(cameraPosition: cameraPosition ?? .front) // .front, .back
}
```

### Events associated with Join

Following callbacks are received when a participant is successfully joined.

- [Local Participant](../concept-and-architecture#2-participant) will receive a [`onMeetingJoined`](/ios/api/sdk-reference/meeting-class/events#onmeetingjoined) event, when successfully joined.
- [Remote Participant](../concept-and-architecture#2-participant) will receive a [`onParticipantJoined`](/ios/api/sdk-reference/meeting-class/events#onparticipantjoined) event with the newly joined `Participant` object from the event callback.

**Swift:**

```js
extension MeetingViewController: MeetingEventListener {

// Event to know meeting is joined
//highlight-start
func onMeetingJoined() { 
    print("You just joined the meeting")
}
//highlight-end

// Event to know some other participant joined
//highlight-start
func onParticipantJoined(_ participant: Participant) {
    print("A new remote participant", \(participant.displayName) + "just joined the meeting")
}
//highlight-end
}
```


### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [initMeeting](/ios/api/sdk-reference/initMeeting)
- [join()](/ios/api/sdk-reference/meeting-class/methods#join)
- [onMeetingJoined()](/ios/api/sdk-reference/meeting-class/events#onmeetingjoined)
- [onParticipantJoined()](/ios/api/sdk-reference/meeting-class/events#onparticipantjoined)


---

# Leave or End Meeting - iOS

Participant can choose to leave the meeting without removing all the other participants. This is typically done by `Leave Meeting`.

Alternatively, if the participant is the host and the last person remaining in the session, they can choose `End Meeting` by removing all other participants, which will end the session for everyone.

### `leave()`

To leave the meeting without removing all the participant you need to call `leave()` method of `Meeting` class.

### `end()`

To leave the meeting by removing all the participant you need to call `end()` method of `Meeting` class.

:::note
This methods can be called after the meeting is joined successfully.
:::

#### Example



**Swift:**

```js
@IBAction func leaveMeetingButtonTapped(_ sender: Any) {
// leave meeting
//highlight-next-line
self.meeting?.leave()
}

@IBAction func endMeetingButtonTapped(_ sender: Any) {
// end meeting for everyone
//highlight-next-line
self.meeting?.end()
}
```

### Events associated with Leave

Following callbacks are received when a participant leaves the meeting.

- [Local Participant](../concept-and-architecture#2-participant) will receive a callback[`onMeetingLeft`](/ios/api/sdk-reference/meeting-class/events#onmeetingleft).
- All [remote participants](../concept-and-architecture#2-participant) will receive a callback [`onParticipantLeft`](/ios/api/sdk-reference/meeting-class/events#onparticipantleft) with Participant object.

### Events associated with End

Following callbacks are received when a participant ends the meeting.

- All [remote participants](../concept-and-architecture#2-participant) and local participant will receive a callback on [`onMeetingLeft`](/ios/api/sdk-reference/meeting-class/events#onmeetingleft) of [`MeetingEventListener`](/ios/api/sdk-reference/meeting-class/events) class.

**Swift:**

```javascript
extension MeetingViewController: MeetingEventListener {
  //highlight-start
func onMeetingLeft() {
    
    // remove listeners
    meeting?.localParticipant.removeEventListener(self)
    meeting?.removeEventListener(self)
    
    print("You left the meeting")
}

func onParticipantLeft(_ participant: Participant) {
    
    // remove listener
    participant.removeEventListener(self)
    
    print(participant.displayName, "just left the meeting")
}
  //highlight-end
}
```

### API Reference

The API references for all the methods and events utilised in this guide are provided below.

- [leave()](/ios/api/sdk-reference/meeting-class/methods#leave)
- [end()](/ios/api/sdk-reference/meeting-class/methods#end)
- [onMeetingLeft()](/ios/api/sdk-reference/meeting-class/events#onmeetingleft)
- [onParticipantLeft()](/ios/api/sdk-reference/meeting-class/events#onparticipantleft)


---

# Precall Setup - iOS

Picture this: before diving into the depths of a video call, imagine giving your setup a quick check-up, like a tech-savvy doctor ensuring all systems are a go. That's essentially what a precall experience does- it’s like your extensive debug session before the main code execution—a crucial step in ensuring your app's performance is top-notch.

## **Why is it necessary?**

Why invest time and effort into crafting a precall experience, you wonder? Well, picture this scenario: your users eagerly join a video call, only to encounter a myriad of technical difficulties—muted microphones, pixelated cameras, and laggy connections. Not exactly the smooth user experience you had in mind, right?

By integrating a robust precall process into your app, developers become the unsung heroes, preemptively addressing potential pitfalls and ensuring that users step into their video calls with confidence.

## **Using PreCall Functions**

### **Check Permissions**

- Begin by ensuring that your application has the necessary permissions to access user devices such as cameras and microphones.
- Utilize the `getAudioPermissionStatus()` and `getVideoPermissionStatus()` methods of the `VideoSDK` class to verify if permissions are granted.



**Swift:**

```js
let audioPermission = VideoSDK.getAudioPermissionStatus(); // audio permission status
let videoPermission = VideoSDK.getVideoPermissionStatus(); // video permission status
```

### **Request Permissions (if necessary)**

- If permission status is `notDetermined`, use the `getAudioPermission()` and `getVideoPermission()` methods of the `VideoSDK` class to prompt users to grant access to their devices.

- Calling the above functions will automatically handle the notDetermined state and prompt the user to grant permission.

**Swift:**

```js
class StartViewController: UIViewController {

override func viewDidLoad() {
    super.viewDidLoad()

    // UI Setup
    setupUI()

    // prompt user to grant permission when the app starts
    VideoSDK.getVideoPermission()
    VideoSDK.getAudioPermission()
}

func setupUI() {
    // your UI code
}
}
```

- If the permissions are `denied` or `restricted` after approving, you need to prompt user to manually approve the permissions from the Settings using the `handlePermission()` function of the `AuthorisationDelegate`. Below is an example on how you can do it.

**Swift:**

```js
class StartViewController: UIViewController {
// settings button
@IBOutlet weak var openSetting: UIButton!

override func viewDidLoad() {
    super.viewDidLoad()

    // UI Setup
    setupUI()

    // prompt user to grant permission when the app starts
    VideoSDK.getVideoPermission()
    VideoSDK.getAudioPermission()
}

func setupUI() {
    // you UI code
    ...
    settingsButton()
}
//sets the visibility of settings button
func settingsButton() {
    let audioStatus = VideoSDK.getAudioPermissionStatus()
    let videoStatus = VideoSDK.getVideoPermissionStatus()

    if (audioStatus == .authorised && videoStatus == .authorised) {
        openSetting.isHidden = true
    }
    else {
        openSetting.isHidden = false
    }
}
// settings button tapped
@IBAction func openSettingsButtonTapped(_ sender: Any) {
    handlePermission()
}
}
// implement Authorisation Delegate
extension StartViewController: AuthorisationDelegate {
func handlePermission() {
    guard let settingsURL = URL(string: UIApplication.openSettingsURLString) else { return }
            if UIApplication.shared.canOpenURL(settingsURL) {
                UIApplication.shared.open(settingsURL, options: [:], completionHandler: nil)
            }
}
}
```

### **Get Device Lists**

- Once you have the necessary permissions, Fetch the lists of available camera, audio device using the `getCameras()` and `getAudioDevices()` methods of the `VideoSDK` class respectively.

**Swift:**

```js
let cameras = VideoSDK.getCameras();
let audioDevices = VideoSDK.getAudioDevices();
```

### **Create Media Tracks**

- Create media tracks for the selected microphone and camera using the `createMicrophoneAudioTrack()` and `createCameraVideoTrack()` methods.
- Ensure that these tracks originate from the user-selected devices for accurate testing.

**Swift:**

```js
import WebRTC
// Create custom Video Track
guard let videoMediaTrack = try? VideoSDK.createCameraVideoTrack(
  // This will accept the enum value of CustomVideoTrackConfig which contains resolution (height x width) of video you want to capture.
  encoderConfig: .h720p_w1280p, // .h540p_w960p | .h720p_w1280p ... // Default : .h360p_w640p

  // It will specify whether to use front or back camera for the video track.
  facingMode: .front, // .back,  Default : .front

  // We will discuss this parameter in next step.
  multiStream:true // false,  Default : true

  // A video codec for compresses video data for efficient transmission over the internet, balancing quality and bandwidth usage.
  codec: .H264 // Default: .VP8

) else { return }

// Create custom Audio Track
guard let audioMediaTrack = try? VideoSDK.createAudioTrack(
noiseConfig: noiseConfig(
    noiseSupression: true,
    echoCancellation: true,
    autoGainControl: true,
    highPassFilter: true
  )
  )
else { return }
```

### **Passing States to Meeting**

- Ensure that all relevant states, such as microphone and camera status (on/off) are passed into the meeting from the precall screen.
- This can be accomplished by passing these crucial states and media streams onto the VideoSDK's `initMeeting`.
- By ensuring this integration, users can seamlessly transition from the precall setup to the actual meeting while preserving their preferred settings.

**Swift:**

```js
let meeting = VideoSDK.initMeeting(
  meetingId: "abcd-efgh-xyzw",
  participantId: "JD", // optional
  participantName: "John Doe",
  micEnabled: micStatus,
  webcamEnabled: webcamStatus
  customCameraVideoStream: videoMediaTrack, //optional
  customAudioStream: customAudioStream, //optional
  mode: .SEND_AND_RECV //optional (default mode is conference)
);
```

:::note

You can explore the complete implementation of the Precall functions in the official iOS SDK example [available here.](https://github.com/videosdk-live/videosdk-rtc-ios-sdk-example)

:::

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [getAudioPermissionStatus()](/ios/api/sdk-reference/videosdk-class/methods#getaudiopermissionstatus)
- [getVideoPermissionStatus()](/ios/api/sdk-reference/videosdk-class/methods#getvideopermissionstatus)
- [getAudioPermission()](/ios/api/sdk-reference/videosdk-class/methods#getaudiopermission)
- [getVideoPermission()](/ios/api/sdk-reference/videosdk-class/methods#getvideopermission)
- [getCameras()](/ios/api/sdk-reference/videosdk-class/methods#getcameras)
- [getAudioDevices](/ios/api/sdk-reference/videosdk-class/methods#getaudiodevices)


---

### Generate Token

To manage secured communication, every participant that connects to a meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key`, which you can obtain from the [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

**For development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for obtaining a token involves generating it from your backend server which will help in **keeping your credentials safe**.
:::



---

SIP Connect allows you to connect any SIP-compatible device or softphone to a VideoSDK room. This guide explains how to configure SIP for your VideoSDK account and connect a SIP user to an existing meeting.

## Architecture

The following diagram illustrates how SIP Connect works. A SIP user connects to the VideoSDK SIP Gateway, which then bridges the call to the VideoSDK Room.

![VideoSDK Telephony Workflow](https://strapi.videosdk.live/uploads/SIP_CONNECT_c81702f580.png)

## Steps

In this guide, we are using Twilio as the SIP provider, but you can choose from other providers like Plivo, Exotel, Telnyx, Ozontel, etc. The configuration process is similar across most providers.

### 1. Create VideoSDK Meeting


:::note
Ensure you have a VideoSDK meeting setup. If you don't have one, follow the <a href={props.quickStartLink}>Quick Start Guide</a> to create a basic video calling app.
:::

You can connect a SIP user to any active VideoSDK meeting. If you already have a meeting ID, you can proceed to the next step.



### 2. Create Inbound Gateway


An **Inbound Gateway** is required to receive calls from a SIP provider (like Twilio, Vonage, Telnyx) and route them to VideoSDK.

**twilio:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/inbound-gateways).
2. Navigate to **Telephony > Inbound Gateways**.
3. Click **Add Inbound Gateway**.
4. Enter a name and the phone number you purchased from your SIP provider.
5. Select the Geo Region option and choose where inbound SIP traffic should be routed (currently supported: India, US).
6. Click **Create**.
7. Copy the **Inbound Gateway SIP URI**
- Default: `sip:orgId.sip.videosdk.live`
- Regional (to restrict calls to a specific region): `sip:orgId.<region>.sip.videosdk.live`
8. Configure this URI as the **Origination SIP URI** in your SIP provider's dashboard (e.g., Twilio, Vonage, Telnyx).

<div style={{textAlign: 'center'}}>
  
</div>

---

**vonage:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/inbound-gateways).
2. Navigate to **Telephony > Inbound Gateways**.
3. Click **Add Inbound Gateway**.
4. Enter a name and the phone number you purchased from Vonage.
5. Select the Geo Region option and choose where inbound SIP traffic should be routed (currently supported: India, US).
6. Click **Create**.
7. Copy the **Inbound Gateway SIP URI**
- Default: `sip:orgId.sip.videosdk.live`
- Regional (to restrict calls to a specific region): `sip:orgId.<region>.sip.videosdk.live`
8. In your **Vonage Console**, go to your SIP Trunk settings.
9. Under **Inbound Calls**, select your region.
10. In the **URI** section, paste the Inbound Gateway SIP URI you copied.
11. Link the phone number you purchased to this trunk.

<div style={{textAlign: 'center'}}>
  
</div>

---

**telnyx:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/inbound-gateways).
2. Navigate to **Telephony > Inbound Gateways**.
3. Click **Add Inbound Gateway**.
4. Enter a name and the phone number you purchased from Telnyx.
5. Select the Geo Region option and choose where inbound SIP traffic should be routed (currently supported: India, US).
6. Click **Create**.
7. Copy the **Inbound Gateway SIP URI**
- Default: `sip:orgId.sip.videosdk.live`
- Regional (to restrict calls to a specific region): `sip:orgId.<region>.sip.videosdk.live`
8. In your **Telnyx Console**, go to **Connections** and create a new SIP Connection.
9. Set the type as **FQDN**.
10. Under **FQDN**, add the VideoSDK Inbound Gateway SIP URI you copied.
11. Assign the phone number you purchased to this connection.

<div style={{textAlign: 'center'}}>
  
</div>

---

**api:**

You can create an inbound gateway programmatically using the API.

```bash title="cURL"
curl --request POST \
  --url https://api.videosdk.live/v2/sip/inbound-gateways \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
"name": "My Inbound Gateway",
"numbers": ["+1234567890"]
  }'
```

> **API Reference**: [Create Inbound Gateway](/api-reference/realtime-communication/sip/inbound-gateway/create-inbound-gateway)



### 3. Create Outbound Gateway


An **Outbound Gateway** is used if you want to dial out to a SIP user from a VideoSDK meeting.

**twilio:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/outbound-gateways).
2. Navigate to **Telephony > Outbound Gateways**.
3. Click **Add Outbound Gateway**.
4. Enter a name.
5. Enter the **Termination SIP URI** provided by your SIP provider.
6. Enter the **Username** and **Password** for your SIP provider.
7. Set the Geo Region to route outbound calls through a specific region (currently supported: India, US).
8. Click **Create**.

<div style={{textAlign: 'center'}}>
  
</div>

---

**vonage:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/outbound-gateways).
2. Navigate to **Telephony > Outbound Gateways**.
3. Click **Add Outbound Gateway**.
4. Enter a name.
5. Enter the **Domain** you set up in your Vonage SIP Trunk settings.
6. Enter the **Username** and **Password** you configured in Vonage under **Outbound Calls**.
7. Set the Geo Region to route outbound calls through a specific region (currently supported: India, US).
8. Click **Create**.
9. **Note:** For outbound gateway numbers, do not use the `+` sign—just use the country code and number.

<div style={{textAlign: 'center'}}>
  
</div>

---

**telnyx:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/outbound-gateways).
2. Navigate to **Telephony > Outbound Gateways**.
3. Click **Add Outbound Gateway**.
4. Enter a name.
5. Enter the **SIP Domain** you configured in your Telnyx SIP Connection.
6. Enter the **Username** and **Password** you set up in Telnyx under **Outbound Authentication**.
7. Set the Geo Region to route outbound calls through a specific region (currently supported: India, US).
8. Click **Create**.

<div style={{textAlign: 'center'}}>
  
</div>

---

**api:**

To route outbound calls through a specific region, set the `geoRegion` property in the API request. By default, the SIP server region is automatically selected based on the location nearest to the dialed number (currently supported: India, US).

```bash title="cURL"
curl --request POST \
  --url https://api.videosdk.live/v2/sip/outbound-gateways \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
"name": "My Outbound Gateway",
"numbers": ["+1234567890"],
"address": "sip.provider.com",
"geoRegion" : "us002",
"auth": {
  "username": "sip_username",
  "password": "sip_password"
}
  }'
```

> **API Reference**: [Create Outbound Gateway](/api-reference/realtime-communication/sip/outbound-gateway/create-outbound-gateway)



### 4. Create Routing Rules


Routing rules determine how calls are handled.

#### Inbound Routing
For inbound calls, you need to route the call to a specific meeting room.

1. Go to **Telephony > Routing Rules**.
2. Click **Add Routing Rule**.
3. Select your **Inbound Gateway**.
4. Select the **Phone Number**.
5. Under **Dispatch**, select **Room**.
6. Choose **Dynamic** (creates a new room) or **Static** (connects to a specific room ID).
7. Click **Create**.

#### Outbound Routing
For outbound calls, the routing rule selects which Outbound Gateway to use based on the dialed number.

1. Go to **Telephony > Routing Rules**.
2. Click **Add Routing Rule**.
3. Select your **Outbound Gateway**.
4. Enter the **Phone Number** pattern (e.g., `+1*`).
5. Click **Create**.

<div style={{textAlign: 'center'}}>
  
</div>



## Connect SIP User

### Inbound Call
Now that everything is configured, a SIP user can join the meeting by simply dialing the phone number configured in the Inbound Gateway.
1. The call reaches your SIP provider.
2. The provider forwards it to VideoSDK.
3. VideoSDK checks the Routing Rule.
4. The user is connected to the VideoSDK Room.

### Outbound Call
To dial a SIP user from the meeting, you can use the `dispatch` API or the SDK method if available.

```bash title="cURL"
curl --request POST \
  --url https://api.videosdk.live/v2/sip/call \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "gatewayId": "outbound-gateway-id",
    "sipCallTo": "+1234567890",
    "destinationRoomId": "room-id"
  }'
```

> **API Reference**: [Make Outbound Call](/api-reference/realtime-communication/sip/calls/call-trigger)

## Webhooks

You can configure webhooks to receive real-time updates about SIP calls.

### Available Webhook Events
Below is the list of all supported webhook events:

| Event Name | Description |
| :--- | :--- |
| `call-started` | Triggered when a new outbound or inbound call is initiated. |
| `call-answered` | Triggered when the call is answered by the recipient. |
| `call-hangup` | Triggered when the call is completed or hung up by either party. |
| `call-transferred` | Call transferred to another destination. |
| `call-missed` | Triggered when the call is not answered or missed by the recipient. |
| `call-update` | Triggered when there is an update in the call status. |
| `call-ringing` | Triggered when the call is ringing at the destination endpoint. |
| `call-transfer-initiated` | Call transfer has been initiated. |
| `call-transfer-accepted` | Call transfer has been accepted by the target. |
| `call-transferring` | Call is being transferred to another destination. |
| `call-transfer-ringing` | Call is ringing at the transfer target. |
| `call-transfer-failed` | Call transfer failed. |

You can configure these in the **Telephony > Webhooks** section of the dashboard.

## Configuring Webhooks

You can set up webhooks using:

- **Dashboard:** Navigate to the SIP section and add a webhook by specifying your target URL and selecting the events you want to subscribe to.
- **API:** Use the `POST /v2/sip/webhooks` endpoint to register a webhook.



## API Reference

- [Create Webhook API](/api-reference/realtime-communication/sip/webhook/create-webhook)
- [Fetch all Webhook API](/api-reference/realtime-communication/sip/webhook/fetch-all-webhooks)
- [Fetch a Webhook API](/api-reference/realtime-communication/sip/webhook/fetch-webhook)
- [Update Webhook API](/api-reference/realtime-communication/sip/webhook/update-webhook)
- [Delete Webhook API](/api-reference/realtime-communication/sip/webhook/delete-webhook)



---

# Explore video & audio calling

This guide will get you running with the VideoSDK video & audio calling in minutes.

## Overview

At it's core, VideoSDK RTC is a distributed SFU. It eanbles highly scalable video & audio meetings unlike vanilla webRTC.

VideoSDK enables opportunity to integrate video & audio calling to Web, Android, IOS applications. it provides Programmable SDKs and REST APIs to build up scalable video conferencing applications.

## Terminology

#### **Meeting**

A Meeting represents real-time audio, video, and/or screen-share session, and is the basic building block for media sharing among participants.

#### **Participants**

Participants are the client applications that are connected to a Meeting and shares video & audio media with one another.

#### **Local Participant**

Local Participant producing audio or video stream from the local client's media sources

#### **Streams**

Streams are indiviual video & audio streams produced by the participants in the meeting

#### **Active Speaker**

Active Speaker represents the participant who is currently producing highest decibels audio stream (in other words speaking)

#### **Active Presenter**

Active Presenter is the participant who is currently sharing his/her screen as a video stream

#### **Main participant**

Main Participant represents the client who shall be displayed on the main screen indicating that he/she is either presenting or speaking

## Architecture

This diagram demonstrates end-to-end flow to implement video & audio calling, record calls and go-live on social media.



---

# Supported Device OS

:::note
The following device OS version represent the minimum required version to ensure full support for the listed features.
:::




##### SDK Size - 18 MB


---

# Supported platforms

## For video & audio calling SDK

This guide will follow installation guide for all the VideoSDK for Video & Audio Calling. Follow the below guide to install VideoSDK RTC in your website or App

## Web SDK

1. [JavaScript](/javascript/guide/video-and-audio-calling-api-sdk/getting-started)
2. [React JS](/react/guide/video-and-audio-calling-api-sdk/concept-and-architecture)

## Mobile SDK

1. [React Native Android](/react-native/guide/video-and-audio-calling-api-sdk/react-native-android-sdk)
2. [React Native IOS](/react-native/guide/video-and-audio-calling-api-sdk/react-native-ios-sdk)
3. [Android](/android/guide/video-and-audio-calling-api-sdk/concept-and-architecture)
4. [IOS](/ios/guide/video-and-audio-calling-api-sdk/concept-and-architecture)
5. [Flutter](/flutter/guide/video-and-audio-calling-api-sdk/concept-and-architecture)


---

# Post Transcription & Summary - iOS

This guide will walk you through the necessary steps to enable post-transcription functionality in your application, allowing users to access transcriptions of recorded meetings.

Moreover, VideoSDK offers flexibility in configuring post-time transcription, allowing you to set up webhooks for this purpose.

:::important

Please ensure eligibility prior to enabling post-transcription. For further details, please **[<u>contact us</u>](https://videosdk.live/contact)**.

:::

## Integrating Post Transcription Feature

![alt text](/img/transcription/post-transcription.png)

In the image above, the recording begins with transcription and summary features turned on. This triggers a webhook call for the start of recording. When the recording stops, another webhook is activated. After the recording, our transcriber starts transcribing, which in turn activates a webhook. Once the transcription is finished, it's sent to the summarizer for summary generation, and then another webhook is triggered.

### **Step 1: Configure Post Transcription & Summary**

- In this step, we set up the configuration for post transcription and summary generation. We define the webhook URL where the webhooks will be received.



**Swift:**

```js
// Webhook URL where, webhooks are received
let webhookUrl = "https://www.example.com";

// highlight-next-line
// Post Transcription Configuration
let transcription: PostTranscriptionConfig =  PostTranscriptionConfig(
        enabled: true,
        summary: SummaryConfig(
              enabled: true,
              prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
    )
)
```

### **Step 2: Start Recording with Transcription Configuration**

- Once the configuration is set, we initiate the recording process for the meeting, incorporating the transcription configuration we defined earlier.

**Swift:**

```js
// Start Recording
meeting.startRecording(webhookUrl: webHookUrl,transcription: transcription);
```

### **Step 3: Stop Recording**

- When the meeting concludes or recording is no longer needed, we stop the recording process.

**Swift:**

```js
// Stop Recording
meeting.stopRecording();
```

### **Step 4: Fetch Post Transcriptions**

- After the meeting recording is stopped, post transcription and summary data can be obtained using the [Post Transcription API](/api-reference/realtime-communication/fetch-post-transcriptions-summary).

- The API provides information such as the status of transcription, file paths for transcription data in various formats (JSON, SRT, TXT, TSV, VTT), and a summarized text file.

- The transcription document is structured as follows:

```json
{
  "id": "40b0a4ed-9842-40c9-a288-e4b1bf98a90a",
  "status": "completed",
  "roomId": "abc-xyzw-lmno",
  "sessionId": "621497578bea0d0404c35c4c",
  "recordingId": "65d303d6d2c373dfd71b38a2",
  "filePath": "https://cdn.videosdk.live/encoded/videos/dummy.mp4",
  "transcriptionFilePaths": {
    "json": "https://cdn.videosdk.live/transcriptions/dummy/dummy.json",
    "srt": "https://cdn.videosdk.live/transcriptions/dummy/dummy.srt",
    "txt": "https://cdn.videosdk.live/transcriptions/dummy/dummy.txt",
    "tsv": "https://cdn.videosdk.live/transcriptions/dummy/dummy.tsv",
    "vtt": "https://cdn.videosdk.live/transcriptions/dummy/dummy.vtt"
  },
  "summarizedFilePaths": {
    "txt": "https://cdn.videosdk.live/transcriptions/dummy/dummy-summary.txt"
  },
  "userStorage": null,
  "start": "2024-02-27T16:00:36.828Z",
  "end": "2024-02-27T16:01:46.939Z"
}
```

:::important

Please be aware that there may be a delay in processing the transcription data after the recording has been stopped. This delay could vary depending on factors such as server load and the duration of the meeting.

:::

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [startRecording()](/ios/api/sdk-reference/meeting-class/methods#startrecording)
- [stopRecording()](/ios/api/sdk-reference/meeting-class/methods#stoprecording)
- [fetchPostTranscriptions](/api-reference/realtime-communication/fetch-post-transcriptions-summary)


---

# Realtime Transcription - iOS

Realtime transcription allows you to transcribe audio content into text in real-time during a session. This guide will walk you through using the `startTranscription()` and `stopTranscription()` functions to manage realtime transcription in your application.

Moreover, VideoSDK offers flexibility in configuring real-time transcription, allowing you to set up webhooks for this purpose.

:::important

Please ensure eligibility prior to enabling post-transcription. For further details, please **[<u>contact us</u>](https://videosdk.live/contact)**.

:::

## Integrating Realtime Transcription Feature

![alt text](/img/transcription/realtime-transcription.png)

The above image represents,

1. **Start Transcription:** The SDK Client initiates real-time transcription using the `startTranscription` method.

2. **Resource Acquisition:** VideoSDK server requests necessary resources from transcription service.

   - If the request is denied, the server sends a `TRANSCRIPTION-FAILED` event to the SDK Client.
   - If the request is successful, the server sends a `TRANSCRIPTION-STARTED` event to the client, indicating that transcription has begun.

3. **Transcription Data:** As transcription progresses, the client receives `onTranscriptionText` event with data such as the text itself, participant ID, and timestamp.

4. **Stop Transcription:** When the client decides to stop transcription, it informs the VideoSDK server to release resources.
   - The server then sends a `TRANSCRIPTION-STOPPED` event to confirm that transcription has ended and resources are released.

### **Step 1: Configure Realtime Transcription**

- In this step, we set up the configuration for realtime transcription. We define the webhook URL where the webhooks will be received.

**Swift:**

```js
// highlight-next-line
// Realtime Transcription Configuration
let config =  TranscriptionConfig(
    webHookUrl: "YOUR_WEBHOOK_URL",
    summary: SummaryConfig(
      enabled: true,
      prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
    )
)
```

### **Step 2: Start realtime transcription**

- Initiate the realtime transcription using the `startTranscription()` method.



**Swift:**

```js
// Starts realtime transcription
@IBAction func startTranscriptionTapped(_ sender: Any) {

let config =  TranscriptionConfig(
        webHookUrl: "YOUR_WEBHOOK_URL",
        summary: SummaryConfig(
        enabled: true,
        prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
        )
)

meeting.startTranscription(config);
}
```

### **Step 3: Stop realtime transcription**

- Terminate the realtime transcription using the `stopTranscription() `method.

**Swift:**

```js
// Stops realtime transcription
@IBAction func stopTranscriptionTapped(_ sender: Any) {
meeting.stopTranscription();
}
```

### **Step 4: Listen for transcription events**

- Here, we configure the callback methods for transcription events.

**Swift:**

```js
import VideoSDKRTC

extension MeetingViewController: MeetingEventListener {

// Listen for transcription state changed event
func onTranscriptionStateChanged(state: TranscriptionState) {

    switch state {
    case .TRANSCRIPTION_STARTING:
        print("transcription starting")

    case .TRANSCRIPTION_STARTED:
        print("transcription started")

    case .TRANSCRIPTION_STOPPING:
        print("transcription stopping")

    case .TRANSCRIPTION_STOPPED:
        print("transcription stopped")
    }

}

// Listen for transcription text event
func onTranscriptionText(_ data: TranscriptionText) {
    print("transcription text: ", data.text)
    print("participant name", data.participantName)
}
}
```

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [startTranscription()](/ios/api/sdk-reference/meeting-class/methods#starttranscription)
- [stopTranscription()](/ios/api/sdk-reference/meeting-class/methods#stoptranscription)
- [onTranscriptionStateChanged](/ios/api/sdk-reference/meeting-class/events#ontranscriptionstatechanged)
- [onTranscriptionText](/ios/api/sdk-reference/meeting-class/events#ontranscriptiontext)


---

# Background Blur - iOS

Want to hide distractions behind you during video calls and maintain a professional or clutter-free appearance? Background blur with VideoSDK can help!

This guide explains how to achieve background blur in your iOS video calling app using the `VideoSDKVideoProcessor` protocol.

### How Background Blur Works

Background blur relies on a process called `person segmentation`. This involves intelligently separating you (the foreground) from the background in the video frame. Once the segmentation is done, the background is blurred while your image remains clear.

## Implementation Steps

Here's a breakdown of how to implement background blur in your app:

### 1. Process Video Frames with `onFrameReceived`

Within the `onFrameReceived` function provided by the `VideoSDKVideoProcessor` protocol, you'll perform the core background blur processing for each video frame:

- **Convert the Frame:** Transform the raw video frame from VideoSDK into a format suitable for processing (CVPixelBuffer).

- **Segment the Person (iOS 15.0+):** (If your app supports iOS 15.0 or later) Leverage ARKit's person segmentation API to intelligently separate you (the foreground) from the background.

- **Blur the Background**: Create a blurred version of the background to achieve the desired effect.

- **Composite the Image:** Seamlessly combine the blurred background with your clear image using a compositing technique.

- **Return the Processed Frame:** Convert the processed image back into a format that VideoSDK can use (RTCVideoFrame) and return it for transmission.

#### Code Example:

This code demonstrates a basic implementation of background blur using VideoSDKVideoProcessor



**Swift:**

```js
import ARKit
import CoreImage
import CoreImage.CIFilterBuiltins
import Foundation

// class conforming to VideoSDKVideoProcessor protocol.
class MyVideoProcessor: VideoSDKVideoProcessor {

func onFrameReceived(frame: RTCVideoFrame) -> RTCVideoFrame? {

    // 1. Convert the Frame: Transform raw frame to CVPixelBuffer
    let buffer = frame.buffer as! RTCCVPixelBuffer
    let pixelBuffer = buffer.pixelBuffer

    // 2. Segment the Person (iOS 15.0+): Separate foreground (you) from background
    if #available(iOS 15.0, *) {
        let request = VNGeneratePersonSegmentationRequest()
        request.qualityLevel = .balanced // Use balanced for smooth video experience
        let requestHandler = VNImageRequestHandler(cvPixelBuffer: pixelBuffer, options: [:])

        do {
            try requestHandler.perform([request])
            request.outputPixelFormat = kCVPixelFormatType_OneComponent8
            guard let result = request.results?.first as? VNPixelBufferObservation else {
                return nil
            }

            let maskPixelBuffer = result.pixelBuffer

            // 3. Blur the Background: Create a blurred version of the background
            if let compositedPixelBuffer = compositeImage(originalPixelBuffer: pixelBuffer, maskPixelBuffer: maskPixelBuffer) {

                // 4. Composite the Image: Combine clear image and blurred background
                let rtcPixelBuffer = RTCCVPixelBuffer(pixelBuffer: compositedPixelBuffer)
                let rtcVideoFrame = RTCVideoFrame(buffer: rtcPixelBuffer, rotation: frame.rotation, timeStampNs: frame.timeStampNs)
                return rtcVideoFrame;
            } else {
            }
        } catch {
            print("Error performing person segmentation request: \(error)")
        }
    }
    return nil
}

@available(iOS 13.0, *)
func compositeImage(originalPixelBuffer: CVPixelBuffer, maskPixelBuffer: CVPixelBuffer) -> CVPixelBuffer? {
    //original image
    let ciImage = CIImage(cvPixelBuffer: originalPixelBuffer)
    //masked image
    let maskCIImage = CIImage(cvPixelBuffer: maskPixelBuffer)

    //scale masked image
    let maskScaleX = ciImage.extent.width / maskCIImage.extent.width
    let maskScaleY = ciImage.extent.height / maskCIImage.extent.height
    let maskScaled =  maskCIImage.transformed(by: __CGAffineTransformMake(maskScaleX, 0, 0, maskScaleY, 0, 0))

    //apply blur to the original image
    let blurredImage = ciImage.applyingGaussianBlur(sigma: 2.0) //tweak sigma to adjust blur amount

    let blendFilter = CIFilter.blendWithMask()
    blendFilter.inputImage = ciImage
    blendFilter.backgroundImage = blurredImage
    blendFilter.maskImage = maskScaled

    let blendedImage = blendFilter.outputImage
    let ciContext = CIContext(options: nil)
    let filteredImageRef = ciContext.createCGImage(blendedImage!, from: blendedImage!.extent)
    let maskDisplayRef = ciContext.createCGImage(maskScaled, from: maskScaled.extent)

    var outputPixelBuffer: CVPixelBuffer?
    let attrs = [kCVPixelBufferCGImageCompatibilityKey: kCFBooleanTrue,
         kCVPixelBufferCGBitmapContextCompatibilityKey: kCFBooleanTrue] as CFDictionary
    let width = Int(blendedImage!.extent.width)
    let height = Int(blendedImage!.extent.height)

    let status = CVPixelBufferCreate(kCFAllocatorDefault, width, height, kCVPixelFormatType_32BGRA, attrs, &outputPixelBuffer)

    guard status == kCVReturnSuccess, let buffer = outputPixelBuffer else {
        return nil
    }
    ciContext.render(blendedImage!, to: buffer)
    return buffer
}
}
```

### 2. Activating Background Blur

Once you've created your `MyVideoProcessor` class, you can enable background blur in your video calls using the `setVideoProcessor` method of the Meeting class. This essentially tells VideoSDK to utilize your custom processor for processing the video stream before transmission.

**Swift:**

```js
class MeetingViewController {

// Indicates whether the background is currently blurred
let isBackgroundBlurred: Bool = false

// Button action that toggles the blur effects  for the local participant
@IBAction func toggleBackgroundBlur(_ sender: Any) {

    // If the background is already blurred, remove the video processor
    guard isBackgroundBlurred == false else {
        meeting.setVideoProcessor(processor: nil)
        self.isBackgroundBlurred = false
        return
    }

    // Otherwise, set the video processor to enable background blur
    let processor = MyVideoProcessor()
    meeting.setVideoProcessor(processor: processor)
    self.isBackgroundBlurred = true
}
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [setVideoProcessor()](/ios/api/sdk-reference/meeting-class/methods#setvideoprocessor)


---

# Video Processor - iOS

VideoSDK allows you to add custom effects to your video stream before it's transmitted during video calls. This lets you enhance your video in creative ways or achieve specific functionalities.

### Understanding Video Processing

Video processing involves manipulating the raw video data (frames) captured by your camera. VideoSDK provides a tool called `VideoSDKVideoProcessor` to achieve this.

### The `VideoSDKVideoProcessor` Protocol

`VideoSDKVideoProcessor` protocol defines a way for your code to interact with the video stream. It essentially lets you intercept each frame before it's sent and apply your processing logic.

#### Key Function: `onFrameReceived`

This is the heart of video processing with VideoSDK. Whenever a new video frame is captured by your camera, the `onFrameReceived` function is called. This function provides you with the raw frame data, allowing you to modify it as needed.

### How it Works:

1. **Implement the Protocol:** You create a class that implements the `VideoSDKVideoProcessor` protocol. Within this class, you define the `onFrameReceived` function.

2. **Process the Frame:** Inside the `onFrameReceived` function, you access the raw video frame data. You can then apply your desired effects or manipulations to this data.

3. **Return the Processed Frame:** After processing the frame, return the modified version back to VideoSDK. This processed frame will then be transmitted during the video call.

### Example: Grayscale Video

This example demonstrates a simple `CustomVideoProcessor` class that converts the video to grayscale:

```js
class CustomVideoProcessor: VideoSDKVideoProcessor {

  func onFrameReceived(frame: RTCVideoFrame) -> RTCVideoFrame? {
    // Convert the frame to grayscale (replace with your desired processing)
    let processedFrame = convertToGrayscale(frame)
    return processedFrame
  }

  private func convertToGrayscale(_ frame: RTCVideoFrame) -> RTCVideoFrame? {
    // Implement grayscale conversion logic here
    var newFrame = frame
    // ... (grayscale conversion logic)
    return newFrame
  }
}
```

## Setting the Video Processor

Once you have your custom processor class, use the `setVideoProcessor` method of the `Meeting` class to activate it. This tells VideoSDK to use your processor for processing the video stream.

**Example:**

```js
class MeetingViewController {
  @IBAction func setProcessorTapped(_ sender: Any) {
    let processor = CustomVideoProcessor()
    meeting.setVideoProcessor(processor: processor)
  }
}
```

#### Removing the Processor

To stop applying the video effects, simply call `setVideoProcessor` again but pass `nil` as the argument. This will disable your custom processor and revert to the original video stream.


---

### create_meeting()

The `create_meeting` function creates a new meeting using the provided token and returns a `create_meeting_result_t` structure.This structure contains two fields: `code` and `roomId`. 
   - If the operation succeeds, `code` is set to `0` and `roomId` holds the newly generated meeting ID. 
   - In case of an error, `code` will be non-zero and `roomId` will be `NULL`.

#### Parameters
- token
  - type: `String`
  - `REQUIRED`

#### Returns
- `create_meeting_result_t` containing `code` and `roomId`

#### Example
```c
  create_meeting_result_t result = create_meeting("Your - generated - token");
  if (result.room_id)
  {
    ESP_LOGI(TAG, "Created meeting roomId = %s", result.room_id);
    free(result.room_id);
  }
  else
  {
     ESP_LOGE(TAG, "Failed to create meeting");
  }
```

---

### init()

The init function  initializes a meeting using the provided configuration in `init_config_t`. A return value of `RESULT_OK` signifies success, while any other value indicates an error.

#### Parameters

```c
init_config_t init_cfg = {
      .meetingID = "Your meeting id",
      .token = "your authentication token",
      .displayName = "ESP32-Device",
      .audioCodec = AUDIO_CODEC_OPUS,
};
```

#### Returns
[`result_t`](iot_docs_versioned_docs/version-0.0.x/api/sdk-reference/result_code.md) enum.

#### Example
```c
result_t init_result = init(&init_cfg);
```

---

### startPublishAudio()

The `startPublishAudio` function captures audio from the IoT device and publishes it into the active meeting session. A return value of `RESULT_OK` means the audio stream has started successfully, while any `non-zero` result code indicates an error and the audio will not be published.

#### Parameters
- publisherId
  - type: `String`
  - `REQUIRED`

#### Returns
[`result_t`](iot_docs_versioned_docs/version-0.0.x/api/sdk-reference/result_code.md) enum.

#### Example
```c
result_t publish_result = startPublishAudio("your publisherId");
```

---

### startSubscribeAudio()

The `startSubscribeAudio` function subscribes to an audio stream from the meeting and plays it through the IoT device. 

The function returns a `result_t` code, where `RESULT_OK` indicates successful subscription and playback, while any non-zero value signals an error.

#### Parameters

- subscriberId
  - type: `String`
  - `REQUIRED`
  -  It represents your subscriber identity and can be `NULL` or an empty string (in which case the SDK generates one automatically).

- subscribeToId
  - type: `String`
  - `REQUIRED`
  - It specifies the participant’s id you want to subscribe to. If you want to subscribe to a specific participant, you must provide their `participantId` here. If you pass `NULL`, the SDK will automatically subscribe to the first participant who joined.

#### Returns
[`result_t`](iot_docs_versioned_docs/version-0.0.x/api/sdk-reference/result_code.md) enum.

#### Example

```c
result_t subscribe_result = startSubscribeAudio(subscriberId, NULL);
```

---

### stopPublishAudio()

The `stopPublishAudio` function stops the ongoing audio publishing task from the IoT device and removes the associated peer from the meeting. Returns a `result_t` code, where `RESULT_OK` indicates success and a non-zero value indicates failure.

#### Parameters
- void

#### Returns
[`result_t`](iot_docs_versioned_docs/version-0.0.x/api/sdk-reference/result_code.md) enum.

#### Example
```c
result_t stop_publish_result = stopPublishAudio();
```

---

### stopSubscribeAudio()

The `stopSubscribeAudio` function stops the ongoing audio consuming task from the IoT device and removes the associated peer from the meeting. Returns a `result_t` code, where `RESULT_OK` indicates success and a non-zero value indicates failure.

#### Parameters
- void

#### Returns
[`result_t`](iot_docs_versioned_docs/version-0.0.x/api/sdk-reference/result_code.md) enum.

#### Example
```c
result_t stop_subscribe_result = stopSubscribeAudio();
```

---

### leave()

The `leave` method removes the peer from the active meeting session and stops all ongoing tasks, including `publishing` and `subscribing`, if they are running.

#### Parameters
- void

#### Returns
[`result_t`](iot_docs_versioned_docs/version-0.0.x/api/sdk-reference/result_code.md) enum.

#### Example
```c
result_t leave_result = leave();
```


---

# VideoSDK Class - IoT

<div div id="tailwind" class="sdk-api-ref">

## Introduction






## IoT SDK Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [create_meeting](./methods#create_meeting)

</div>



<div class="col col--4 margin-bottom--sm" >

- [init](./methods#init)

</div>

<div class="col col--4 margin-bottom--sm" >

- [startPublishAudio](./methods#startpublishaudio)

</div>

<div class="col col--4 margin-bottom--sm" >

- [startSubscribeAudio](./methods#startsubscribeaudio)

</div>

<div class="col col--4 margin-bottom--sm" >

- [stopPublishAudio](./methods#stoppublishaudio)

</div>

<div class="col col--4 margin-bottom--sm" >

- [stopSubscribeAudio](./methods#stopsubscribeaudio)

</div>


<div class="col col--4 margin-bottom--sm" >

- [leave](./methods#leave)

</div>



</div>

</div>


---

# Result Code - IoT SDK

This file defines all possible result codes returned by the VideoSDK functions. Each result code is represented as an enum constant, making it easier for developers to identify, handle, and debug errors in a standardized way across publishing, subscribing, and other SDK operations.


| **Enum Constant** | **Value** | **Description** |
| --- | --- | --- |
| `RESULT_OK` | 0 | Operation completed successfully with no errors. |
| `SSL_CONNECT_FAILED` | 3001 | SSL handshake errors occur when the client and server fail to establish a secure connection due to mismatched protocols, certificates, or cipher suites. |
| `HTTP_REQUEST_FAILED` | 3002 | The HTTP request could not be sent from the device, or the server did not respond to the request. |
| `MEMORY_ALLOC_FAILED` | 3003 | The system failed to allocate memory because the requested buffer size exceeded the available heap. |
| `DEVICE_NOT_SUPPORTED` | 3004 | The selected device/board is not supported by the SDK or its drivers, indicating a configuration mismatch. To resolve this, try using a supported board. |
| `NULL_PARAMETER` | 3005 | A function call failed because a required input parameter was `NULL` or empty, resulting in an invalid operation. Ensure all required parameters are properly initialized before invoking the function. |
| `INIT_BOARD_FAILED` | 3006 | Initialization of the board or audio codec hardware failed, preventing proper device setup. |
| `PEER_INIT_FAILED` | 3007 | SRTP connection initialization failed due to cryptographic or configuration errors. |
| `TASK_ALREADY_STARTED` | 3008 | An attempt was made to start a task that was already running. To resolve this, stop the task first and then try again. |
| `PUBLISH_MUTEX_CREATE_FAILED` | 3009 | Failed to create a mutex required for synchronizing the media publishing operation. |
| `AUDIO_CODEC_INIT_FAILED` | 3010 | Audio codec initialization failed due to a codec mismatch. Try using a different codec to resolve the issue. |
| `PUBLISH_PEER_CONNECTION_FAILED` | 3011 | The peer connection setup for publishing failed, usually due to signaling or transport issues. |
| `PUBLISH_MEMORY_ALLOC_FAILED` | 3012 | The system failed to allocate the memory required for the publishing process. |
| `PUBLISH_TASK_CREATE_FAILED` | 3013 | Task creation for handling media publishing failed, often due to insufficient or incorrect parameters. |
| `SUBSCRIBE_MUTEX_CREATE_FAILED` | 3014 | Failed to create a mutex required for synchronizing the media subscription operation. |
| `SUBSCRIBE_PEER_CONNECTION_FAILED` | 3015 | The peer connection setup for subscribing to media failed, typically due to negotiation or network errors. |
| `SUBSCRIBE_MEMORY_ALLOC_FAILED` | 3016 | The system failed to allocate the memory required for the subscribing process. |
| `SUBSCRIBE_TASK_CREATE_FAILED` | 3017 | Task creation for handling subscriptions failed, often due to insufficient resources. |
| `STOP_PUBLISH_TASK_CREATE_FAILED` | 3018 | Failed to create a task for stopping the publishing process cleanly. |
| `STOP_SUBSCRIBE_TASK_CREATE_FAILED` | 3019 | Failed to create a task for stopping the subscribing process cleanly. |
| `CANDIDATE_PAIR_FAILED` | 3020 | ICE candidate pair checks failed, which means no valid network path was found between peers. |
| `DTLS_HANDSHAKE_FAILED` | 3021 | The DTLS handshake between peers failed due to a certificate or cryptographic mismatch. |
| `LEAVE_FAILED` | 3022 | The `leave()` function call failed, so the client could not properly exit the session. |
| `INIT_NOT_CALLED` | 3023 | This error occurs when the `init()` function was not called before using other functions like `publish()` or `subscribe()`. To resolve this, call `init()` first. |
| `DUPLICATE_ID` | 3024 | The `subscriberId` and `publisherId` must be unique for each participant. If a duplicate ID is detected, the SDK returns a `DUPLICATE_ID` result code. To resolve this, please ensure your IDs are unique. |

---

# Getting Started - IoT SDK

The IoT SDK is a natively written SDK in C, compatible with ESP32-S3 microcontrollers.  

## Installing the IoT SDK

The IoT SDK enables real-time communication for microcontrollers and follows the same terminology as other SDKs.  

### Step 1: Add the VideoSDK IoT Component to Your IoT Project

To integrate the IoT SDK component, clone the repository below.

```
git clone https://github.com/videosdk-live/IoTSdk
```

After cloning, copy the component's local path and provide it in the `idf_component.yml` file as shown below.
```yml title="main/idf_component.yml"
dependencies:
  IoTSdk: 
    path: // Full local path of the component
  // your existing dependencies ...
```


---

# Publish Audio - IoT SDK

The Audio publishing feature allows IoT devices to stream audio content into meetings, enabling real-time audio communication and integration with your VideoSDK-powered applications.

### `startPublishAudio()`

- Initiates publishing audio data from your IoT device into the active meeting session.

This function requires one parameter:

 - publisherId: Your unique `publish` identifier. This can be set to `NULL` or an `empty` string, in which case the SDK will generate a random publish ID for you.

:::note
- You must call the `init()` method before invoking `startPublishAudio()`. If not, the function will return an `INIT_NOT_CALLED` result code.

- Only one publish task can run at a time. If another publsih task is already active, calling this function again will result in a `TASK_ALREADY_STARTED` result code.


:::caution
The subscriberId and publisherId must be unique for each participant in the meeting. If a duplicate ID is detected, the SDK will return a DUPLICATE_ID result code. To resolve this please recheck your (subscriberId and publisherId).
:::

#### Example

``` c 
#include "videosdk.h"
#include "esp_log.h"
char *subscriberId;
void app_main(){
// Call the function from videosdk.c and pass publisherId if required
  //highlight-next-line
  result_t publish_result = startPublishAudio("your publisherId");
  ESP_LOGI("Publish Result: %d", publish_result);
}
```

### `stopPublishAudio`

- The `stopPublishAudio()` function stops audio publishing and removes the peer from the active meeting session.
- When invoked, it halts all ongoing audio publishing processes and ensures that the peer associated with the audio stream is cleanly disconnected from the meeting.


#### Example

``` c 
#include "videosdk.h"
#include "esp_log.h"
void app_main(){
// simply call the function present in videosdk.c file
  //highlight-next-line
  result_t stop_publish_result = stopPublishAudio();
  ESP_LOGI("Stop Publish Result: %d", stop_publish_result);
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startPublishAudio](/iot/api/sdk-reference/Methods#startpublishaudio)
- [stopPublishAudio](/iot/api/sdk-reference/Methods#stoppublishaudio)


---

# Result Code - IoT SDK

This file defines all possible result codes returned by the VideoSDK functions. Each result code is represented as an enum constant, making it easier for developers to identify, handle, and debug errors in a standardized way across publishing, subscribing, and other SDK operations.


| **Enum Constant** | **Value** | **Description** |
| --- | --- | --- |
| `RESULT_OK` | 0 | Operation completed successfully with no errors. |
| `SSL_CONNECT_FAILED` | 3001 | SSL handshake errors occur when the client and server fail to establish a secure connection due to mismatched protocols, certificates, or cipher suites. |
| `HTTP_REQUEST_FAILED` | 3002 | The HTTP request could not be sent from the device, or the server did not respond to the request. |
| `MEMORY_ALLOC_FAILED` | 3003 | The system failed to allocate memory because the requested buffer size exceeded the available heap. |
| `DEVICE_NOT_SUPPORTED` | 3004 | The selected device/board is not supported by the SDK or its drivers, indicating a configuration mismatch. To resolve this, try using a supported board. |
| `NULL_PARAMETER` | 3005 | A function call failed because a required input parameter was `NULL` or empty, resulting in an invalid operation. Ensure all required parameters are properly initialized before invoking the function. |
| `INIT_BOARD_FAILED` | 3006 | Initialization of the board or audio codec hardware failed, preventing proper device setup. |
| `PEER_INIT_FAILED` | 3007 | SRTP connection initialization failed due to cryptographic or configuration errors. |
| `TASK_ALREADY_STARTED` | 3008 | An attempt was made to start a task that was already running. To resolve this, stop the task first and then try again. |
| `PUBLISH_MUTEX_CREATE_FAILED` | 3009 | Failed to create a mutex required for synchronizing the media publishing operation. |
| `AUDIO_CODEC_INIT_FAILED` | 3010 | Audio codec initialization failed due to a codec mismatch. Try using a different codec to resolve the issue. |
| `PUBLISH_PEER_CONNECTION_FAILED` | 3011 | The peer connection setup for publishing failed, usually due to signaling or transport issues. |
| `PUBLISH_MEMORY_ALLOC_FAILED` | 3012 | The system failed to allocate the memory required for the publishing process. |
| `PUBLISH_TASK_CREATE_FAILED` | 3013 | Task creation for handling media publishing failed, often due to insufficient or incorrect parameters. |
| `SUBSCRIBE_MUTEX_CREATE_FAILED` | 3014 | Failed to create a mutex required for synchronizing the media subscription operation. |
| `SUBSCRIBE_PEER_CONNECTION_FAILED` | 3015 | The peer connection setup for subscribing to media failed, typically due to negotiation or network errors. |
| `SUBSCRIBE_MEMORY_ALLOC_FAILED` | 3016 | The system failed to allocate the memory required for the subscribing process. |
| `SUBSCRIBE_TASK_CREATE_FAILED` | 3017 | Task creation for handling subscriptions failed, often due to insufficient resources. |
| `STOP_PUBLISH_TASK_CREATE_FAILED` | 3018 | Failed to create a task for stopping the publishing process cleanly. |
| `STOP_SUBSCRIBE_TASK_CREATE_FAILED` | 3019 | Failed to create a task for stopping the subscribing process cleanly. |
| `CANDIDATE_PAIR_FAILED` | 3020 | ICE candidate pair checks failed, which means no valid network path was found between peers. |
| `DTLS_HANDSHAKE_FAILED` | 3021 | The DTLS handshake between peers failed due to a certificate or cryptographic mismatch. |
| `LEAVE_FAILED` | 3022 | The `leave()` function call failed, so the client could not properly exit the session. |
| `INIT_NOT_CALLED` | 3023 | This error occurs when the `init()` function was not called before using other functions like `publish()` or `subscribe()`. To resolve this, call `init()` first. |
| `DUPLICATE_ID` | 3024 | The `subscriberId` and `publisherId` must be unique for each participant. If a duplicate ID is detected, the SDK returns a `DUPLICATE_ID` result code. To resolve this, please ensure your IDs are unique. |

---

# Subscribe Audio - IoT SDK

The Audio subscribing feature allows IoT devices to receive and render audio streams from other participants in a meeting. This enables real-time playback of audio from remote peers in your VideoSDK-powered applications.

### `startSubscribeAudio()`

The `startSubscribeAudio()` function initiates the process of subscribing to another participant’s audio stream. This allows your IoT device to receive and render audio from a specified peer in the active meeting.

This function requires two parameters:

 - `subscriberId`: Your unique subscriber ID. This can be set to `NULL` or an `empty` string, in which case the SDK will generate a random subscriber ID for you.
 - `subscribeToId` : It specifies the participant’s id that you want to subscribe to. If you want to subscribe to a specific participant, you must provide their `participantId` here. If you pass `NULL`, the SDK will automatically subscribe to the first participant who joined.


:::note
- You must call the `init()` method before invoking `startSubscribeAudio()`. If not, the function will return an `INIT_NOT_CALLED` result code.

- Only one subscribe task can run at a time. If another subscribe task is already active, calling this function again will result in a `TASK_ALREADY_STARTED` result code.

:::

:::caution
The subscriberId and publisherId must be unique for each participant in the meeting. If a duplicate ID is detected, the SDK will return a DUPLICATE_ID result code. To resolve this please recheck your subscriberId and publisherId.
:::

#### Example

``` c 
#include "videosdk.h"
#include "esp_log.h"

void app_main() {
  // Ensure init() is called before this
  char *subscriberId = "your subscriberId";  // replace it with your subscriber Id
  char *subscriberToId = "remoteParticipant123";  // ID of participant to subscribe
  
  //highlight-next-line
  result_t subscribe_result = startSubscribeAudio(subscriberId, subscriberToId);
  ESP_LOGI("Subscribe Result: %d", subscribe_result);
}
```

### `stopSubscribeAudio`

- The `stopSubscribeAudio()` function stops the active audio subscription. 
- When invoked, it halts all ongoing subscription processes, terminates the `subscribe` task, and `removes` the peer from the active meeting.

#### Example

``` c 
#include "videosdk.h"
#include "esp_log.h"

void app_main() {
  // Call the function to stop the active subscription task
  //highlight-next-line
  result_t stop_subscribe_result = stopSubscribeAudio();
  ESP_LOGI("Stop Subscribe Result: %d", stop_subscribe_result);
}
```


## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startSubscribeAudio](/iot/api/sdk-reference/Methods#startsubscribeaudio)
- [stopSubscribeAudio](/iot/api/sdk-reference/Methods#stopsubscribeaudio)


---

# Initialise Meeting - IoT

To configure a VideoSDK meeting you require two things, first the `token` which will be used for **Authentication** purpose and a `meetingId` which will be used to specify where a participant will join. Let's see each of the steps closely.

### Generating Token

You can generate a `token` in two ways:

1. **`Temporary Token`** : You can visit [Dashboard's API Key section](https://app.videosdk.live/api-keys) and generate the temporary token from there.

2. **`Server`** : You can setup **JWT** in backend and make an API call to get the token from your server.

To learn more about **Authentication** and token in detail you can follow [this guide](../../authentication-and-tokens).





### Generating Meeting Id

For generating the meetingId you can use the function present in the IoT Sdk which is `create_meeting` which will return `create_meeting_result_t`. 

- `create_meeting_result_t` contains two fields: 
     1. Result Code
     2. room_id 

:::note  
If there is any error in the code, the function will stop performing its task and it will return the result code defined in [`result_t`](/iot/guide/video-and-audio-calling-api-sdk/audio-call/handling-media/result-code) (please refer to this) in such cases, it will return `NULL` in `room_id`.  
:::

```js

char * token = "Generated token from Dashboard/API";
create_meeting_result_t result = create_meeting(token);
if (room_id) {
  ESP_LOGI(TAG, "Created meeting roomId = %s", result.room_id);
  free(result.room_id);
} else {
  ESP_LOGE(TAG, "Failed to create meeting");
}
```

### Initialization of Meeting
- This function initiates the VideoSDK IoT client with the configuration provided in an `init_config_t` structure.
- If the initialization succeeds it will return 0; otherwise it returns an error. 
:::note
This function must be called before starting publish or subscribe operations.
:::
```c
init_config_t init_cfg = {
      .meetingID = "Your meeting id ",
      .token = "your authentication token",
      .displayName = "ESP32-Device",
      .audioCodec = AUDIO_CODEC_OPUS,
  };

init(&init_cfg);

```

- **`MeetingId`** :

  - MeetingId is unique identifiers that allow participants to join a specific meeting or room.
  - It will be in the format of `xxx-yyy-zzz` and will be generated using the [create_meeting method](../setup-call/init_call.md#generating-meeting-id) or [VideoSDK's Room API](/api-reference/realtime-communication/create-room).

- **`token`** :
  -  A unique token allocated for each user by the videosdk.
  -  This token allows to authorize meeting participants.

- **`displayName`**:

  - This will represent the name of the participant in the meeting.
  - It will accept `String` type value.

- **`audiocodec`**:

  - An audio codec is a software component that encodes and decodes digital audio data.
  - This enum `audio_codec_t` defines the supported audio codecs for the system, where PCMA and PCMU are standard telephony codecs, and OPUS is a modern codec optimized for real-time audio.

```c
typedef enum {
  AUDIO_CODEC_PCMA,
  AUDIO_CODEC_PCMU,
  AUDIO_CODEC_OPUS,
} audio_codec_t;
```
  :::tip
  - The default audio codec is OPUS. It can be configured via audio_codec_t.                                             
     Example: .audioCodec = AUDIO_CODEC_PCMA
:::
### Example code 

```c

void app_main(void) {
  /*This function allow us to create a Meeting ID with the help of the token and
  on passing the wrong token it returns an error "Failed to created meeting"
  */
  char * token = "Generated token from Dashboard/API";
  //highlight-next-line
  create_meeting_result_t result = create_meeting(token);
  if (room_id) {
    ESP_LOGI(TAG, "Created meeting roomId = %s", result.room_id);
    free(result.room_id);
  } else {
    ESP_LOGE(TAG, "Failed to create meeting");
  }
/* this function allow us to create a meeting by authenticating
  the meetingID, token, audioCodec and dislayName */
  //highlight-next-line
  init_config_t init_cfg = {
      .meetingID = "your meeting id ",
      .token = "your metting id npm run dev",
      .displayName = "ESP32-Device",
      .audioCodec = AUDIO_CODEC_PCMA,
  };

  //highlight-next-line
  init(&init_cfg);

  while (1) {
    vTaskDelay(pdMS_TO_TICKS(10));
  }
}

```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [create_meeting](/iot/api/sdk-reference/Methods#create_meeting)
- [init](/iot/api/sdk-reference/Methods#init)



---

# Leave Meeting - IoT SDK
A participant can leave the meeting without affecting other participants. This is typically done using the `Leave Meeting` option present in the IoT SDK.


### `leave()`

To leave the meeting, you need to call the `leave()` method.
#### Example

``` c 
#include "videosdk.h"
#include "esp_log.h"

void app_main(){
  // call leave method and it will stop all running task and will leave the meeting. 
  //highlight-next-line
  result_t leave_result = leave();
  ESP_LOGI("Leave Result: %d", leave_result);
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [leave](/iot/api/sdk-reference/Methods#leave)

---

<h1> {props.title} </h1>{" "}

### Why we are using JWT based Token ?

Token based authentication allows users to verify their identity by providing generated API key and secret.

We use JWT token for the authentication purpose because Token-based authentication is **widely used** in modern web applications and APIs because it offers several benefits over traditional authentication. For example, it can **reduce the risk of the credentials being misused**, and it allows for **more fine-grained control** over access to resources. Additionally, tokens can be easily revoked or expired, making it easier to manage access rights.

### How to generate Token ?

To manage secured communication, every participant that connects to the meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key` which you can get from [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

#### 1. Generating token from Dashboard

If you are looking to do **testing or for development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for getting token includes generating it from your backend server which will help in **keeping your credentials safe**.
:::

#### 2. Generating token in your backend

- Your server will generate access token using your API key and secret.
  - While generating a token, you can provide **expiration time, permissions and roles** which are discussed later in this section.
- Your client obtains token from your backend server.
- For token validation, client will pass this token to VideoSDK server.
- VideoSDK server will only allow entry in the meeting if the token is valid.

![img2.png](../../static/img/authentication-and-token.png)




Follow our official example repositories to setup token API [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)

### Payload while generating token

```js
{
 apikey: API_KEY, //MANDATORY
 permissions: [`allow_join`], //`ask_join` || `allow_mod` //MANDATORY
 version: 2, //OPTIONAL
 roomId: ROOM_ID, //OPTIONAL,
 participantId: PARTICIPANT_ID, //OPTIONAL
 roles: ['crawler', 'rtc'], //OPTIONAL
}
```

- **`apikey`(Mandatory)**: This must be the API Key generated from the VideoSDK Dashboard. You can get it from [here](https://app.videosdk.live/api-keys).

- **`permissions`(Mandatory)**: By providing the permissions, you can control what a participant can do in the meeting and whether he can join the meeting directly.

  Available permissions are:

  - **`allow_join`**: The participant is **allowed to join** the meeting directly.
  - **`ask_join`**: The participant is required to **ask for permission to join** the meeting. The participant having the permission `allow_join` can accept or reject a participant whenever someone wants to join.
  - **`allow_mod`**: The participant is **allowed to toggle** webcam & mic of other participants.

- **`version`(optional)**: For accessing the [v2 API](/api-reference/realtime-communication/intro), you need to provide `2` as the version value.

  - For passing `roomId`, `participantId` or `roles` parameters in payload, it is essential to set the version value to `2`.

- **`roomId`(optional)**: To provide customised access control, you can make the token applicable to a particular room by including the `roomId` in the payload.

- **`participantId`(optional)**: You can include the `participantId` in the payload to limit the token's access to a particular participant.

- **`roles`(optional)**:

  - **`crawler`**: This role is only for accessing [v2 API](/api-reference/realtime-communication/intro), you can not use this token for running the `Meeting`/`Room`.
  - **`rtc`**: This role is only allowed for running the `Meeting` / `Room`, with this role you can not use [server-side APIs](/api-reference/realtime-communication/intro).

Then, you have to sign this payload with your **`SECRET KEY`** and `jwt` options using the **`HS256 algorithm`**.

### Expiration time

You can set any expiration time to the token. But in the **production environment**, it is recommended to generate a token with **short expiration time** because by any chance if someone gets hold of the token, it won't be valid for a longer period of time.

### What happens if token is expired?

If your token is expired, the user won't be able to join the meeting and all the API calls will give error with message `Token is invalid or expired`.

:::note
Token is validated only once while joining the meeting, so if a person joins the meeting and the token gets expired after that, there won't be any issue in the current meeting.
:::

## How to check validity of token?

1. After generating the token, visit [jwt.io](https://jwt.io) and paste your token in the given area.
2. You will be able to see the payload you passed while generating the token and also be able to see the expiration time and token creation time.

![img1.png](../../static/img/validate-token.png)

## API Settings & Controls

The VideoSDK Dashboard provides a powerful [API Settings](https://app.videosdk.live/api-keys) section where you can configure various services and controls for your meetings. These settings allow you to customize the behavior of different features directly from the dashboard without requiring code changes.

## Audio/Video Configurations

:::note
Runtime configuration from the dashboard has higher precedence than static SDK configurations.
If a value is modified in the dashboard, it will override any previously defined SDK settings for that session.

Example:
Code: Video = HD → Dashboard: Video = Full HD → Applied: Full HD
:::

### Maximum Send Bitrate Per Participant

Control the maximum total upload bandwidth for all media streams from a single participant.

![Maximum Send Bitrate](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.00.11%E2%80%AFPM.png)

**Available Options:**
- **Auto**: Removes the upload bitrate limit (recommended for best quality)
- **SD (800kbps)**: Standard definition bitrate
- **HD (1500kbps)**: High definition bitrate
- **Full HD (3000kbps)**: Full high definition bitrate

:::tip
Setting this to **Auto** provides the best video quality as it removes upload bitrate constraints, allowing adaptive streaming based on network conditions.
:::

## Recording & Streaming Configuration

:::note
Recording and HLS follow a precedence-based configuration model:

API/SDK configuration → Highest priority
Dashboard configuration → Used only when no API values are defined

Any parameters explicitly set via the API will not be overridden by dashboard changes.
:::

### Recording Configuration

Configure recording settings for your meetings including layout, quality, and auto-start options.

![Recording Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.01.00%E2%80%AFPM.png)

**Recording Controls:**
- **Enabled**: Toggle to enable/disable recording functionality
- **Enabled Modes**: Choose between Video & Audio or Audio Only recording
- **Start Recording Automatically**: Auto-start recording when meeting begins
- **Layout Style**: Select Grid layout for recording composition
- **Maximum Tiles In Grid**: Set the number of participants visible in grid (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme for recordings
- **Video Orientation**: Choose between Landscape or Portrait mode
- **Recording Quality**: Select quality level (e.g., HD Medium)
- **Recording Mode**: Choose between Video & Audio or Audio Only

### HLS Streaming Configuration

Configure HTTP Live Streaming (HLS) settings for broadcasting your meetings.

![HLS Streaming Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.02.18%E2%80%AFPM.png)

**HLS Streaming Controls:**
- **Enabled**: Toggle to enable/disable HLS streaming
- **Enabled Modes**: Choose between Video & Audio or Audio Only streaming
- **Auto Start HLS**: Automatically start HLS when meeting begins
- **Record HLS Stream**: Enable recording of the HLS stream
- **Layout Style**: Select Grid layout for stream composition
- **Maximum Tiles In Grid**: Set the number of participants visible (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme
- **HLS Orientation**: Choose between Landscape or Portrait mode
- **HLS Quality**: Select streaming quality (e.g., HD Medium)
- **HLS Streaming Mode**: Choose between Video & Audio or Audio Only

### Additional Service Controls

Enable or disable additional services for your API key.

![Service Controls](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.08%E2%80%AFPM.png)

**Available Services:**
- **RTMP Output**: Enable RTMP streaming to external platforms
- **SIP Integration**: Enable SIP (Session Initiation Protocol) integration for telephony
- **Realtime Translation**: Enable real-time language translation in meetings

### Transcription & Summary

Configure transcription and domain whitelisting for your API key.

![Transcription Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.50%E2%80%AFPM.png)

**Transcription Controls:**
- **Enabled**: Toggle to enable/disable transcription and summary features
- **Whitelist Domain**: Add domain restrictions for API key usage
  - Enter domain names in the format `https://domain.name`
  - Click "Add Domain" to whitelist specific domains
  - Only whitelisted domains can use this API key
  - When no domains are whitelisted, the API key can be used from any domain


---

# Concept and Architecture - IoT
The IoT SDK provides tools and APIs for enabling real-time communication directly through IoT devices. It allows a user to join meetings, share and receive audio streams, and interact with other participants, including AI agents, using lightweight devices such as ESP boards.


## Concepts 

### 1. `Meeting / Room`

Meeting or Room object in the VideoSDK provides a virtual place for participants to interact and engage in real-time audio session. The object is in charge of handling media streams and participant communication.
- To create a meeting room refer [`Meeting Initialization`](/iot_docs_versioned_docs/version-0.0.x/guide/video-and-audio-calling-api-sdk/audio-call/setup-call/init_call.md)

### 2. `Participant`

- A participant represents a user in the meeting and can share or receive audio streams via the IoT SDK.

- **2.1 `Local Participant`**:  
    - The local participant represents the user on the ESP device using the IoT SDK. 
    - The user on the ESP device controls their own audio streams and can also receive audio from others in real time.


- **2.2 `Remote Participant`**: 
    - A remote participant is any other participant in the meeting apart from the user.
    - The user can subscribe to the audio stream of the remote participant. 
  

- Each participant is uniquely identified by a **ParticipantId** in the meeting.

### 3. `Session`

- A Session is the instance of an ongoing meeting/room which has one or more participants in it. A single room or meeting can have multiple sessions.
- Each session can be uniquely identified by `sessionId`.

![img.png](/img/meeting-session.jpg)

### 4. `AudioStream` 
- An audio stream is a continuous flow of sound data transmitted in real time, allowing participants to hear and communicate instantly in a meeting.
- **Publish Audio**   
                      - The user captures audio through the ESP device and shares it in real time.            
                      - To publish audio refer this [`Publish_Audio`](/iot_docs_versioned_docs/version-0.0.x/guide/video-and-audio-calling-api-sdk/audio-call/handling-media/publish_audio.md)           
- **Subscribe Audio**
                      - The user receives audio and plays it through the ESP device.
                      - To Subscribe audio refer this [`Subscribe_Audio`](/iot_docs_versioned_docs/version-0.0.x/guide/video-and-audio-calling-api-sdk/audio-call/handling-media/subscribe_audio.md)




--- 
## `Architecture` 

This diagram illustrates the complete interaction of a user joining a meeting through the IoT SDK on an ESP device. It covers sending a join request to the server, publishing and subscribing to audio streams, and leaving the meeting, showing how the SDK and server coordinate to enable seamless real-time communication.




<center>
<img width="500" height="600" alt="ViewAudience" src="https://cdn.videosdk.live/docs/iotsdk/iot_architecture.png"/>
</center>

---

# Getting Started - IoT SDK

IoT SDK is natively written SDK using C Language. It is compatible with ESP32S3 Microcontrollers. 

## Installing IoT SDK

IoT SDK is client for real-time communication for Microcontrollers. It inherits the same terminology as all other SDKs does.

### Step 1: Add VideoSDK IoT Component in your IoT project


To integrate the IoT SDK component, clone the repository below.

```
git clone https://github.com/videosdk-live/IoTSdk
```

After cloning, copy the component's local path and provide it in the `idf_component.yml` file as shown below.
```yml title="main/idf_component.yml"
dependencies:
  IoTSdk: 
    path: // Full local path of the component
  // your existing dependencies ...
```



:::note

Check out official example of IoT SDK implementation: [`IoT-SDK-Example`](iot_docs_versioned_docs/version-0.0.x/guide/video-and-audio-calling-api-sdk/quickstart/quick-start.md)

:::


---

# IoT SDK + AI Agent Example

By pairing the IoT SDK with an AI Agent, your devices stop being passive endpoints and start acting like intelligent participants. Instead of simply sending sensor data or audio streams, they can listen, understand, and respond instantly — just like a human participant in a meeting.

This isn’t a traditional IoT integration. It’s a way to give your hardware a voice, a brain, and the ability to interact naturally with people and systems.

#### What You Can Build

###### Smart Home & Lifestyle

- **Adaptive Climate Control** – Imagine your AC or heater not only sensing the temperature but predicting your comfort level. It speaks up before you even reach for the remote: “It feels a bit warm — shall I cool things down?”

- **Interactive Home Chef** – Your countertop companion scans your fridge, suggests recipes you’ll actually love, then adjusts the oven and guides you step by step like a live sous-chef.

- **Wellness Coach** – A smart wearable that keeps a real-time eye on your heart rate and talks to you the moment it spikes: “Your heart rate just jumped — let’s do a 30-second calming-breath exercise together.” It becomes your on-the-go guide for instant stress relief and better wellbeing.

###### Education & Entertainment

- **Child-Friendly Storyteller** – A smart toy that doesn’t just read stories but acts them out, changing voices for characters, pausing to answer a child’s questions, and weaving their name into the plot.

- **Interactive Tutor** – An IoT classroom buddy that listens to students’ questions in real time and explains concepts instantly, tailoring difficulty to each child’s understanding like a personal teacher.

These examples are just a starting point. Once your IoT device can join a meeting as a participant alongside an AI Agent, you unlock endless two-way use cases.

#### Demo: IoT SDK in Conversation with AI Agent
<div style={{textAlign: 'center'}}>



</div>
---

### Prerequisites
Before you get started, ensure you have the following:

- **Python**: Python version >= 3.11
- Video SDK Developer Account (Not having one, follow **[Video SDK Dashboard](https://app.videosdk.live/)**)
---

### Step 1: Setup for AI Agent

On the AI Agent side, configure it to join the meeting as a participant, where it can listen to `live` audio, `process` it, and generate `responses` in real time. Once initialized, the AI Agent becomes the processing core, handling speech `recognition`, `reasoning`, and `synthesis`, and enabling low-latency, two-way sinteraction between the device and the meeting.

```python
def make_context() -> JobContext:
    room_options = RoomOptions(
        room_id="YOUR_MEETING_ID",
        name="VideoSDK Cascaded Agent",
        playground=True
    )

return JobContext(room_options=room_options)
```

:::caution 
Make sure you keep the **same `meetingID` in the RoomOptions** here, which you’ll also use on the IoT device side later.
:::


<div style={{fontWeight: 'bold', fontSize: '18px', marginTop: '20px'}}>
See the full setup in the <a href="https://docs.videosdk.live/ai_agents/voice-agent-quick-start">AI Agent Quick Start Guide →</a>
</div>



### Step 2: Setup for IoT SDK


Now it’s time to configure the `IoT SDK` on your ESP device. This step enables the device to `capture` and `publish` audio streams into the meeting, as well as `receive` and `play` responses from the `AI Agent`. With this setup, your device transitions from being a `simple` endpoint to an `active` communication node.

```c
char *token = "Generated - token";
init_config_t init_cfg = {
    .meetingID = "meeting-id",     
    .token = token,
    .displayName = "ESP32-Device",
    .audioCodec = AUDIO_CODEC_OPUS,
};

result_t init_result = init(&init_cfg);
printf("Result: %d\n", init_result);

```

:::caution 
Ensure that the `meetingID` configured on the IoT device is identical to the `meetingID` defined in the AI Agent’s `RoomOptions`.
:::


<div style={{fontWeight: 'bold', fontSize: '18px', marginTop: '20px'}}>
See the full setup in the <a href="../quickstart/quick-start">IoT SDK Quick Start Guide →</a>
</div>



### Step 3: Fuse IoT + AI into One Experience


This is where the real magic happens.  

1. The **AI Agent** joins first, ready to process and respond.  

```python
if __name__ == "__main__":
    # Start the AI Agent, which will join the meeting as a participant
    job = WorkerJob(entrypoint=start_session, jobctx=make_context) 
    #highlight-start
    job.start()
    #highlight-end
```
2. Your **IoT device** follows, sending audio streams and receiving real-time replies.

```c
  // joining the User through IoT - device once AI - Agent joins the meeting.
  // highlight-start
  result_t result_publish = startPublishAudio("your-publisherId"); 
  result_t result_susbcribe = startSubscribeAudio("your-subscriberId");
  //highlight-end
  printf("Result Publish:%d\n", result_publish);
  printf("Result Publish:%d\n", result_susbcribe); 
```  

3. Together, they create a **seamless two-way interaction**, as if your device just became a **smart teammate inside the meeting**.  



Now it’s not just IoT anymore — it’s **IoT with a brain, a voice, and instant intelligence**.  


---

# IoT Quick Start

 The IoT SDK enables real-time audio conferencing by connecting devices directly to the VideoSDK server. Beyond data collection, IoT devices become interactive nodes—joining meetings, sharing media or sensor data, and subscribing to streams—transforming them into active participants within a connected ecosystem.
## Prerequisites

Before you get started, ensure you have the following:

- **Python**: Python version >= 3.11
- Video SDK Developer Account (Not having one, follow **[Video SDK Dashboard](https://app.videosdk.live/)**)

## Install VideoSDK's IoT component

### Step 1: Setup for esp-idf

Install and configure the ESP-IDF environment on your system to prepare the toolchain, dependencies, and base project structure for development.
For more information visit [**ESP-IDF**](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html)



**Linux:**

```js
// Tools
sudo apt update
sudo apt install -y cmake ninja-build dfu-util ccache git wget flex bison gperf 
sudo apt install -y libssl-dev libffi-dev

// Create Project directory
mkdir esp
cd esp

//Now Clone  esp-idf from the github
git clone -b v5.3 https://github.com/espressif/esp-idf.git
cd esp-idf

// Set Python env path and install ESP-IDF tools
./install.sh

//Export ESP-IDF environment variables
. ./export.sh
//or
source export.sh

// Create a esp-idf project
cd ~/esp
idf.py create-project your-project-name
cd your-project-name

```

---

**Windows:**

```js
// Tools
winget install Kitware.CMake
winget install Ninja-build.Ninja
winget install dfu-util
winget install git.git
winget install GnuWin32.Wget
winget install winflexbison
winget install gperf
winget install OpenSSL.Light


// Create Project directory
mkdir esp
cd esp

//Now Clone  esp-idf from github
git clone -b v5.3 https://github.com/espressif/esp-idf.git
cd esp-idf

// Set Python env path and install ESP-IDF tools
install.bat

//Export ESP-IDF environment variables
export.bat

// Create a esp-idf project
cd ~/esp
idf.py create-project your-project-name
cd your-project-name

```

---

**Mac os:**

```js
// Tools
brew install cmake ninja dfu-util ccache git wget flex bison gperf
brew install openssl libffi
// Create Project directory
mkdir esp
cd esp

//Now Clone  esp-idf from the github
git clone -b v5.3 https://github.com/espressif/esp-idf.git
cd esp-idf

// Set Python env path and install ESP-IDF tools
./install.sh

//Export ESP-IDF environment variables
. ./export.sh
//or
source export.sh

// Create a esp-idf project
cd ~/esp
idf.py create-project your-project-name
cd your-project-name

```

  
### Step 2: Add IoT SDK component

To integrate the IoT SDK component, create a file named `idf_component.yml` in your main folder and then clone the repository below.

```
git clone https://github.com/videosdk-live/IoTSdk
```
Once cloned, update your idf_component.yml file as shown below.

```yml title="main/idf_component.yml"
dependencies:
  IoTSdk: 
    path: // Full local path of the component
  mdns: '*'
  espressif/esp_audio_codec: ~2.3.0
  espressif/esp_codec_dev: ~1.3.4
  espressif/esp_video_codec: ~0.5.2
  espressif/esp_audio_effects: ~1.1.0
  esp_lcd_ek79007:
    version: ~1.0.2
    rules:
    - if: target in [esp32p4]
  espressif/esp_lcd_ili9881c:
    version: ~1.0.1
    rules:
    - if: target in [esp32p4]
  protocol_examples_common:
    path: ${IDF_PATH}/examples/common_components/protocol_examples_common
    ## Required IDF version
  idf:
    version: '>=4.1.0'
  sepfy/srtp: ^2.3.0
```



### Step 3: Update your CmakeLists.txt

This ensures that your project links correctly with the required IoT SDK and ESP-IDF components.Make sure to replace your project name with "your-project-name.c".
For more information visit [**CMake**](https://cmake.org/cmake/help/latest/)
``` js title="main/cmakelists.txt"
idf_component_register(SRCS
  "quick_start.c"
  INCLUDE_DIRS "."
  REQUIRES mbedtls REQUIRES json  REQUIRES esp_netif  REQUIRES fatfs  REQUIRES vfs REQUIRES  esp_common REQUIRES esp_timer  REQUIRES esp_lcd  REQUIRES nvs_flash
)

target_compile_options(${COMPONENT_LIB} PRIVATE "-Wno-format")
```



### Step 4: Hardware configuration

Inside your project directory, create a file named `kconfig.projbuild` to select your microcontroller configuration. This configures hardware-specific options before compilation.
For more information visit [**kconfig**](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/kconfig-reference.html)
``` js title="main/kconfig.projbuild"
menu "Set Microcontroller "

choice AUDIO_BOARD
    prompt "Audio hardware board"
    default ESP32S3_XIAO
    help
        Select an audio board to use

config ESP32_S3_KORVO_2_V3_0_BOARD
    bool "ESP32-S3-Korvo-2"
    depends on IDF_TARGET_ESP32S3
config ESP32S3_XIAO
    bool "ESP32-S3-XIAO"
endchoice

endmenu
```



### Step 5: Create Partitions Table

Create a file named `partitions.csv` in your project folder. This file includes the flash memory partitions for your device. Different boards need different partition layouts for firmware and storage.
For more information visit [**Partitions Table**](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-guides/partition-tables.html)
**ESP32-S3 Korvo V2:**

``` js title="partitions.csv"
# ESP-IDF Partition Table
# Name,   Type, SubType, Offset,  Size, Flags
nvs,      data, nvs,     0x9000,  0x6000,
phy_init, data, phy,     0xf000,  0x1000,
factory,  app,  factory, 0x10000, 4M,
```

---

**ESP32-S3 XIAO:**

``` js title="partitions.csv"
# ESP-IDF Partition Table
# Name,   Type, SubType, Offset,  Size, Flags
nvs,      data, nvs,     0x9000,  0x6000,
phy_init, data, phy,     0xf000,  0x1000,
factory,  app,  factory, 0x10000, 2M,
```


### Step 6: Add board configurations


Create a file named `sdkconfig.defaults` in your project folder. This file includes default build and Wi-Fi configuration values and sets essential project parameters such as target chip, memory, and networking.
For more information [**sdkconfig**](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/kconfig-reference.html)
``` js title="sdkcongfig.defaults"
CONFIG_IDF_TARGET="esp32s3"
CONFIG_APP_RETRIEVE_LEN_ELF_SHA=16
CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
CONFIG_PARTITION_TABLE_CUSTOM=y
CONFIG_ESP32S3_XIAO_SENSE=y
CONFIG_EXAMPLE_WIFI_SSID="myssid" 
CONFIG_EXAMPLE_WIFI_PASSWORD="mypassword" 
CONFIG_EXAMPLE_CONNECT_IPV6=n
CONFIG_ESP_PHY_REDUCE_TX_POWER=y
CONFIG_SPIRAM=y
CONFIG_SPIRAM_MODE_OCT=y
CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_240=y
CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE=2048
CONFIG_ESP_MAIN_TASK_STACK_SIZE=4096
CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1=n
CONFIG_ESP_IPC_TASK_STACK_SIZE=2048
CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM=16
CONFIG_ESP_WIFI_STATIC_TX_BUFFER_NUM=32
CONFIG_ESP_WIFI_CACHE_TX_BUFFER_NUM=64
CONFIG_LWIP_IPV6_AUTOCONFIG=y
CONFIG_LWIP_IPV6_DHCP6=y
CONFIG_LWIP_TCP_SND_BUF_DEFAULT=5744
CONFIG_LWIP_TCP_WND_DEFAULT=5744
CONFIG_MBEDTLS_EXTERNAL_MEM_ALLOC=y
CONFIG_MBEDTLS_SSL_PROTO_DTLS=y
CONFIG_PTHREAD_TASK_STACK_SIZE_DEFAULT=8192
```



### Step 7: Update your-project-main.c


Write your project logic inside `your-project-main.c`. This is where you’ll add the actual logic of your project, initialize the IoT SDK, handle connections, and manage data flow. 
``` js title="main/your-project-main.c"
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <string.h>
#include <sys/param.h>
#include <sys/time.h>
#include "esp_event.h"
#include "esp_log.h"
#include "esp_mac.h"
#include "esp_netif.h"
#include "esp_partition.h"
#include "esp_system.h"
#include "freertos/FreeRTOS.h"
#include "mdns.h"
#include "nvs_flash.h"
#include "protocol_examples_common.h"
#include "videosdk.h"

static const char *TAG = "VideoSDK";    // Logging tag
const char *token = "GENRERATED_TOKEN"; // Your VideoSDK Authentication token
const char *meetingId = "MEETING_ID" ; 
// Task to create a meeting using the VideoSDK
static void meeting_task(void *pvParameters)
{
   

    create_meeting_result_t result = create_meeting(token); // Create meeting using IoT SDK

    if (result.room_id)
    {
        ESP_LOGI(TAG, "Created meeting roomId = %s", result.room_id);
        meetingId = result.room_id; // Set global meetingId`
        free(result.room_id); // Free allocated memory
    }
    else
    {
        ESP_LOGE(TAG, "Failed to create meeting");
    }

    ESP_LOGI(TAG, "meeting_task finished, deleting self");
    vTaskDelete(NULL); // Delete task after completion
}

void app_main(void)
{
    static char deviceid[32] = {0}; // Buffer to hold device ID
    uint8_t mac[8] = {0};           // MAC address buffer

    ESP_LOGI(TAG, "[APP] Startup..");
    ESP_LOGI(TAG, "[APP] Free memory: %d bytes", esp_get_free_heap_size());
    ESP_LOGI(TAG, "[APP] IDF version: %s", esp_get_idf_version());

    // Configure logging levels
    esp_log_level_set("*", ESP_LOG_INFO);
    esp_log_level_set("esp-tls", ESP_LOG_VERBOSE);
    esp_log_level_set("MQTT_CLIENT", ESP_LOG_VERBOSE);
    esp_log_level_set("MQTT_EXAMPLE", ESP_LOG_VERBOSE);
    esp_log_level_set("TRANSPORT_BASE", ESP_LOG_VERBOSE);
    esp_log_level_set("TRANSPORT", ESP_LOG_VERBOSE);
    esp_log_level_set("OUTBOX", ESP_LOG_VERBOSE);

    // Initialize system components
    ESP_ERROR_CHECK(nvs_flash_init());
    ESP_ERROR_CHECK(esp_netif_init());
    ESP_ERROR_CHECK(esp_event_loop_create_default());
    ESP_ERROR_CHECK(example_connect());

    // Generate unique device ID from MAC address of your esp
    if (esp_read_mac(mac, ESP_MAC_WIFI_STA) == ESP_OK)
    {
        sprintf(deviceid, "esp32-%02x%02x%02x%02x%02x%02x",
                mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
        ESP_LOGI(TAG, "Device ID: %s", deviceid);
    }

    // Create a task to handle meeting creation
    BaseType_t ok = xTaskCreate(meeting_task, "meeting_task", 16384, (void *)token, 5, NULL);
    if (ok != pdPASS)
    {
        ESP_LOGE(TAG, "Failed to create meeting_task");
    }

    // Initialize VideoSDK configuration
    init_config_t init_cfg = {
        .meetingID = meetingId,
        .token = token,
        .displayName = "ESP32_Device",
        .audioCodec = AUDIO_CODEC_OPUS,
    };

    result_t init_result = init(&init_cfg); // Initialize SDK with config
    printf("Result: %d\n", init_result);

    // Start publishing audio stream
    result_t result_publish = startPublishAudio("your-publisherId");

    // Start subscribing to an audio stream
    result_t result_susbcribe = startSubscribeAudio("your-subscriberId","your-subscriberToId");

    // Keep the session active for a defined duration (adjust as per your application use case)
    vTaskDelay(pdMS_TO_TICKS(100000));

    // Leave the meeting
    result_t result_leave = leave();
    printf("Result:%d\n", result_susbcribe);

    // Keep main loop alive
    while (1)
    {
        vTaskDelay(pdMS_TO_TICKS(10));
    }
}

```


### Step 8: Build & Flash Project


Configure, build, and flash the firmware onto your ESP32 board. This compiles the code, applies the configurations, and uploads it to your device.
:::warning
Ensure you set the target board correctly; failure to do so may cause the project build to fail.
:::

```
1. 
idf.py set-target esp32-s3

2. 

idf.py menuconfig  

         a. Inside the component config:
                |
                |———> mbedtls
                      | ——>Enable Support DTLS    
                      | ——>Enable Support TLS      
          And click S to save and again enter       

          b. Inside Example Connection Configuration:
                |
                |———> WIFI SSID         
                |———> WIFI Password     
          And click S to save and again enter 

          c. Inside the Partition table :
                |
                |———> Partition table (custom partition table CSV)        
                      |———> Enable Custom partition table CSV

          d. Adjust the flash size inside Serial flasher config 
             (because some boards have limited flash memory)
                | ——> flash size: 2MB (esp32s3 XIAO sense)
                | ——> flash size: 4MB (esp32s3 qorvo2 v3.1)
          And click S to save and again enter

          e. Inside the Set Microcontroller : 
                | ——>**Audio hardware board (example : ESP32-S3-Korvo-2)**
                      | ——> Select your board name
                              |———> ESP32-S3-XIAO       
                              |———> ESP32- ESP32-S3-Korvo
          And click S to save and again enter

3. 
idf.py build

4. 
idf.py flash monitor 
```




### Step 9: Connecting with VideoSDK Client Applications

Integrate IoT devices with VideoSDK client applications. Ensure that both the IoT device and client apps connect to the same room for communication.









:::tip
You can checkout the complete [quick start example here](https://github.com/videosdk-live/videosdk-rtc-iot-sdk-example).
:::

---

# Run a Sample IoT SDK Project 
IoT SDK provides open-source sample project [videosdk-rtc-iot-sdk-example](https://github.com/videosdk-live/videosdk-rtc-iot-sdk-example/tree/main/quick_start) on Github. This document introduces how to run this project.
##  Prerequisites
Before you get started, ensure you have the following:
- Python >= 3.11
- A valid [Video SDK Account](https://app.videosdk.live/)

### Generate Token

To manage secured communication, every participant that connects to a meeting needs an access token. You can easily generate this token from the [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

**For development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />
## Run the Sample Project

### Step 1: Configure ESP-IDF enviorment

:::tip 
For setting up **ESP-IDF**, follow only **Step 1** from the [Videosdk's Documentation](/iot/guide/video-and-audio-calling-api-sdk/quickstart/quick-start).  
Inside Step 1, **you do not need to run the project creation commands**
:::
```
// Create a esp-idf project
cd ~/esp
idf.py create-project your-project-name
cd your-project-name
```
once the tools and environment are set up, jump directly to **`Step 2 in this Run Sample Project`**.


### Step 2: Clone the sample project

Clone the repository to your local environment.

```js
git clone https://github.com/videosdk-live/videosdk-rtc-iot-sdk-example.git
```



### Step 3: Add IoT SDK component


To integrate the IoT SDK component, clone the repository below.

```
git clone https://github.com/videosdk-live/IoTSdk
```

After cloning, copy the component’s local path and provide it in the `idf_component.yml` file as shown below.
```yml title="main/idf_component.yml"
dependencies:
  IoTSdk: 
    path: // Full local path of the component
```



### Step 3: Generate Token
 
Generate a token from [generate videosdk token](https://app.videosdk.live) and modify token variable in `quick_start.c` file
```
const char *token = "GENRERATED_TOKEN"; // Your VideoSDK Authentication token
```



### Step 5: Configure Publisher and Subscriber IDs
 
- You can pass your your Ids or use any random ID for `your-publisherId` and `your-subscriberId`.  
- For `your-subscriberToId`, pass the participant’s ID whose audio you want to subscribe to.

```
result_t result_publish = startPublishAudio("your-publisherId");

// Start subscribing to an audio stream
result_t result_susbcribe = startSubscribeAudio("your-subscriberId", "your-subscriberToId");

```



### Step 5: Build & Flash Project
 


Configure, build, and flash the firmware onto your ESP32 board. This compiles the code, applies the configurations, and uploads it to your device.
```
1. 
idf.py set-target esp32-s3

2. 

idf.py menuconfig  

         a. Inside the component config:
                |
                |———> mbedtls
                      | ——>Enable Support DTLS    
                      | ——>Enable Support TLS      
          And click S to save and again enter       

          b. Inside Example Connection Configuration:
                |
                |———> WIFI SSID         
                |———> WIFI Password     
          And click S to save and again enter 

          c. Inside the Partition table :
                |
                |———> Partition table (custom partition table CSV)        
                      |———> Enable Custom partition table CSV

          d. Adjust the flash size inside Serial flasher config 
             (because some boards have limited flash memory)
                | ——> flash size: 2MB (esp32s3 XIAO sense)
                | ——> flash size: 4MB (esp32s3 qorvo2 v3.1)
          And click S to save and again enter

          e. Inside the Set Microcontroller : 
                | ——>**Audio hardware board (example : ESP32-S3-Korvo-2)**
                      | ——> Select your board name
                              |———> ESP32-S3-XIAO       
                              |———> ESP32- ESP32-S3-Korvo
          And click S to save and again enter

3. 
idf.py build

4. 
idf.py flash monitor 
```


---

# Release Notes - IoT

This page will keep you updated with all the releases of IoT SDK.


## v0.0.1

**Release Date** : 23rd September 2025



---

# Supported Microcontrollers 




<div align="center">

| Supported Boards | Support |
|-----------------|---------------|
| ESP32-S3 XIAO Sense           | |
| ESP32-S3 Korvo V2      | |

</div>



---

# Connection Class - Javascript

<div class="sdk-api-ref-only-h4">

Connection class is used for making connections to different rooms, and it also provides facility to switch between rooms of a meeting

Whenever a new connection establishes between meetings, a Connection instance is created inside [Meeting](../meeting-class/introduction.md) property connections.

## Properties

### roomId

- type : `String`

- unique id of a meeting

### meeting

- type : `ConnectionMeeting`

- Connected Meeting Instance.

### payload

- type : `String`

- Any arbitrary payload you define during the connection.

---

## Methods

### close()

- `close()` is used to close the connection with the meeting.

#### Events associated with `close()`:

- `connection-close` event of meeting class is triggered to all participant whenever `connection.close()` being called.

#### Returns

- `void`

#### Example

```js
connection.close();
```

</div>


---

# Connection Meeting Class - Javascript

`ConnectionMeeting` entity is an instance of a Meeting which is connected with the current meeting.

<div class="sdk-api-ref-only-h4">

## Properties

### id

- type : `String`

- Represents Unique id of the connection meeting.

### participants

- type: `Map<ConnectionParticipant>`

- Represents Participants of connected meeting.

---

## Methods

### sendChatMessage()

- If you want to communicate participants of connected meetings, it can be achieved by `sendChatMessage`

#### Parameters

- message : `String`

#### Events associated with `sendChatMessage`:

- When any participant of Meeting A sends a chat message to Meeting B, then `chat-message` event will be emitted to all participants of Meeting B.

#### Returns

- `void`

#### Examples

```js
connection.meeting.sendChatMessage("Hi there, from MARS!");
```

---

### on()

#### Parameters

- eventType : "participant-joined" | "participant-left" | "chat-meesage"
- listener : `function`

#### Returns

- `void`

#### Example

```js
//for participant-joined
connection.meeting.on("participant-joined", listener);

//for participant-left
connection.meeting.on("participant-joined", listener);

//for chat-message
connection.meeting.on("chat-message", listener);
```

---

### off()

#### Parameters

- eventType : "participant-joined" | "participant-left" | "chat-meesage"
- listener : `function`

#### Returns

- `void`

#### Example

```js
//for participant-joined
connection.meeting.off("participant-joined", listener);

//for participant-left
connection.meeting.off("participant-joined", listener);

//for chat-message
connection.meeting.off("chat-message", listener);
```

---

### end()

- `end()` is used to end the connected meeting.
- After executing this method, all participants of that meeting will leave automatically.

#### Returns

- `void`

#### Example

```js
connection.meeting.end();
```

---

## Events

### participant-joined

- `participant-joined` event will be emitted when any participant joins the connected meetings.

#### Example

```js
connection.meeting.on("participant-joined", () => {
  //
});
```

---

### participant-left

- `participant-left` event will be emitted when any participant leaves the connected meetings.

#### Example

```js
connection.meeting.on("participant-left", () => {
  //
});
```

---

### chat-message

- `chat-message` event will be emitted when any participant send messages in the connected meeting.

#### Example

```js
connection.meeting.on("chat-message", () => {
  //
});
```

</div>


---

# Connection Participant Class - Javascript

<div class="sdk-api-ref-only-h4">

`ConnectionParticipant` class is used to represent participants of the connected meeting.

## Properties

### id

- type : `String`

- Unique id of the participant.

### displayName

- type : `String`

- Displayname of the participant.

---

## Methods

### switchTo()

- `switchTo()` method is used to switch participants between different rooms of a meeting

#### Parameters

- meetingId : `String`
- token : `String`
- payload : `String`

#### Events associated with `switchTo()`

- Meeting class `switch-meeting` event will be emitted whenever `switchTo()` method is called.

#### Returns

- `void`

</div>


---

# Connection - Javascript

This feature allows participant for establishing connection and getting information from other meetings. Also, a participant will have basic control over other running meetings.

For example, there are two meetings running parallelly Meeting A and Meeting B, in case one of the participant from Meeting A wants to access information of Meeting B without joining it, now this can be achieved by establishing connection between meetings, so that participants of Meeting A and Meeting B will get all the updates from each other.

## Classes / Entities

### [Connection](./connection-class.md)

### [ConnectionMeeting](./connection-meeting-class.md)

### [ConnectionParticipants](./connection-participant-class.md)


---

# Custom Audio Track - Javascript

We have introduced the ability to pass a custom Audio track for the Audio of the participants. This feature can be used to add custom layers like background noise removal, echo cancellation, etc. on audio and send it to other participants.

## Creating a Custom Audio Track

- You can create a Audio Track using `createMicrophoneAudioTrack()` method of `VideoSDK` class.
- This method can be used to create audio track using different encoding parameters and noise cancellation configuration.

### Parameters

- **microphoneId**:

  - type: `String`
  - required: `false`
  - It will be the id of the mic from which the audio should be captured.

- **encoderConfig**:

  - type: `String`
  - required: `false`
  - default: `speech_standard`
  - Allowed values : `speech_low_quality` | `speech_standard` | `music_standard` | `standard_stereo` | `high_quality` | `high_quality_stereo`
  - It will be the encoder configuration you want to use for Audio Track.

- **noiseConfig**

  - **echoCancellation**

    - type: `boolean`
    - required: `false`
    - If `true` echo cancellation will turned on else it would be turned off.

  - **autoGainControl**

    - type: `boolean`
    - required: `false`
    - If `true` auto gain will turned on else it would be turned off.

  - **noiseSuppression**
    - type: `boolean`
    - required: `false`
    - If `true` noise suppression will turned on else it would be turned off.

#### Returns

- `MediaStream`

### Example

```javascript
let customTrack = await VideoSDK.createMicrophoneAudioTrack({
  encoderConfig: "high_quality",
  noiseConfig: {
    noiseSuppression: true,
    echoCancellation: true,
    autoGainControl: true,
  },
});
```

## Using Custom Audio Track

### Custom Track while initializing the meeting

If you are passing `micEnabled: true` in the `initMeeting` and want to use custom tracks from start of the meeting, you can pass custom track in the `initMeeting` as shown below.

```javascript
let customTrack = await VideoSDK.createMicrophoneAudioTrack({
  encoderConfig: "high_quality",
  noiseConfig: {
    noiseSuppression: true,
    echoCancellation: true,
    autoGainControl: true,
  },
});

meeting = VideoSDK.initMeeting({
  meetingId: meetingId, // required
  name: name, // required
  micEnabled: true, // optional, default: true
  webcamEnabled: true, // optional, default: true

  // Pass the custom track here which will be used to mic is auto started
  customMicrophoneAudioTrack: customTrack,
});
```

### Custom Track with `unmuteMic()`

In order to switch tracks during the meeting, you have to pass the `MediaStream` in the `meeting.unmuteMic()` method.

:::note

Make sure to call `muteMic()` before you create a new track as it may lead to unexpected behavior.

:::

```javascript
let customTrack = await VideoSDK.createMicrophoneAudioTrack({
  encoderConfig: "high_quality",
  noiseConfig: {
    noiseSuppression: true,
    echoCancellation: true,
    autoGainControl: true,
  },
});

meeting.unmuteMic(customTrack);
```


---

# Custom Screen Share Track - Javascript

We have introduced the ability to pass a custom Screen Share track while sharing the screen of participants. This feature can be used to add custom video encoder config, optimization mode (whether you want to focus on **motion**, **text** or **detail** of the video) and background removal & video filter from external SDK(e.g., [Banuba](https://www.banuba.com/)) and send it to other participants.

## Creating a Custom Screen Share Track

- You can create a Video Track using `createScreenShareVideoTrack()` method of `VideoSDK` class.
- This method can be used to create video track using different encoding parameters and optimization mode.

### Parameters

- **encoderConfig**:

  - type: `String`
  - required: `false`
  - default: `h720p_15fps`
  - You can choose from the below mentioned list of values for the encoder config.

| Encoder Config | Resolution | Frame Rate | Bitrate (High)       |
| -------------- | ---------- | ---------- | -------------------- |
| h360p_30fps    | 640x360    | 30 fps     | 400 kbps             |
| h480p_15fps    | 854x480    | 15 fps     | 300 kbps             |
| h480p_30fps    | 854x480    | 30 fps     | 500 kbps             |
| h720p_5fps     | 1280x720   | 5 fps      | 400 kbps             |
| h720p_15fps    | 1280x720   | 15 fps     | 1000 kbps (1 Mbps)   |
| h720p_30fps    | 1280x720   | 30 fps     | 1500 kbps (1.5 Mbps) |
| h1080p_15fps   | 1920x1080  | 15 fps     | 1500 kbps (1.5 Mbps) |
| h1080p_30fps   | 1920x1080  | 30 fps     | 2000 kbps (2 Mbps)   |

:::note

- Above mentioned encoder configurations are valid for both, landscape as well as portrait mode.
- The following encoder configurations are newly added in SDK v0.2.5+:
  - `h480p_15fps`
  - `h480p_30fps`
  - `h720p_30fps`

:::

- **optimizationMode**
  - type: `String`
  - required: `false`
  - Allowed values: `motion` | `text` | `detail`
  - It will specify the optimization mode for the video track being generated.

#### Returns

- `MediaStream`

### Example

```javascript
let customTrack = await VideoSDK.createScreenShareVideoTrack({
  optimizationMode: "motion",
  encoderConfig: "h720p_15fps",
});
```

## Using Custom Screen Share Track

### Custom Track with `enableScreenShare()`

In order to switch tracks during the meeting, you have to pass the `MediaStream` in the `meeting.enableScreenShare()` method.

:::note

Make sure to call `disableScreenShare()` before you create a new track as it may lead to unexpected behavior.

:::

```javascript
let customTrack = await VideoSDK.createScreenShareVideoTrack({
  optimizationMode: "motion",
  encoderConfig: "h720p_15fps",
});

meeting.enableScreenShare(customTrack);
```


---

# Custom Video Track - Javascript

We have introduced the ability to pass a custom video track for the video of the participants. This feature can be used to add custom video encoder config, optimization mode (whether you want to focus on **motion**, **text** or **detail** of the video) and background removal & video filter from external SDK(e.g., [Banuba](https://www.banuba.com/)) and send it to other participants.

## Creating a Custom Video Track

- You can create a Video Track using `createCameraVideoTrack()` method of `VideoSDK` class.
- This method can be used to create video track using different encoding parameters, camera facing mode, bitrateMode, maxLayer and optimization mode.

### Parameters

- **cameraId**:

  - type: `String`
  - required: `false`
  - It will be the id of the camera from which the video should be captured.

- **encoderConfig**:

  - type: `String`
  - required: `false`
  - default: `h720p_w1280p`
  - You can choose from the below mentioned list of values for the encoder config.

| Encoder Config | Resolution | Frame Rate | Optimized (kbps) | Balanced (kbps) | High Quality (kbps) |
| -------------- | :--------: | :--------: | :----------: | :----------: | :----------: |
| h90p_w160p | 160x90 | 15 fps | 60  | 100 | 150|
| h180p_w320p | 320x180 | 15 fps | 100 | 150 | 250 |
| h216p_w384p | 384x216 | 15 | 120 | 200 | 350 |
| h360p_w640p | 640x360 | 20 | 200 | 400 | 600 |
| h540p_w960p | 960x540 | 25 | 350 | 550 | 800 |
| h720p_w1280p | 1280x720 | 30 | 1000 | 1500 | 2000 |
| h1080p_w1920p | 1920x1080 | 30 | 1600 | 2200 | 2700 |
| h1440p_w2560p | 2560x1440 | 30 | 5000 | 5500 | 6000 |
| h2160p_w3840p | 3840x2160 | 30 | 8000 | 8500 | 9000 |
| h120p_w160p | 160x120 | 15 | 60 | 100 | 150 |
| h180p_w240p | 240x180 | 15 | 100 | 150 | 250 |
| h240p_w320p | 320x240 | 15 | 120 | 200 | 350 |
| h360p_w480p | 480x360 | 20 | 200 | 400 | 600 |
| h480p_w640p | 640×480 | 25 | 300 | 500 | 700 |
| h540p_w720p | 720×540 | 30 | 350 | 550 | 800 |
| h720p_w960p | 960×720 | 30 | 900 | 1300 | 1600 |
| h1080p_w1440p | 1440×1080 | 30 | 1600 | 2200 | 2700 |
| h1440p_w1920p | 1920×1440 | 30 | 3500 | 4000 | 4500 |
:::note

Above mentioned encoder configurations are valid for both, landscape as well as portrait mode.

:::

- **facingMode**:

  - type: `String`
  - required: `false`
  - Allowed values : `front` | `environment`
  - It will specify whether to use front or back camera for the video track.

- **optimizationMode**

  - type: `String`
  - required: `false`
  - Allowed values: `motion` | `text` | `detail`
  - It will specify the optimization mode for the video track being generated.

- **multiStream**

  - type: `boolean`
  - required: `false`
  - default: true
  - It will specify if the stream should send multiple resolution layers or single resolution layer.

  :::info

  - For meetings with fewer than or equal to four participants, setting `multiStream:false` is regarded as best practice.
  - This parameter is only available from `v0.0.53`.

  :::

- **bitrateMode**:

  - type: `String`
  - required: `false`
  - Allowed values : `bandwidth_optimized` | `balanced` | `high_quality`
  - Controls the video quality and bandwidth consumption. You can choose between `high_quality` for the best picture, `bandwidth_optimized` to save data, or `balanced` for a mix of both. Defaults to `balanced`.

- **maxLayer**:

  - type: `Number`
  - required: `false`
  - Allowed values : `2` | `3` 
  - default: `3`
  - Specifies the maximum number of simulcast layers to publish. This parameter only has an effect if `multiStream` is set to true.



#### Returns

- `MediaStream`

### Example

```javascript
let customTrack = await VideoSDK.createCameraVideoTrack({
  optimizationMode: "motion",
  encoderConfig: "h540p_w960p",
  facingMode: "environment",
  bitrateMode: VideoSDK.Constants.BitrateMode.HIGH_QUALITY,
  maxLayer: 2
});
```

## Using Custom Video Track

### Custom Track while initializing the meeting

If you are passing `webcamEnabled: true` in the `initMeeting` and want to use custom tracks from start of the meeting, you can pass custom track in the `initMeeting` params as shown below.

```javascript
let customTrack = await VideoSDK.createCameraVideoTrack({
  optimizationMode: "motion",
  encoderConfig: "h540p_w960p",
  facingMode: "environment",
  bitrateMode: VideoSDK.Constants.BitrateMode.HIGH_QUALITY,
  maxLayer: 2
});

meeting = VideoSDK.initMeeting({
  meetingId: meetingId, // required
  name: name, // required
  micEnabled: micOn, // optional, default: true
  webcamEnabled: webcamOn, // optional, default: true

  // Pass the custom track here which will be used to when webcam is auto started
  customCameraVideoTrack: customTrack,
});
```

### Custom Track with `enableWebcam()`

In order to switch tracks during the meeting, you have to pass the `MediaStream` in the `meeting.enableWebcam()` method.

:::note

Make sure to call `disableWebcam()` before you create a new track as it may lead to unexpected behavior.

:::

```javascript
let customTrack = await VideoSDK.createCameraVideoTrack({
  optimizationMode: "motion",
  encoderConfig: "h540p_w960p",
  facingMode: "environment",
  bitrateMode: VideoSDK.Constants.BitrateMode.HIGH_QUALITY,
  maxLayer: 2
});

meeting.enableWebcam(customTrack);
```


---

# Meeting Error Codes - JavaScript

If you encounter any of the errors listed below, refer to the [Developer Experience Guide](../../guide/best-practices/developer-experience.md#listen-for-error-events), which offers recommended solutions based on common error categories.



### 1. Errors associated with Organization 

This table lists errors that occur due to the configuration and limitations within your organization’s account. These include account status, participant limits, and add-on service availability.

| Type                                   | Code  | Message                                             |
|----------------------------------------|-------|-----------------------------------------------------|
| ACCOUNT_DEACTIVATED                   | 4006  | Your account has been deactivated. Please contact VideoSDK support. |
| ACCOUNT_DISCONTINUED                  | 4007  | Your account has been discontinued. Please reach out to support for more details. |
| MAX_PARTICIPANT_REACHED               | 4009  | You have reached the maximum participant limit for this meeting. |
| MAX_SPEAKER_REACHED                   | 4010  | The maximum number of speakers for this meeting has been reached. |
| MAX_SPEAKER_LIMIT_REACHED_ON_ORGANIZATION | 4026  | Your organization has reached the maximum number of speakers allowed. |
| MAX_VIEWER_LIMIT_REACHED_ON_ORGANIZATION | 4027  | Your organization has reached the maximum number of viewers allowed. |
| ADD_ON_SERVICES_DISABLED              | 4021  | Add-On services have been disabled. Please contact support to enable them. |
| MAX_RECORDING_LIMIT_REACHED_ON_ORGANIZATION              | 4028  | You have reached max limit of recording on organization. To increase contact at support@videosdk.live |
| MAX_HLS_LIMIT_REACHED_ON_ORGANIZATION  | 4029  | You have reached max limit of hls on organization. To increase contact at support@videosdk.live |
| MAX_LIVESTREAM_LIMIT_REACHED_ON_ORGANIZATION  | 4030  | You have reached max limit of livestream on organization. To increase contact at support@videosdk.live |

### 2. Errors associated with Token

Errors listed here are related to issues with the API key, authentication tokens, or permissions assigned to users. These errors can occur when tokens are missing, expired, or improperly configured.

| Type                                    | Code  | Message                                                |
|-----------------------------------------|-------|--------------------------------------------------------|
| INVALID_API_KEY                        | 4001  | The provided API key is either missing or invalid. |
| INVALID_TOKEN                          | 4002  | The provided token is empty, invalid, or has expired. |
| INVALID_PERMISSIONS                    | 4008  | The permissions in the token are incorrect. Please verify them. |
| UNAUTHORIZED_MEETING_ID                | 4022  | The provided token is not authorized for this meeting ID. |
| UNAUTHORIZED_PARTICIPANT_ID            | 4023  | The provided token is not authorized for this participant ID. |
| UNAUTHORIZED_ROLE                      | 4024  | The role specified in the token is not valid for joining this meeting. |
| UNAUTHORIZED_REQUEST                      | 4025 | Your request does not match the security configuration. |

### 3. Errors associated with Meeting and Participant

This table lists errors resulting from invalid or missing meeting or participant details, including cases where a participant attempts to join with a duplicate ID.

| Type                    | Code  | Message                                         |
|-------------------------|-------|-------------------------------------------------|
| INVALID_MEETING_ID      | 4003  | The meeting ID provided is either invalid or missing. |
| INVALID_PARTICIPANT_ID  | 4004  | The participant ID is either invalid or missing. |
| DUPLICATE_PARTICIPANT   | 4005  | This participant has joined from another device. |

### 4. Errors associated with Add-on Service

This section addresses errors that occur while using VideoSDK's add-on services such as recording, livestreaming, HLS streaming, and transcription.

### Recording-related errors

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_RECORDING_FAILED      | 4011  | Failed to start recording. Please try again.   |
| STOP_RECORDING_FAILED       | 4012  | Failed to stop recording. Please try again.    |
| RECORDING_FAILED            | 5001  | Recording was stopped due to an error.         |
| START_PARTICIPANT_RECORDING_FAILED | 4035 | Failed to start participant recording. Please check the request. |
| STOP_PARTICIPANT_RECORDING_FAILED  | 4036 | Failed to stop participant recording. |
| PARTICIPANT_RECORDING_FAILED       | 5012 | Participant recording has stopped due to an error. |
| START_TRACK_RECORDING_FAILED | 4037 | Failed to start track recording.                |
| STOP_TRACK_RECORDING_FAILED  | 4038 | Failed to stop track recording.                 |
| TRACK_RECORDING_FAILED  | 5013 | Track recording stopped due to an unknown error.                 |
| PREV_RECORDING_PROCESSING  | 4018 | Previous recording session is being processed, please try again after few seconds.                 |
| RECORDING_DURATION_LIMIT_REACHED | 5004 | Recording stopped due to maximum duration being reached. |

### Livestream-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| INVALID_LIVESTREAM_CONFIG           | 4015  | Livestream 'outputs' configuration provided was invalid            |
| START_LIVESTREAM_FAILED     | 4013  | Failed to start livestream. Please try again.  |
| STOP_LIVESTREAM_FAILED      | 4014  | Failed to stop livestream. Please try again.   |
| LIVESTREAM_FAILED           | 5002  | Livestream stopped due to an error.            |
| PREV_RTMP_RECORDING_PROCESSING | 4019 | Previous RTMP recording session is being processed, please try again after few seconds! |
| LIVESTREAM_DURATION_LIMIT_REACHED | 5005 | Livestream stopped due to maximum duration being reached. |

### HLS-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_HLS_FAILED            | 4016  | Failed to start HLS stream.                    |
| STOP_HLS_FAILED             | 4017  | Failed to stop HLS stream.                     |
| HLS_FAILED                  | 5003  | HLS streaming stopped due to an error.         |
| PREV_HLS_STREAMING_PROCESSING | 4020 | Previous HLS streaming session is still being processed. |
| HLS_DURATION_LIMIT_REACHED  | 5006  | HLS stream stopped due to maximum duration being reached. |

### Transcription-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_TRANSCRIPTION_FAILED  | 4031  | Failed to start transcription. Please try again. |
| STOP_TRANSCRIPTION_FAILED   | 4032  | Failed to stop transcription.                  |
| TRANSCRIPTION_FAILED        | 5007  | Transcription stopped due to an error.         |

### 5.Errors associated with Media

These errors involve media access, device availability, or permission-related issues affecting camera, microphone, and screen sharing.

### Device permission-related errors
| Type                                      | Code  | Message                                          |
|-------------------------------------------|-------|--------------------------------------------------|
| ERROR_GET_VIDEO_MEDIA_PERMISSION_DENIED  | 3014  | Permission for video capture has been denied. |
| ERROR_GET_AUDIO_MEDIA_PERMISSION_DENIED  | 3015  | Permission for audio capture has been denied. |
| ERROR_GET_DISPLAY_MEDIA_PERMISSION_DENIED | 3016 | Permission for screen sharing has been denied. |
| ERROR_CAMERA_ACCESS_DENIED_OR_DISMISSED      | 3017  | Oops! It seems like camera access was denied or dismissed. To proceed, kindly grant access through your browser settings. |
| ERROR_MICROPHONE_ACCESS_DENIED_OR_DISMISSED      | 3018  | Oops! It seems like microphone access was denied or dismissed. To proceed, kindly grant access through your browser settings. |
| ERROR_CAMERA_ACCESS_UNAVAILABLE          | 3033  | Camera access is unavailable.                 |
| ERROR_MICROPHONE_ACCESS_UNAVAILABLE      | 3034  | Microphone access is unavailable.             |
| ERROR_CAMERA_PERMISSION_DENIED_BY_OS     | 3019  | Camera permission has been denied by the operating system. |
| ERROR_MICROPHONE_PERMISSION_DENIED_BY_OS | 3020  | Microphone permission has been denied by the operating system. |
| ERROR_CAMERA_PERMISSION_OR_AUTOPLAY_ISSUE      | 3025  | It seems like there's an issue with camera permission or video autoplay, you can check out this link for details: http://tinyurl.com/autoplay-issue |
| ERROR_VIDEO_SOURCE_INITIATION_FAILED      | 3026  | Unable to initiate video source. Please verify browser settings for video permissions. |


### Device-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| ERROR_GET_VIDEO_MEDIA      | 3011  | Your browser/Device does not support Video. |
| ERROR_GET_AUDIO_MEDIA      | 3012  | Your browser/Device does not support Audio. |
| ERROR_GET_DISPLAY_MEDIA      | 3013  | Your browser/Device does not support Screen Sharing. |
| ERROR_CAMERA_NOT_FOUND       | 3021  | Camera not found. Please ensure it's properly connected. |
| ERROR_MICROPHONE_NOT_FOUND   | 3022  | Microphone not found. Please ensure it's properly connected. |
| ERROR_CAMERA_IN_USE          | 3023  | Camera is already in use by another application. |
| ERROR_MICROPHONE_IN_USE      | 3024  | Microphone is already in use by another application. |


### 6.Errors associated with Track

These errors occur when there are issues with video or audio tracks, such as disconnections or invalid custom tracks.

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| ERROR_WEBCAM_TRACK_ENDED      | 3027  | Webcam track has ended or the webcam is disconnected. Please ensure your webcam is properly connected and try restarting it. |
| ERROR_MICROPHONE_TRACK_ENDED      | 3028  | Microphone track has ended or the microphone is disconnected. Please check your microphone connection and try again. |
| ERROR_INVALID_CUSTOM_VIDEO_TRACK      | 3029  | The provided custom video track is invalid; reverting to the default video track. Please ensure that the video track meets the required specifications. |
| ERROR_INVALID_CUSTOM_AUDIO_TRACK      | 3030  | The provided custom audio track is invalid; reverting to the default audio track. Please ensure that the audio track meets the required specifications. |
| ERROR_CUSTOM_VIDEO_TRACK_ENDED      | 3031  | The provided custom video track is in an ended state. Please verify the video track's status, and try again. |
| ERROR_CUSTOM_AUDIO_TRACK_ENDED     | 3032  | The provided custom audio track is in an ended state. Please verify the audio track's status, and try again. |

### 7.Errors associated with Actions

Below error is triggered when an action is attempted before joining a meeting.

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| ERROR_ACTION_PERFORMED_BEFORE_MEETING_JOINED     | 3035  | Oops! Something went wrong. The room was in a connecting state, and during that time, an action encountered an issue. Please try again after joining a meeting. |



---

# Initiallizing a Meeting - Javascript

<div class="sdk-api-ref">

## config()

Before initializing the meeting, you will need to first provide `token`. Please refer this [documentation](/api-reference/realtime-communication/intro/) to generate a token.

```js
//meeting configuration using VideoSDK

VideoSDK.config("<your token>");
```

You can initialize the meeting using a factory method provided by the SDK called `initMeeting()`. By passing the parameters according to the need, it will generate a new `Meeting` class and then return the initiated meeting.

## initMeeting()

```js title="Javascript"
const meeting = VideoSDK.initMeeting({
  meetingId: "abc-1234-xyz",
  name: "John Doe",
  micEnabled: true,
  webcamEnabled: true,
  maxResolution: "hd",
  multiStream: true,
  mode: "SEND_AND_RECV", // "SEND_AND_RECV" || "SIGNALLING_ONLY"
});
```

## Meeting Initialization Parameters

---

### meetingId

- Unique Id of the meeting where that participant will be joining.

  - type : `String`
  - `REQUIRED`

Please refer this [documentation](/api-reference/realtime-communication/create-room) to create a room.

---

### name

- Name of the participant who will be joining the meeting, this name will be displayed to other participants in the same meeting.

  - type : String
  - `REQUIRED`

---

### participantId

- Unique Id of the participant. If not passed then SDK will create an Id by itself and will use that id.

  - type : `String`
  - `OPTIONAL`

---

### micEnabled

- Whether `mic` of the participant will be on while joining the meeting. If it is set to `false`, then mic of that participant will be `disabled` by default, but can be `enabled` or `disabled` later.

  - type: `Boolean`
  - defaultValue : true
  - `OPTIONAL`

---

### webcamEnabled

- Whether `webcam` of the participant will be on while joining the meeting. If it is set to `false`, then webcam of that participant will be `disabled` by default, but can be `enabled` or `disabled` later.

  - type: `Boolean`
  - defaultValue : true
  - `OPTIONAL`

---

### maxResolution

- Sets the maximum upload resolution of that participant's webcam stream.

  - type: `String`
  - value: `sd` | `hd`
  - defaultValue: `sd`
  - `OPTIONAL`

---

### multiStream

- Sets wheather to send multi resoultion streams while publishing video.

  - type: `boolean`
  - defaultValue: true
  - `OPTIONAL`

---

### customCameraVideoTrack

- Set the initial custom video track using different encoding parameters, camera facing mode, and optimization mode.

  - type: `MediaStream`
  - `OPTIONAL`

---

### customMicrophoneAudioTrack

- Set the initial custom audio track using different encoding parameters and optimization mode.

  - type: `MediaStream`
  - `OPTIONAL`

---

### mode

- `OPTIONAL`

- There are 2 types of modes:

  - `SEND_AND_RECV`: Both audio and video streams will be produced and consumed in this mode.
  - `SIGNALLING_ONLY`: Audio and video streams will not be produced or consumed in this mode.

  - defaultValue : `SEND_AND_RECV`

---

### metaData

- If you want to provide additional details about a user joining a meeting, such as their profile image, you can pass that information in this parameter.

  - type: `Object`
  - `OPTIONAL`

---

### debugMode

- The `debugMode` parameter, when set to true, enables users to view detailed error logs generated by our SDK directly on the VideoSDK's dashboard. This feature facilitates efficient troubleshooting and debugging processes, providing users with valuable insights into the functioning of the SDK and aiding in the identification and resolution of potential issues.

  - type: `Boolean`
   - defaultValue : true
  - `OPTIONAL`

---

## Returns

### meeting

- After initializing the meeting, `initMeeting()` will return a new [`Meeting`](/javascript/api/sdk-reference/meeting-class/introduction) instance.

</div>


---

# Meeting Class Events - Javascript

<div class="sdk-api-ref-only-h4">

---

### meeting-joined

- This event will be emitted when a [localParticipant](../participant-class/introduction.md) successfully joined the meeting.

#### Example

```javascript
meeting.on("meeting-joined", () => {
  //
});
```

---

### meeting-left
- This event will be emitted when a [localParticipant](../participant-class/introduction.md) left the meeting.
- When `meeting-left` is triggered, a reason object is also provided.
- The table below outlines the possible reason codes and their descriptions:

| **Reason** | **Code** | **Message** |
|---------|------|----------|
| WEBSOCKET_DISCONNECTED | 1001 | Socket disconnected |
| REMOVE_PEER | 1002 | Participant was removed from the meeting |
| REMOVE_PEER_VIEWER_MODE_CHANGED | 1003 | Participant removed because viewer mode was changed |
| REMOVE_PEER_MEDIA_RELAY_STOP | 1004 | Participant removed because media relay was stopped |
| SWITCH_ROOM | 1005 | Participant switched to a different room |
| ROOM_CLOSE | 1006 | The meeting has been closed |
| UNKNOWN | 1007 | Participant disconnected due to an unknown reason |
| REMOVE_ALL | 1008 | Remove All from the meeting |
| MEETING_END_API | 1009 | Meeting Ended. |
| REMOVE_PEER_API | 1010 | Participant removed from the meeting |
| DUPLICATE_PARTICIPANT | 1011 | Leaving meeting, since this participantId joined from another device. |
| MANUAL_LEAVE_CALLED | 1101 | Participant manually called the leave() method to exit the meeting |
| WEBSOCKET_CONNECTION_ATTEMPTS_EXHAUSTED | 1102 | Meeting left after multiple failed websocket connection attempts. |
| JOIN_ROOM_FAILED | 1103 | Meeting left due to an error while joining the room. |
| SWITCH_ROOM_FAILED | 1104 | Meeting left due to an error while switching rooms. |

#### Example

```javascript
meeting.on("meeting-left", (reason) => {
  if(reason.code === Constants.leaveReason.MANUAL_LEAVE_CALLED){
    // do - something
  }
});
```

---

### participant-joined

- This event will be emitted when a new [participant](../participant-class/introduction.md) joined the meeting.

#### Event callback parameters

- **participant**: [Participant](../participant-class/introduction.md)

#### Example

```javascript
meeting.on("participant-joined", (participant) => {
  //
});
```

---

### participant-left

- This event will be emitted when a joined [participant](../participant-class/introduction.md) left the meeting.
- When `participant-left` is triggered, a reason object is also provided.
- The table below outlines the possible reason codes and their descriptions:

| **Reason** | **Code** | **Message** |
|---------|------|----------|
| WEBSOCKET_DISCONNECTED | 1001 | Socket disconnected |
| REMOVE_PEER | 1002 | Participant was removed from the meeting |
| REMOVE_PEER_VIEWER_MODE_CHANGED | 1003 | Participant removed because viewer mode was changed |
| REMOVE_PEER_MEDIA_RELAY_STOP | 1004 | Participant removed because media relay was stopped |
| SWITCH_ROOM | 1005 | Participant switched to a different room |
| ROOM_CLOSE | 1006 | The meeting has been closed |
| UNKNOWN | 1007 | Participant disconnected due to an unknown reason |
| REMOVE_ALL | 1008 | Remove All from the meeting |
| MEETING_END_API | 1009 | Meeting Ended. |
| REMOVE_PEER_API | 1010 | Participant removed from the meeting |
| DUPLICATE_PARTICIPANT | 1011 | Leaving meeting, since this participantId joined from another device |
| MANUAL_LEAVE_CALLED | 1101 | Participant manually called the leave() method to exit the meeting |
| WEBSOCKET_CONNECTION_ATTEMPTS_EXHAUSTED | 1102 | Meeting left after multiple failed websocket connection attempts. |
| JOIN_ROOM_FAILED | 1103 | Meeting left due to an error while joining the room. |
| SWITCH_ROOM_FAILED | 1104 | Meeting left due to an error while switching rooms. |

#### Event callback parameters

- **participant**: [Participant](../participant-class/introduction.md)
- **reason**: An object containing the `reason` and `code`

#### Example

```javascript
meeting.on("participant-left", (participant ,reason) => {
  if(reason.code === Constants.leaveReason.MANUAL_LEAVE_CALLED){
    // do something
  }
});
```

---

### speaker-changed

- This event will be emitted when a active speaker changed.
- If you want to know which participant is actively speaking, then this event will be used.
- If no participant is actively speaking, then this event will pass `null` as en event callback parameter.

#### Event callback parameters

- **activeSpeakerId**: String?

#### Example

```javascript
meeting.on("speaker-changed", (activeSpeakerId) => {
  //
});
```

---

### presenter-changed

- This event will be emitted when any [participant](../participant-class/introduction.md) starts or stops screen sharing.
- It will pass `participantId` as an event callback parameter.
- If a participant stops screensharing, then this event will pass `null` as en event callback parameter.

#### Event callback parameters

- **activePresenterId**: String?

#### Example

```javascript
meeting.on("presenter-changed", (activePresenterId) => {
  //
});
```

---

### error

- This event will be emitted when any error occured.
- It will pass **`code`** and **`message`**, as an event callback parameter.
- To see all available error codes from SDK. [Meeting Error Codes](../error-codes)

#### Event callback parameters

- **data**: \{ **code**: Number; **message**: String }
  - **code**: Number
  - **message**: String

#### Example

```javascript
meeting.on("error", (data) => {
  const { code, message } = data;
});
```

---

### entry-requested

- This event will be emitted when a new [participant](../participant-class/introduction.md) who is trying to join the meeting, is having permission **`ask_join`** in token.
- This event will only be emitted to the [participants](../participant-class/introduction.md) in the meeting, who is having the permission **`allow_join`** in token.
- This event will pass following parameters as an event parameters, `participantId` and `name` of the new participant who is trying to join the meeting, `allow()` and `deny()` to take required actions.

#### Event callback parameters

- **data**: \{ **allow**: Function; **deny**: Function; **name**: String; **participantId**: String }
  - **allow**: Function
  - **deny**: Function
  - **name**: String
  - **participantId**: String

#### Example

```javascript
meeting.on("entry-requested", (data) => {
  const { participantId, name, allow, deny } = data;

  console.log(`${name} requested to join the meeting.`);

  // If you want to allow the entry request
  allow();

  // if you want to deny the entry request
  deny();
});
```

---

### entry-responded

- This event will be emitted when the `join()` request is responded.
- This event will be emitted to the [participants](../participant-class/introduction.md) in the meeting, who is having the permission **`allow_join`** in token.
- This event will be also emitted to the [participant](../participant-class/introduction.md) who requested to join the meeting.

#### Event callback parameters

- **participantId**: _String_
- **decision**: _"allowed"_ | _"denied"_

#### Example

```javascript
meeting.on("entry-responded", (participantId, decision) => {
  // participantId will be id of participant who requested to join meeting

  if (decision === "allowed") {
    // entry allowed
  } else {
    // entry denied
  }
});
```

---

### webcam-requested

- This event will be emitted to the participant `B` when any other participant `A` requests to enable webcam of participant `B`.
- On accepting the request, webcam of participant `B` will be enabled.

#### Event callback parameters

- **data**: \{ **accept**: Function; **participantId**: String; **reject**: Function }
  - **accept**: Function
  - **participantId**: String
  - **reject**: Function

#### Example

```javascript
meeting.on("webcam-requested", (data) => {
  const { participantId, accept, reject } = data;

  // participantId, will be the id of participant who requested to enable webcam

  // if accept request
  accept();

  // if reject request
  reject();
});
```

### mic-requested

- This event will be emitted to the participant `B` when any other participant `A` requests to enable mic of participant `B`.
- On accepting the request, mic of participant `B` will be enabled.

#### Event callback parameters

- **data**: \{ **accept**: Function; **participantId**: String; **reject**: Function }
  - **accept**: Function
  - **participantId**: String
  - **reject**: Function

#### Example

```javascript
meeting.on("mic-requested", (data) => {
  const { participantId, accept, reject } = data;

  // participantId, will be the id of participant who requested to enable webcam

  // if accept request
  accept();

  // if reject request
  reject();
});
```

---

### recording-state-changed

- This event will be emitted when the meeting's recording status changed.

#### Event callback parameters

- **data**: \{ **status**: String }

  - **status**: String

`status` has following values

- `RECORDING_STARTING` - Recording is in starting phase and hasn't started yet.
- `RECORDING_STARTED` - Recording has started successfully.
- `RECORDING_STOPPING` - Recording is in stopping phase and hasn't stopped yet.
- `RECORDING_STOPPED` - Recording has stopped successfully.

#### Example

```javascript

const Constants = VideoSDK.Constants;

meeting.on("recording-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.recordingEvents.RECORDING_STARTING) {
    console.log("Meeting recording is starting");
  } else if (status === Constants.recordingEvents.RECORDING_STARTED) {
    console.log("Meeting recording is started");
  } else if (status === Constants.recordingEvents.RECORDING_STOPPING) {
    console.log("Meeting recording is stopping");
  } else if (status === Constants.recordingEvents.RECORDING_STOPPED) {
    console.log("Meeting recording is stopped");
  } else {
    //
  }
});
```

---

### recording-started

_`This event will be deprecated soon`_

- This event will be emitted when recording of the meeting is started.

#### Example

```javascript
meeting.on("recording-started", () => {
  //
});
```

---

### recording-stopped

_`This event will be deprecated soon`_

- This event will be emitted when recording of the meeting is stopped.

#### Example

```javascript
meeting.on("recording-stopped", () => {
  //
});
```

---

### livestream-state-changed

- This event will be emitted when the meeting's livestream status changed.

#### Event callback parameters

- **data**: \{ **status**: String }

  - **status**: String

`status` has following values

- `LIVESTREAM_STARTING` - Livestream is in starting phase and hasn't started yet.
- `LIVESTREAM_STARTED` - Livestream has started successfully.
- `LIVESTREAM_STOPPING` - Livestream is in stopping phase and hasn't stopped yet.
- `LIVESTREAM_STOPPED` - Livestream has stopped successfully.

#### Example

```javascript

const Constants = VideoSDK.Constants;

meeting.on("livestream-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.livestreamEvents.LIVESTREAM_STARTING) {
    console.log("Meeting livestream is starting");
  } else if (status === Constants.livestreamEvents.LIVESTREAM_STARTED) {
    console.log("Meeting livestream is started");
  } else if (status === Constants.livestreamEvents.LIVESTREAM_STOPPING) {
    console.log("Meeting livestream is stopping");
  } else if (status === Constants.livestreamEvents.LIVESTREAM_STOPPED) {
    console.log("Meeting livestream is stopped");
  } else {
    //
  }
});
```

---

### livestream-started

_`This event will be deprecated soon`_

- This event will be emitted when `RTMP` live stream of the meeting is started.

#### Example

```javascript
meeting.on("livestream-started", () => {
  //
});
```

---

### livestream-stopped

_`This event will be deprecated soon`_

- This event will be emitted when `RTMP` live stream of the meeting is stopped.

#### Example

```javascript
meeting.on("livestream-stopped", () => {
  //
});
```

---

### hls-state-changed

- This event will be emitted when the meeting's HLS(Http Livestreaming) status changed.

#### Event callback parameters

- **data**: \{ **status**: String , **playbackHlsUrl**: String , **livestreamUrl**: String }
  - **status**: String
  - **playbackHlsUrl**: String _`will receive this property only in HLS_STARTED status`_
  - **livestreamUrl**: String _`will receive this property only in HLS_STARTED status`_

`status` has following values

- `HLS_STARTING` - Hls is in starting phase and hasn't started yet.
- `HLS_STARTED` - Hls has started successfully will return `playbackHlsUrl` and `livestreamUrl`.
- `HLS_PLAYABLE` - Hls has started and the `playbackHlsUrl` and `livestreamUrl` is not playable.
- `HLS_STOPPING` - Hls is in stopping phase and hasn't stopped yet.
- `HLS_STOPPED` - Hls has stopped successfully.

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

#### Example

```javascript

const Constants = VideoSDK.Constants;

meeting.on("hls-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.hlsEvents.HLS_STARTING) {
    console.log("Meeting Hls is starting");
  } else if (status === Constants.hlsEvents.HLS_STARTED) {
    // when hls is started you will receive playbackHlsUrl
    const { playbackHlsUrl } = data;

    console.log("Meeting Hls is started");
  } else if (status === Constants.hlsEvents.HLS_STOPPING) {
    console.log("Meeting Hls is stopping");
  } else if (status === Constants.hlsEvents.HLS_STOPPED) {
    console.log("Meeting Hls is stopped");
  } else {
    //
  }
});
```

---

### hls-started

_`This event will be deprecated soon`_

- This event will be emitted when `HLS` of the meeting is started.

#### Event callback parameters

- **data**: \{ **playbackHlsUrl**: String; **livestreamUrl**: String }
  - **playbackHlsUrl**: String
  - **livestreamUrl**: String

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

#### Example

```javascript
meeting.on("hls-started", ({ playbackHlsUrl, livestreamUrl }) => {
  //
});
```

---

### hls-stopped

_`This event will be deprecated soon`_

- This event will be emitted when `HLS` of the meeting is stopped.

#### Example

```javascript
meeting.on("hls-stopped", () => {
  //
});
```

---

### whiteboard-started

- This event will be triggered when whiteboard is successfully started and it will return the url.

#### Example

```js
meeting.on("whiteboard-started", (data) => {
  const { url } = data;
  //
});
```

---

### whiteboard-stopped

- This event will be triggered when whiteboard session is stopped for all participants.

#### Example

```js
meeting.on("whiteboard-stopped", () => {
  //
});
```

---

### transcription-state-changed

- This event will be triggered whenever state of realtime transcription is changed.

#### Event callback parameters

- **data**: \{ **status**: String, **id**: String }
  - **status**: String
  - **id**: String

`status` has following values

- `TRANSCRIPTION_STARTING` - Realtime Transcription is in starting phase and hasn't started yet.
- `TRANSCRIPTION_STARTED` - Realtime Transcription has started successfully.
- `TRANSCRIPTION_STOPPING` - Realtime Transcription is in stopping phase and hasn't stopped yet.
- `TRANSCRIPTION_STOPPED` - Realtime Transcription has stopped successfully.

#### Example

```javascript

const Constants = VideoSDK.Constants;

meeting.on("transcription-state-changed", (data) => {
  let { status, id } = data;

  if (status === Constants.transcriptionEvents.TRANSCRIPTION_STARTING) {
    console.log(`Realtime Transcription with ${id} is starting`);
  } else if (status === Constants.transcriptionEvents.TRANSCRIPTION_STARTED) {
    console.log(`Realtime Transcription with ${id} is started`);
  } else if (status === Constants.transcriptionEvents.TRANSCRIPTION_STOPPING) {
    console.log(`Realtime Transcription with ${id} is stopping`);
  } else if (status === Constants.transcriptionEvents.TRANSCRIPTION_STOPPED) {
    console.log(`Realtime Transcription with ${id} is stopped`);
  }
});
```

---

### transcription-text

- This event will be emitted when text for running realtime transcription received.

#### Example

```javascript
meeting.on("transcription-text", (data) => {
  let { participantId, participantName, text, timestamp, type } = data;
  console.log(`${participantName}: ${text} ${timestamp}`);
});
```

---



### participant-mode-changed

- This event will be triggered when participant mode changes.
- It will pass `participantId` and `mode` as an event callback parameter.
- All available modes are `SEND_AND_RECV`, `SIGNALLING_ONLY`, `RECV_ONLY`.




#### Example

```javascript
meeting.on("participant-mode-changed", ({ participantId, mode }) => {
  console.log(`${participantId} has changed ${mode}`);
});
```

### meeting-state-changed

- This event will be triggered when state of meeting changes.
- It will pass **`state`** as an event callback parameter which will indicate current state of the meeting.
- All available states are `CONNECTING`, `CONNECTED`, `RECONNECTING`, `DISCONNECTED`.

#### Event callback parameters

- **data**: \{ **state**: String }
  - **state**: String

#### Example

```javascript
meeting.on("meeting-state-changed", (data) => {
  const { state } = data;

  switch (state) {
    case "CONNECTING":
      console.log("Meeting is Connecting");
      break;
    case "CONNECTED":
      console.log("Meeting is Connected");
      break;
    case "DISCONNECTED":
      console.log("Meeting connection disconnected abruptly");
      break;
    case "RECONNECTING":
      console.log("Meeting is Reconnecting");
      break;
    case 'FAILED':
      console.log("Meeting is in Failed State");
      break;
    default:
      console.log("Unknown state:", state);
      break;
  }
  //
});
```

---

### paused-all-streams

- This callback is triggered when all or specified media streams within the meeting are successfully paused

#### Parameters

- **`kind`**: Specifies the type of media stream that was paused.
  - **Type**: `String`
  - **Possible values**:
    - `"audio"`: Indicates that audio streams have been paused.
    - `"video"`: Indicates that video streams have been paused.
    - `"share"`: Indicates that screen-sharing video streams have been paused
    - `"shareAudio"`: Indicates that screen-sharing audio streams have been paused

#### Example

```javascript
meeting.on("paused-all-streams", (data) => {
  const { kind } = data;
});
```

---

### resumed-all-streams

- This callback is triggered when all or specified media streams within the meeting are successfully resumed

#### Parameters

- **`kind`**: Specifies the type of media stream that was resumed.
  - **Type**: `String`
  - **Possible values**:
    - `"audio"`: Indicates that audio streams have been resumed.
    - `"video"`: Indicates that video streams have been resumed.
    - `"share"`: Indicates that screen-sharing video streams have been resumed
    - `"shareAudio"`: Indicates that screen-sharing audio streams have been paused

#### Example

```javascript
meeting.on("resumed-all-streams", (data) => {
  const { kind } = data;
});
```

### media-relay-request-received

- This callback is triggered when a request is recieved for media relay in the destination meeting.

#### Parameters

- **`participantId - (String)`**: Specifies the participantId who requested the media relay.

- **`meetingId - (String)`**: Specifies the meeting from where the media relay request was made.

- **`displayName - (String)`**: Specifies the displayName of the participant who requested the media relay.

- **`accept - (Function)`**: Specifies the function to accept the media relay request.

- **`reject - (Function)`**: Specifies the function to reject the media relay request..

#### Example

```javascript
meeting.on(
  "media-relay-request-received",
  ({ participantId, meetingId, displayName, accept, reject }) => {
    //
  }
);
```

---

### media-relay-request-response

- This callback is triggered when a response is recieved for media relay request in the source meeting.

#### Parameters

- **`participantId - (String)`**: Specifies the participantId who responded the request for the media relay.

- **`decision - (String)`**: Specifies the decision whether the request for media relay was accepted or not.

#### Example

```javascript
meeting.on("media-relay-request-response", (participantId, decision) => {
  //
});
```

---

### media-relay-started

- This callback is triggered when the media relay to the destination meeting succesfully starts.

#### Parameters

- **`meetingId - (String)`**: Specifies the meeting where the media relay started.

#### Example

```javascript
meeting.on("media-relay-started", ({ meetingId }) => {
  //
});
```

---

### media-relay-stopped

- This callback is triggered when the media relay to the destination meeting stops for any reason.

#### Parameters

- **`meetingId - (String)`**: Specifies the meeting where the media relay stopped.

- **`reason - (String)`**: Specifies the reason why the media relay stopped

#### Example

```javascript
meeting.on("media-relay-stopped", ({ meetingId, reason }) => {
  //
});
```

---

### media-relay-error

- This callback is triggered when an error occurs during media relay to the destination meeting.

#### Parameters

- **`meetingId - (String)`**: Specifies the meeting where the media relay stopped.

- **`error - (String)`**: Specifies the error that occured.

#### Example

```javascript
meeting.on("media-relay-error", (meetingId, error) => {
  //
});
```

---

### quality-limitation

- This callback is triggered when a quality limitation is detected or resolved during the meeting.

#### Parameters

- **`type`**: Specifies the type of limitation.
  - **Type**: `String`
  - **Possible values**:
    - `"congestion"`: Network congestion detected.
    - `"bandwidth"`: Insufficient network bandwidth.
    - `"cpu"`: High CPU usage on the device.

- **`state`**: Specifies whether the limitation is currently active or resolved.
  - **Type**: `String`
  - **Possible values**:
    - `"detected"`: Limitation has been detected.
    - `"resolved"`: Limitation has been resolved.

- **`timestamp`**: The time (in milliseconds since epoch) when the event occurred.
  - **Type**: `Number`

#### Example

```javascript
meeting.on("quality-limitation", ({ type, state, timestamp }) => {
  //
});
```

---

### data

* This callback is triggered whenever a message is received over the DataStream.

#### Parameters

* **`payload`**: The actual data received.
  * **Type**: `Uint8Array | string`
  * **Details**:
    * If the sender transmitted a string, the payload will be a `string`.
    * If the sender transmitted binary data (e.g., ArrayBuffer, Blob), the payload will be a `Uint8Array`.

* **`from`**: The identity of the participant who sent the message.
  * **Type**: `String`

* **`timestamp`**: The time (in milliseconds since epoch) when the message was sent.
  * **Type**: `Number`

* **`reliability`**: Specifies whether the message was delivered reliably or unreliably.
  * **Type**: `String`
  * **Possible values**:
    * `"reliable"`: Message delivery is guaranteed.
    * `"unreliable"`: Message may be dropped under poor network conditions but has lower latency.

#### Example

```javascript
meeting.on("data", ({ payload, from, timestamp, reliability }) => {
  if (typeof payload === "string") {
    console.log(`Text message from ${from}: ${payload}`);
  } else {
    console.log(`Binary data from ${from}:`, payload);
  }

  console.log(`Received at: ${new Date(timestamp).toLocaleTimeString()}`);
  console.log(`Reliability: ${reliability}`);
});
```


</div>


---

# Video SDK Meeting Class - Javascript

<div class="sdk-api-ref">

## Introduction

The `Meeting` class includes properties, methods and events for managing a meeting, participants video, audio and share streams, messaging and UI customization.





## Meeting Properties

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [id](./properties.md#id)

</div>
<div class="col col--4 margin-bottom--sm" >

- [activeSpeakerId](./properties.md#activespeakerid)

</div>
<div class="col col--4 margin-bottom--sm" >

- [activePresenterId](./properties.md#activepresenterid)

</div>

<div class="col col--4 margin-bottom--sm">

- [hlsState](./properties#hlsstate)

</div>
<div class="col col--4 margin-bottom--sm">

- [livestreamState](./properties#livestreamstate)

</div>
<div class="col col--4 margin-bottom--sm">

- [recordingstate](./properties#recordingstate)

</div>
<div class="col col--4 margin-bottom--sm">

- [hlsUrls](./properties#hlsurls)

</div>

<div class="col col--4 margin-bottom--sm" >

- [localParticipant](./properties.md#localparticipant)

</div>
<div class="col col--4 margin-bottom--sm" >

- [participants](./properties.md#participants)

</div>
<div class="col col--4 margin-bottom--sm" >

- [pubsub](./pubsub)

</div>
<div class="col col--4 margin-bottom--sm" >

- [selectedCameraDevice](./properties.md#selectedcameradevice)

</div>

<div class="col col--4 margin-bottom--sm" >

- [selectedMicrophoneDevice](./properties.md#selectedmicrophonedevice)

</div>

</div>

## Meeting Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [join](./methods.md#join)

</div>
<div class="col col--4 margin-bottom--sm" >

- [leave](./methods.md#leave)

</div>
<div class="col col--4 margin-bottom--sm" >

- [end](./methods.md#end)

</div>
<div class="col col--4 margin-bottom--sm" >

- [enableWebcam](./methods.md#enablewebcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disableWebcam](./methods.md#disablewebcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [unmuteMic](./methods.md#unmutemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [muteMic](./methods.md#mutemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [enableScreenShare](./methods.md#enablescreenshare)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disableScreenShare](./methods.md#disablescreenshare)

</div>
<div class="col col--4 margin-bottom--sm" >

- [uploadBase64File](/javascript/api/sdk-reference/meeting-class/methods#uploadbase64file)

</div>
<div class="col col--4 margin-bottom--sm" >

- [fetchBase64File](/javascript/api/sdk-reference/meeting-class/methods#fetchbase64file)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startRecording](./methods.md#startrecording)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopRecording](./methods.md#stoprecording)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startLiveStream](./methods.md#startlivestream)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopLiveStream](./methods.md#startlivestream)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startHls](./methods.md#starthls)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopHls](./methods.md#stophls)

</div>
<div class="col col--4 margin-bottom--sm" >

- [startTranscription](./methods.md#starttranscription)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stopTranscription](./methods.md#stoptranscription)

</div>
<div class="col col--4 margin-bottom--sm">

- [startWhiteboard](./methods.md#startwhiteboard)
</div>

<div class="col col--4 margin-bottom--sm">

- [stopWhiteboard](./methods.md#stopwhiteboard)
</div>

<div class="col col--4 margin-bottom--sm" >

- [getWebcams](./methods.md#getwebcams)

</div>
<div class="col col--4 margin-bottom--sm" >

- [changeWebcam](./methods.md#changewebcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [setWebcamQuality](./methods.md#setwebcamquality)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getMics](./methods.md#getmics)

</div>
<div class="col col--4 margin-bottom--sm" >

- [changeMic](./methods.md#changemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [on](./methods.md#on)

</div>
<div class="col col--4 margin-bottom--sm" >

- [off](./methods.md#off)

</div>
<div class="col col--4 margin-bottom--sm" >

- [pauseAllStreams](./methods.md#pauseallstreams)

</div>
<div class="col col--4 margin-bottom--sm" >

- [resumeAllStreams](./methods.md#resumeallstreams)

</div>
<div class="col col--4 margin-bottom--sm">

- [requestMediaRelay](./methods#requestmediarelay)

</div>
<div class="col col--4 margin-bottom--sm">

- [stopMediaRelay](./methods#stopmediarelay)

</div>
<div class="col col--4 margin-bottom--sm">

- [switchTo](./methods#switchto)

</div>
<div class="col col--4 margin-bottom--sm">

- [send](./methods#send)

</div>

</div>

## Meeting Events

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [meeting-joined](./events.md#meeting-joined)

</div>
<div class="col col--4 margin-bottom--sm" >

- [meeting-left](./events.md#meeting-left)

</div>
<div class="col col--4 margin-bottom--sm" >

- [participant-joined](./events.md#participant-joined)

</div>
<div class="col col--4 margin-bottom--sm" >

- [participant-left](./events.md#participant-left)

</div>
<div class="col col--4 margin-bottom--sm" >

- [speaker-changed](./events.md#speaker-changed)

</div>
<div class="col col--4 margin-bottom--sm" >

- [presenter-changed](./events.md#presenter-changed)

</div>
<div class="col col--4 margin-bottom--sm" >

- [error](./events.md#error)

</div>
<div class="col col--4 margin-bottom--sm" >

- [entry-requested](./events.md#entry-requested)

</div>
<div class="col col--4 margin-bottom--sm" >

- [entry-responded](./events.md#entry-responded)

</div>
<div class="col col--4 margin-bottom--sm" >

- [webcam-requested](./events.md#webcam-requested)

</div>
<div class="col col--4 margin-bottom--sm" >

- [mic-requested](./events.md#mic-requested)

</div>
<div class="col col--4 margin-bottom--sm" >

- [recording-started](./events.md#recording-started)

</div>
<div class="col col--4 margin-bottom--sm" >

- [recording-stopped](./events.md#recording-stopped)

</div>
<div class="col col--4 margin-bottom--sm" >

- [livestream-started](./events.md#livestream-started)

</div>
<div class="col col--4 margin-bottom--sm" >

- [livestream-stopped](./events.md#livestream-stopped)

</div>
<div class="col col--4 margin-bottom--sm" >

- [hls-started](./events.md#hls-started)

</div>
<div class="col col--4 margin-bottom--sm" >

- [hls-stopped](./events.md#hls-stopped)

</div>

<div class="col col--4 margin-bottom--sm" >

- [whiteboard-started](./events.md#whiteboard-started)
</div>

<div class="col col--4 margin-bottom--sm" >

- [whiteboard-stopped](./events.md#whiteboard-stopped)

</div>

<div class="col col--4 margin-bottom--sm" >

- [transcription-state-changed](./events.md#transcription-state-changed)

</div>
<div class="col col--4 margin-bottom--sm" >

- [transcription-text](./events.md#transcription-text)

</div>

<div class="col col--4 margin-bottom--sm" >

- [meeting-state-changed](./events.md#meeting-state-changed)

</div>
<div class="col col--4 margin-bottom--sm" >

- [participant-mode-changed](./events.md#participant-mode-changed)

</div>
<div class="col col--4 margin-bottom--sm" >

- [paused-all-streams](./events.md#paused-all-streams)

</div>
<div class="col col--4 margin-bottom--sm" >

- [resumed-all-streams](./events.md#resumed-all-streams)

</div>
<div class="col col--4 margin-bottom--sm" >

- [media-relay-request-received](./events#media-relay-request-received)

</div>
<div class="col col--4 margin-bottom--sm" >

- [media-relay-request-response](./events#media-relay-request-response)

</div>
<div class="col col--4 margin-bottom--sm" >

- [media-relay-started](./events#media-relay-started)

</div>
<div class="col col--4 margin-bottom--sm" >

- [media-relay-stopped](./events#media-relay-stopped)

</div>
<div class="col col--4 margin-bottom--sm" >

- [media-relay-error](./events#media-relay-error)

</div>

<div class="col col--4 margin-bottom--sm" >

- [quality-limitation](./events#quality-limitation)

</div>

<div class="col col--4 margin-bottom--sm" >

- [data](./events#data)

</div>

</div>

</div>


---



---

# Meeting Class Methods - Javascript

<div class="sdk-api-ref-only-h4">

### join()

- It is used to join a meeting.
- After meeting initialization by [`initMeeting()`](../initMeeting.md) it returns a new instance of [Meeting](../meeting-class/introduction.md). However, by default, it will not automatically join the meeting. Hence, to join the meeting you should call `join()`.

#### Events associated with `join()`:

- Local Participant will receive a [`meeting-joined`](../meeting-class/events.md#meeting-joined) event when successfully joined.
- Remote Participant will receive a [`participant-joined`](../meeting-class/events.md#participant-joined) event with the newly joined [`Participant`](../participant-class/introduction.md) object from the event callback.

#### Participant having `ask_join` permission inside token

- If a token contains the permission `ask_join`, then the participant will not join the meeting directly after calling `join()`, but an event will be emitted to the participant having the permission `allow_join` called [`entry-requested`](../meeting-class/events.md#entry-requested).

- After the decision from the remote participant, an event will be emitted to the participant called [`entry-responded`](../meeting-class/events.md#entry-responded). This event will contain the decision made by the remote participant.

#### Participant having `allow_join` permission inside token

- If a token containing the permission `allow_join`, then the participant will join the meeting derectly after calling `join()`.

#### Returns

- _`void`_

---

### leave()

- It is used to leave the current meeting.

#### Events associated with `leave()`:

- Local participant will receive a [`meeting-left`](../meeting-class/events.md#meeting-left) event.
- All remote participants will receive a [`participant-left`](../meeting-class/events.md#participant-left) event with `participantId`.

#### Returns

- _`void`_

---

### end()

- It is used to end the current running session.
- By calling `end()`, all joined [participants](../participant-class/introduction.md) including [localParticipant](../participant-class/introduction.md) of that session will leave the meeting.

#### Events associated with `end()`:

- All [participants](../participant-class/introduction.md) and [localParticipant](../participant-class/introduction.md), will be emitted [`meeting-left`](../meeting-class/events.md#meeting-left) event.

#### Returns

- _`void`_

---

### enableWebcam()

- It is used to enable self camera.
- [`stream-enabled`](../participant-class/events.md#stream-enabled) event will be emitted with [`stream`](../stream-class/introduction.md) object from the event callback, inside that [participant](../participant-class/introduction.md) object.

#### Returns

- _`void`_

---

### disableWebcam()

- It is used to disable self camera.
- [`stream-disabled`](../participant-class/events.md#stream-disabled) event will be emitted with [`stream`](../stream-class/introduction.md) object from the event callback, inside that [participant](../participant-class/introduction.md) object.

#### Returns

- _`void`_

---

### unmuteMic()

- It is used to enable self microphone.
- [`stream-enabled`](../participant-class/events.md#stream-enabled) event will be emitted with [`stream`](../stream-class/introduction.md) object from the event callback, inside that [participant](../participant-class/introduction.md) object.

#### Returns

- _`void`_

---

### muteMic()

- It is used to disable self microphone.
- [`stream-disabled`](../participant-class/events.md#stream-disabled) event will be emitted with [`stream`](../stream-class/introduction.md) object from the event callback, inside that [participant](../participant-class/introduction.md) object.

#### Returns

- _`void`_

---

### enableScreenShare()

- it is used to enable screen-sharing.
- [`stream-enabled`](../participant-class/events.md#stream-enabled) event will be emitted with [`stream`](../stream-class/introduction.md) object from the event callback, inside that [participant](../participant-class/introduction.md) object.

- [`presenter-changed`](./events#presenter-changed) will also receive a callback with the `presenterId`.

#### Returns

- _`void`_

---

### disableScreenShare()

- It is used to disable screen-sharing.
- [`stream-disabled`](../participant-class/events.md#stream-disabled) event will be emitted with [`stream`](../stream-class/introduction.md) object from the event callback, inside that [participant](../participant-class/introduction.md) object.

- [`presenter-changed`](./events#presenter-changed) will also receive a callback with the `null`.

#### Returns

- _`void`_

---

### uploadBase64File()

- It is used to upload your file to Videosdk's Temporary storage

- `base64Data` convert your file to base64 and pass here.
- `token` pass your videosdk token. Read more about token [here](/javascript/guide/video-and-audio-calling-api-sdk/authentication-and-token)
- `fileName` provide your fileName with extension

- The method will return the corresponding fileUrl, which will use to retrieve the file from the VideoSDK's storage system.

#### Parameters

- **base64Data**: String
- **token**: String
- **fileName**: String

#### Returns

- `fileUrl` - It will use to retrieve the file from the VideoSDK's storage system.

#### Example

```javascript
const fileUrl = await meeting.uploadBase64File({
  base64Data: "

#### Parameters

- **mode**: String

#### Returns

- _`void`_

---

### pauseAllStreams()

This method pauses active media streams within the meeting.

#### Parameters

- **kind**: Specifies the type of media stream to be paused. If this parameter is omitted, all media streams (audio, video, and screen share) will be paused.

  - **Type**: `String`
  - **Optional**: Yes
    - Possible values:
    - `"audio"`: Pauses audio streams.
    - `"video"`: Pauses video streams.
    - `"share"`: Pauses screen-sharing video streams.
    - `"shareAudio"`:Resumes screen-sharing audio streams.

#### Returns

- _`void`_

---

### resumeAllStreams()

This method resumes media streams that have been paused

#### Parameters

- **kind**: Specifies the type of media stream to be resumed. If this parameter is omitted, all media streams (audio, video, and screen share) will be resumed.

  - **Type**: `String`
  - **Optional**: Yes

    - Possible values:
    - `"audio"`: Resumes audio streams.
    - `"video"`: Resumes video streams.
    - `"share"`:Resumes screen-sharing video streams.
    - `"shareAudio"`:Resumes screen-sharing audio streams.

#### Returns

- _`void`_

### requestMediaRelay()

This method starts relaying selected media streams (like camera video, microphone audio, screen share, etc.) from the current meeting to a specified destination meeting.

#### Parameters

- **destinationMeetingId (String) – Required**: ID of the target meeting where media should be relayed.

- **token (String) – Optional**: Authentication token for the destination meeting.

- **kinds (Array of Strings) – Optional**: Array of media types to relay.
  - Possible values:
    - `"audio"`: Resumes audio streams.
    - `"video"`: Resumes video streams.
    - `"share"`:Resumes screen-sharing video streams.
    - `"share_audio"`:Resumes screen-sharing audio streams.

#### Returns

- _`void`_

---

### stopMediaRelay()

This method stops the ongoing media relay to a specific destination meeting.

#### Parameters

- **destinationMeetingId (String) – Required**: ID of the destination meeting where the media relay should be stopped.

#### Returns

- _`void`_

---

### switchTo()

This method enables a seamless transition from the current meeting to another, without needing to disconnect and reconnect manually.

#### Parameters

- **meetingId (String) – Required**: ID of the new meeting to switch to.

- **token (String) – Optional**: Authentication token for the new meeting.

#### Returns

- _`void`_

--- 

### send()

This method sends a message to all the participants in the meeting over a DataStream..

#### Parameters

- **payload (string | Blob | ArrayBuffer | ArrayBufferView) – Required**: - The message to send.
  - Maximum allowed size: **15 KiB**.

- **options (Object) – Optional**: 
  - **reliability**:
    - **"reliable"**: Send data using reliable data stream. This mode guarantees delivery.
    - **"unreliable"**: Send data using unreliable data stream. This mode is faster but may drop messages under network loss.


#### Returns

- _`Promise<boolean>`_


</div>


---

# Meeting Class Properties - Javascript

<div class="sdk-api-ref-only-h4">

### id

- type: `String`

- Unique id of the meeting where the participant has joined.

---

### activeSpeakerId

- type: `String`

- It will be the `id` of the participant who is actively speaking in the meeting. If no participant is speaking, at that time value of `activeSpeakerId` will be `null`.

---

### activePresenterId

- type: `String`

- It will be the `id` of the participant who started `Presenting` / `Screen sharing` in the meeting. If no participant is sharing the screen, at that time value of `activePresenterId` will be `null`.

---

### hlsUrls

- type : `Object`
  - **playbackHlsUrl**: `String`
  - **livestreamUrl**: `String`
- `hlsUrls` will proide all the URLs for the ongoing meeting HLS.

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

---

### hlsState

- type : `string`
- `hlsState` will be the current state of the meeting HLS.

---

### livestreamState

- type : `string`
- `livestreamState` will be the current state of the meeting Livestream.

---

### recordingState

- type : `string`
- `recordingState` will be the current state of the meeting recording.

---

### localParticipant

- type: [Participant](../participant-class/introduction.md)

- It will be the instance of [Participant](../participant-class/introduction.md) class for the local participant(You) who joined the meeting.

---

### participants

- type: [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) of [Participant](../participant-class/introduction.md)

- `Map<String, Participant>`

  - Map{'<'}`participantId`, [Participant](../participant-class/introduction.md)>

- It will contain all joined participants in the meeting except the [`localParticipant`](../participant-class/introduction.md).

- This will be the [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) what will container all participants attached with the key as id of that participant.

```javascript
const remoteParticipantId = "ajf897";

const remoteParticipant = participants.get(remoteParticipantId);
```

---



### selectedCameraDevice

- type : `InputDeviceInfo`
- `selectedCameraDevice` will be return `InputDeviceInfo` object describing the camera device used during the meeting.

---

### selectedMicrophoneDevice

- type : `InputDeviceInfo`
- `selectedMicrophoneDevice` will be return `InputDeviceInfo` object describing the microphone device used during the meeting.

---

### pubSub

- It is used to enable Publisher-Subscriber feature in [`meeting`](introduction) class.

Learn more about `PubSub`, [here](./pubsub)

</div>


---

# PubSub - Javascript

- `PubSub` one of the property of a [Meeting Class](../meeting-class/introduction.md) is used for messaging purpose for an ongoing meeting

<div class="sdk-api-ref-only-h4">

--- 

## Methods

### publish()

- `publish()` is used to publish messages on a specified topic in the meeting.

- While publishing message, if you provide `persist` as `true`, then it will persist the message throughout the meeting and newly joined participant will get all old messages of a meeting, otherwise not.

#### Parameters

- topic :

  - type : `String`

- message :

  - type: `String`

- persist :

  - type : `Boolean`

- payload :

  - type : `Object`

#### Returns

- `void`

#### Example

```js
const topic = "CHAT";

const _handlePublishChat = (message) => {
  //
  try {
    await meeting?.pubSub.publish(topic, message, { persist: true });
  } catch (e) {
    console.log("Error while sending message through pubsub", e);
  }
};

_handlePublishChat("Hello world!");
```

---

### subscribe()

- `subscribe()` is used to subscribe a particular topic to get all the messages of that particular topic in the meeting. While `publish()` subscribe callback will be invoked.

#### Parameters

- topic :

  - type : `String`
  - Participants can listen to messages on that particular topic.

- callback :
  - type : `function`
  - in callback you will get `newMessage` object which contains [Pubsub message data](#pubsub-message-data)

#### Returns

- This will return old messages for this topic, if you passed `persist` to `true` while [publish](#publish)

- Array{'<'}[message](#pubsub-message-data)>

#### Example

```js
const topic = "CHAT";

const _handleChat = (newMessage) => {
  //
  console.log(newMessage);
};

const _handleSubscribePubSub = async () => {
  let oldMessages = await meeting.pubSub.subscribe("CHAT", _handleChat);

  console.log(oldMessages);
};
```

---

### unsubscribe()

- `unsubscribe()` is used to unsubscribe a particular topic on which you have subscribed priviously.

#### Parameters

- topic :

  - type : `String`
  - callback : `function`

- listener : `function`

#### Returns

- `void`

#### Example

```js
const topic = "CHAT";

// same handler used for meeting.pubSub.subscribe()
const _handleChat = (newMessage) => {
  //
  console.log(newMessage);
};

const _handleUnsubscribePubSub = async () => {
  meeting.pubSub.unsubscribe("CHAT", _handleChat);
};
```

---

## Pubsub message data

### message

- type : `String`

- Message that has been published on the specific topic.

### senderId

- type : `String`

- id of a sender who has published this message.

### senderName

- type : `String`

- Name of a sender who has published this message.

### timestamp

- type : `DateTime`

- Timestamp of when a message has been published.

### topic

- type : `String`

- Name of the topic.

### payload

- type : `Object`

- The additional data that you have send with message.

:::important
If you pass anything other than a string in the `message` parameter, or anything other than an object in the `payload`, an exception will be thrown.
:::


</div>


---

# RealtimeStore – JavaScript

The `RealtimeStore`, a property of the [Meeting Class](../meeting-class/introduction.md), allows you to **set**, **get**, and **listen** to value changes for specific keys shared across all participants in a meeting.

It provides a simple key–value storage system that stays synchronized in real time among all connected participants.

---

## Methods

### `setValue()`

The `setValue()` method is used to store or update data in the Realtime Store. If a key already exists, it will be overwritten with the new value. Passing `null` as the value deletes the key.

#### Parameters

- **`key`** (`string`) – The unique key under which the data will be stored.  
- **`value`** (`string | null`) – The value to be stored. Pass `null` to delete the key.

#### Returns

- **`Promise<void>`**
- Throws an error if:
   - Key or value is missing or not of type string.
   - Payload size exceeds 1 KB per key.
   - Session exceeds the 100-key limit.
   - Request fails due to network or internal issues.

#### Example

```js
try {
  await meeting.realtimeStore.setValue("Blocked_Students", "[Halima, Rajan]");
  console.log("Data set successfully!");
} catch (error) {
  console.error("Failed to set data:", error);
}
```

---

### `getValue()`

The `getValue()` method retrieves the current value associated with a given key from the Realtime Store.

#### Parameters

* **`key`** (`string`) – The key whose value you want to retrieve.

#### Returns

* **`Promise<string | null>`** — The stored value, or `null` if the key does not exist or retrieval fails.
- Throws an error if:
   - Key is missing or not of type string.
   - Request fails due to network or internal issues.

#### Example

```js
try {
  const value = await meeting.realtimeStore.getValue("Blocked_Students");
  console.log("Current value:", value);
} catch (error) {
  console.error("Failed to get data:", error);
}
```

---

### `observe()`

The `observe()` method subscribes to real-time updates for a given key.
When the value of that key changes, the provided callback function is triggered automatically for all participants.


#### Parameters

* **`key`** (`string`) – The key to observe for changes.
* **`callback`** (`function`) – Function triggered on each update. Receives:

  * `value` (`string | null`) – The new value or `null` if deleted.
  * `updatedBy` (`string`) – The participant ID of the participant who updated the value.

#### Returns

* **`Promise<string>`** — The unique observer ID.

#### Example

```js
try {
  const observerId = await meeting.realtimeStore.observe(
    "Blocked_Students",
    (value, updatedBy) => {
      console.log("Value updated:", value, "by", updatedBy);
    }
  );
} catch (error) {
  console.error("Failed to observe key:", error);
}
```

---

### `stopObserving()`

The `stopObserving()` method stops receiving updates for a previously observed key using its observer ID.

#### Parameters

* **`observerId`** (`string`) – The observer ID returned from the `observe()` method.

#### Returns

* **`Promise<void>`**

#### Example

```js
try {
  await meeting.realtimeStore.stopObserving(observerId);
  console.log("Stopped observing successfully!");
} catch (error) {
  console.error("Failed to stop observing:", error);
}
```

---



---

# Participant Class Events - Javascript

<div class="sdk-api-ref-only-h4">

### stream-enabled

- `stream-enabled` is a callback which gets triggered whenever a participant's video, audio or screen share stream is enabled.

#### Example

```js
participant.on("stream-enabled", (stream) => {
  //
});
```

---

### stream-disabled

- `stream-disabled` is a callback which gets triggered whenever a participant's video, audio or screen share stream is disabled.

#### Example

```js
participant.on("stream-disabled", (stream) => {
  //
});
```

### media-status-changed

- `media-status-changed` is a callback which gets triggered whenever a participant's video, audio is disabled or enabled.

#### Example

```js
participant.on("media-status-changed", (data) => {
  const { kind, newStatus } = data;
  //
});
```

---

### video-quality-changed

- `video-quality-changed` is a callback which gets triggered whenever a participant's video quality changes.

- `currentQuality` and `prevQuality` can have values `HIGH` | `MEDIUM` | `LOW`.

#### Example

```js
participant.on("video-quality-changed", (data) => {
  const { currentQuality, prevQuality } = data;
  //
});
```

---

</div>


---

# Video SDK Participant Class - Javascript

<div class="sdk-api-ref">





Participant class includes all the properties, methods and events related to all the participants joined in a particular meeting.

## Get local and remote participants

You can get the local streams and participant meta from `meeting.localParticipant`. And a Map of joined participants is always available via `meeting.participants`.

```js title="Javascript"
const localParticipant = meeting.localParticipant;
const participants = meeting.participants;
```

## Participant Properties

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [id](./properties.md#id)

</div>
<div class="col col--4 margin-bottom--sm" >

- [displayName](./properties.md#displayname)

</div>
<div class="col col--4 margin-bottom--sm" >

- [streams](./properties.md#streams)

</div>
<div class="col col--4 margin-bottom--sm" >

- [metaData](./properties.md#metadata)

</div>

</div>

## Participant Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [enableWebcam](./methods.md#enablewebcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disableWebcam](./methods.md#disablewebcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [enableMic](./methods.md#enablemic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disableMic](./methods.md#disablemic)

</div>

<div class="col col--4 margin-bottom--sm" >

- [pin](./methods.md#pin)

</div>

<div class="col col--4 margin-bottom--sm" >

- [unpin](./methods.md#unpin)

</div>
<div class="col col--4 margin-bottom--sm" >

- [remove](./methods.md#remove)

</div>
<div class="col col--4 margin-bottom--sm" >

- [setQuality](./methods.md#setquality)

</div>
<div class="col col--4 margin-bottom--sm" >

- [setViewPort](./methods.md#setviewport)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getAudioStats](./methods.md#getaudiostats)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getVideoStats](./methods.md#getvideostats)

</div>

<div class="col col--4 margin-bottom--sm" >

- [getShareStats](./methods.md#getsharestats)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getShareAudioStats](./methods.md#getshareaudiostats)

</div>

<div class="col col--4 margin-bottom--sm" >

- [captureImage](./methods.md#captureimage)

</div>

</div>

## Participant Events

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [stream-enabled](./events.md#stream-enabled)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stream-disabled](./events.md#stream-disabled)

</div>
<div class="col col--4 margin-bottom--sm" >

- [media-status-changed](./events.md#media-status-changed)

</div>

</div>

</div>


---

# Participant Class Methods - Javascript

<div class="sdk-api-ref-only-h4">

### enableWebcam()

- `enableWebcam()` is used to enable participant's camera.

#### Events associated with `enableWebcam()` :

- First the participant will get a callback on [`webcam-requested`](../meeting-class/events#webcam-requested) and once the participant accepts the request, webcam will be enabled.

- Every Participant will receive a `stream-enabled` event with `stream` object.

#### Returns

- `void`

---

### disableWebcam()

- `disableWebcam()` is used to disable participant camera.

#### Events associated with `disableWebcam()` :

- Every Participant will receive a `stream-disabled` event with `stream` object.

#### Returns

- `void`

---

### enableMic()

- `enableMic()` is used to enable participant microphone.

#### Events associated with `enableMic()` :

- First the participant will get a callback on [`mic-requested`](../meeting-class/events#mic-requested) and once the participant accepts the request, mic will be enabled.

- Every Participant will receive a `stream-enabled` event with `stream` object.

#### Returns

- `void`

---

### disableMic()

- `disableMic()` is used to disable participant microphone.

#### Events associated with `disableMic()`:

- Every Participant will receive a `stream-disabled` event with `stream` object.

#### Returns

- `void`

---

### setQuality()

- `setQuality()` is used to set the quality of the participant's video stream.

#### Parameters

- `quality`: low | med | high

#### Returns

- `void`

---

### pin()

- It is used to set pin state of the participant. You can use it to pin the screen share, camera or both of the participant. It accepts a optional paramter of type `String`. Default `SHARE_AND_CAM`

#### Parameters

- **pinType**: `SHARE_AND_CAM` | `CAM` | `SHARE`

#### Returns

- _`void`_

#### Example

```js
participant.pin("CAM");
```

---

### unpin()

- It is used to unpin participant. You can use it to unpin the screen share, camera or both of the participant. It accepts a optional paramter of type `String`. Default is `SHARE_AND_CAM`

#### Parameters

- **pinType**: `SHARE_AND_CAM` | `CAM` | `SHARE`

#### Returns

- _`void`_

#### Example

```js
participant.unpin("CAM");
```

---

### remove()

- It is used to remove a participant from the meeting

---

### captureImage()

- It is used to capture image of the participant's current videoStream.

- It will return image in a form of `base64`.

#### Parameters

- **height**: number
- **width**: number

---

### setViewPort()

- `setViewPort()` is used to set the quality of the participant's video stream based on the viewport height and width.

#### Parameters

- **width**: int
- **height**: int

#### Returns

- `void`

---

### getVideoStats()

- `getVideoStats()` will return an object which will contain details regarding the participant's critical video metrics such as **Jitter**, **Packet Loss**, **Quality Score** etc.

#### Returns

- `object`
  - `jitter` : It represents the distortion in the stream.
  - `bitrate` : It represents the bitrate of the stream which is being transmitted.
  - `totalPackets` : It represents the total packet count which were transmitted for that particiular stream.
  - `packetsLost` : It represents the total packets lost during the transimission of the stream.
  - `rtt` : It represents the time between the stream being reached to client from the server in milliseconds(ms).
  - `codec`: It represents the codec used for the stream.
  - `network`: It represents the network used to transmit the stream
  - `size`: It is object containing the height, width and frame rate of the stream.

:::note

getVideoStats() will return the metrics for the participant at that given point of time and not average data of the complete meeting.

To view the metrics for the complete meeting using the stats API documented [here](/api-reference/realtime-communication/fetch-session-quality-stats).

:::

:::info

If you are getting `rtt` greater than 300ms, try using a different region which is nearest to your user. To know more about changing region [visit here](/api-reference/realtime-communication/create-room).

:::

---

### getAudioStats()

- `getAudioStats()` will return an object which will contain details regarding the participant's critical audio metrics such as **Jitter**, **Packet Loss**, **Quality Score** etc.

#### Returns

- `object`
  - `jitter` : It represents the distortion in the stream.
  - `bitrate` : It represents the bitrate of the stream which is being transmitted.
  - `totalPackets` : It represents the total packet count which were transmitted for that particiular stream.
  - `packetsLost` : It represents the total packets lost during the transimission of the stream.
  - `rtt` : It represents the time between the stream being reached to client from the server in milliseconds(ms).
  - `codec`: It represents the codec used for the stream.
  - `network`: It represents the network used to transmit the stream

:::note

getAudioStats() will return the metrics for the participant at that given point of time and not average data of the complete meeting.

To view the metrics for the complete meeting using the stats API documented [here](/api-reference/realtime-communication/fetch-session-quality-stats).

:::

:::info

If you are getting `rtt` greater than 300ms, try using a different region which is nearest to your user. To know more about changing region [visit here](/api-reference/realtime-communication/create-room).

:::

---

### getShareStats()

- `getShareStats()` will return an object which will contain details regarding the participant's critical video metrics such as **Jitter**, **Packet Loss**, **Quality Score** etc.

#### Returns

- `object`
  - `jitter` : It represents the distortion in the stream.
  - `bitrate` : It represents the bitrate of the stream which is being transmitted.
  - `totalPackets` : It represents the total packet count which were transmitted for that particiular stream.
  - `packetsLost` : It represents the total packets lost during the transimission of the stream.
  - `rtt` : It represents the time between the stream being reached to client from the server in milliseconds(ms).
  - `codec`: It represents the codec used for the stream.
  - `network`: It represents the network used to transmit the stream
  - `size`: It is object containing the height, width and frame rate of the stream.

:::note

getShareStats() will return the metrics for the participant at that given point of time and not average data of the complete meeting.

To view the metrics for the complete meeting using the stats API documented [here](/api-reference/realtime-communication/fetch-session-quality-stats).

:::

:::info

If you are getting `rtt` greater than 300ms, try using a different region which is nearest to your user. To know more about changing region [visit here](/api-reference/realtime-communication/create-room).

:::

---

### getShareAudioStats()

- `getShareAudioStats()` will return an object which will contain details regarding the participant's critical screen share audio metrics such as **Jitter**, **Packet Loss**, **Quality Score** etc.

#### Returns

- `object`
  - `jitter` : It represents the distortion in the stream.
  - `bitrate` : It represents the bitrate of the stream which is being transmitted.
  - `totalPackets` : It represents the total packet count which were transmitted for that particiular stream.
  - `packetsLost` : It represents the total packets lost during the transimission of the stream.
  - `rtt` : It represents the time between the stream being reached to client from the server in milliseconds(ms).
  - `codec`: It represents the codec used for the stream.
  - `network`: It represents the network used to transmit the stream

:::note

getShareAudioStats() will return the metrics for the participant at that given point of time and not average data of the complete meeting.

To view the metrics for the complete meeting using the stats API documented [here](/api-reference/realtime-communication/fetch-session-quality-stats).

:::

:::info

If you are getting `rtt` greater than 300ms, try using a different region which is nearest to your user. To know more about changing region [visit here](/api-reference/realtime-communication/create-room).

::: 

---

### getTransportStats()

- `getTransportStats()` will return an object containing details regarding the participant’s transport-level network metrics.
- These stats help in understanding the bandwidth allocation and the bitrate that can be achieved for receiving media from the participant.

#### Returns

- `object`
  - `availableBitrate` : The estimated bitrate that the connection can currently handle for receiving media.
  - `targetBitrate` : The target bitrate (in bps) that the connection is trying to achieve for receiving media.
 
---

</div>


---

# Participant Class Properties - Javascript

<div class="sdk-api-ref-only-h4">

### id

- type: `String`

- Unique id of the participant who has joined the meeting.

---

### displayName

- type: `String`

- It will be the `displayName` of the participant.

---

### isLocal

- type: `boolean`

- It will represents whether the participant is [`LocalParticipant`](../meeting-class/properties#localparticipant)(You) or not. If it is true, then participant is [`LocalParticipant`](../meeting-class/properties#localparticipant) otherwise RemoteParticipant.

---

### streams

- type: `Map<String,name>`

- It will represents the stream for that particular participant who has joined the meeting. Streams could be `audio` , `video` or `share`.

---

### metaData

- type: `Object`

- It will represents the additional information, that you have passed in `initMeeting()`.

</div>


---

# Participant Class - Javascript

Participant class includes all the properties, methods and events related to all the participants joined in a particular meeting.

## Participant Class

### Get local and remote participants

You can get the local streams and participant meta from `meeting.localParticipant`. And a Map of joined participants is always available via `meeting.participants`.

```js title="Javascript"
const localParticipant = meeting.localParticipant;
const participants = meeting.participants;
```




### Properties


      
      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>

### Events


      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>

### Methods


      
      
      
      
      
      
      
      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>

### Example

```js title="Javascript"
meeting.on("participant-joined", (participant) => {
  setParticipants(new Map(meeting.participants));
});
meeting.on("participant-left", (participant) => {
  setParticipants(new Map(meeting.participants));
});
```


---

# Setup - Javascript

With javascript SDK, you can

- Customise call layout and interface
- Manage all the events related to meetings and participants
- Call routines on particular event.

To use `javascript-sdk`, you have two choices to make either use `npm` module or `<script>` tag in your bundler or direct in HTML.

## Loading the library using `<script>` tag

You can import this library using `<script>` tag. The easiest way to get started is to load this library from CDN, and add a couple of lines of code to your web page or app.

```js {5} title="Load JS SDK in your app"
<html>
  <head>....</head>
  <body>
    .....
    <script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
  </body>
</html>
```

## Install JS SDK in your app / Bundling with webpack and other tools

Another interesting option is to install library in your app and bundle it using webpack or rollup.



**npm:**

```js
npm install @videosdk.live/js-sdk
```

---

**yarn:**

```js
yarn add @videosdk.live/js-sdk
```

Then in your application code:

```js
// Webpack/node-style require
const VideoSDK = require("@videosdk.live/js-sdk");

// or

// es6 import

VideoSDK.config("<token>")

VideoSDK.initMeeting({...})
```


---

# Stream Class Events - Javascript

<div class="sdk-api-ref-only-h4">

---

### state

- This callback is triggered when the state of a video or screen-share video stream changes.
- It helps track whether the stream is active, stuck, frozen, resolved, or ended.

:::note
This event is emitted exclusively for remote participants, specifically for their video and screen share video streams.
:::

#### Parameters

- **`state`**: Specifies the current state of the stream.

  - **Type**: `String`
  - **Possible values**:
    - `"active"`: Stream is working normally.
    - `"stuck"`: Stream is not progressing as expected.
    - `"freeze-detected"`: Video freeze has been detected.
    - `"freeze-resolved"`: Video freeze has been resolved.
    - `"ended"`: Stream has ended.

- **`timestamp`**: The time (in milliseconds since epoch) when the state change occurred.
  - **Type**: `Number`

#### Example

```javascript
stream.on("state", ({ state, timestamp }) => {
  // 
});
```

---

</div>


---

# Video SDK Stream Class - Javascript

<div id="tailwind" class="sdk-api-ref">




Stream class is responsible for handling audio, video and screen sharing streams.

Stream class defines instance of audio, video and shared screen stream of participants.

## Stream Properties

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [id](./properties.md#id)

</div>
<div class="col col--4 margin-bottom--sm" >

- [kind](./properties.md#kind)

</div>
<div class="col col--4 margin-bottom--sm" >

- [codec](./properties.md#codec)

</div>
<div class="col col--4 margin-bottom--sm" >

- [track](./properties.md#track)

</div>

</div>

## Stream Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [resume](./methods.md#resume)

</div>
<div class="col col--4 margin-bottom--sm" >

- [pause](./methods.md#pause)

</div>

</div>

## Stream Events

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [state](./events.md#state)

</div>

</div>

</div>


---

# Participant Class Methods - Javascript

<div class="sdk-api-ref-only-h4">

### resume()

- By using `resume()` function, a participant can resume the stream of Remote Participant.

#### Returns

- `void`

---

### pause()

- By using `pause()`, a participant can pause the stream of Remote Participant.

#### Returns

- `void`

</div>


---

# Participant Class Properties - Javascript

<div class="sdk-api-ref-only-h4">

### id

- type: `String`

- Represents the id for that stream .

---

### kind

- type: `String`

- `kind` represents the type of stream which could be `audio` | `video` or `share` .

---

### codec

- type: `String`

- `codec` stand for encoding and decoding which is useful for shrinking the stream size.

---

### track

- type: `MediaStreamTrack`

- It represents a single media track within a stream.

</div>


---

# Stream Class - Javascript

Stream class is responsible for handling audio, video and screen sharing streams.

## Stream Class

Stream class defines instance of audio, video and shared screen stream of participants.




### Properties


      
      
      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>

### Methods


      
      
    </MethodListGroup>
  </MethodListItemLabel>
</MethodListGroup>

:::note Chrome Autoplay policy workaround

Chrome's autoplay policy does not allow audio autoplay unless user has interacted with the domain (click, tap, etc.) or the user's <a href="https://developers.google.com/web/updates/2017/09/autoplay-policy-changes#mei">Media engagement Index</a> threshold has been crossed. Thus, as a workaround before starting the meeting, user can either create a meeting join page or create a join meeting confirmation dialog by which we can perform a user click interaction to enable audio autoplay in chrome's newer versions.

:::

:::info You can find more about MediaStreamTrack class by following link.

<a href="https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack">https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack</a>

:::


---

<h1> {props.title} </h1>{" "}

When integrating VideoSDK, you will come across with multiple terms like meeting, room, session and many more.

Let's discuss each term in detail so while integrating VideoSDK you don't get confused.

### Meeting / Room

- A Meeting or Room is a VideoSDK object which represents a real-time audio, video, and/or screen-share session, and is the basic building block for media sharing among participants which is returned by the VideoSDK once a successful connection is established.
- Meeting or Room can be uniquely identified by `meetingId` or `roomId`.

:::note
Meeting and Room are both the same. Similarly `meetingId` and `roomId` are same.
:::

### Session

- A Session is the instance of an ongoing meeting/room which has one or more participants in it. A single room or meeting can have multiple sessions.
- Each session can be uniquely identified by `sessionId`.
- All the sessions are associated with `meetingId`/`roomId` and can be listed using it.

### Participant

- Participant is a VideoSDK object which represents each user/client in the meeting or room and can share audio/video media with other.
- There can be multiple participants in a meeting/room and each participant can be uniquely identified by `participantId`.

### MediaStream

- MediaStream is the collection of audio and video tracks which holds the segments of audio/video media that are send and received by all the participants in the meeting.

### RTMP Live Stream

- RTMP live streaming is used to live stream your video conferencing apps to platforms like YouTube, Twitch, Facebook, etc. by providing the platform specific `streamKey` and `streamUrl`.

### Interactive Live streaming (HLS)

- Interactive live streaming is used to live stream your video conferencing apps within your own platform to allow a larger number of viewers who can not be accomodated in a real-time conference.



---

# VideoSDK Class Events - Javascript

<div class="sdk-api-ref-only-h4">

---

### device-changed

- The `device-changed` event is triggered whenever a media device such as a camera, microphone, or speaker is connected to or removed from the system.

#### Event callback parameters

- devices : `Array<DeviceInfo>`

#### Example

```javascript
meeting.on("device-changed", (devices) => {
  //
});
```

---

</div>

---

# Video SDK Class - Javascript

<div class="sdk-api-ref">

## Introduction

The `VideoSDK` class includes methods and events for managing a permissions, devices.




## VideoSDK Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [config](./methods#config)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getDevices](./methods#getdevices)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getCameras](./methods#getcameras)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getMicrophones](./methods#getmicrophones)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getPlaybackDevices](./methods#getplaybackdevices)

</div>
<div class="col col--4 margin-bottom--sm" >

- [getNetworkStats](./methods#getnetworkstats)

</div>
<div class="col col--4 margin-bottom--sm" >

- [requestPermission](./methods#requestpermission)

</div>
<div class="col col--4 margin-bottom--sm" >

- [checkPermissions](./methods#checkpermissions)

</div>
<div class="col col--4 margin-bottom--sm" >

- [on](./methods#on)

</div>
<div class="col col--4 margin-bottom--sm" >

- [off](./methods#off)

</div>

</div>

## VideoSDK Events

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [device-changed](./events#device-changed)

</div>

</div>

</div>


---

# VideoSDK Class Methods - Javascript

<div class="sdk-api-ref-only-h4">

### config()

- Before initializing the meeting, you will first need to provide `token`. By using `config()` method, you can set the token property of VideoSDK class. 
- Please refer this [documentation](/api-reference/realtime-communication/intro/) to generate a token.

#### Returns

- `void`

---

### getDevices()

- The `getDevices()` method returns a list of the currently available media input and output devices, such as microphones, cameras, headsets, and so forth. The returned `Promise` is resolved with an array of `DeviceInfo` objects describing the devices.

- `DeviceInfo` class has four properties :

  1. `DeviceInfo.deviceId`
        - Returns a string that is an identifier for the represented device, persisted across sessions.

  2. `DeviceInfo.groupId`
      - Returns a string that is a group identifier. Two devices have the same group identifier if they belong to the same physical device — for example a monitor with both a built-in camera and a microphone.

  3. `DeviceInfo.kind`
      - Returns an enumerated value that is either `videoinput`, `audioinput` or `audiooutput`.

  4. `DeviceInfo.label`
      - Returns a string describing this device (for example "External USB Webcam").

#### Returns

- `Promise<Array<DeviceInfo>>`

---

### getCameras()

- The `getCameras()` method returns a list of currently available video input devices. The returned `Promise` is resolved with an array of `CameraDeviceInfo` objects describing the video input devices.

- `CameraDeviceInfo` class has four properties :

  1. `CameraDeviceInfo.deviceId`
        - Returns a string that is an identifier for the represented device, persisted across sessions.

  2. `CameraDeviceInfo.groupId`
      - Returns a string that is a group identifier. Two devices have the same group identifier if they belong to the same physical device — for example a monitor with both a built-in camera and a microphone.

  3. `CameraDeviceInfo.kind`
      - Returns an enumerated value that is `videoinput`.

  4. `CameraDeviceInfo.label`
      - Returns a string describing this device (for example "External USB Webcam").

#### Returns

- `Promise<Array<CameraDeviceInfo>>`

---

### getMicrophones()

- The `getMicrophones()` method returns a list of currently available audio input devices. The returned `Promise` is resolved with an array of `MicrophoneDeviceInfo` objects describing the audio input devices.

- `MicrophoneDeviceInfo` class has four properties :

  1. `MicrophoneDeviceInfo.deviceId`
        - Returns a string that is an identifier for the represented device, persisted across sessions.

  2. `MicrophoneDeviceInfo.groupId`
      - Returns a string that is a group identifier. Two devices have the same group identifier if they belong to the same physical device — for example a monitor with both a built-in camera and a microphone.

  3. `MicrophoneDeviceInfo.kind`
      - Returns an enumerated value that is `audioinput`.

  4. `MicrophoneDeviceInfo.label`
      - Returns a string describing this device (for example "External Microphone").

#### Returns

- `Promise<Array<MicrophoneDeviceInfo>>`

---

### getPlaybackDevices()

- The `getPlaybackDevices()` method returns a list of currently available playback devices. The returned `Promise` is resolved with an array of `PlaybackDeviceInfo` objects describing the playback devices.

- `PlaybackDeviceInfo` class has four properties :

  1. `PlaybackDeviceInfo.deviceId`
        - Returns a string that is an identifier for the represented device, persisted across sessions.

  2. `PlaybackDeviceInfo.groupId`
      - Returns a string that is a group identifier. Two devices have the same group identifier if they belong to the same physical device — for example a monitor with both a built-in camera and a microphone.

  3. `PlaybackDeviceInfo.kind`
      - Returns an enumerated value that is `audiooutput`.

  4. `PlaybackDeviceInfo.label`
      - Returns a string describing this device (for example "External HeadPhones").

#### Returns

- `Promise<Array<PlaybackDeviceInfo>>`
---

### getNetworkStats()

-  The `getNetworkStats()` method will return a `Promise` that resolves with an object, containing network speed statistics or rejects with an error message, if the operation fails or exceeds the specified timeout.
- The result object will include the `downloadSpeed` and `uploadSpeed`, expressed in megabytes per second (MB/s).

#### Parameters

- `timeoutDuration`
   - It helps prevent the method from getting stuck indefinitely when fetching network statistics. It lets you set a maximum time for the operation, and if it takes longer than that, the method stops gracefully. 
   - You can specify `timeoutDuration` in milliseconds. If it is not provided or is not an integer, the default timeout is set to `60,000` milliseconds (1 minute).
   - `Optional`

#### Returns

- `Promise<{downloadSpeed: number,uploadSpeed: number}>`

#### Example

```js
try {
  const options = { timeoutDuration: 45000 }; // Set a custom timeout of 45 seconds
  const networkStats = await VideoSDK.getNetworkStats(options);
  console.log("Download Speed: ", networkStats["downloadSpeed"]);  // will return value in Mb/s
  console.log("Upload Speed: ", networkStats["uploadSpeed"]); // will return value in Mb/s
} catch(ex)
{
  console.log("Error in networkStats: ", ex);
}

```

:::important

The `getNetworkStats()` method has been deprecated in javascript version 0.3.6

:::

---

### requestPermission()

-  The `requestPermission()` method prompts the user for permission to use a media input. It returns a `Promise` that resolves to a `Map<string, boolean>` object.

#### Parameters

- `Permission`
  - A `string` specifying the specific kinds of media, that you want to request.
  - `Optional`
  - Allow Values : `audio` ,`video`,`audio_video`
  - Default : `audio_video`

#### Returns

- `Promise<Map<string, boolean>>`

#### Example

```js
try {
  const requestPermission = await VideoSDK.requestPermission(
      VideoSDK.Constants.permission.AUDIO_AND_VIDEO,
  );
  console.log(
    "request Audio and Video Permissions",
    requestPermission.get(VideoSDK.Constants.permission.AUDIO),
    requestPermission.get(VideoSDK.Constants.permission.VIDEO)
  );
} catch(ex)
{
  console.log("Error in requestPermission ", ex);
}

```

:::tip
`requestPermission()` will throw an error when matching media is not available.
:::

---

### checkPermissions()

-  The `checkPermissions()` method checks for permission to use a media input. It returns a `Promise` that resolves to a `Map<string, boolean>` object.

#### Parameters

- `Permission`
  - A `string` specifying the types of media to check.
  - `Optional`
  - Allow Values : `audio` ,`video`,`audio_video`
  - Default : `audio_video`

#### Returns

- `Promise<Map<string, boolean>>`

#### Example

```js
try {
  const checkAudioVideoPermission = await VideoSDK.checkPermissions(
    VideoSDK.Constants.permission.AUDIO_AND_VIDEO,
  );
  console.log(
    "check Audio and Video Permissions",
    checkAudioVideoPermission.get(VideoSDK.Constants.permission.AUDIO),
    checkAudioVideoPermission.get(VideoSDK.Constants.permission.VIDEO)
  );
} catch(ex)
{
  console.log("Error in checkPermissions ", ex);
}

```

:::tip
`checkPermissions()` will throw an error when the browser doesn't support permission check functionality.
:::

---

### on()

#### Parameters

- eventType : [`event of VideoSDK class`](./events.md)
- listener : `function`

#### Returns

- `void`

#### Example

```js
//for device-changed-event
VideoSDK.on("device-changed", deviceChangeEventListener);
```

---

### off()

#### Parameters

- eventType : [`event of VideoSDK class`](./events.md)
- listener : `function`

#### Returns

- `void`

#### Example

```js
//for device-changed-event
VideoSDK.off("device-changed", deviceChangeEventListener);
```

---

</div>


---

# Developer Experience Guidelines - JavaScript

This section provides best practices for creating a smooth and efficient development process when working with VideoSDK. From handling errors gracefully to managing resources and event subscriptions, these guidelines help developers build more reliable and maintainable applications. Following these practices can simplify troubleshooting, prevent common pitfalls, and improve overall application performance.

### Initiate Key Features After Meeting Join Event

To provide a seamless and reliable meeting experience, initiate specific features **only** after the [meeting-joined](https://docs.videosdk.live/javascript/api/sdk-reference/meeting-class/events#meeting-joined) event has been triggered.

- **Trigger Key Actions After Joining the Meeting** : Initiating crucial actions after the `meeting-joined` event helps avoid errors and optimizes the meeting setup, ensuring a smoother experience for participants. If your application utilizes any of the following features or you want to perform any action as soon as meeting joins, it's recommended to call them only after the meeting has successfully started:

  - `Chat Subscription`: To enable in-meeting chat functionality, subscribe to the chat topic after the `meeting-joined` event is triggered. This ensures that messages are reliably received by participants.

     <br/>
  <div style={{textAlign: 'center'}}>

  {" "}
  <img src="https://cdn.videosdk.live/docs/best-practices/web/js_chat_correct_incorrect_code.png" />

    </div>

  - `Device Management`: If you need users to use specific audio or video devices when the meeting is first joined, you can utilize the custom track. Pass the `cameraId` to the [createCameraVideoTrack()](https://docs.videosdk.live/javascript/api/sdk-reference/custom-track/custom-video-track) method for video, and the `microphoneId` to the [createMicrophoneAudioTrack()](https://docs.videosdk.live/javascript/api/sdk-reference/custom-track/custom-audio-track) method for audio. Once the track is created, provide it to the [initMeeting()](https://docs.videosdk.live/javascript/api/sdk-reference/initMeeting#initmeeting) method.

  - `Recording and Transcription`: To automatically start recording or transcription as soon as the meeting begins, configure the `autoStartConfig` in the `createMeeting` API. For detailed information, refer to the documentation [here](https://docs.videosdk.live/api-reference/realtime-communication/create-room#autoCloseConfig).

### Dispose Custom Tracks When Necessary

Proper disposal of custom tracks is essential for managing system resources and ensuring a smooth experience. In most scenarios, tracks are automatically disposed of by the SDK, ensuring efficient resource management. However, in specific cases outlined below, you will need to dispose of custom tracks explicitly:

1. **When Enabling/Disabling the Camera on a Precall Screen**:

   - If your application includes a precall screen and you want to ensure that the device's camera is not used when the camera is disabled, you must dispose of the custom video track. Otherwise, the device’s camera will continue to be used even when the camera is off.
   - Additionally, remember to create a new track when the user enables the camera again.
   - If you don’t need to manage the camera's usage on the device level (i.e., you’re okay with the camera being used whether it’s enabled or disabled), you can skip this step.
   - Here's how you can manage customTrack on a precall screen :
     <br />

   ```js
   let joinPageVideoStream = null;
   let webCamEnable = false;
   let joinPageWebcam = document.getElementById("joinCam");

   async function toggleWebCam() {
     if (joinPageVideoStream) {
       // Remove the video stream from the video element
       joinPageWebcam.srcObject = null;
       webCamEnable = false;
       const tracks = joinPageVideoStream.getTracks();
       // Stop each track to release the resources
       tracks.forEach((track) => {
         track.stop();
       });
       joinPageVideoStream = null;
     } else {
       enableCam();
     }
   }

   // Function to enable the webcam and create a new video stream
   async function enableCam() {
     try {
       joinPageVideoStream = await window.VideoSDK.createCameraVideoTrack({
         // Pass the selected camera ID
         cameraId: selctedCameraId ? selectedCameraId : undefined,
         optimizationMode: "motion",
         multiStream: false,
       });
     } catch (ex) {
       console.log("Exception in enableCam", ex);
     }

     if (joinPageVideoStream) {
       // Set the stream as the source for the video element
       joinPageWebcam.srcObject = mediaStream;
       joinPageWebcam
         .play()
         .catch((error) =>
           console.log("videoElem.current.play() failed", error)
         );
       webCamEnable = true;
     }
   }
   ```

## Listen for Error Events

Listening to error events enables your application to handle unexpected issues efficiently, providing users with clear feedback and potential solutions. Error codes pinpoint specific problems, whether from configuration settings, account restrictions, permission limitations, or device constraints. Here are recommended solutions based on common error categories:

1. [Errors associated with Organization](../../api/sdk-reference/error-codes#1-errors-associated-with-organization): If you encounter errors related to your organization (e.g., account status or participant limits), reach out to support at support@videosdk.live or reach out to us on [Discord](https://discord.com/invite/Qfm8j4YAUJ) for assistance.

2. [Errors associated with Token](../../api/sdk-reference/error-codes#2-errors-associated-with-token): For errors related to authentication tokens, ensure the token is valid and hasn’t expired, then try the request again.

3. [Errors associated with Meeting and Participant](../../api/sdk-reference/error-codes#3-errors-associated-with-meeting-and-participant): Check that meetingId and participantId are correctly passed and valid. Also, ensure each participant has a unique participantId to avoid duplicate entries.

4. [Errors associated with Add-on Service](../../api/sdk-reference/error-codes#4-errors-associated-with-add-on-service): If you encounter errors with add-on services (such as recording or streaming), try restarting the service after receiving a failure event. For example, if a `START_RECORDING_FAILED` error event occurs, attempt to call the `startRecording()` method again. If you're using webhooks, you can also retry on [recording-failed](https://docs.videosdk.live/api-reference/realtime-communication/user-webhooks#recording-failed) hook.

5. [Errors associated with Media](../../api/sdk-reference/error-codes#5errors-associated-with-media): Inform the user about media access issues, such as microphone or camera permissions. Design the UI to clearly indicate what is preventing the mic or camera from enabling, helping the user understand the problem.

6. [Errors associated with Track](../../api/sdk-reference/error-codes#6errors-associated-with-track): Ensure that the track you’ve created and passed to enable the mic or camera methods meets the required specifications.

7. [Errors associated with Actions](../../api/sdk-reference/error-codes#7errors-associated-with-actions): If you need to perform actions as soon as a meeting joins, only initiate them after receiving the [meeting-joined](https://docs.videosdk.live/javascript/api/sdk-reference/meeting-class/events#meeting-joined) event, otherwise it will not work well.

- Here's how to listen for the error event:

```js
meeting.on("error", (data) => {
  const { code, message } = data;
});
```


---

# Handle Large Rooms - JavaScript

Managing large meetings requires specific strategies to ensure performance, stability, and a seamless user experience. This section provides best practices for optimizing VideoSDK applications to handle high participant volumes effectively. By implementing these recommendations, you can reduce lag, maintain video and audio quality, and provide a smooth experience even in large rooms.

## User Interface Optimization

When hosting large meetings, an optimized UI helps manage participant visibility and ensures smooth performance.

Recommended Practices:

- `Limit Visible Participants`: Display only a limited number of participants on screen at any given time, adapting the view based on screen size. Use pagination to allow users to browse or switch between additional participants seamlessly. For example, you could display only users whose video stream is enabled, or you could choose to display all active speakers. This approach helps manage screen space efficiently, ensuring that the most relevant participants are visible without overwhelming the interface.
- `Switch Between Layouts`: Provide multiple layout options, such as grid, sidebar, or spotlight view, allowing users to choose the best layout for their needs. For instance, spotlight view may suit presentations, while grid view works well for collaborative discussions. [[Documentation](https://docs.videosdk.live/javascript/guide/video-and-audio-calling-api-sdk/render-media/layout-and-grid-management)]
- `Prioritize Active Speakers`: Ensure all active speakers are displayed on the screen to highlight who is currently talking, helping participants stay engaged and aware of ongoing discussions. To identify which participant is speaking, you can use the [speaker-changed](https://docs.videosdk.live/javascript/api/sdk-reference/meeting-class/events#speaker-changed) event.

## Optimizing Media Streams

In large video calls, it’s important to manage media streams effectively to optimize system resources while maintaining a smooth user experience.

Recommended Practices:

- `Pause Streams for Non-Visible Participants`: To optimize performance, pause the video streams of participants who are not currently visible on the screen. This reduces unnecessary resource consumption.
- `Resume Streams When Visible`: Once a participant comes into view, resume their stream to provide an uninterrupted experience as they appear on the screen.

For detailed setup instructions on how to achieve this, check out our in-depth documentation [here](https://docs.videosdk.live/javascript/guide/video-and-audio-calling-api-sdk/render-media/layout-and-grid-management#grid-with-pagination).

## Media Stream Quality Adjustment

In large meetings, managing media stream quality is essential to balance performance and user experience.

Recommended Practices:

- `High Quality for Active Speakers`: For all active speakers, set the video stream quality to a higher level using the `setQuality` method (e.g., `setQuality("high")`). This ensures that participants will receive higher-quality video for active speakers, providing a clearer and more engaging experience.
- `Lower Quality for Non-Speaking Participants`: For other participants who are not actively speaking, set their video stream quality to a lower level (e.g., `setQuality("low")`). This helps conserve bandwidth and system resources while maintaining overall meeting performance.

Checkout the documentation for `setQuality()` method [here](https://docs.videosdk.live/javascript/api/sdk-reference/participant-class/methods#setquality).


---

# User Experience Guidelines - JavaScript


This guide aims to help developers optimize the user experience and functionality of video conferencing applications with VideoSDK. By following these best practices, you can create smoother interactions, minimize common issues, and deliver a more reliable experience for users.

Here are our recommended best practices to enhance the user experience in your application:

| **Section**                                                                                     | **Description**                                                                                                                                                           |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Configure Precall for Effortless Meeting Join](#configure-precall-for-effortless-meeting-join) | Users may enter meetings unprepared due to device or connection issues. A Precall setup can help them configure devices and settings beforehand for a smooth start.       |
| [Permission Management: Manual UI Guidance](#permission-management-manual-ui-guidance)          | Users struggle when permissions are denied and often need help re-enabling access. Clear UI guidance helps them adjust permissions manually in their browser settings.    |
| [Listen Key Events for Optimal User Experience](#listen-key-events-for-optimal-user-experience) | Users can feel lost without real-time updates on meeting status, events, and errors. Event monitoring and notifications keep them informed and engaged.                   |
| [Handling Media Devices](#handling-media-devices)                                               | Users may want to change their audio or video setup mid-meeting but struggle to manage device controls. Providing easy device switching enhances control and flexibility. |
| [Monitoring Real-Time Participant Statistics](#monitoring-real-time-participant-statistics)     | Poor video or audio quality without real-time feedback leaves users frustrated. Real-time stats let them assess connection quality and troubleshoot issues actively.      |

### Configure Precall for Effortless Meeting Join

A Precall step is crucial for ensuring users are set up correctly and have no device or connection issues before joining a meeting. This step allows users to configure their devices and settings before entering a meeting, leading to a smoother experience and minimizing technical issues once the call begins.

Recommended Practices:

- `Request Permissions`: Prompt users to grant microphone, camera, and speaker permissions before entering the meeting, ensuring seamless access to their devices.
- `Device Selection`: Allow users to select their preferred camera, microphone, and speaker, giving them control over their setup from the start.
- `Entry Preferences`: Provide options to join with the microphone and camera either on or off, letting users choose their level of engagement upon entry.
- `Microphone Test`: Offer a recording feature so users can hear how they will sound in the meeting, helping them adjust their settings for optimal audio quality.
- `Speaker Test`: Enable users to test their speaker by playing a sample audio clip, ensuring they can hear others clearly once the meeting starts.
- `Camera Preview`: Show a live camera preview, allowing users to adjust angles and lighting to ensure they appear clearly and professionally.
- `Virtual Backgrounds`: Allow users to choose from different virtual backgrounds or enter with a virtual background enabled, enhancing privacy and creating a more polished appearance.
- `Network Test`: Allow users to check their network upload and download speeds before joining to help identify potential connectivity issues and adjust settings accordingly.

For detailed setup instructions on each of these features, check out our in-depth documentation [here](https://docs.videosdk.live/javascript/guide/video-and-audio-calling-api-sdk/setup-call/precall).

<div style={{textAlign: 'center'}}>



</div>

### Permission Management: Manual UI Guidance

In web applications, browser permission dialogues are typically displayed only once per permission request. If a user denies access, they must manually adjust permissions in their browser settings. To enhance user experience in this scenario, it's essential to proactively manage this situation within your application.

Recommended Practices:

- `Detect Permission Status`: Implement checks to determine if permissions have been granted or denied before the user attempts to join a meeting.[[Documentation](https://docs.videosdk.live/javascript/guide/video-and-audio-calling-api-sdk/setup-call/precall#step-1-check-permissions)]
- `Provide Clear Instructions`: If permissions are denied, display an instructional modal guiding users on how to navigate to their browser settings and enable the required permissions. Include step-by-step guidance for common browsers to make the process as easy as possible.

<div style={{textAlign: 'center'}}>

<img
  style={{ width: "75%" }}
  src="https://cdn.videosdk.live/docs/best-practices/web/manual_permission.png"
/>

</div>

### Listen Key Events for Optimal User Experience

Listening for crucial events is vital for providing users with a responsive and engaging experience in your application. By effectively managing state changes and user notifications, you can keep participants informed and enhance their overall experience during meetings.

Recommended Practices:

- `Monitor State Change Events`: Listen for state change events, such as `meeting-state-changed` and `recording-state-changed`, and notify users promptly about these transitions. Keeping users informed helps them understand the current state of the meeting.

<div style={{textAlign: 'center'}}>

<img
  style={{ width: "75%" }}
  src="https://cdn.videosdk.live/docs/best-practices/web/web_meeting_state.png"
/>

</div>

- `UI Handling on Event Trigger`: Update the user interface only in response to specific events. For instance, display that the meeting is recording only when the `recording-state-changed` event with the status `RECORDING_STARTED` is received, rather than when the record button is clicked. This ensures users receive accurate and timely updates.

<div style={{textAlign: 'center'}}>



</div>

- `Notify Participants of Join/Leave Events`: Keep users informed about participant activity by notifying them when someone joins or leaves the meeting. This fosters a sense of presence and awareness of who is currently available to engage.
- `Listen for Error Events`: It is crucial to monitor error events and notify users promptly when issues arise. Clear communication about errors can help users troubleshoot and address problems quickly, minimizing disruptions to the meeting.

<div style={{textAlign: 'center'}}>

<img
  style={{ width: "75%" }}
  src="https://cdn.videosdk.live/docs/best-practices/web/web_error_display.png"
/>

</div>

### Handling Media Devices

Providing seamless control over input and output devices enhances user convenience and allows participants to adjust their setup for the best meeting experience. Proper device management within the UI also helps users stay informed about their current settings and troubleshoot issues effectively.

Recommended Practices:

- `Allow Device Switching`: Provide users with the option to switch between available microphone, camera, and speaker devices during the meeting. This flexibility is essential, especially if users want to adjust their setup mid-call.
- `Display Selected Devices`: Ensure the UI shows users which microphone, camera, and speaker devices are currently selected. Clear device labeling in the interface can reduce confusion and help users verify their setup at a glance.

<div style={{textAlign: 'center'}}>

<img
  style={{ width: "75%" }}
  src="https://cdn.videosdk.live/docs/best-practices/web/web_audio_select_device.png"
/>

</div>

- `Guide Users if Devices Are Unavailable`: In cases where permissions are granted but no input/output devices are detected, display a helpful prompt with instructions. For example, suggest connecting an external device or checking device connections, so users can quickly resolve the issue and participate fully.

### Monitoring Real-Time Participant Statistics

Providing real-time insights into stream quality allows participants to monitor and optimize their connection for the best experience. With detailed metrics on video, audio, and screen sharing, users can assess and troubleshoot quality issues, ensuring smooth and uninterrupted meetings. To display these statistics, you can use the [getVideoStats()](https://docs.videosdk.live/javascript/api/sdk-reference/participant-class/methods#getvideostats), [getAudioStats()](https://docs.videosdk.live/javascript/api/sdk-reference/participant-class/methods#getaudiostats), and [getShareStats()](https://docs.videosdk.live/javascript/api/sdk-reference/participant-class/methods#getsharestats) methods.

<div style={{textAlign: 'center'}}>



</div>


---

# Face Match API (BETA)


This API verifies whether two provided images are same or not. It returns a boolean value indicating whether the faces match.

:::important

This API is available in Enterprise plan only.

:::

## HTTP Method and Endpoint

**<span style={{ color: "#86EFAC", fontWeight: "bold" }}>POST</span>** | `https://api.videosdk.live/ai/v1/face-verification/verify`

## Headers Parameter

### Authorization

**values** : YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

_Note_ : the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by referring to this Guide: [Generate Auth token](https://docs.videosdk.live/api-reference/realtime-communication/intro)

### Content-Type

**values** : `application/json`

This is useful for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.

## Data Parameter

#### Base64 Encoding Format

The images should be converted from binary format to a Base64 string




Images must be Base64 encoded in the following format:

```
data:image/jpeg;base64,${Base64data}
```

#### Request Format

The request body should contain two Base64-encoded images in the following format:

```js
const data = {
  img1: "data:image/jpeg;base64,${Base64data}", // Base64-encoded image 1
  img2: "data:image/jpeg;base64,${Base64data}", // Base64-encoded image 2
};
```

## Sending Image Comparison Request

The request is made using the following code:




This sends the encoded images to the specified URL for comparison.

## Code Snippet for API Integration

Below is a code snippet demonstrating how to use the Face Match API (BETA) with Node.js:

```js




// Load environment variables from .env file
dotenv.config();

// Get the directory of the current file
const __dirname = path.resolve();

// Function to read image files and convert them to base64
function getBase64Image(imageName) {
  const filePath = path.join(__dirname, "image", imageName);
  console.log(`Resolved file path: ${filePath}`);
  try {
    const image = readFileSync(filePath);
    const base64Data = Buffer.from(image).toString("base64");
    return `data:image/jpeg;base64,${base64Data}`;
  } catch (error) {
    console.error(`Error reading image file: ${filePath}`, error.message);
    throw error;
  }
}

// Function to perform Face Match
async function faceMatch(ovdImageName, selfieImageName) {
  const url = "https://api.videosdk.live/ai/v1/face-verification/verify";
  const headers = {
    Authorization: `${process.env.API_KEY}`,
    "Content-Type": "application/json",
  };

  const data = {
    img1: getBase64Image(ovdImageName),
    img2: getBase64Image(selfieImageName),
  };

  try {
    const response = await axios.post(url, data, { headers });
    console.log("Face Match Result:", response.data);
  } catch (error) {
    console.error(
      "Error during face match:",
      error.response ? error.response.data : error.message
    );
  }
}

// Main function to run the API calls
async function main() {
  const ovdImageName = "img1.jpg";
  const selfieImageName = "img2.jpg";

  await faceMatch(ovdImageName, selfieImageName);
}

// Run the main function
main().catch((error) =>
  console.error("Error in main function:", error.message)
);
```

## Examples of Face Match API (BETA) Usage

### Example 1 : Matching Images of the Same Person

In this scenario, we take two different pictures of the same individual. For instance:

<div
  style={{ display: "flex", justifyContent: "center", alignItems: "center" }}
>
  <div style={{ textAlign: "center", marginRight: "-15px" }}>
    <img
      src="https://cdn.videosdk.live/website-resources/docs-resources/face_match_girl_1.png"
      alt="Image 1"
      width="90%"
    />
    <p>Image 1</p>
  </div>
  <div style={{ textAlign: "center", marginLeft: "-15px" }}>
    <img
      src="https://cdn.videosdk.live/website-resources/docs-resources/face_match_girl_2.png"
      alt="Image 2"
      width="90%"
    />
    <p>Image 2</p>
  </div>
</div>

When these images are sent to the Face Match API (BETA), the expected output would be:

```
Face Match Result: { "verified": true }
```

This result indicates that despite differences in lighting, angle, or expression, the API successfully recognizes that both images depict the same individual.

### Example 2 : Matching Images of Different Persons

In this case, we compare two photos of different individuals. For example:

<div
  style={{ display: "flex", justifyContent: "center", alignItems: "center" }}
>
  <div style={{ textAlign: "center", marginRight: "-15px" }}>
    <img
      src="https://cdn.videosdk.live/website-resources/docs-resources/face_match_male_1.png"
      alt="Image 1"
      width="90%"
    />
    <p>Image 1</p>
  </div>
  <div style={{ textAlign: "center", marginLeft: "-15px" }}>
    <img
      src="https://cdn.videosdk.live/website-resources/docs-resources/face_match_male_2.png"
      alt="Image 2"
      width="90%"
    />
    <p>Image 2</p>
  </div>
</div>

When these images are processed through the Face Match API (BETA), the expected output would be:

```
Face Match Result: { "verified": false }
```

This result demonstrates the API's ability to differentiate between distinct individuals accurately.



---

# Face Spoof Detection (BETA)


This API verifies if the image is original or spoofed. It returns a boolean value spoof_detected in output.

:::important

This API is available in Enterprise plan only.

:::

## HTTP Method and Endpoint

**<span style={{ color: "#86EFAC", fontWeight: "bold" }}>POST</span>** | `POST https://api.videosdk.live/ai/v1/face-verification/detect-spoof`

## Headers Parameter

### Authorization

**values** : YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

_Note_ : the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by refering this Guide: [Generate Auth token](https://docs.videosdk.live/api-reference/realtime-communication/intro)

### Content-Type

**values** : `application/json`

This is usefull for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.




## Data Parameter

#### Base64 Encoding Format

The images should be converted from binary format to a Base64 string




Images must be Base64 encoded in the following format:

```
data:image/jpeg;base64,${Base64data}
```

#### Request Format

The request body should contain two Base64-encoded images in the following format:

```js
const data = {
  img: "data:image/jpeg;base64,${Base64data}", // Base64-encoded image
};
```

## Sending Image Comparison Request

The request is made using the following code:




This sends the encoded images to the specified URL for comparison.

## Code Snippet for API Integration

Below is a code snippet demonstrating how to use the Face Spoof Detection API (BETA) with Node.js:

```js




// Load environment variables from .env file
dotenv.config();

// Get the directory of the current file
const __dirname = path.resolve();

// Function to read image files and convert them to base64
function getBase64Image(imageName) {
  const filePath = path.join(__dirname, "image", imageName);
  console.log(`Resolved file path: ${filePath}`);
  try {
    const image = readFileSync(filePath);
    const base64Data = Buffer.from(image).toString("base64");
    return `data:image/jpeg;base64,${base64Data}`;
  } catch (error) {
    console.error(`Error reading image file: ${filePath}`, error.message);
    throw error;
  }
}

async function spoofDetection(spoofimg) {
  const url = "https://api.videosdk.live/ai/v1/face-verification/detect-spoof";
  const headers = {
    Authorization: `${process.env.API_KEY}`,
    "Content-Type": "application/json",
  };
  const data = {
    img: getBase64Image(spoofimg),
  };

  try {
    const response = await axios.post(url, data, { headers });
    console.log(response.data);
  } catch (error) {
    console.error(
      "Error during spoof detection:",
      error.response ? error.response.data : error.message
    );
  }
}

// Main function to run the API calls
async function main() {
  const spoofimg = "img.jpg";
  await spoofDetection(spoofimg);
}

// Run the main function
main().catch((error) =>
  console.error("Error in main function:", error.message)
);
```

##### Given below is a test run of the example.

**Input Image** :

<div
  style={{
    display: "flex",
    justifyContent: "left",
    alignItems: "left",
    gap: "10px",
  }}
>
  <img
    src="https://cdn.videosdk.live/website-resources/docs-resources/input_spoof.jpg"
    alt="Image 1"
    width="45%"
  />
</div>

When this image is sent to the Face Spoof Detection API (BETA), the response will return a boolean value spoof_detected in output :

```js
{
  spoof_detected: true; // true if spoof detected in image else false
  accuracy: 0.9899068176746368; // accuracy of spoof detection
}
```



---

# Number of Face Detection (BETA)


This API checks how many faces are there in the image and returns an int value number_of_faces in output.

:::important

This API is available in Enterprise plan only.

:::

## HTTP Method and Endpoint

**<span style={{ color: "#86EFAC", fontWeight: "bold" }}>POST</span>** | `https://api.videosdk.live/ai/v1/face-verification/detect-faces`

## Headers Parameter

### Authorization

**values** : YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

_Note_ : the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by refering this Guide: [Generate Auth token](https://docs.videosdk.live/api-reference/realtime-communication/intro)

### Content-Type

**values** : `application/json`

This is usefull for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.




## Data Parameter

#### Base64 Encoding Format

The images should be converted from binary format to a Base64 string




Images must be Base64 encoded in the following format:

```
data:image/jpeg;base64,${Base64data}
```

#### Request Format

The request body should contain two Base64-encoded images in the following format:

```js
const data = {
  img: "data:image/jpeg;base64,${Base64data}", // Base64-encoded image
};
```

## Sending Image Comparison Request

The request is made using the following code:




This sends the encoded images to the specified URL for comparison.

## Code Snippet for API Integration

Below is a code snippet demonstrating how to use the number of faces detection API with Node.js:

```js




// Load environment variables from .env file
dotenv.config();

// Get the directory of the current file
const __dirname = path.resolve();

// Function to read image files and convert them to base64
function getBase64Image(imageName) {
  const filePath = path.join(__dirname, "image", imageName);
  console.log(`Resolved file path: ${filePath}`);
  try {
    const image = readFileSync(filePath);
    const base64Data = Buffer.from(image).toString("base64");
    return `data:image/jpeg;base64,${base64Data}`;
  } catch (error) {
    console.error(`Error reading image file: ${filePath}`, error.message);
    throw error;
  }
}

async function noOfFaces(getImg) {
  const url = "https://api.videosdk.live/ai/v1/face-verification/detect-faces";
  const headers = {
    Authorization: `${process.env.API_KEY}`,
    "Content-Type": "application/json",
  };
  const data = {
    img: getBase64Image(getImg),
  };

  try {
    const response = await axios.post(url, data, { headers });
    console.log(response.data);
  } catch (error) {
    console.error(
      "Error during Number of face detection :",
      error.response ? error.response.data : error.message
    );
  }
}

// Main function to run the API calls
async function main() {
  const getImg = "img1.jpg";
  await spoofDetection(getImg);
}

// Run the main function
main().catch((error) =>
  console.error("Error in main function:", error.message)
);
```

##### Given below is a test run of the example.

**Input Image** : group_photo.jpg - A photo showing a group of five people.

<div style={{ display: "flex", alignItems: "center", gap: "10px" }}>
  <img
    src="https://cdn.videosdk.live/website-resources/docs-resources/group_of_people.jpg"
    alt="Image 1"
    width="45%"
  />
</div>

When this image is sent to the Face Detection API, The response will return an int value number_of_faces in output :

```js
{
  number_of_faces: 5; // number of faces detected
}
```



---

# OCR API (BETA)


---
title: Ocr | Android SDK Documentation | VideoSDK
description: Learn how to implement ocr using VideoSDK's Android SDK. Step-by-step integration guide for seamless identity verification or SIP connectivity.
---

This API will take front and back part of the document in input, scan through the document and return all the available fields of the document in JSON formatted response. Fields can vary as per type of document in response..

:::important

This API is available in Enterprise plan only.

:::

## HTTP Method and Endpoint

**<span style={{ color: "#86EFAC", fontWeight: "bold" }}>POST</span>** | `https://api.videosdk.live/ai/v1/ocr`

## Headers Parameter

### Authorization

**values** : YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

_Note_ : the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by referring this Guide: [Generate Auth token](https://docs.videosdk.live/api-reference/realtime-communication/intro)

### Content-Type

**values** : `application/json`

This is useful for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.




## Data Parameter

#### Base64 Encoding Format

The images should be converted from binary format to a Base64 string




Images must be Base64 encoded in the following format:

```
data:image/jpeg;base64,${Base64data}
```

#### Request Format

The request body should contain two Base64-encoded images in the following format:

```
const data = {
   "frontpart": "data:image/jpeg;base64,${Base64data}", // Base64-encoded image
   "backpart": "data:image/jpeg;base64,${Base64data}", // Base64-encoded image
}
```

## Sending Image Comparison Request

The request is made using the following code:




This sends the encoded images to the specified URL for comparison.

## Response

The response will return all the available fields of document in JSON formated response :

```javascript
{
   idType: "", // document Type
   idNumber: "", // document Number
   name: "", // name
   dateOfBirth: "",
   address: "",
   gender: "",
   mobileNumber: ""
};
```

## Code Snippet for API Integration

Below is a code snippet demonstrating how to use OCR API (BETA) with Node.js:

```javascript




// Load environment variables from .env file
dotenv.config();

// Get the directory of the current file
const __dirname = path.resolve();

// Function to read image files and convert them to base64
function getBase64Image(imageName) {
  const filePath = path.join(__dirname, "image", imageName);
  console.log(`Resolved file path: ${filePath}`);
  try {
    const image = readFileSync(filePath);
    const base64Data = Buffer.from(image).toString("base64");
    return `data:image/jpeg;base64,${base64Data}`;
  } catch (error) {
    console.error(`Error reading image file: ${filePath}`, error.message);
    throw error;
  }
}

async function ocr(frontImg, backImg) {
  const url = "https://api.videosdk.live/ai/v1/ocr";
  const headers = {
    Authorization: `${process.env.API_KEY}`,
    "Content-Type": "application/json",
  };
  const data = {
    frontPart: getBase64Image(frontImg),
    backPart: getBase64Image(backImg),
  };

  try {
    const response = await axios.post(url, data, { headers });
    console.log(response.data);
  } catch (error) {
    console.error(
      "Error during OCR :",
      error.response ? error.response.data : error.message
    );
  }
}

// Main function to run the API calls
async function main() {
  const frontImg = "img4.jpg";
  const backImg = "img5.jpg";
  await ocr(frontImg, backImg);
}

// Run the main function
main().catch((error) =>
  console.error("Error in main function:", error.message)
);
```



---

# AI Noise Suppresion - Javascript

Noise suppression is a feature that identifies and filters out background noise from an audio input during a liveStream or call. This feature can be particularly useful in noisy environments or when participants are using low-quality microphones.


### Install VideoSDK Media Processor package

**npm:**

```js
npm install --save "@videosdk.live/videosdk-media-processor-web"
```

---

**yarn:**

```js
yarn add "@videosdk.live/videosdk-media-processor-web"
```

### Instantiate `VideoSDKNoiseSuppressor`

After installing the library, initialize an instance of the `VideoSDKNoiseSuppressor`. 

```js
// Import package

let liveStream;

// Initialize Meeting
liveStream = VideoSDK.initMeeting({
  // ...
});

// Instantiate VideoSDKNoiseSuppressor Class
const noiseProcessor = new VideoSDKNoiseSuppressor();
```

### Getting Processed Stream

You can obtain the processed stream using the `getNoiseSuppressedAudioStream` method, which takes a `MediaStream` as input and returns the noise-suppressed stream.

```js
// Import package

let liveStream;

// Initialize Meeting
liveStream = VideoSDK.initMeeting({
  // ...
});

// Instantiate VideoSDKNoiseSuppressor Class
const noiseProcessor = new VideoSDKNoiseSuppressor();

const startNoiseSuppressionBtn = document.getElementById(
  "startNoiseSuppressionBtn"
);
startNoiseSuppressionBtn.addEventListener("click", async () => {
  //highlight-start
  // Getting stream from mic
  const stream = await VideoSDK.createMicrophoneAudioTrack({});
  const processedStream = await noiseProcessor.getNoiseSuppressedAudioStream(
    stream
  );
  //highlight-end
});
```

### Passing Processed Stream to VideoSDK

Once you have the processed stream, you can pass it to functions like `enableMic()` or `changMic()` to apply the noise suppresion effect during your liveStream.

```js
// Import package

let liveStream;

// Initialize Meeting
liveStream = VideoSDK.initMeeting({
  // ...
});

// Instantiate VideoSDKNoiseSuppressor Class
const noiseProcessor = new VideoSDKNoiseSuppressor();

const startNoiseSuppressionBtn = document.getElementById(
  "startNoiseSuppressionBtn"
);
startNoiseSuppressionBtn.addEventListener("click", async () => {
  // Getting stream from mic
  const stream = await createMicrophoneAudioTrack({});
  const processedStream = await noiseProcessor.getNoiseSuppressedAudioStream(
    stream
  );

  //highlight-start
  liveStream?.changeMic(processedStream);
  //highlight-end
});
```

### Stopping Noise Suppression

You can stop the noise suppression by replacing the audio stream with a new plain audio stream.

```js
// Import package

let liveStream;

// Initialize Meeting
liveStream = VideoSDK.initMeeting({
  // ...
});

// Instantiate VideoSDKNoiseSuppressor Class
const noiseProcessor = new VideoSDKNoiseSuppressor();

const stopNoiseSuppressionBtn = document.getElementById(
  "stopNoiseSuppressionBtn"
);
stopNoiseSuppressionBtn.addEventListener("click", async () => {
  //highlight-start
  // Pass mic MediaStream in VideoSDK `changeMic` method
  const stream = await VideoSDK.createMicrophoneAudioTrack({});
  liveStream?.changeMic(stream);
  //highlight-end
});
```

### Extras

You can also pass this processed stream during initialization of the liveStream.

```js
// Import package

// Instantiate VideoSDKNoiseSuppressor Class
const noiseProcessor = new VideoSDKNoiseSuppressor();

// Getting stream from mic
const stream = await VideoSDK.createMicrophoneAudioTrack({});
const processedStream = await noiseProcessor.getNoiseSuppressedAudioStream(
  stream
);

let liveStream;
liveStream = VideoSDK.initMeeting({
  meetingId: "meetingId",
  micEnabled: true,
  webcamEnabled: true,
  name: "TestUser",
  customMicrophoneAudioTrack: processedStream, // Pass processed MediaStream in VideoSDK
});
```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [unmuteMic()](/javascript/api/sdk-reference/meeting-class/methods#unmutemic)
- [muteMic()](/javascript/api/sdk-reference/meeting-class/methods#mutemic)


---

# Understanding Analytics Dashboard - JavaScript

Welcome to the world of actionable insights and empowered decision-making. VideoSDK's session analytics dashboard is your gateway to understanding, optimizing, and elevating every aspect of your sessions.

## Accessing Analytics Made Easy

Navigating through session data is a breeze with VideoSDK. Simply head to your session page at https://app.videosdk.live/meetings/sessions, where a treasure trove of session information awaits.

### How to Access Analytics?

Open Session Analytics effortlessly by following these steps:

1. **Click on Meeting-ID:**
    - Directly access analytics by clicking on the meeting-ID within the session table.
2. **Hover and Click View Analytics:**
    - Hover over a specific meeting row to reveal the **View Analytics** button in the Actions Column.
    - Click on **View Analytics** to open the Session Overview sidebar, unlocking a wealth of insights.

![Access Analytics](https://cdn.videosdk.live/website-resources/docs-resources/access_analytics.png)

---

There are three tabs available within the session analytics view:

## **1. Session Overview**

This tab provides an overview of the session, including its duration and participant details. You can explore individual participant statistics to understand their session performance better.

## **2. Errors**

In this tab, you can find information about any errors encountered during the session. It helps you identify and address issues like network problems or technical glitches promptly.

## **3. Session Stats**

Explore data and metrics sent and received by participants to measure performance of the session in this tab. It offers insights into data exchange among participants, including metrics on jitter, RTT, and packet loss, resolutions, and fps aiding in assessing communication efficiency.

Let's dive deeper into each of these tabs to gain a better understanding of session analytics.

# Session Overview

The session overview page is your compass in the sea of data. Here's what you'll uncover:

- **Meeting ID:** Unique identifier for the meeting in the format of `abcd-efgh-ijkl`.
- **Session ID:** Unique identifier for each session, uniquely identified by its `sessionId`.
- **Session Status:** Indicates if the session is ongoing or ended.
- **Session Initiating Time:** Time taken by the first participant to establish the connection.
- **Start and End Time:** Marks the start and end of the session.
- **Total Unique Participants Joined:** Total number of unique participants in the session.
- **Total Session Duration:** Overall duration of the session from start to end.
- **Total Participant Minutes:** A sum of all participant duration.
- **Recording, HLS, RTMP:** Additional services used in the session.

### Participant Table List

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for each participant.
- **Join Time:** Time taken by the participant to establish connection.
- **Duration:** Total time spent by this participant in the session.

### Efficient Session Management with Actions

Enhance your session management with streamlined actions:

- **Kick Out Participants:** Effortlessly remove/kickout participants from ongoing sessions.
- **Detailed Participant Analytics:**
- Hover over a specific participant row to reveal the `View Stats` button at the end of the row.
- Click on `View Stats` to open the Participant Overview sidebar.
    
![View Stats](https://cdn.videosdk.live/website-resources/docs-resources/view_stats.png)

## Explore Participant Insights

Discover valuable participant data that provides a clear view of engagement and experience:

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for better interaction.
- **Joined At:** Indicates the precise moment when participant connects to the session.
- **Left At:** Indicates the precise moment when participant left the session.
- **Total Duration:** Total duration of participant within that session.
- **Joining Time:** Time taken by the this participant to establish the connection.
- **Location:** Approx. geographic location from where the participant joined.
- **Platform:** Specifies whether participants are using a desktop or mobile device.
- **Device Info:** Offers details regarding the participant's device.
- **OS:** Provides information about the participant's OS.
- **Browser:** Provides specifics about the participant's browser
- **SDK Version:** Indicates the version of the SDK used by participants.

### Understanding Participant Call Health

We've developed call health to offer a rapid assessment of participant performance during calls. This feature highlights the performance of audio, video, and screen sharing audio-video separately. We've utilized color theory, with green indicating good performance, orange for moderate, and red for poor performance, to enhance clarity. For detailed insights, simply hover over the bars

![Participant Call Health](https://cdn.videosdk.live/website-resources/docs-resources/participant_call_health.png)

## Participant Session Stats

Dive into Participant Session Stats for valuable insights into your session experience! With just a click on `View Session Stats` at the bottom of the page, unlock a treasure trove of data crucial for understanding audio and video experiences.

Within this section, you can observe quality metrics for the selected participant, comparing them to others. Additionally, the `Sessions Stats` covers quality stats comparison for every participant. Keep reading to explore more about Session Stats.

**Visualizing Session Performance from Both Sides**

This section provides a two-sided view of your session's metrics.

- **Left Side: Sender Participant Graph** This section displays graphs representing the metrics sent by the sender participant.. Here, you can see how the various factors impacted the data you transmitted.
- **Right Side: Receiver Participant Graph** On the right side, you'll find a dropdown menu where you can select a specific participant. Choosing a receiver will display graphs showcasing the metrics **received by that participant**. This allows you to compare the sending experience (left side) with the receiving experience (right side) for different participants.

![VideoSDK Jitter Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_jitter_graph.png)

**See How Your Session Performed**

These metrics give you a clear picture of your session's quality. Understanding them helps you spot any issues and keep things running smoothly. Let's dive into what each metric means!

**Jitter:** Imagine your internet connection like a bumpy road. Jitter is how much those bumps cause your signal to bounce around. Less jitter means a smoother ride for your data (audio and video, threshold ≤ 30ms).

**RTT (Latency):** This is how long it takes for data to travel between you and the server you're connected to. Think of it like the time it takes for a message to get delivered – a lower RTT means a faster delivery (affects both audio and video, threshold ≤ 300ms).

**Bitrate:** This measures the amount of data flowing through your connection per second. Imagine it like the width of a water pipe – a higher bitrate allows for more data to flow, which can be good for high-quality audio/video or fast downloads.

**Packet Loss:** Think of data traveling in tiny packets. Packet loss is when some of those packets get dropped along the way. More packet loss means information might be missing, affecting things like audio/video quality or lag in games (threshold ≤ 5%).

**Resolution:** This refers to the sharpness and detail of an image or video. Think of it like the number of pixels on your screen – a higher resolution means a crisper picture (**Video Only**).

**FPS (Frames Per Second):** This measures how many images (frames) are displayed on your screen every second. Imagine it like a flipbook – a higher FPS creates a smoother and more fluid animation or video experience (**Video Only**).

![VideoSDK FPS Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_fps_graph.png)

![VideoSDK Resolution Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_resolution_graph.png)

---

# **Investigate Session Errors**

Get to the root of smoother sessions by addressing errors directly. Use the Errors tab to explore details of errors encountered during your session. Note: Session errors are visible with JS SDK v0.0.82 or higher, React SDK v0.1.85 or higher, and React Native v0.1.6 or newer versions.

- **Participant Name & ID:** Quickly identify the participant associated with each error for swift resolution.
- **Error Types:** Understand the different types of errors encountered, such as network issues or connection disruptions.
- **Detailed Descriptions:** Access clear explanations of errors to take actionable steps towards solution.

![VideoSDK Error Details](https://cdn.videosdk.live/website-resources/docs-resources/error_new.png)

# **Analyse Session Stats**

Similar to `Participant Session Stats`, this tab covers quality statistics sent by individual participants. You can select any participant to compare effectively with others.

Choose a sender participant from the dropdown menu on the left and select a recipient on the right to compare data over different time frames. This allows you to identify and explore issues within specific durations.

This tab covers the same metrics as covered in the `participant session stats`: Jitter, RTT (Latency), Bitrate, Packet-loss, Resolution (Video only), and FPS (Video only).

![VideoSDK Session Stats](https://cdn.videosdk.live/website-resources/docs-resources/session_stats.png)


---

# Understanding Call Quality - JavaScript

When developing a video call app, customer satisfaction heavily depends on the app's video and audio quality and its fluctuation.

## Call Quality

From the user's perspective, good video quality is defined as smooth and clear video, along with crystal clear audio. Developers consider good video quality as high-resolution, high-frame-rate video with minimal latency and high-bitrate audio with minimal audio loss.

## Factors affecting Quality

When measuring video and audio quality, several variables come into play. The common factors affecting quality are as follows:

### `1. Network Bandwidth`

- Network bandwidth is the measure of a user's network capacity, indicating how much data can be received and sent.
- If the participant's bandwidth is low, they are likely to experience pixelated or frozen video, along with robotic voice or minor audio interruptions.
- Frequent changes in network providers can also lead to significant fluctuations in internet bandwidth, resulting in poor video quality.

### `2. Latency`

- Latency refers to the time it takes for data to transfer from one machine to another.
- If the meeting is hosted in `Ohio` region, and users are joining from `Singapore` region, this can result in a long delay for data to transfer between mackines. Therefore, it is advisable to choose a server based on your user base.
- With VideoSDK, you can specify the server during the creation of a Meeting/Room.

### `3. CPU Usage`

- CPU Usage is also a determining factor, as all the audio and video streams going out and coming in need to be encoded or decoded, requiring a significant amount of computation.
- The higher the resolution and frame rate of the videos, the greater the computation required, which can lead to a bottleneck in delivering good-quality video.
- If the CPU is heavily consumed, it can also result in choppy or robotic audio.

### `4. Camera and Mic Quality`

- The camera and microphone should capture high-quality streams to ensure that remote users don't receive a low-quality stream even if they have bad network bandwidth.

## Identifying various issues related to Quality.

In order to identify potential issues, VideoSDK collects various audio and video-related metrics that can help pinpoint quality concerns. Take a look at these metrics and understand what they indicate.

### `1. Resolution and Framerate`

- Resolution and frame rate serve as crucial metrics for video quality in a video call app. Resolution indicates the number of pixels in a video image, while frame rate denotes the number of frames displayed per second.

- While higher resolutions and frame rates can enhance video quality, they also demand more bandwidth and processing power. It's essential to optimize these metrics based on the devices and network conditions of your users.

- For instance, if the majority of your users are on mobile devices, opting for a lower resolution and frame rate may be more suitable to ensure smooth playback and minimize bandwidth usage.

- If your user base comprises both mobile and desktop devices, adopting higher resolution for desktops and mid-resolutions for mobile devices can contribute to improved performance and quality while conserving bandwidth on mobile devices.

### `2. Bitrate`

- Bitrate represents the number of bits per second transmitted or received during the transmission of audio or video streams. It is a crucial parameter for assessing the quality of audio or video streams and should be adjusted for each resolution to strike a balance between performance and bandwidth utilization.

- In scenarios with excellent network conditions, a higher bitrate can lead to significantly improved video quality. However, it's essential to be cautious when dealing with very high bitrates on mobile devices, as it may result in heating issues due to the substantial computational requirements for encoding and decoding videos.

##### Example

We used the same phone **(iPhone 14)**, for both participants, but there were differences in resolution and bitrate. The first participant had a resolution of **`1280x720`** with a bitrate of **`1442 kbps`**, while the second participant had a resolution of **`960x540`** with a bitrate of **`642 kbps`**. Surprisingly, both participants' videos appeared to be of equal quality despite variations in resolution and bitrate.

![resolution-and-bitrate](/img/resolution-and-bitrate.png)

### `3. Packet Loss`

- Packet loss is a metric that reveals the number of lost data packets during transmission from the sender to the receiver. It can happen due to network congestion, hardware or software issues, or network latency. Increased packet loss can lead to degraded video and audio quality, as the absence of packets may cause gaps or distortions in the media stream.


<div style={{textAlign: 'center'}}>



</div>

### `4. Jitter`

- The audio and video packets are sent out at random intervals over a specified time frame as they travel between the server and client. Jitter occurs when there is a variation in transmitting or receiving these data packets due to a faulty network connection.

- When data packets experience delays during transmission to the participant, usually because the network is busy, they may result in pixelated video during a video call or sound choppy, distorted, or robotic in a voice call upon arrival. This creates jitter, with packets arriving at random intervals.

### `5. Round Trip Time (Latency)`

- Round trip time refers to the duration it takes for data packets to be transmitted from the user's device to the server and back. If the servers are located far from the user's location, they may experience high latency (delay).

- With VideoSDK, this factor is addressed as we automatically choose the nearest available server for participants. However, if you are geofencing to a specific region, ensure that you choose the server nearest to your users.

<center>

![resolution-and-bitrate](/img/rtt.png)

</center>

## Checking Realtime Statistics

VideoSDK provides methods to check the realtime statistics of audio and video of all the participants.

### `getVideoStats()`

- The `getVideoStats()` method returns an object containing the different quality parameters for video stream, which can be accessed through the `useParticipant` hook.

- This object will contain values for the specific participant's video stream, including resolution, frame rate, bitrate, jitter, round trip time, and packet loss.

<div style={{textAlign: 'center'}}>



</div>

### `getAudioStats()`

- The `getAudioStats()` method returns an object containing the different quality parameters for audio stream, which can be accessed through the `useParticipant` hook.

- This object will contain values for the specific participant's audio stream, including bitrate, jitter, round trip time and packet loss.

### `getShareStats()`

- The `getShareStats()` method returns an object containing the different quality parameters for screen share stream, which can be accessed through the `useParticipant` hook.

- This objects will contain values for the specific participant's screen share stream, including resolution, frame rate, bitrate, jitter, round trip time, and packet loss.

### `getShareAudioStats()`

- The `getShareAudioStats()` method returns an object containing the different quality parameters for screen share audio stream, which can be accessed through the `useParticipant` hook.

- This object will contain values for the specific participant's screen share audio stream, including bitrate, jitter, round trip time and packet loss.

:::note
To show the popup dialog for the participant's realtime stats, you can [refer to this component](https://github.com/videosdk-live/videosdk-rtc-react-sdk-example/blob/main/src/utils/common.js#L142).
:::

## Quality analysis Graphs

For all sessions conducted using VideoSDK, you can access quality analysis graphs from the [VideoSDK Dashboard](https://app.videosdk.live/meetings/sessions). These graphs help you visualize real-time data and identify spikes in certain parameters during calls, aiding in understanding the reasons for quality issues.

![quality analysis](/img/quality-analysis.png)

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [getVideoStats()](/javascript/api/sdk-reference/participant-class/methods#getvideostats)
- [getAudioStats()](/javascript/api/sdk-reference/participant-class/methods#getaudiostats)
- [getShareStats()](/javascript/api/sdk-reference/participant-class/methods#getsharestats)


---

# Change Mode - JavaScript

In a live stream, audience members usually join in `RECV_ONLY` mode, meaning they can only view and listen to the hosts. However, if a host invites an audience member to actively participate (e.g., to speak or present), the audience member can switch their mode to `SEND_AND_RECV` using the changeMode() method.

This guide explains how to use the changeMode() method and walks through a sample implementation where a host invites an audience member to become a host using PubSub.

### `changeMode()`

- The `changeMode()` method allows a participant to switch between modes during a live stream—for example, from audience to host.

#### Example

```js
let liveStream;

// Initialize Live Stream
liveStream = VideoSDK.initMeeting({
  // ...
});

const changeModeBtn = document.getElementById("changeModeBtn");
changeModeBtn.addEventListener("click", () => {
  // Changing Mode
  liveStream?.changeMode("SEND_AND_RECV");
});
```

#### Implementation Guide

#### Step 1 : Create a Pubsub Topic

- Set up a PubSub topic to send a mode change request from the host to a specific audience member.

```js
// Create a topic for the participant
const topic = `REQUEST_TO_JOIN_AS_HOST_${participantId}`;

// Publish function
function invitePublish(message) {
  liveStream?.pubSub.publish(topic, message);
}
```

#### Step 2 : Create an Invite Button

- Add an "Invite on Stage" button for each audience member. When clicked, it publishes a PubSub message with the mode "SEND_AND_RECV" to that participant.

```js
const participants = liveStream.participants;
const participant = participants.get("<participant-id>");
const mode = participant ? participant.mode : null;

// Define the topic
const topic = `REQUEST_TO_JOIN_AS_HOST_${participantId}`;

// Publish function to send the request
function invitePublish(message) {
  liveStream?.pubSub.publish(topic, message);
}

// Handle request
function handleRequest() {
  invitePublish({ mode: "SEND_AND_RECV" });
}

// Render a button if the mode is "RECV_ONLY"
const container = document.createElement("div");

if (mode === "RECV_ONLY") {
  const container = document.createElement("div"); // Container for the button

  const button = document.createElement("div");
  button.innerText = "Invite on Stage";
  button.style.cursor = "pointer"; // Make the button look clickable
  button.onclick = handleRequest;

  container.appendChild(button);

  // Append the container to the body (or specific container)
  document.body.appendChild(container);
}
```

#### Step 3 : Create a Listener to Change the Mode

- On the audience side, subscribe to the specific PubSub topic. When a mode request is received, update the participant’s mode using changeMode().

```js
const topic = `REQUEST_TO_JOIN_${mMeeting?.localParticipant?.id}`;
function handleMessage({ message }) {
  if (message && message.mode) {
    liveStream.changeMode(message.mode);
  }
}
liveStream.pubSub.subscribe(topic, handleMessage);
```




## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [changeMode()](/javascript/api/sdk-reference/meeting-class/methods#changemode)
- [PubSub](/javascript/api/sdk-reference/meeting-class/pubsub)


---

# Remove Participant - JavaScript

When hosting a live stream, it's essential for the host to have the capability to to remove a participant from the live stream. This can be useful in various scenarios where a participant is causing disturbance, behaving inappropriately, or is not following the guidelines. This guide focuses on this very aspect of removing a particpant from the live stream.

VideoSDK provides three ways to do so:

1. [Using SDK](#1-using-sdk)
2. [Using VideoSDK Dashboard](#2-using-videosdk-dashboard)
3. [Using Rest API](#3-using-rest-api)

## 1. Using SDK

### `remove()`

The `remove()` method allows for the removal of a participant during an on-going session. This can be helpful when moderation is required in a particular live stream.

```js
const participants = liveStream.participants;
const participant = participants.get("<participant-id>");

// remove remote participant
participant?.remove();
```

### Events associated with remove()

Following callbacks are received when a participant is removed from the meeting.

- The participant who was removed from the meeting will receive a callback on the [`meeting-left`](/javascript/api/sdk-reference/meeting-class/events#meeting-left) event.
- All other [remote participants-including all the hosts and audience members](/javascript/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a callback on the [`participant-left`](/javascript/api/sdk-reference/meeting-class/events#participant-left) event with the Participant object.

## 2. Using VideoSDK Dashboard

- For removing a participant using the VideoSDK Dashboard, navigate to the session page on [VideoSDK Dashboard](https://app.videosdk.live/meetings/sessions). Select the specific session, and from the list of participants, choose the participant you wish to remove. Utilize the provided options to remove the selected participant from the session.


<div style={{textAlign: 'center'}}>



</div>

## 3. Using Rest API

- You can also remove a particular participant from the live stream [using the REST API](/api-reference/realtime-communication/remove-participant).
- To employ this method, you need the `sessionId` of the live stream and the `participantId` of the individual you intend to remove.

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [remove()](/javascript/api/sdk-reference/participant-class/methods#remove)
- [meeting-left](/javascript/api/sdk-reference/meeting-class/events#meeting-left)
- [participant-left](/javascript/api/sdk-reference/meeting-class/events#participant-left)


---

# Audience Polls during Live Stream - JavaScript

Interactive polls are a great way to increase engagement during livestreams. Using VideoSDK’s PubSub mechanism, you can easily implement real-time audience polling, where viewers can vote and see live results instantly.

This guide walks you through how to create, send, and visualize poll results during a livestream.

### Step 1: Creating and Publishing a Poll

To initiate a poll, use the `pubsub` method with a `POLL` topic. The poll structure should include a question and multiple options. This message will be published to all participants.

```js title="PollHostView.js"
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

const startPoll = () => {
  const pollData = {
    id: Date.now(),
    question: "Which feature do you love the most?",
    options: ["Reactions", "Screen Share", "Whiteboard", "Polls"],
    responses: {},
  };

  liveStream?.pubSub.publish("POLL", pollData);
};

// Create the button
const button = document.createElement("button");
button.innerText = "Start Poll";
button.onclick = startPoll;

// Append to DOM
document.body.appendChild(button);
```

### Step 2: Subscribing to Polls and Displaying Options

Participants can listen to the POLL topic and render voting options dynamically based on the incoming data.

```js
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

let activePoll = null;

const pollContainer = document.createElement("div");
document.body.appendChild(pollContainer);

const renderPoll = () => {
  pollContainer.innerHTML = ""; // Clear previous poll

  if (!activePoll) return;

  const questionElem = document.createElement("h3");
  questionElem.innerText = activePoll.question;
  pollContainer.appendChild(questionElem);

  activePoll.options.forEach((option) => {
    const button = document.createElement("button");
    button.innerText = option;
    button.onclick = () => {
      liveStream?.pubSub.publish("POLL_RESPONSE", {
        pollId: activePoll.id,
        option,
      });

      // Optionally disable buttons after vote
      pollContainer.innerHTML = `<p>Thanks for voting!</p>`;
    };
    pollContainer.appendChild(button);
  });
};

// Subscribe to incoming polls
liveStream?.pubSub.subscribe("POLL", ({ message }) => {
  activePoll = message;
  renderPoll();
});
```

### Step 3: Aggregating and Displaying Poll Results

The host can subscribe to the POLL_RESPONSE topic to collect responses and render the result in real-time.

```js
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

const results = {};

const resultsContainer = document.createElement("div");
document.body.appendChild(resultsContainer);

const renderResults = () => {
  resultsContainer.innerHTML = "";

  Object.entries(results).forEach(([pollId, pollResult]) => {
    const pollDiv = document.createElement("div");

    const heading = document.createElement("h4");
    heading.innerText = `Poll ID: ${pollId}`;
    pollDiv.appendChild(heading);

    const list = document.createElement("ul");
    Object.entries(pollResult).forEach(([option, count]) => {
      const item = document.createElement("li");
      item.innerText = `${option}: ${count} votes`;
      list.appendChild(item);
    });

    pollDiv.appendChild(list);
    resultsContainer.appendChild(pollDiv);
  });
};

// Subscribe to poll responses
liveStream?.pubSub.subscribe("POLL_RESPONSE", ({ message }) => {
  const { pollId, option } = message;
  const current = results[pollId] || {};
  results[pollId] = {
    ...current,
    [option]: (current[option] || 0) + 1,
  };

  renderResults();
});
```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [PubSub](/javascript/api/sdk-reference/meeting-class/pubsub)


---

<h1> {props.title} </h1>{" "}

### Why we are using JWT based Token ?

Token based authentication allows users to verify their identity by providing generated API key and secret.

We use JWT token for the authentication purpose because Token-based authentication is **widely used** in modern web applications and APIs because it offers several benefits over traditional authentication. For example, it can **reduce the risk of the credentials being misused**, and it allows for **more fine-grained control** over access to resources. Additionally, tokens can be easily revoked or expired, making it easier to manage access rights.

### How to generate Token ?

To manage secured communication, every participant that connects to the meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key` which you can get from [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

#### 1. Generating token from Dashboard

If you are looking to do **testing or for development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for getting token includes generating it from your backend server which will help in **keeping your credentials safe**.
:::

#### 2. Generating token in your backend

- Your server will generate access token using your API key and secret.
  - While generating a token, you can provide **expiration time, permissions and roles** which are discussed later in this section.
- Your client obtains token from your backend server.
- For token validation, client will pass this token to VideoSDK server.
- VideoSDK server will only allow entry in the meeting if the token is valid.

![img2.png](../../static/img/authentication-and-token.png)




Follow our official example repositories to setup token API [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)

### Payload while generating token

```js
{
 apikey: API_KEY, //MANDATORY
 permissions: [`allow_join`], //`ask_join` || `allow_mod` //MANDATORY
 version: 2, //OPTIONAL
 roomId: ROOM_ID, //OPTIONAL,
 participantId: PARTICIPANT_ID, //OPTIONAL
 roles: ['crawler', 'rtc'], //OPTIONAL
}
```

- **`apikey`(Mandatory)**: This must be the API Key generated from the VideoSDK Dashboard. You can get it from [here](https://app.videosdk.live/api-keys).

- **`permissions`(Mandatory)**: By providing the permissions, you can control what a participant can do in the meeting and whether he can join the meeting directly.

  Available permissions are:

  - **`allow_join`**: The participant is **allowed to join** the meeting directly.
  - **`ask_join`**: The participant is required to **ask for permission to join** the meeting. The participant having the permission `allow_join` can accept or reject a participant whenever someone wants to join.
  - **`allow_mod`**: The participant is **allowed to toggle** webcam & mic of other participants.

- **`version`(optional)**: For accessing the [v2 API](/api-reference/realtime-communication/intro), you need to provide `2` as the version value.

  - For passing `roomId`, `participantId` or `roles` parameters in payload, it is essential to set the version value to `2`.

- **`roomId`(optional)**: To provide customised access control, you can make the token applicable to a particular room by including the `roomId` in the payload.

- **`participantId`(optional)**: You can include the `participantId` in the payload to limit the token's access to a particular participant.

- **`roles`(optional)**:

  - **`crawler`**: This role is only for accessing [v2 API](/api-reference/realtime-communication/intro), you can not use this token for running the `Meeting`/`Room`.
  - **`rtc`**: This role is only allowed for running the `Meeting` / `Room`, with this role you can not use [server-side APIs](/api-reference/realtime-communication/intro).

Then, you have to sign this payload with your **`SECRET KEY`** and `jwt` options using the **`HS256 algorithm`**.

### Expiration time

You can set any expiration time to the token. But in the **production environment**, it is recommended to generate a token with **short expiration time** because by any chance if someone gets hold of the token, it won't be valid for a longer period of time.

### What happens if token is expired?

If your token is expired, the user won't be able to join the meeting and all the API calls will give error with message `Token is invalid or expired`.

:::note
Token is validated only once while joining the meeting, so if a person joins the meeting and the token gets expired after that, there won't be any issue in the current meeting.
:::

## How to check validity of token?

1. After generating the token, visit [jwt.io](https://jwt.io) and paste your token in the given area.
2. You will be able to see the payload you passed while generating the token and also be able to see the expiration time and token creation time.

![img1.png](../../static/img/validate-token.png)

## API Settings & Controls

The VideoSDK Dashboard provides a powerful [API Settings](https://app.videosdk.live/api-keys) section where you can configure various services and controls for your meetings. These settings allow you to customize the behavior of different features directly from the dashboard without requiring code changes.

## Audio/Video Configurations

:::note
Runtime configuration from the dashboard has higher precedence than static SDK configurations.
If a value is modified in the dashboard, it will override any previously defined SDK settings for that session.

Example:
Code: Video = HD → Dashboard: Video = Full HD → Applied: Full HD
:::

### Maximum Send Bitrate Per Participant

Control the maximum total upload bandwidth for all media streams from a single participant.

![Maximum Send Bitrate](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.00.11%E2%80%AFPM.png)

**Available Options:**
- **Auto**: Removes the upload bitrate limit (recommended for best quality)
- **SD (800kbps)**: Standard definition bitrate
- **HD (1500kbps)**: High definition bitrate
- **Full HD (3000kbps)**: Full high definition bitrate

:::tip
Setting this to **Auto** provides the best video quality as it removes upload bitrate constraints, allowing adaptive streaming based on network conditions.
:::

## Recording & Streaming Configuration

:::note
Recording and HLS follow a precedence-based configuration model:

API/SDK configuration → Highest priority
Dashboard configuration → Used only when no API values are defined

Any parameters explicitly set via the API will not be overridden by dashboard changes.
:::

### Recording Configuration

Configure recording settings for your meetings including layout, quality, and auto-start options.

![Recording Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.01.00%E2%80%AFPM.png)

**Recording Controls:**
- **Enabled**: Toggle to enable/disable recording functionality
- **Enabled Modes**: Choose between Video & Audio or Audio Only recording
- **Start Recording Automatically**: Auto-start recording when meeting begins
- **Layout Style**: Select Grid layout for recording composition
- **Maximum Tiles In Grid**: Set the number of participants visible in grid (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme for recordings
- **Video Orientation**: Choose between Landscape or Portrait mode
- **Recording Quality**: Select quality level (e.g., HD Medium)
- **Recording Mode**: Choose between Video & Audio or Audio Only

### HLS Streaming Configuration

Configure HTTP Live Streaming (HLS) settings for broadcasting your meetings.

![HLS Streaming Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.02.18%E2%80%AFPM.png)

**HLS Streaming Controls:**
- **Enabled**: Toggle to enable/disable HLS streaming
- **Enabled Modes**: Choose between Video & Audio or Audio Only streaming
- **Auto Start HLS**: Automatically start HLS when meeting begins
- **Record HLS Stream**: Enable recording of the HLS stream
- **Layout Style**: Select Grid layout for stream composition
- **Maximum Tiles In Grid**: Set the number of participants visible (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme
- **HLS Orientation**: Choose between Landscape or Portrait mode
- **HLS Quality**: Select streaming quality (e.g., HD Medium)
- **HLS Streaming Mode**: Choose between Video & Audio or Audio Only

### Additional Service Controls

Enable or disable additional services for your API key.

![Service Controls](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.08%E2%80%AFPM.png)

**Available Services:**
- **RTMP Output**: Enable RTMP streaming to external platforms
- **SIP Integration**: Enable SIP (Session Initiation Protocol) integration for telephony
- **Realtime Translation**: Enable real-time language translation in meetings

### Transcription & Summary

Configure transcription and domain whitelisting for your API key.

![Transcription Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.50%E2%80%AFPM.png)

**Transcription Controls:**
- **Enabled**: Toggle to enable/disable transcription and summary features
- **Whitelist Domain**: Add domain restrictions for API key usage
  - Enter domain names in the format `https://domain.name`
  - Click "Add Domain" to whitelist specific domains
  - Only whitelisted domains can use this API key
  - When no domains are whitelisted, the API key can be used from any domain


---

# Developer Experience Guidelines - Javascript




---

# Handle Large Rooms - Javascript




---

# User Experience Guidelines - Javascript




---

# Chat during Live Stream - JavaScript

Enhance your live stream experience by enabling real-time audience chat using VideoSDK's `pubSub` property. Whether you’re streaming a webinar, online event, or an interactive session, integrating a chat system lets your viewers engage, ask questions, and react instantly. This guide shows how to build a group or private chat interface for a live stream using the Publish-Subscribe (PubSub) mechanism.

This guide focuses on using PubSub to implement Chat functionality. If you are not familiar with the PubSub mechanism and `usePubSub` hook, you can [follow this guide](/javascript/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

## Implementing Chat

### `Group Chat`(Public Chat for All Viewers)

To allow your entire audience to chat during the stream:

1. Choose a topic name (e.g. "CHAT") that everyone will publish and subscribe to. Retrieve the `publish()` method and messages array using `pubSub`. Next create a message input and a send button to publish the messages.

```js
let liveStream;

// Initialize LiveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

const msgSendBtn = document.getElementById("msgSendBtn");

//publish chat meesage on button click
msgSendBtn.addEventListener("click", async () => {
  const message = document.getElementById("txtChat").value;

  document.getElementById("txtChat").value = "";

  liveStream.pubSub
    .publish("CHAT", message, { persist: true })
    .then((res) => console.log(`response of publish : ${res}`))
    .catch((err) => console.log(`error of publish : ${err}`));
});
```

2. Finally Display incoming chat messages from all users, creating a real-time chat feed during the stream.

```js
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

liveStream.on("meeting-joined", async () => {
  let oldMessages = await meeting.pubSub.subscribe("CHAT", (data) => {
    let { message, senderId, senderName, timestamp } = data;

    const chatBox = document.getElementById("chatArea");

    const chatTemplate = `
        <div style="margin-bottom: 10px; ${
          meeting.localParticipant.id == senderId && "text-align : right"
        }">
          <span style="font-size:12px;">${senderName}</span>
          <div style="margin-top:5px">
            <span style="background:${
              meeting.localParticipant.id == senderId ? "grey" : "crimson"
            };color:white;padding:5px;border-radius:8px">${message}<span>
          </div>
        </div>
        `;

    chatBox.insertAdjacentHTML("beforeend", chatTemplate);
  });

  // Getting Old messages for upcoming participant
  console.log("OLD Message", oldMessages);
});
```

### `Private Chat` (1:1 between Host and Viewer)

Private messaging is ideal when a host or moderator needs to directly respond to a viewer’s question. This can be achieved using the `sendOnly` property.

```js
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});
// ...
//publish chat meesage on button click
msgSendBtn.addEventListener("click", async () => {
  const message = document.getElementById("txtChat").value;

  document.getElementById("txtChat").value = "";

  // Pass the participantId of the participant to whom you want to send the message.
  liveStream.pubSub
    //highlight-next-line
    .publish("CHAT", message, { persist: true, sendOnly: ["XYZ"] })
    .then((res) => console.log(`response of publish : ${res}`))
    .catch((err) => console.log(`error of publish : ${err}`));
});
```

## Downloading Chat Messages

All the messages from PubSub published with `persist : true` can be downloaded as an `.csv` file. This file will be accessible in the VideoSDK dashboard and through the [Sessions API](/api-reference/realtime-communication/fetch-session-using-sessionid).

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [PubSub](/javascript/api/sdk-reference/meeting-class/pubsub)


---

# Cloud Proxy - JavaScript


Our SDK features a Cloud Proxy that allows you to manage how your streaming content is routed through different network paths. This feature ensures compliance with various regional internet regulations by restricting traffic to specified proxy servers, based on your needs and the geographical location of users.

This capability is crucial for adhering to local data protection laws and optimizes the streaming experience by overcoming geographical network constraints. By directing user connections to appropriate regional servers, Cloud Proxy enhances overall service performance and reliability.

Cloud Proxy offers three straightforward operating modes to fit different business and firewall requirements:

- **UDP_OVER_TCP (Default)**: In this mode, the connection starts by attempting to establish a UDP connection for media transmission. If that fails, it will automatically shifts to a secure TCP connection, which is compatible with most firewalls.

- **Force UDP**: This mode uses only UDP to send media, ensuring high-quality streams. It's ideal for environments where media quality is critical and the firewall can be configured accordingly.

- **Force TCP**: Only uses TCP for secure media transmission, suitable for strict firewall settings that only permit TCP traffic over centain ports. This might require additional firewall configuration and could affect media quality under poor network conditions.




### In this sequence diagram:
- Client to Proxy Server: The client sends a request to the proxy server, which processes and forwards it based on predefined rules.
- Proxy Server to Destination Server: The proxy server sends the request to the destination server, receives the response, and relays it back to the client.

:::info

Cloud Proxy is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Implementation

```js

meeting = VideoSDK.initMeeting({
  meetingId: "<Id-of-meeting>",
  name: "<Name-of-participant>",
  preferredProtocol: "UDP_ONLY",
  signalingBaseUrl: "proxy.yourwebsite.com",
});
```

### Parameters

- preferredProtocol:
  - UDP_OVER_TCP (default): Initially the server attempts to establish a connection using UDP, if that fails it automatically switches to TCP protocol.
  - UDP_ONLY: Force UDP protocol
  - TCP_ONLY: Force TCP protocol
- signalingBaseUrl: Proxy URL to origin signaling and media.

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [initMeeting](/javascript/api/sdk-reference/initMeeting#initmeeting)


---

# Concept and Architecture - Javascript

Before diving into the concept, it's essential to understand the VideoSDK. VideoSDK is a software development kit that offers tools and APIs for creating apps that are based on video and audio. It typically includes features such as video and audio calls, chat, cloud recording, simulcasting (RTMP), interactive live streaming (HLS), and many more across a wide range of platforms and devices.

## Concepts

![img.png](../../../../static/img/room-concept.png)

### `1. Meeting / Room`

- Meeting or Room object in the VideoSDK provides a virtual place for participants to interact and engage in real-time voice, video, and screen-sharing sessions. The object is in charge of handling media streams and participant communication.

- Meeting or Room can be uniquely identified by `meetingId` or `roomId`.

### `2. Participant`

- Participant is a VideoSDK object that represents each user/client in the meeting or room and allows them to share audio/video assets.

- `2.1 Local Participant` :
  The local participant is the one that runs on the user's device. The local participant has control over their own media streams, including the ability to start and stop audio and video.

  - The local participant in a meeting/room can also connect with other participants by transmitting and receiving audio and video streams, exchanging chat messages, and more.

- `2.2 Remote Participant` :
  The remote participant receives audio and video streams from both the local participant and other remote participants. Additionally, they have the ability to exchange audio, video, and chat messages with the local participant.

- Each participant in VideoSDK can be uniquely identified by `participantId`.

### `3. MediaStream & Track`

- A mediastream is a collection of audio & video tracks that can be transmitted between participants in real-time.

- A track is a continuous flow of audio or video data and can be thought of as a stream of media frames.

- A mediastream can contain multiple tracks. One video track for the video feed from the camera and one audio track for the audio feed from the microphone. These tracks can be transmitted between participants in VideoSDK Meeting / Room.

### `4. Events / Notifications`

- Events / Notifications can be used to inform users about various activities happening in a Meeting / Room, including participant join/leave and new messages. They can also be used to alert users about any SDK-level errors that occur during a call.

### `5. Session`

- A Session is the instance of an ongoing meeting/room which has one or more participants in it. A single room or meeting can have multiple sessions.
- Each session can be uniquely identified by `sessionId`.

![img.png](../../../../static/img/meeting-session.jpg)

---

![img.png](../../../../static/img/recording-hls-rtmp.png)

### `6. Cloud Recording`

- Cloud recording in VideoSDK refers to the process of recording audio or video content and storing it on a remote server or VideoSDK server.

### `7. Simulcasting (RTMP)`

- RTMP is a popular protocol for live streaming video content from the VideoSDK to platforms such as YouTube, Twitch, Facebook, and others.
- By providing the platform-specific `stream key` and `stream URL`, the VideoSDK can connect to the platform's RTMP server and transmit the live video stream.

### `8. Http Live Streaming (HLS)`

- Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

- In an interactive live stream (HLS), viewers can participate in various activities, such as live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

## Architecture

This diagram illustrates the comprehensive flow for implementing video and audio calls, recording calls, and broadcasting live on social media platforms.

![Video-sdk-architecture!](/img/video-sdk-archietecture.svg)


---

# Custom Audio Sources - JavaScript 

For a high-quality streaming experience, fine-tuning audio tracks becomes essential—especially when delivering content to a broader live audience.

To enhance your live audio pipeline, we've introduced the capability to provide a custom audio track for a hosts's stream both before and during a live session.


## Custom Audio Track

This feature allows you to integrate advanced audio layers like background noise suppression, echo cancellation, and more—so your stream sounds polished and professional to every viewer.

### `How to Create a Custom Audio Track ?`

- You can create a Custom Audio Track using `createMicrophoneAudioTrack()` method.
- This method lets you configure encoding parameters and noise control settings, returning a high-quality `MediaStream` suitable for streaming scenarios.

#### Example

```javascript
let customTrack = await VideoSDK.createMicrophoneAudioTrack({
  // highlight-next-line
  // It will be the id of the mic from which the voice should be captured.
  microphoneId : 'mic-id' // OPTIONAL

  // highlight-next-line
  // This will accept the voice profile you want to capture.
  encoderConfig: "speech_standard", // `high_quality` | `music_standard`,  Default : `speech_standard`

  noiseConfig: {
  // highlight-start
  // It is used to improve the quality of audio by removing background noise
  // that can interfere with the clarity of speech.
  // highlight-end
    noiseSuppression: true,

  // highlight-next-line
  // It is used to remove unwanted echoes from voice.
    echoCancellation: true,

 // highlight-next-line
  // It is used to maintain a consistent level of loudness or amplitude in a voice.
    autoGainControl: true,
  },
});
```
Here are different configurations for customizing audio tracks based on specific use cases:

- `speech_standard` : This config is optimised for normal voice communication.
- `high_quality` : This config is used for obtaining RAW audio, allowing you to apply your `noiseConfig`.
- `music_standard` : This config is optimised for communication scenarios, where the sharing of musical elements, such as songs or instrumental sounds, is crucial.

### `How to Setup Custom Audio Track ?`

You can plug in your custom audio track either before going live or dynamically while the session is ongoing.

1. [Setup during live stream initialization](/javascript/guide/interactive-live-streaming/custom-media-sources/custom-audio-sources#1-setup-during-live-stream-initialization)
2. [Setup dynamically using methods](/javascript/guide/interactive-live-streaming/custom-media-sources/custom-audio-sources#2-setup-dynamically-using-methods)

##### 1. Setup during live stream initialization

If you're starting the stream with the mic enabled `(micEnabled: true)` and wish to use a custom track from the beginning, pass it through the config of MeetingProvider.

:::caution
Custom Track will not apply on `micEnabled: false` configuration.
:::

##### Example

```javascript
let customAudioTrack = await VideoSDK.createMicrophoneAudioTrack({
  encoderConfig: "high_quality",
  noiseConfig: {
    noiseSuppresion: true,
    echoCancellation: true,
    autoGainControl: true,
  },
});

// liveStream Init
liveStream = window.VideoSDK.initMeeting({
  meetingId: meetingId, // required
  name: name, // required
  //highlight-next-line
  micEnabled: true, //If true, it will use the passed custom track to turn mic on
  webcamEnabled: true,
  //highlight-start
  //Pass the custom audio track here
  customMicrophoneAudioTrack: customAudioTrack,
  //highlight-end
});
```

#### 2. Setup dynamically using methods

During the live stream, you can update the audio source by passing the `MediaStream` into `unmuteMic()` method.

:::tip
Make sure to call the `muteMic()` method before you create a new track as it may lead to unexpected behavior.
:::

##### Example

```javascript
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

const unmuteMicBtn = document.getElementById("unmuteMicBtn");
unmuteMicBtn.addEventListener("click", async () => {
  let customAudioTrack = await VideoSDK.createMicrophoneAudioTrack({
    encoderConfig: "high_quality",
    noiseConfig: {
      noiseSuppresion: true,
      echoCancellation: true,
      autoGainControl: true,
    },
  });

  liveStream?.unmuteMic(customAudioTrack);
});
```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [Custom Audio Track](/javascript/api/sdk-reference/custom-track/custom-audio-track)


---

# Custom ScreenShare Sources - JavaScript 

To deliver high-quality livestreams, it's essential to fine-tune screen share tracks being broadcasted. Whether you’re hosting a webinar, or going live with a presentation, using custom media tracks gives you better control over stream quality and performance.

## Custom Screen Share Track

This feature enables the customization of screenshare streams with enhanced optimization modes and predefined encoder configuration (resolution + FPS) for specific use cases, which can then be sent to other hosts and audience members.

### `How to Create a Custom Screen Share Track ?`

- You can create a Video Track using the `createScreenShareVideoTrack()` method.
- This method enables the creation of a screen share track with different encoding parameters and optimization modes.

#### Example

```javascript
let customShareTrack = await VideoSDK.createScreenShareVideoTrack({
  optimizationMode: "motion", // "text" | "detail",  Default : "motion"

  // This will accept the  height & FPS of video you want to capture.
  encoderConfig: "h720p_15fps", //  `h360p_30fps` | `h1080p_30fps` // Default : `h720p_15fps`
});
```

You can learn more about the `optimizationMode` from [here](/javascript/guide/interactive-live-streaming/custom-media-sources/custom-video-sources#what-is-optimizationmode)

### `How to Setup a Custom Screen Share Track ?`

During the live stream, you can update the screenshare track by passing the `MediaStream` into `enableScreenShare()` method.

:::note

Make sure to call the `disableScreenShare()` method before you create a new track as it may lead to unexpected behavior.

:::

##### Example

```javascript
let liveStream;

// Initialize LiveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

const enableScreenShareBtn = document.getElementById("enableScreenShareBtn");
enableScreenShareBtn.addEventListener("click", async () => {
  let customShareTrack = await VideoSDK.createScreenShareVideoTrack({
    optimizationMode: "motion",
    encoderConfig: "h720p_15fps",
  });

  liveStream?.enableScreenShare(customShareTrack);
});
```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [Custom Screen Share Track](/javascript/api/sdk-reference/custom-track/custom-screen-share-track)


---

# Custom Video Sources - JavaScript 

To deliver high-quality livestreams, it's essential to fine-tune the video tracks being broadcasted. Whether you’re hosting a webinar, or streaming an event, using custom video tracks gives you better control over stream quality and performance.

## Custom Video Track

In a livestream, your webcam feed plays a central role. With custom video tracks, you can:
- Define the resolution and frame rate using encoder settings
- Select optimization modes that suit your stream content (e.g., motion for dynamic scenes, text for documents).
- Apply real-time background effects or filters using libraries like [videosdk-media-processor](https://www.npmjs.com/package/@videosdk.live/videosdk-media-processor-web)
- Stream directly from custom MediaStreams, including canvas or virtual backgrounds.

### `How to Create a Custom Video Track ?`

- You can create a Custom Video Track using `createCameraVideoTrack()` method.
- This method enables the creation of a video track with various encoding parameters, camera facing modes, and optimization modes, ultimately returning a `MediaStream`.

#### Example

```javascript
let customTrack = await VideoSDK.createCameraVideoTrack({
  // highlight-next-line
  // It will be the id of the camera from which the video should be captured.
  cameraId:"camera-id", // OPTIONAL

  // highlight-next-line
  // This parameter will be discussed in the next step.
  optimizationMode: "motion", // "text" | "detail",  Default : "motion"

  // highlight-next-line
  // This will accept the resolution (height x width) of video you want to capture.
  encoderConfig: "h480p_w640p", // "h540p_w960p" | "h720p_w1280p" ... // Default : "h360p_w640p"

  // highlight-next-line
  // For Mobile browser It will specify whether to use front or back camera for the video track.
  facingMode: "environment", // "front",  Default : "environment"

  // highlight-next-line
  // This parameter will be discussed in the next step.
  multiStream:true // false,  Default : true

});
```

:::caution
The behavior of custom track configurations is influenced by the capabilities of the device. For example, if you set the encoder configuration to 1080p but the webcam only supports 720p, the encoder configuration will automatically adjust to the highest resolution that the device can handle, which in this case is 720p.
:::

##### What is `optimizationMode`?

- This parameter specifies the optimization mode for the video track being generated.
- `motion` : This type of track focuses more on motion video such as webcam video, movies or video games.
  - It will degrade `resolution` in order to maintain `frame rate`.
- `text` : This type of track focuses on significant sharp edges and areas of consistent color that can change frequently such as presentations or web pages with text content.
  - It will degrade `frame rate` in order to maintain `resolution`.
- `detail` : This type of track focuses more on the details of the video such as, presentations, painting or line art.
  - It will degrade `frame rate` in order to maintain `resolution`.

##### What is `multiStream`?

- By enabling multiStream, your livestream will broadcast multiple resolutions (e.g., 720p, 480p, 360p), allowing viewers to receive the best stream quality based on their network.
The **`multiStream : true`** configuration indicates that VideoSDK, by default, sends multiple resolution video streams to the server. For example, if a user's device capability is 720p, VideoSDK sends streams in 720p, 640p, and 480p resolution. This enables VideoSDK to deliver the appropriate stream to each participant based on their network bandwidth.


<center>

![Multi Stream False](/img/multistream_true.png)

</center>

Setting **`multiStream : false`** restricts VideoSDK to send only one stream, helping to maintain quality by focusing on a single resolution.

<center>

![Multi Stream False](/img/multistream_false.png)

</center>

:::danger
The `setQuality` parameter will not have any effect if multiStream is set to `false`.
:::

### `How to Setup a Custom Video Track ?`

You can plug in your custom video track either before going live or dynamically while the session is ongoing.

1. [Setup during live stream initialization](/javascript/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track#1-setup-during-live-stream-initialization)
2. [Setup dynamically using methods](/javascript/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track#2-setup-dynamically-using-methods)

##### 1. Setup during live stream initialization

If you're starting the stream with the webcam enabled `(webcamEnabled: true)` and wish to use a custom track from the beginning, pass it through the config of MeetingProvider.

:::caution
Custom Track will not apply on the `webcamEnabled: false` configuration.
:::

##### Example

```javascript
let customVideoTrack = await VideoSDK.createCameraVideoTrack({
  optimizationMode: "motion",
  encoderConfig: "h540p_w960p",
  facingMode: "environment",
});

// Meeting Init
liveStream = VideoSDK.initMeeting({
  meetingId: meetingId, // required
  name: name, // required
  //highlight-start
  //If true, it will use the passed custom track to turn webcam on
  webcamEnabled: true,
  //Pass the custom video track here
  customCameraVideoTrack: customVideoTrack,
  //highlight-end
});
```

#### 2. Setup dynamically using methods

During the live stream, you can update the audio source by passing the `MediaStream` into `enableWebcam()` method.

:::tip
Make sure to call the `disableWebcam()` method before you create a new track as it may lead to unexpected behavior.
:::

##### Example

```javascript
let liveStream;

// Initialize Live Stream
liveStream = VideoSDK.initMeeting({
  // ...
});

const enableWebcamBtn = document.getElementById("enableWebcamBtn");
enableWebcamBtn.addEventListener("click", async () => {
  let customVideoTrack = await VideoSDK.createCameraVideoTrack({
    optimizationMode: "motion",
    encoderConfig: "h720p_w960p",
    facingMode: "environment",
    multiStream: false,
  });

  // Enable Webcam in Live Stream
  liveStream?.enableWebcam(customVideoTrack);
});
```

:::info
Using custom video tracks is not just limited to the video tracks created using the `createCameraVideoTrack` method. You can use any `MediaStream` object as a replacement, including a [custom canvas track created by you](https://developer.chrome.com/blog/capture-stream/).
:::

### `Which configuration is suitable for me ?`

In this section, the focus is on understanding participant size and platform-wise `encoder(Resolution)` and `multiStream` configuration.

##### 1. For Desktop Browser

![web_browser](/img/web_browser.png)

##### 2. For Mobile Browser

![web_browser](/img/mobile_browser.png)

##### 3. For Desktop + Mobile Browser

![web_browser](/img/mobile+web.png)


## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [Custom Video Track](/javascript/api/sdk-reference/custom-track/custom-video-track)


---

# Customized Live Stream - Javascript

VideoSDK offers a range of video streaming tools and solutions for content creators, publishers, and developers.

### Custom Template

- A custom template is a specialized layout for a live stream that allows users to integrate real-time graphics into their broadcasts.

- With custom templates, users can enhance their video content by overlaying graphics, text, images, and animations onto their live streams. These elements can be customized to align with specific branding requirements.

- By leveraging custom templates, users can craft dynamic and engaging video experiences. Whether incorporating live scoreboards, social media feeds, or other personalized elements, users have the flexibility to create visually appealing streams that stand out and capture audience attention.

:::note

Custom templates can also be used with recordings and RTMP service provided by VideoSDK.

:::

### What you can do with Custom Template

By utilizing a custom template, you have the flexibility to create various modes for your live stream. Here are some popular modes that you can design:

- **`PK Host:`** The host can organize a player vs. player battle, as illustrated in the example of a gaming battle shown below.

![pk host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_pk_battle.png)

- **`Watermark:`** The host has the ability to add and update watermarks anywhere in the template; for instance, the image below features a VideoSDK watermark on the top right side of the screen.

![watermark host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_water_mark.png)

- **`News Mode:`** Additionally, the host can incorporate dynamic text in the lower third banner, as demonstrated by the sample text in the bottom left of the screen.

![news mode](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_news_live.png)

## Custom template with VideoSDK

In this section, we will discuss how Custom Templates work with VideoSDK.

- **`Host`**: The host initiates live streaming by providing the `templateURL`. The `templateURL` is the URL of the hosted template webpage. The host is also responsible for managing the template, including tasks such as altering text, logos, and switching template layouts.

- **`VideoSDK Template Engine`** : The VideoSDK Template Engine accepts and opens the templateURL in the browser, actively listening to all events initiated by the Host. It facilitates the customization of the template in accordance with the host's preferences.

- **`Viewer`**: Viewers can stream the content, experiencing the live stream with added real-time graphics. This feature contributes to a distinctive and engaging viewing experience.

![custom template](https://cdn.videosdk.live/website-resources/docs-resources/custom_template.png)

### Understanding Template URL

The template URL is a webpage that VideoSDK Template Engine will open while composing the live stream.

It will appear as shown below.

![template url](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_url.png)

The Template URL comprises of two essential parts:

- Your actual page URL, resembling something like `https://example.com/videosdk-template`.
- Query parameters, designed to enable the VideoSDK Template Engine to seamlessly join the meeting upon opening the URL. There are three key query parameters in total:
  - `token`: Your token, serving as the authentication key to join the meeting.
  - `meetingId`: The meeting Id of the meeting that the VideoSDK Template Engine will join.
  - `participantId`: The participant ID of the VideoSDK Template Engine. This should be included when joining the template engine in your template, ensuring that the template engine participant remains invisible to other participants. **This parameter is automatically added by the VideoSDK**.

:::info

Above mentioned query parameters are mandatory. Apart from these parameters, you can pass any other extra parameters which are required according to your use-case.

:::

### **Creating Template**

**`Step 1:`** Import VideoSDK using `<script>` tag or install it using the below-mentioned npm command.
Make sure you are in your app directory before you run this command.



**Tab:**

" label="<script>" default>

```html
<html>
  <head></head>
  <body>
// highlight-next-line
<script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
  </body>
</html>
```

---

**npm:**

```bash
npm install @videosdk.live/js-sdk
```

---

**yarn:**

```bash
yarn add @videosdk.live/js-sdk
```

:::note

You can use VideoSDK's React or JavaScript SDK to create custom template. Following is the example of building custom template with JavaScript SDK.

:::

###### Structure of the Project

```jsx title="Project Structure"
  root
   ├── index.html
   ├── index.js
```

**`Step 2:`** Craft a user interface (UI) tailored for your live stream presentation.

```html title="index.html"
<!DOCTYPE html>
<html>
  <head> </head>

  <body>
    <div id="textDiv">Starting live stream...</div>

    
    <div class="row" id="videoContainer"></div>

    <script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
    <script src="index.js"></script>
  </body>
</html>
```




**`Step 3:`** Next, fetch the query parameters, from the URL which will be later used to initialize the meeting and get the elements from DOM.

```js title=index.js
const url = window.location;
const urlParams = new URLSearchParams(url.search);

const meetingId = urlParams.get("meetingId");
const token = urlParams.get("token");
const participantId = urlParams.get("participantId");

const videoContainer = document.getElementById("videoContainer");
const textDiv = document.getElementById("textDiv");
```

**`Step 4:`** Subsequently, initialize the meeting with the parameters that were extracted from the URL. Ensure direct initialization so that the template engine seamlessly joins the meeting upon page load.

```js title=index.js
window.VideoSDK.config(token);

const meeting = window.VideoSDK.initMeeting({
  meetingId: meetingId, // required
  name: "recorder", // required
  micEnabled: false,
  webcamEnabled: false,
  participantId: participantId,
});

meeting.join();

meeting.on("meeting-joined", () => {
  textDiv.style.display = "none";
});
```

**`Step 5:`** Next step is to create the container that will render the meeting view on the `participant-joined` event.

```js title=index.js
//  participant joined
meeting.on("participant-joined", (participant) => {
  let videoElement = createVideoElement(
    participant.id,
    participant.displayName
  );
  let audioElement = createAudioElement(participant.id);

  participant.on("stream-enabled", (stream) => {
    setTrack(stream, audioElement, participant, false);
  });
  videoContainer.appendChild(videoElement);
  videoContainer.appendChild(audioElement);
});

// participants left
meeting.on("participant-left", (participant) => {
  let vElement = document.getElementById(`f-${participant.id}`);
  vElement.remove(vElement);

  let aElement = document.getElementById(`a-${participant.id}`);
  aElement.remove(aElement);
});

// creating video element
function createVideoElement(pId, name) {
  let videoFrame = document.createElement("div");
  videoFrame.setAttribute("id", `f-${pId}`);

  //create video
  let videoElement = document.createElement("video");
  videoElement.classList.add("video-frame");
  videoElement.setAttribute("id", `v-${pId}`);
  videoElement.setAttribute("playsinline", true);
  videoElement.setAttribute("width", "300");
  videoElement.muted = true;
  videoFrame.appendChild(videoElement);

  let displayName = document.createElement("div");
  displayName.innerHTML = `Name : ${name}`;
  videoFrame.appendChild(displayName);

  return videoFrame;
}

// creating audio element
function createAudioElement(pId) {
  let audioElement = document.createElement("audio");
  audioElement.setAttribute("autoPlay", "false");
  audioElement.setAttribute("playsInline", "true");
  audioElement.setAttribute("controls", "false");
  audioElement.setAttribute("id", `a-${pId}`);
  audioElement.style.display = "none";
  return audioElement;
}

// setting media track
function setTrack(stream, audioElement, participant, isLocal) {
  if (stream.kind == "video") {
    isWebCamOn = true;
    const mediaStream = new MediaStream();
    mediaStream.addTrack(stream.track);
    let videoElm = document.getElementById(`v-${participant.id}`);
    videoElm.srcObject = mediaStream;
    videoElm
      .play()
      .catch((error) =>
        console.error("videoElem.current.play() failed", error)
      );
  }
  if (stream.kind == "audio") {
    if (isLocal) {
      isMicOn = true;
    } else {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(stream.track);
      audioElement.srcObject = mediaStream;
      audioElement
        .play()
        .catch((error) => console.error("audioElem.play() failed", error));
    }
  }
}
```

**`Step 6:`** Now, listen to PubSub messages from the `CHANGE_BACKGROUND` topic, triggering a change in the meeting's background color accordingly.

:::note

The PubSub mechanism is utilized to communicate with the template. You can learn more about [PubSub from here](../video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

:::

```js title=index.js
meeting.on("meeting-joined", () => {
  //  ...

  meeting.pubSub.subscribe("CHANGE_BACKGROUND", (data) => {
    let { message } = data;
    document.body.style.backgroundColor = message;
  });
});
```

**`Step 7:`** Once tested, you can deploy it using your backend or host it on services like [firebase](https://www.geeksforgeeks.org/how-to-deploy-react-project-on-firebase/) or vercel.

:::tip

You can checkout the github repository for sample custom template [created here](https://github.com/videosdk-live/videosdk-custom-recording-template-js-example).

:::

### Setup Livestream Using Custom Template

- To utilize Custom Templates with Livestream, you need to establish both the Host and Viewer setups. The Host initiates the livestream, while Viewers can watch the broadcast.

![template manager](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_manager.png)

- To understand custom templates, clone this example and run it on your system.

```bash
git clone https://github.com/videosdk-live/videosdk-custom-recording-template-js-example.git
```

- To utilize the custom template that has been deployed, invoke the [Start HLS API](https://docs.videosdk.live/api-reference/realtime-communication/start-hlsStream) instead of the `startHls` method from the `Meeting` class. The necessary code has already been incorporated in the cloned example above.

:::important

You can create your own custom template manager in JavaScript. In this example, we are using one for better understanding.

:::

```js
<button
  onClick={async () => {
    const url = `https://api.videosdk.live/v2/hls/start`;
    //Update your Custom Template URL here if you have deployed your own, if not deployed you can use this template from our URL.
    //highlight-next-line
    const templateUrl = `https://lab.videosdk.live/js-template-demo/?meetingId=${meetingId}&token=${authToken}`;
    const options = {
      method: "POST",
      headers: {
        Authorization: authToken,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        roomId: meetingId,
        templateUrl: templateUrl,
      }),
    };

    const result = await fetch(url, options)
      .then((response) => response.json()) // result will have playbackHlsUrl and livestreamUrl
      .catch((error) => console.error("error", error));
  }}
>
  Start HLS
</button>
```

- In this example, the host has two options on their side, enabling them to change the background and send messages to the viewers.

- Given below is a test run of the example.


<div style={{textAlign: 'center'}}>



</div>

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start HLS API](/api-reference/realtime-communication/start-hlsStream)
- [hlsState](/react/api/sdk-reference/use-meeting/properties#hlsstate)
- [hlsUrls](/react/api/sdk-reference/use-meeting/properties#hlsurls)
- [onHlsStateChanged](/react/api/sdk-reference/use-meeting/events#onhlsstatechanged)


---

# Manage Audio and Video Devices - JavaScript

This feature allows hosts to switch their microphone, speaker, or camera devices during a live stream. Only hosts (in `SEND_AND_RECV` mode) can change input/output devices, ensuring they maintain control over their audio and video quality, while audience members (in `RECV_ONLY` mode) continue to receive the broadcast seamlessly.

### Changing Audio Input Device
 
###### `getMics()`

- This method provides a list of all available microphones, which can be shown in a dropdown for selection.

- It returns an array of objects, each containing a `deviceId` and a `label` representing an audio input device.

###### `changeMic()`

- To change the input audio device of the host, you need to call this method by passing the desired device's `deviceId`.

#### Example

```js
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

const mics = await liveStream?.getMics();

const { deviceId, label } = mics[0];

liveStream?.changeMic(deviceId);
```

### Changing Audio Output Device

###### `getPlaybackDevices()`

- This method provides a list of all available speakers, which can be shown in a dropdown for selection.

- It returns an array of objects, each containing `deviceId` , `groupId` , `kind` and the `label` of the audio output device.

###### `setSinkId()`

- To change the output audio device of the host, you need to set the `sinkId` for each `<audio>` element used to render the audio during the livestream.

```js
const speakers = await VideoSDK?.getPlaybackDevices();

const { deviceId, label } = speakers[0];

const setAudioOutputDevice = (deviceId) => {
  const audioTags = document.getElementsByTagName("audio");
  audioTags.forEach((tag) => {
    tag.setSinkId(deviceId);
  });
};
```

:::note
To learn more about changing the audio output device [check this documentation](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/setSinkId).
:::

## Changing Camera Input Device

###### `getWebcams()`

- This method provides a list of all available cameras, which can be shown in a dropdown for selection.

- It returns an array of objects, each containing a `deviceId` and a `label` representing the camera device.

###### `changeWebcam()`

- To change the camera device of the host, you need to call this method by passing the desired device's `deviceId`.


#### Example

```js
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

const webcams = await liveStream?.getWebcams();

const { deviceId, label } = webcams[0];

liveStream?.changeWebcam(deviceId);
```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [getMics()](/javascript/api/sdk-reference/meeting-class/methods#getmics)
- [getWebcams()](/javascript/api/sdk-reference/meeting-class/methods#getwebcams)
- [changeMic()](/javascript/api/sdk-reference/meeting-class/methods#changemic)
- [changeWebcam()](/javascript/api/sdk-reference/meeting-class/methods#changewebcam)
- [getPlaybackDevices()](/javascript/api/sdk-reference/videosdk-class/methods#getplaybackdevices)


---

---
title: Mute / Unmute Mic | Video SDK
hide_title: true
hide_table_of_contents: false
description: Mic Controls features quick integrate in Javascript, React JS, Android, IOS, React Native, Flutter with Video SDK to add live video & audio conferencing to your applications.
sidebar_label: Mute / Unmute Mic
pagination_label: Mute / Unmute Mic
keywords:
  - audio calling
  - video calling
  - real-time communication
  - collaboration
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: mute-unmute-mic
--- 

# Mute / Unmute Mic - JavaScript

This feature allows hosts to communicate with each other during the livestream by enabling or disabling their microphones. While only hosts (participants in SEND_AND_RECV mode) can speak, audience members (in RECV_ONLY mode) can listen to the conversation in real time.

### `unmuteMic()`

- By using the `unmuteMic()` function of the `liveStream` object, the host can publish their audio to other hosts and audience members.

- You can also pass a customised audio track in the `unmuteMic()` method by using [Custom Audio Track](/javascript/guide/interactive-live-streaming/custom-media-sources/custom-audio-sources).

- Audio stream of the participant can be accessed from the `micStream` property of the `Participant` object.

### `muteMic()`

- By using the `muteMic()` function of the `liveStream` object, the host can stop publishing their audio to other hosts and audience members.

#### Example

```jsx
let liveStream;

// Initialize Meeting
liveStream = VideoSDK.initMeeting({
  // ...
});

const unmuteMicBtn = document.getElementById("unmuteMicBtn");
unmuteMicBtn.addEventListener("click", () => {
  // unmuteMic Meeting
  liveStream?.unmuteMic();
});

const muteMicBtn = document.getElementById("muteMicBtn");
muteMicBtn.addEventListener("click", () => {
  // unmuteMic Meeting
  liveStream?.muteMic();
});
```

:::note
To learn, how to render audio in the live stream, follow this detailed [guide](/javascript/guide/video-and-audio-calling-api-sdk/render-media/display-audio-video#3-rendering-audio).
:::

### Events associated with unmuteMic

- Every Participant—including all the hosts and audience members will receive a callback on [`stream-enabled`](/javascript/api/sdk-reference/participant-class/events#stream-enabled) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object with the `Stream` object.

- Every Participant—including all the hosts and audience members will receive a callback on [`media-status-changed`](/javascript/api/sdk-reference/participant-class/events#media-status-changed) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object hook with the type of media and its status.

### Events associated with muteMic

- Every Participant—including all the hosts and audience members will receive a callback on [`stream-disabled`](/javascript/api/sdk-reference/participant-class/events#stream-disabled) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object with the `Stream` object.

- Every Participant—including all the hosts and audience members will receive a callback on [`media-status-changed`](/javascript/api/sdk-reference/participant-class/events#media-status-changed) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object with the type of media and its status.


```js
const participants = liveStream.participants;
const participant = participants.get("<participant-id>");

participant.on("stream-enabled", (stream) => {
  if (stream.kind === "audio") {
    //particiapnt turned on audio
    //Render Participant audio logic here
  }
});

participant.on("stream-disabled", (stream) => {
  if (stream.kind === "audio") {
    //particiapnt turned off audio
    //remove Participant audio logic here
  }
});

participant.on("media-status-changed", (data) => {
  const { kind, newStatus } = data;
  if (kind === "audio") {
    //particiapnt media status changed
  }
});
```
### Audio Permissions

- By default, VideoSDK will request audio permission when a participant attempts to turn on the mic. Once the permission is granted, the mic is activated. If the permission is denied, VideoSDK will send an error message in the `onError` event callback of the `liveStream` object.


<div style={{textAlign: 'center'}}>



</div>

### Troubleshoot Audio Permissions

- If a participant denies the microphone permission, they can **manually grant** it by following the below shown steps.

<div style={{textAlign: 'center'}}>



</div>

:::caution
To use the audio and video communications in the web browser, your site must be **`SSL enabled`**, i.e. it must be secured and **`running on https`**.
:::

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [unmuteMic()](/javascript/api/sdk-reference/meeting-class/methods#unmutemic)
- [muteMic()](/javascript/api/sdk-reference/meeting-class/methods#mutemic)
- [stream-enabled event](/javascript/api/sdk-reference/participant-class/events#stream-enabled)
- [stream-disabled event](/javascript/api/sdk-reference/participant-class/events#stream-disabled)
- [media-status-changed](/javascript/api/sdk-reference/participant-class/events#media-status-changed)


---

# On / Off Camera - JavaScript

This feature enables hosts to turn their cameras on or off to share their video stream with other hosts and audience members during the meeting. Only hosts (in `SEND_AND_RECV` mode) can broadcast their camera feed, while audience members (in `RECV_ONLY` mode) can view it in real time.

### `enableWebcam()`

- By using the `enableWebcam()` function of the `liveStream` object, the host can publish their video to to other hosts and audience members.

- You can also pass a customised video track in `enableWebcam()` by using [Custom Video Track](/javascript/guide/interactive-live-streaming/custom-media-sources/custom-video-sources).

- The video stream of a participant can be accessed from the `webcamStream` property of the `Participant` object.

### `disableWebcam()`

- By using the `disableWebcam()` function of the `liveStream` object, the host can stop publishing their video to to other hosts and audience members.

#### Example

```js
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

const enableWebcamBtn = document.getElementById("enableWebcamBtn");
enableWebcamBtn.addEventListener("click", () => {
  // Enable Webcam in liveStream
  liveStream?.enableWebcam();
});

const disableWebcamBtn = document.getElementById("disableWebcamBtn");
disableWebcamBtn.addEventListener("click", () => {
  // Disable Webcam in liveStream
  liveStream?.disableWebcam();
});
```

### Events associated with enableWebcam

- Every Participant—including all the hosts and audience members will receive a callback on [`stream-enabled`](/javascript/api/sdk-reference/participant-class/events#stream-enabled) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object with the `Stream` object.

- Every Participant—including all the hosts and audience members will receive a callback on [`media-status-changed`](/javascript/api/sdk-reference/participant-class/events#media-status-changed) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object with the type of media and its status.

### Events associated with disableWebcam

- Every Participant—including all the hosts and audience members will receive a callback on [`stream-disabled`](/react/api/sdk-reference/use-participant/events#onstreamdisabled) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object with the `Stream` object.

- Every Participant—including all the hosts and audience members will receive a callback on [`media-status-changed`](/javascript/api/sdk-reference/participant-class/events#media-status-changed) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object with the type of media and its status.

```js
const participants = liveStream.participants;
const participant = participants.get("<participant-id>");

participant.on("stream-enabled", (stream) => {
  if (stream.kind === "video") {
    //particiapnt turned on video
    //Render Participant video logic here
  }
});

participant.on("stream-disabled", (stream) => {
  if (stream.kind === "video") {
    //particiapnt turned off video
    //remove Participant video logic here
  }
});

participant.on("media-status-changed", (data) => {
  const { kind, newStatus } = data;
  if (kind === "video") {
    //particiapnt media status changed
  }
});
```

### Video Permissions

- By default, VideoSDK will request video permission when the participants attempts to turn on the camera. Once the permission is granted the camera gets turned on. If the permission is denied, VideoSDK will send an error message in the `onError` event callback of the `liveStream` object.


<div style={{textAlign: 'center'}}>



</div>

### Troubleshoot Video Permissions

- If a participant denies the camera permission, they can **manually grant** it by following below shown steps.

<div style={{textAlign: 'center'}}>



</div>

:::caution
To use the audio and video communications in the web browser, your site must be **`SSL enabled`**, i.e. it must be secured and **`running on https`**.
:::

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [enableWebcam()](/javascript/api/sdk-reference/meeting-class/methods#enablewebcam)
- [disableWebcam()](/javascript/api/sdk-reference/meeting-class/methods#disablewebcam)
- [stream-enabled event](/javascript/api/sdk-reference/participant-class/events#stream-enabled)
- [stream-disabled event](/javascript/api/sdk-reference/participant-class/events#stream-disabled)
- [media-status-changed event](/javascript/api/sdk-reference/participant-class/events#media-status-changed)


---

---
title: Screen Share | Video SDK
hide_title: true
hide_table_of_contents: false
description: Share your Screen features quick integrate in Javascript, React JS, Android, IOS, React Native, Flutter with Video SDK to add live video & audio conferencing to your applications.
sidebar_label: Screen Share
pagination_label: Screen Share
keywords:
  - audio calling
  - video calling
  - real-time communication
  - collaboration
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1 
slug: screen-share
--- 

# Screen Share - JavaScript

This feature enables hosts to start or stop sharing their screen with other hosts and audience members during the live stream. Only hosts (in `SEND_AND_RECV` mode) can broadcast their screen, while audience members (in `RECV_ONLY` mode) can view it in real time.

### `enableScreenShare()`

- By using the `enableScreenShare()` function of the `liveStream` object, the host can share their desktop screen to other hosts and audience members.

- You can also pass a customised screenshare track in the `enableScreenShare()` method by using [Custom Screen Share Track](/javascript/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track#custom-screen-share-track).

- The Screen Share stream of a participant can be accessed from the `screenShareStream` property of the `Participant` object.

### `disableScreenShare()`

- By using the `disableScreenShare()` function of the `liveStream` object, the host can stop sharing their desktop screen to other hosts and audience members.

:::note
Screen Sharing is only supported in the **Desktop browsers** and **not in mobile/tab browser**.
:::

```js
let liveStream;

// Initialize Meeting
liveStream = VideoSDK.initMeeting({
  // ...
});

const enableScreenShareBtn = document.getElementById("enableScreenShareBtn");
enableScreenShareBtn.addEventListener("click", () => {
  // Enabling ScreenShare
  liveStream?.enableScreenShare();
});

const disableScreenShareBtn = document.getElementById("disableScreenShareBtn");
disableScreenShareBtn.addEventListener("click", () => {
  // Disabling ScreenShare
  liveStream?.disableScreenShare();
});
```

### Events associated with enableScreenShare

- Every Participant—including all the hosts and audience members will receive a callback on [`stream-enabled`](/javascript/api/sdk-reference/participant-class/events#stream-enabled) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object with the `Stream` object.

- Every participant—including all the hosts and audience members will receive the [`presenter-changed`](/javascript/api/sdk-reference/meeting-class/events#presenter-changed), which provides the `participantId` as the `presenterId` of the participant who started the screen share.

### Events associated with disableScreenShare

- Every Participant—including all the hosts and audience members will receive a callback on [`stream-disabled`](/react/api/sdk-reference/use-participant/events#onstreamdisabled) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object with the `Stream` object.

- Every Participant—including all the hosts and audience members will receive the [`presenter-changed`](/javascript/api/sdk-reference/meeting-class/events#presenter-changed) callback, with the `presenterId` as `null`, indicating that there is no current presenter.

```js
const participants = liveStream.participants;
const participant = participants.get("<participant-id>");

participant.on("stream-enabled", (stream) => {
  if (stream.kind === "share") {
    //particiapnt turned on screen share
    //Render screenshare logic here
  }
});

participant.on("stream-disabled", (stream) => {
  if (stream.kind === "share") {
    //particiapnt turned off screenshare
    //remove screenshare logic here
  }
});

let liveStream;

// Initialize Meeting
liveStream = VideoSDK.initMeeting({
  // ...
});

liveStream.on("presenter-changed", (presenterId) => {
  if (presenterId) {
    //someone start presenting
  } else {
    //someone stopped presenting
  }
});
```

### Screen Share with Audio

To enable screen sharing with audio, select the **Share tab audio** option when sharing the chrome tab as shown below.

<center>

![Screen Share with Audio](/img/screenshare-with-audio.png)

</center>

After clicking the `Share` button, you will receive the selected tab's audio stream in the participant's `screenShareAudioStream`.

:::note
Screen Share with Audio is only supported while sharing **Chrome Tab** in a **Chromium based browser** like Google Chrome, Brave etc.
:::

### Rendering Screen Share and Screen Share Audio

1. To display the screenshare video stream, you will receive it in the participant's stream-enabled callback with the stream kind set as "share".

```js
const participants = liveStream.participants;
const participant = participants.get("<participant-id>");

participant.on("stream-enabled", (stream) => {
  if (stream.kind == "share") {
    const videoElem = createShareVideoElement(participant.id, stream);

    //add audioElem to your container
    container.appendChild(videoElem);
  }

  if (stream.kind == "shareAudio") {
  }
});

// creating video element
function createShareVideoElement(pId, stream) {
  if (pId == liveStream.localParticipant.id) return;

  let videoElement = document.createElement("video");
  videoElement.setAttribute("autoPlay", false);
  videoElement.setAttribute("controls", "false");
  videoElement.setAttribute("id", `v-share-${pId}`);

  const mediaStream = new MediaStream();
  mediaStream.addTrack(stream.track);
  videoElement.srcObject = mediaStream;
  videoElement
    .play()
    .catch((error) => console.error("audioElem.play() failed", error));
  return videoElement;
}

// creating audio element
function createShareAudioElement(pId, stream) {}
```

2. Now to render the screenshare audio stream, you will receive it in the participant's stream-enabled callback with the stream kind set as `shareAudio`.

```js
const participants = liveStream.participants;
const participant = participants.get("<participant-id>");

participant.on("stream-enabled", (stream) => {
  if (stream.kind == "share") {
  }
  if (stream.kind == "shareAudio") {
    const audioElem = createShareAudioElement(participant.id, stream);

    //add audioElem to your container
    container.appendChild(audioElem);
  }
});

// creating video element
function createShareVideoElement(pId, stream) {}

// creating audio element
function createShareAudioElement(pId, stream) {
  if (pId == liveStream.localParticipant.id) return;

  let audioElement = document.createElement("audio");
  audioElement.setAttribute("autoPlay", false);
  audioElement.setAttribute("playsInline", "false");
  audioElement.setAttribute("controls", "false");
  audioElement.setAttribute("id", `a-share-${pId}`);
  audioElement.style.display = "none";

  const mediaStream = new MediaStream();
  mediaStream.addTrack(stream.track);
  audioElement.srcObject = mediaStream;
  audioElement
    .play()
    .catch((error) => console.error("audioElem.play() failed", error));
  return audioElement;
}
```

### Troubleshoot MacOS Screen Share Permissions

- If you are using MacOS, you will have to allow the browser to do screen share. You can follow the steps shown in the video to do so.


<div style={{textAlign: 'center'}}>



</div>

:::caution
To use the audio and video communications in the web browser, your site must be **`SSL enabled`** i.e. it must be secured and **`running on https`**.
:::

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [enableScreenShare()](/javascript/api/sdk-reference/meeting-class/methods#enablescreenshare)
- [disableScreenShare()](/javascript/api/sdk-reference/meeting-class/methods#disablescreenshare)
- [stream-enabled event](/javascript/api/sdk-reference/participant-class/events#stream-enabled)
- [stream-disabled event](/javascript/api/sdk-reference/participant-class/events#stream-disabled)
- [presenter-changed event](/javascript/api/sdk-reference/meeting-class/events#presenter-changed)


---

# Geo Fencing - JavaScript


Our SDK includes a region geofencing feature to comply with local laws and regulations worldwide. It restricts connections to servers within specified regions, ensuring users connect only to designated areas, regardless of their location. 

This helps meet regional data protection requirements and enhances user experience by addressing geographical network limitations.




### In this sequence diagram:
- User 1 (India) tries to connect to a meeting. In a regular scenario, the meeting would connect to the India region, but due to the geofence configuration, the meeting will connect to North America.

## Considerations
- If the user’s location differs from the chosen region, the network quality between these locations may be poor, affecting audio and video quality.
- Avoid using geofencing unless your scenario requires regional compliance.

:::info

Geo Fencing is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Available Regions
- INDIA
- USA
- UAE
- EUROPE
- SINGAPORE
- AUSTRALIA

---

# Overview - JavaScript

Interactive Live Streaming (ILS) is a low-latency streaming solution designed for real-time engagement at scale. Unlike traditional streaming protocols like HTTP Live Streaming (HLS), which typically have a delay of 15–30 seconds, ILS offers latency as low as 300 milliseconds—making it ideal for experiences that rely on immediate interaction.

While originally designed for meetings, VideoSDK seamlessly adapts to live streaming—supporting 100+ simultaneous hosts/co-hosts (Need more? Contact support@videosdk.live) and 2,000+ real-time viewers (scalable on request). This flexible architecture empowers dynamic events with multiple speakers, performers, or presenters.

ILS is not just about watching—it's about participating. While hosts and co-hosts can interact via audio/video and screen share, the audience consumes the content in real time and engages through interactive features like chat, polls and virtual gifting.

:::info

If you're already using VideoSDK for meetings, throughout this documentation you will learn how to extend its capabilities to support interactive live streaming.
Much of the core structure remains the same, but you'll discover how to adapt roles, scale the audience, and integrate interactive features to build engaging live stream experiences—all using the familiar tools and APIs you're used to.

:::

### Key Benefits:

- `Ultra-low latency`: Sub-second delivery for seamless interaction

- `Multiple host support`: Up to 100 simultaneous broadcasters

- `Scalable viewer capacity`: Handle up to 2,000 real-time audience members

- `Interactive tools`: Chat, polls, virtual gifts, hand raise, and more

- `Cross-platform compatibility`: Works across mobile, web, and desktop

<img src="https://www.videosdk.live/_next/image?url=https%3A%2F%2Fcdn.videosdk.live%2Fwebsite-resources%2Fproduct-pages%2Fils%2Freal-time-streaming-multiple-host.jpg&w=2048&q=100" />

## When to Use ILS?

Use Interactive Live Streaming when you need to:

- Run virtual events with multiple speakers
- Engage your audience actively during webinars
- Host fitness or coaching sessions with feedback
- Stream concerts, shows, or ceremonies with real-time reactions
- Organize town halls, investor calls, or product launches
- Facilitate audio rooms for casual or topic-based discussions
- Power social experiences like live meetups, talent shows, or community hangouts

:::info

If your requirement is strictly one-way broadcasting where interactivity is minimal and latency isn't critical (e.g., sports highlights, pre-recorded shows), http live streaming (HLS) may be more appropriate. To learn more about HLS, go through the [documentation](../integrate-hls/overview).

:::


---

# Host vs Audience Modes - JavaScript

Before diving into implementation, it's important to understand the two core modes of participation in an `Interactive Live Stream (ILS)` session powered by VideoSDK:

### Mode Architecture

Here’s a visual representation of how these modes function within an ILS session:

![Interactive Live Streaming architecture diagram](https://assets.videosdk.live/images/interactive-live-streaming-architecture.png)


By clearly separating hosts from viewers, and offering seamless transitions between roles, VideoSDK ILS ensures high performance, low latency, and exceptional flexibility for all live streaming scenarios.

:::note

Throughout the rest of this documentation, whenever we mention "Host", we are specifically referring to a participant in the `SEND_AND_RECV` mode. Similarly, when we mention "Audience" or "Viewer", we are referring to participants in the `RECV_ONLY` mode. These distinctions are important, as each mode comes with its own set of capabilities and limitations.

:::

### `1. SEND_AND_RECV` – Host / Co-host Mode

This mode is designed for Hosts or Co-hosts who need to broadcast their audio and video to the audience and potentially interact with other hosts. Following is the list of everything a host is capable of:

- Publish and receive media (audio/video/screen share)
- Participate in conversations with other hosts
- Engage with the audience using chat, polls, reactions, and more
- Moderate the stage and manage participants
- Invite audience members on stage to become temporary broadcasters

🔢 Supports 100+ simultaneous hosts/co-hosts (Need more? Contact support@videosdk.live)

### `2. RECV_ONLY` – Audience Mode

This mode is optimized for audience members who are viewing the live stream and engaging via non-verbal interaction tools. Following is the list of everything audience is capable of:

- Receive media from all active hosts in real time (audio/video/screen share)
- No media publishing – cannot share their own audio/video unless promoted
- Engage via:
  - Live chat
  - Polls and quizzes
  - Reactions (emojis, claps, hearts, etc.)
  - Virtual gifts
  - Hand raise to request stage access

🔢 Scales to 2,000+ real-time viewers (Need more? Contact support@videosdk.live)

### Seamless Transition Between Modes

VideoSDK offers a dynamic role management system, making it easy to transition a participant from audience to stage. If a host invites an audience member on stage, they can seamlessly switch from `RECV_ONLY` mode to `SEND_AND_RECV` mode. This allows them to publish their audio/video and interact like a host or co-host. Once their role is revoked, they can return to the audience mode.



---

# Display Attendees Count - Javascript

This guide explains the process of displaying the number of attendees in realtime.

:::note
Before proceeding with this guide, ensure that all attendees join the meeting with the mode set to `SIGNALLING_ONLY`.
:::




**`Step 1:`** Start by obtaining all the `participants` using the `meeting` object.

```js
function attendessCount() {
  const participants = meeting.participants;
}
```

**`Step 2:`** Subsequently, filter out those who have joined as `SIGNALLING_ONLY` and display the count.

```js
function attendessCount() {
  const participants = meeting.participants;

  const attendees = [...participants.values()].filter((participant) => {
    return participant.mode == VideoSDK.Constants.modes.SIGNALLING_ONLY;
  });

  return attendees.length || 0;
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Meeting](/javascript/api/sdk-reference/meeting-class/introduction)


---

# Invite Guest on Stage - Javascript

This guide explains the process of inviting a viewer to join a livestream using the `changeMode()` method.

:::note
Before proceeding with this guide, ensure that all attendees join the meeting with the mode set to `SIGNALLING_ONLY`, while the host joins with the mode set to `SEND_AND_RECV`.
:::




The diagram below illustrates the utilization of the `PubSub` mechanism to facilitate the requesting and switching of the participant's mode.

![invite-guest-pubsub](https://cdn.videosdk.live/website-resources/docs-resources/invite_guest_pubsub.png)

### Step 1: Loading Viewer List

First, the host will be presented with a list of participants who have joined as `SIGNALLING_ONLY`, accompanied by a button that, when selected, will invite that user to join the livestream.

```js
const participants = meeting.participants;

// Filtering only viewer participant
const viewers = [...participants.values()].filter((participant) => {
  return participant.mode == VideoSDK.Constants.modes.SIGNALLING_ONLY;
});

viewers.map((participant) => {
  const name = participant.displayName;
  const participantId = participant.id;

  const textEle = document.createElement("p");
  textEle.textContent = name;

  // Create the button
  var button = document.createElement("button");
  button.innerHTML = "Request to join Livestream";

  // Append elements to your viewers list
});
```

![invite-guest-pubsub](https://cdn.videosdk.live/website-resources/docs-resources/react_ils_viewer_list.png)

### Step 2: Requesting a Viewer to Join Livestream

Now, with the Viewer list in place, handle the click event for the "Join Livestream" button by utilizing `CHANGE_MODE_$participantId` as the topic for PubSub.

```js
const participants = meeting.participants;

// Filtering only viewer participant
const viewers = [...participants.values()].filter((participant) => {
  return participant.mode == VideoSDK.Constants.modes.SIGNALLING_ONLY;
});

viewers.map((participant) => {
  const name = participant.displayName;
  const participantId = participant.id;

  const textEle = document.createElement("p");
  textEle.textContent = name;

  // Create the button
  var button = document.createElement("button");
  button.innerHTML = "Request to join Livestream";

  // Append elements to your viewers list

  //highlight-start
  const topic = `CHANGE_MODE_${participantId}`;

  // Publishing the pubsub message with new mode
  button.addEventListener("click", function () {
    meeting?.pubSub.publish(topic, VideoSDK.Constants.modes.SEND_AND_RECV);
  });
  //highlight-end
});
```

### Step 3: Showing Viewer Request Dialog

After implementing the host's request for a viewer to join the livestream, display the viewer's request dialogue and switch the mode from `SIGNALLING_ONLY` to `SEND_AND_RECV`.

```js
function onMessageReceived(data) {
  let { message, senderId, senderName } = data;
  const textEle = document.createElement("p");
  textEle.textContent = `${senderName} requested you to join Livestream`;

  // Create the button
  var acceptButton = document.createElement("button");
  acceptButton.innerHTML = "Accept";

  acceptButton.addEventListener("click", function () {
    meeting?.changeMode(message);
  });

  var rejectButton = document.createElement("button");
  rejectButton.innerHTML = "Reject";
  rejectButton.addEventListener("click", function () {
    //
  });
}

meeting?.pubSub?.subscribe("CHAT", onMessageReceived);
```

![react_ils_cohost_join_request](https://cdn.videosdk.live/website-resources/docs-resources/react_ils_cohost_join_request.png)


<div style={{textAlign: 'center'}}>



</div>

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Meeting](/javascript/api/sdk-reference/meeting-class/introduction)
- [pubSub](/javascript/api/sdk-reference/meeting-class/pubsub)
- [participant](/javascript/api/sdk-reference/participant-class/introduction)


---

# Manage On-Screen Participants - Javascript

When engaging in interactive live streaming, it is essential to have only the necessary participant on the screen during the livestream. To manage this, the `pin` and `unpin` methods of the `Participant` Class are employed.

:::note
To ensure only the hosts/speakers are displayed in the grid, utilize the `SPOTLIGHT` layout and prioritize the `pin` function when initiating the interactive livestream.
:::

Below is an explanation of the methods used to manage on-screen participants.

### `pin()`

This method allows you to pin any participant's camera, screen share, or both. It is particularly useful for identifying specific participants, enabling you to optimize the rendering of the participant grid.

### `unpin()`

This method allows you to unpin any participant's camera, screen share, or both. It is particularly useful for resetting the pin state of the participant.




### Managing On-Screen Participants

1. If you want to automatically pin all the hosts/speakers, you can achieve this by listening to the `meeting-joined` callback and `participant-mode-changed` event. In these callbacks, you can `pin` and `unpin` participants based on their mode.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

meeting.on("meeting-joined", () => {
  //highlight-start
  const localParticipant = meeting?.localParticipant;
  //Pin the participant if mode is conference
  if (localParticipant.mode == VideoSDK.Constants.modes.SEND_AND_RECV) {
    localParticipant.pin();
  } else {
    localParticipant.unpin();
  }
  //highlight-end
});

meeting.on("participant-joined", (participant) => {
  //highlight-start
  //Pin the participant if mode is conference else unpin them
  if (participantId == localParticipant.id) {
    if (localParticipant.mode == VideoSDK.Constants.modes.SEND_AND_RECV) {
      localParticipant.pin();
    } else {
      localParticipant.unpin();
    }
  }
  //highlight-end
});
```

2. When rendering the participant grid on the Speaker side, ensure that only participants in `SEND_AND_RECV` mode are displayed. You can filter the participants as shown in the example provided below.

```js
const participants = meeting.participants;
const speakers = [...participants.values()].filter((participant) => {
  return participant.mode == VideoSDK.Constants.modes.SEND_AND_RECV;
});
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [pin](/javascript/api/sdk-reference/participant-class/methods#pin)
- [unpin](/javascript/api/sdk-reference/participant-class/methods#unpin)


---

# Manage Roles - Javascript

## Roles with VideoSDK

When engaging in interactive live streaming, managing user roles is crucial. VideoSDK supports two participant modes to facilitate role management:

**`1. SEND_AND_RECV`** When a participant joins with the mode set to `SEND_AND_RECV`, they have the capability to both publish and consume the media of other participants. Additionally, they can interact with others using features like chat and polls.

**`2. SIGNALLING_ONLY`** When a participant joins with the mode set to `SIGNALLING_ONLY`, they are restricted from both **publishing and consuming any media** from other participants. However, they can still interact with other participants using features like chat and polls.




![manage-roles](https://cdn.videosdk.live/website-resources/docs-resources/meeting_modes.jpg)


## When to use the Roles?

##### 1. Simple Adaptive Streaming

- Simple Adaptive Streaming (SAS) is a type of livestreaming designed for events where minimal interaction between the host and viewers is preferred.

- Ideal for scenarios with a large audience that does not actively engage with the host, SAS operates with each speaker participating in a VideoSDK meeting in `SEND_AND_RECV` mode. 


- In SAS, each speaker attends a VideoSDK meeting in `SEND_AND_RECV` mode, while viewers can simply watch the livestream using the `playbackHlsUrl` or `livestreamUrl`. Unlike the speakers, viewers do not need to join the meeting in `SEND_AND_RECV` or `SIGNALLING_ONLY` mode. This allows for a seamless streaming experience without any unnecessary interruptions or distractions.
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::



<div style={{textAlign: 'center'}}>



</div>

##### 2. Adaptive Streaming with increased engagement

- If you aim to enhance engagement with your audience during a live streaming event, Adaptive Streaming technology is the way to go. This approach allows you to integrate interactive features like polls and conversations, empowering viewers to join and leave the livestream at the host's discretion.

- To implement this, ensure that all speakers join as `SEND_AND_RECV` mode participants, while the audience joins as `SIGNALLING_ONLY` mode participants. This setup enables everyone to actively participate in the interactive elements of the live stream, creating a more dynamic and engaging experience for all involved.

<div style={{textAlign: 'center'}}>



</div>

## Using roles

The mode of the participants is configured during the meeting initialization using `initMeeting`.

```js
VideoSDK.config(token);

const meeting = VideoSDK.initMeeting({
  meetingId: "<Id-of-meeting>",
  name: "<Name-of-participant>",
  micEnabled: true,
  webcamEnabled: true,
  //highlight-next-line
  mode: "SEND_AND_RECV", // allowed: SEND_AND_RECV | SIGNALLING_ONLY
});
```

## Getting Participant Mode

The role of the participant is identified using the `mode` property of the `participant` object.

```js
const participants = meeting.participants;
const participant = participants.get("<participant-id>");

const participantMode = participant.mode;
```

## Changing Participant's Mode

Suppose you are hosting a livestream and wish to have one of your viewers join the livestream with you. In this scenario, you can modify the mode of the participant using the `changeMode()` method of the `meeting` object.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

// For SEND_AND_RECV mode
meeting?.changeMode(Constants.modes.SEND_AND_RECV);

// For SIGNALLING_ONLY mode
meeting?.changeMode(Constants.modes.SIGNALLING_ONLY);
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [changeMode()](/javascript/api/sdk-reference/meeting-class/methods#changemode)


---

# Interactive Livestream (HLS) - Javascript

### What is Interactive Livestream (HLS)?

Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

In an interactive live stream (HLS), viewers can participate in various activities, such as live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

### What is Adaptive Live Streaming?

In the context of interactive live streaming, Adaptive Live Streaming optimizes the viewing experience by dynamically adjusting the livestream's resolution based on user preferences and network conditions. This ensures seamless transitions between lower and higher resolutions, enhancing audience engagement.

### What is Latency?

Latency is the delay between capturing video content and its playback. Key factors affecting latency are as follows:

- **Buffering**: Finding the right balance in buffer size is crucial for achieving smoother playback without compromising on latency.
- **Network Conditions**: The efficiency of servers and the overall health of the network significantly impact latency.

Standard HLS typically has a latency of around 5-6 seconds.

### HLS Architecture of VideoSDK

<center>

![VideoSDK HLS](/img/VideoSDK-HLS.png)

</center>

When a host initiates an interactive live stream using VideoSDK, the platform utilizes either a default theme or a user-specified template to compose and encode a live stream. This live stream is delivered to viewers through an `M3U8` video file, enabling direct playback on the viewer's end while adapting to their network bandwidth.

VideoSDK provides multiple types of URLs for interactive live streaming, catering to various requirements:

**`1. Standard Streaming:`** In this type of streaming, users can engage in real-time without the ability to go back in the live stream; it's a continuous streaming experience.

**`2. Rolling Playback:`** In this type of streaming, users have the capability to rewind and playback the entire stream, offering a more flexible viewing experience.

**`3. VoD Playback`** In this type of streaming, users can playback the complete live stream on demand, providing the flexibility to watch at their convenience.

## Using HLS with VideoSDK

You can use HLS with VideoSDK in two different ways.

#### 1. Simple Adaptive Streaming

Simple Adaptive Streaming refers to a type of live stream where there is minimal interaction between hosts and viewers.

This type of livestream is particularly useful when there is a large audience, and the viewers don't actively engage with the hosts. In such a scenario, presenters participate in a VideoSDK meeting, while viewers primarily watch the livestream without direct interaction with the hosts.


<div style={{textAlign: 'center'}}>



</div>

#### 2. Adaptive Streaming with increased engagement

When aiming to interact with your audience through features like polls, discussions, and the ability for viewers to join and leave the livestream based on the host's decisions, adaptive streaming with enhanced engagement is the most suitable option.

In this setup, both the host and viewers must join a VideoSDK meeting with distinct roles. To gain more insights into managing roles within VideoSDK meetings, you can [follow this guide.](../handling-participants/manage-roles)

<div style={{textAlign: 'center'}}>



</div>


---

# Setup HLS Player - Javascript

This guide focuses on creating the Component responsible for playing the HLS stream.
Before proceeding, ensure that you have set up a VideoSDK meeting, enabling you to join the room. For instructions on setting up a VideoSDK meeting, refer to the [quick start guide](../../video-and-audio-calling-api-sdk//quick-start.md).

For playing the HLS stream, you need to use the [hls.js](https://www.npmjs.com/package/hls.js/v/canary) library.

### `1. Setup Component with HLS events`

**`Step 1:`** Begin by creating the video container in your HTML file and importing the [hls.js](https://hlsjs.video-dev.org/demo/) library using the `<script>` tag.
 
```html
<!DOCTYPE html>
<html>
  <head> </head>
  <body>
    

    
    <div id="videoContainer"></div>

    
    <script src="https://cdn.jsdelivr.net/npm/hls.js"></script>
  </body>
</html>
```

### `2. Playing HLS stream`

- Now on the `hls-state-changed` event, when you get `HLS_PLAYABLE` for the viewer participant, create a video element in the videoContainer div and pass playbackHlsUrl to hls.js.

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::


```js
meeting.on("hls-state-changed", (data) => {
  const { status } = data;

  if (mode === Constants.modes.SIGNALLING_ONLY) {
    if (status === Constants.hlsEvents.HLS_PLAYABLE) {
      const { playbackHlsUrl } = data;
      let video = document.createElement("video");
      video.setAttribute("width", "100%");

      if (Hls.isSupported()) {
        var hls = new Hls({
          maxLoadingDelay: 1, // max video loading delay used in automatic start level selection
          defaultAudioCodec: "mp4a.40.2", // default audio codec
          maxBufferLength: 0, // If buffer length is/become less than this value, a new fragment will be loaded
          maxMaxBufferLength: 1, // Hls.js will never exceed this value
          startLevel: 0, // Start playback at the lowest quality level
          startPosition: -1, // set -1 playback will start from intialtime = 0
          maxBufferHole: 0.001, // 'Maximum' inter-fragment buffer hole tolerance that hls.js can cope with when searching for the next fragment to load.
          highBufferWatchdogPeriod: 0, // if media element is expected to play and if currentTime has not moved for more than highBufferWatchdogPeriod and if there are more than maxBufferHole seconds buffered upfront, hls.js will jump buffer gaps, or try to nudge playhead to recover playback.
          nudgeOffset: 0.05, // In case playback continues to stall after first playhead nudging, currentTime will be nudged evenmore following nudgeOffset to try to restore playback. media.currentTime += (nb nudge retry -1)*nudgeOffset
          nudgeMaxRetry: 1, // Max nb of nudge retries before hls.js raise a fatal BUFFER_STALLED_ERROR
          maxFragLookUpTolerance: 0.1, // This tolerance factor is used during fragment lookup.
          liveSyncDurationCount: 1, // if set to 3, playback will start from fragment N-3, N being the last fragment of the live playlist
          abrEwmaFastLive: 1, // Fast bitrate Exponential moving average half-life, used to compute average bitrate for Live streams.
          abrEwmaSlowLive: 3, // Slow bitrate Exponential moving average half-life, used to compute average bitrate for Live streams.
          abrEwmaFastVoD: 1, // Fast bitrate Exponential moving average half-life, used to compute average bitrate for VoD streams
          abrEwmaSlowVoD: 3, // Slow bitrate Exponential moving average half-life, used to compute average bitrate for VoD streams
          maxStarvationDelay: 1, // ABR algorithm will always try to choose a quality level that should avoid rebuffering
        });
        hls.loadSource(playbackHlsUrl);
        hls.attachMedia(video);
        hls.on(Hls.Events.MANIFEST_PARSED, function () {
          video.play();
        });
      } else if (video.canPlayType("application/vnd.apple.mpegurl")) {
        video.src = playbackHlsUrl;
        video.addEventListener("canplay", function () {
          video.play();
        });
      }

      videoContainer.appendChild(video);
    }
  }
});
```

With this, the player is setup to play the HLS.

![VideoSDK JS Interactive Live Streaming Quick Start Meeting Container Component](https://cdn.videosdk.live/website-resources/docs-resources/quick_start_react_ils_viewer.png)

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [hlsState](/javascript/api/sdk-reference/meeting-class/properties#hlsstate)
- [hlsUrls](/javascript/api/sdk-reference/meeting-class/properties#hlsurls)
- [hls-state-changed](/javascript/api/sdk-reference/meeting-class/events#hls-state-changed)


---

# Start HLS - Javascript

Before initiating HLS, it is essential to have a VideoSDK Meeting in progress, which you intend to utilize for interactive live streaming. For detailed instructions on setting up interactive live streaming, please refer to the steps outlined in the [quick start guide here.](/javascript/guide/video-and-audio-calling-api-sdk/quick-start-ILS)

## Starting HLS

Once the user has joined the meeting, the `startHls()` method, accessible from the `meeting` object, is used to initiate interactive livestream of a meeting. This method accepts the following parameter:

- `config (optional)`: This parameter defines how the interactive livestream layout should look like.

```js
 const config = {
   // highlight-next-line
   // Layout Configuration
   layout: {
     type: "GRID", // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
     priority: "SPEAKER", // "PIN", Default : "SPEAKER"
     gridSize: 4, // MAX : 25
   },
​
   // highlight-next-line
   // Theme of interactive livestream layout
   theme: "DARK", //  "LIGHT" | "DEFAULT"
​
   // highlight-next-line
   // `mode` is used to either interactive livestream video & audio both or only audio.
   mode: "video-and-audio", // "audio", Default : "video-and-audio"
​
   // highlight-next-line
   // Quality of interactive livestream and is only applicable to `video-and-audio` type mode.
   quality: "high", /* Default : "med"
   "low" (SD HLS) | "med" (HD HLS) | "high" (FHD HLS) */
​
   //highlight-start
   // This mode refers to orientation of interactive livestream.
   // landscape : Start interactive livestream of the meeting in horizontally
   // portrait : Start interactive livestream of the meeting in vertically (Best for mobile view)
   //highlight-end
   orientation: "landscape", // "portrait",  Default : "landscape"
 };
​
 meeting?.startHls(config);
```

:::note
If you wish for only the conference participants to be visible in the livestream, you can `pin` all participants in the conference mode and commence the livestream with the `SPOTLIGHT` layout, prioritizing pinned participants.
:::

### Example

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const startHlsBtn = document.getElementById("startHlsBtn");
startHlsBtn.addEventListener("click", () => {
  // Start HLS
  meeting?.startHls({
    layout: {
      type: "GRID",
      priority: "SPEAKER",
      gridSize: 4,
    },
    theme: "DARK",
    mode: "video-and-audio",
    quality: "high",
    orientation: "landscape",
  });
});
```

## Understanding Layouts

##### 1. GRID Layout

This layout serves as the default layout when no participants are pinned, resembling a typical meeting grid layout. However, when a participant is pinned, that individual takes precedence and is showcased prominently at the top of the main screen grid, surpassing all non-pinned participants.

During screenshare, the main view exclusively displays screenshare media, while the side panel maintains the same order of pinned and unpinned participants.


|                       Grid                        |                     Grid with Screenshare                     |
| :-----------------------------------------------: | :-----------------------------------------------------------: |
| ![prebuilt-grid](/img/prebuilt/prebuilt-grid.png) | ![prebuilt-grid-share](/img/prebuilt/prebuilt-grid-share.png) |

##### 2. SIDEBAR Layout

This layout contains a primary screen view and an accompanying sidebar grid layout. Only pinned participants are visible, with all unpinned participants excluded from this view. If more than one participant is pinned, the first participant to be pinned takes the main screen layout, and any remaining pinned participants appear in the sidebar.

In case a pinned participant initiates screenshare, the screenshare media will be visible in the main screen layout, and the webcam views of other pinned participants will be visible in the sidebar.

|                         Sidebar                         |                      Sidebar with Screenshare                       |
| :-----------------------------------------------------: | :-----------------------------------------------------------------: |
| ![prebuilt-sidebar](/img/prebuilt/prebuilt-sidebar.png) | ![prebuilt-sidebar-share](/img/prebuilt/prebuilt-sidebar-share.png) |

##### 3. SPOTLIGHT Layout

This layout solely features the main screen view, where multiple pinned participants are visible. Similar to the `SIDEBAR` layout, only pinned participants are visible in the main screen.

If a pinned participant begins screenshare, only the screenshare view will be visible on the main screen, and no webcam views of pinned participants will be displayed during screenshare.

|                          Spotlight                          |                       Spotlight with Screenshare                        |
| :---------------------------------------------------------: | :---------------------------------------------------------------------: |
| ![prebuilt-spotlight](/img/prebuilt/prebuilt-spotlight.png) | ![prebuilt-spotlight-share](/img/prebuilt/prebuilt-spotlight-share.png) |

## Event associated with HLS

- **hls-state-changed** - The `hls-state-changed` event is triggered whenever the state of meeting HLS changes.

- You can get the `playbackHlsUrl` and `livestreamUrl` of the HLS to play it on the Viewer side when the state changes to `HLS_PLAYABLE` as well as from the `hlsUrls` from the `meeting` object.
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::


```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const Constants = VideoSDK.Constants;

meeting.on("hls-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.hlsEvents.HLS_STARTING) {
    console.log("Meeting Hls is starting");
  } else if (status === Constants.hlsEvents.HLS_STARTED) {
    console.log("Meeting Hls is started");
  } else if (status === Constants.hlsEvents.HLS_PLAYABLE) {
    //highlight-start
    // on hlsStateChanged started you will receive playbackHlsUrl and livestreamUrl
    const { playbackHlsUrl } = data;
    //highlight-end
    console.log("Meeting Hls is Playable");
  } else if (status === Constants.hlsEvents.HLS_STOPPING) {
    console.log("Meeting Hls is stopping");
  } else if (status === Constants.hlsEvents.HLS_STOPPED) {
    console.log("Meeting Hls is stopped");
  } else {
    //
  }
});
```

## Custom Template

With VideoSDK, you have the option to employ your own custom-designed layout template for meeting recordings. To use a custom template, [follow this guide](/javascript/guide/interactive-live-streaming/custom-template) to create and set up the template. Once the template is configured, you can initiate recording using the [REST API](/api-reference/realtime-communication/start-livestream), specifying the `templateURL` parameter.


## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startHls()](/javascript/api/sdk-reference/meeting-class/methods#starthls)
- [hlsState](/javascript/api/sdk-reference/meeting-class/properties#hlsstate)
- [hlsUrls](/javascript/api/sdk-reference/meeting-class/properties#hlsurls)
- [hls-state-changed](/javascript/api/sdk-reference/meeting-class/events#hls-state-changed)


---

# Stop HLS - Javascript

Stopping HLS refers to the process of halting the ongoing HLS stream transmission, indicating that the stream is no longer accessible to viewers.

## Stopping HLS

The `stopHls()` method, accessible from the `meeting` object, is used to stop the interactive livestream of a meeting.

### Example

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const stopHlsBtn = document.getElementById("stopHlsBtn");
stopHlsBtn.addEventListener("click", () => {
  // Stop HLS
  meeting?.stopHls();
});
```

## Event associated with HLS

- **hls-state-changed** - The `hls-state-changed` event is triggered whenever the state of meeting HLS changes.

- You will get `HLS_STOPPING` and `HLS_STOPPED` status on calling `stopHls()`.

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const Constants = VideoSDK.Constants;

meeting.on("hls-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.hlsEvents.HLS_STARTING) {
    console.log("Meeting Hls is starting");
  } else if (status === Constants.hlsEvents.HLS_STARTED) {
    // on hlsStateChanged started you will receive playbackHlsUrl and livestreamUrl
    const { playbackHlsUrl } = data;
    console.log("Meeting Hls is started");
    //highlight-start
  } else if (status === Constants.hlsEvents.HLS_STOPPING) {
    console.log("Meeting Hls is stopping");
  } else if (status === Constants.hlsEvents.HLS_STOPPED) {
    console.log("Meeting Hls is stopped");
    //highlight-end
  } else {
    //
  }
});
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [stopHls()](/javascript/api/sdk-reference/meeting-class/methods#stophls)
- [hls-state-changed](/javascript/api/sdk-reference/meeting-class/events#hls-state-changed)


---

# Getting Started - JavaScript SDK




---

# Chat using PubSub - Javascript

For communication or any kind of messaging between participants, VideoSDK provides the `pubSub` property, which utilizes the Publish-Subscribe mechanism. It can be employed to develop a wide variety of functionalities. For example, participants could use it to send chat messages to each other, share files or other media, or even trigger actions like muting or unmuting audio or video.

This guide focuses on using PubSub to implement Chat functionality. If you are not familiar with the PubSub mechanism and `pubSub`, you can [follow this guide](/javascript/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

### Implementing Chat

1. The initial step in setting up a group chat involves selecting a topic to which all participants will publish and subscribe, facilitating the exchange of messages. In the following example, `CHAT` is used as the topic. 
Next step is to create a message input and a send button to publish the messages using the `pubSub` method from the `meeting` object.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const msgSendBtn = document.getElementById("msgSendBtn");

//publish chat meesage on button click
msgSendBtn.addEventListener("click", async () => {
  const message = document.getElementById("txtChat").value;

  document.getElementById("txtChat").value = "";

  meeting.pubSub
    .publish("CHAT", message, { persist: true })
    .then((res) => console.log(`response of publish : ${res}`))
    .catch((err) => console.log(`error of publish : ${err}`));
});
```

2. The final step in the group chat is to display the messages sent by others. For this use the `messages` array and display all the messages.


```js
//subscribe to the 'CHAT' on meeting join
meeting.on("meeting-joined", () => {
  meeting.pubSub.subscribe("CHAT", (data) => {
    let { message, senderId, senderName, timestamp } = data;

    const chatBox = document.getElementById("chatArea");

    const chatTemplate = `
        <div style="margin-bottom: 10px; ${
          meeting.localParticipant.id == senderId && "text-align : right"
        }">
          <span style="font-size:12px;">${senderName}</span>
          <div style="margin-top:5px">
            <span style="background:${
              meeting.localParticipant.id == senderId ? "grey" : "crimson"
            };color:white;padding:5px;border-radius:8px">${message}<span>
          </div>
        </div>
        `;

    chatBox.insertAdjacentHTML("beforeend", chatTemplate);
  });
});
```

### Display Latest Message Notificaiton

To show the notification to the user when a new message arrives, following code snippet has to be followed.

```js
meeting.pubSub.subscribe("CHAT", (data) => {
  let { message, senderId, senderName, timestamp } = data;

  window.alert(senderName + " says " + message);

  // ...
});
```

### Downloading Chat Messages

All the messages from PubSub published with `persist : true` can be downloaded as an `.csv` file. This file will be accessible in the VideoSDK dashboard and through the [Sessions API](/api-reference/realtime-communication/fetch-session-using-sessionid).

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [pubSub](/javascript/api/sdk-reference/meeting-class/pubsub)


---

# Notify Attendees in Realtime - Javascript

This guide explains how PubSub can be used to implement the functionality of broadcasting a message to all the viewers at once. If you are not familiar with the PubSub mechanism and `pubSub`, you can [follow this guide](/javascript/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

### Notifying Attendees

1. To implement this functionality, begin by creating a "Notify Attendees" button along with a text input to capture the message. When a message is entered into the input and the button is clicked, publish a message with the topic `NOTIFY_ATTENDEES`.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const notifyAttendeesBtn = document.getElementById("notifyAttendeesBtn");
notifyAttendeesBtn.addEventListener("click", async () => {
  const message = document.getElementById("notifyAttendeesTxt").value;

  const topic = "NOTIFY_ATTENDEES";
  meeting?.pubSub.publish(topic, message, { persist: true });
});
```

2. Next, alert all the speakers, displaying the message posted by the speaker.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

// Callback function
function notifyAttendees(data) {
  let { message, senderId, senderName, timestamp } = data;

  if (meeting.localParticipant.mode == "SIGNALLING_ONLY") {
    window.alert(message);
  }
}

meeting?.pubSub?.subscribe("RAISE_HAND", notifyAttendees);
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [pubSub](/javascript/api/sdk-reference/meeting-class/pubsub)


---

# Raise Hand - Javascript

This guide explains how PubSub can be used to implement the Raise Hand functionality. If you are not familiar with the PubSub mechanism and `pubSub` property of meeting object, you can [follow this guide](/javascript/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

### Implementing Raise Hand

1. To implement this functionality, first create a Raise Hand button. When this button is clicked, publish a message with the topic `RAISE_HAND`.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const raiseHandBtn = document.getElementById("raiseHandBtn");
raiseHandBtn.addEventListener("click", () => {
  const topic = "RAISE_HAND";

  meeting?.pubSub.publish(topic, "Raise Hand");
});
```

2. Next, alert all the speakers, displaying the identity of the participant who raised their hand.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

// Callback function
function raiseHand(data) {
  let { message, senderId, senderName, timestamp } = data;

  if (meeting.localParticipant.mode == "SEND_AND_RECV") {
    window.alert(`${senderName} raise hand`);
  }
}

meeting?.pubSub?.subscribe("RAISE_HAND", raiseHand);
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [pubSub](/javascript/api/sdk-reference/meeting-class/pubsub)


---

# Introduction

Welcome to the JavaScript Interactive Live Streaming (ILS). Build real-time, low-latency experiences where hosts and audiences connect, interact, and engage seamlessly using VideoSDK.

## Architecture Overview

**Architecture at a Glance** — Hosts join with `SEND_AND_RECV` permissions to broadcast and collaborate, while audiences connect with `RECV_ONLY` access to enjoy the stream without publishing their own media.

![Interactive Live Streaming architecture diagram](https://assets.videosdk.live/images/ils-architecture-live-streaming.png)

## Streaming Modes

**Interactive Live Streaming (ILS):** Low-latency, two-way sessions where hosts and promoted guests publish audio/video, manage roles, and drive rich audience participation.

**HTTP Live Streaming (HLS):** Broadcast delivery tuned for massive audiences with receiver-only playback and CDN scaling, perfect for town halls and one-to-many events.

- [Interactive Live Streaming Quick Start](/javascript/guide/video-and-audio-calling-api-sdk/quick-start-js-ils): Bootstrap an ILS experience in vanilla JavaScript with role control and audience tools.
- [HTTP Live Streaming Quick Start](/javascript/guide/video-and-audio-calling-api-sdk/quick-start-ILS): Configure VideoSDK's HLS pipeline for browser-based broadcasts that scale instantly.


Use the guide below to explore the modular capabilities that help you design each part of this flow.

## Key Features

- [Stage & Layout Control](/javascript/guide/interactive-live-streaming/layout-management/rendering-host-audience-views): Drive dynamic layouts and backstage flows tuned for browser-based broadcasters.
- [Audience Moderation](/javascript/guide/interactive-live-streaming/audience-management/change-mode): Promote speakers, manage viewer modes, and keep chats orderly at scale.
- [Device & Screen Control](/javascript/guide/interactive-live-streaming/device-management/change-devices): Switch cameras, microphones, and share screens with native browser APIs.
- [Interactive Layers](/javascript/guide/interactive-live-streaming/chat-during-livestream): Bring chat, reactions, polls, and raise-hand experiences into your timeline.
- [Analytics & QoE](/javascript/guide/interactive-live-streaming/analytics/understanding-analytics-dashboard): Monitor network health and user engagement with built-in dashboards.
- [Recording & Highlights](/javascript/guide/interactive-live-streaming/recording/overview): Capture live sessions, generate recaps, and automate storage policies.
- [Geo & Proxy Controls](/javascript/guide/interactive-live-streaming/geo-fencing): Respect regional policies and enterprise network constraints effortlessly.
- [Relay & Multistream](/javascript/guide/interactive-live-streaming/relay-media): Simulcast to secondary rooms or destinations with relay media workflows.


## Sample Projects

- [JavaScript ILS Starter](https://github.com/videosdk-live/quickstart/tree/main/interactive-live-streaming/js-ils): Start from a ready-to-run host and viewer experience built with plain JavaScript.
- [JavaScript HLS Broadcast](https://github.com/videosdk-live/quickstart/tree/main/js-hls): Explore a broadcast workflow that pairs VideoSDK publishing with HLS playback.


## Quick Start Paths

- [Install the SDK](/javascript/guide/interactive-live-streaming/integrate-sdk): Add the VideoSDK JavaScript packages and bootstrap your first meeting.
- [Configure Tokens](/javascript/guide/interactive-live-streaming/authentication-and-token): Provision API keys and set up a secure token service before going live.
- [Launch the ILS Sample](/javascript/guide/video-and-audio-calling-api-sdk/quick-start-js-ils): Clone the interactive sample to experience host and viewer flows end-to-end.
- [Broadcast with HLS](/javascript/guide/video-and-audio-calling-api-sdk/quick-start-ILS): Validate large-audience playback with the HLS quick start.
- [Review Best Practices](/javascript/guide/interactive-live-streaming/best-practices/user-experience): Refine UX, moderation, and scalability with the recommended patterns.
- [Track Updates](/javascript/guide/interactive-live-streaming/release-notes): Monitor release notes and supported browser guidance before shipping.



---

# Known Issues




---

# Pin/Unpin Participants - JavaScript

In a live stream setup, you often want to control which participant is actively visible on screen — whether it’s the host, a special guest, or someone screen sharing. To manage this dynamically, the `useParticipant` hook provides two key methods:

- `pin()` – Focus on a specific participant’s camera or screen share

- `unpin()` – Remove that focus and return to the default layout

This allows you to programmatically decide who gets the spotlight in your live stream layout.

### `pin()`

The pin() method makes it easy to bring a host camera or screen share front and center in the broadcast layout. Once pinned, you can write the layout logic to place this host in the primary frame, e.g. fullscreen or in a highlighted position.

```js
let liveStream;

// Initialize Meeting
liveStream = VideoSDK.initMeeting({
  // ...
});

const participants = liveStream.participants;
const participant = participants.get("<participant-id>");

const pinBtn = document.getElementById("pinBtn");
pinBtn.addEventListener("click", () => {
  // unmuteMic Meeting
  participant?.pin();
});
```

### `unpin()`

When a host is no longer the focus (e.g. their segment is over), you can reset their pinned state using unpin(). This allows your live stream UI to revert to a default grid view or automatically promote the next speaker.

```js
let liveStream;

// Initialize LiveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

const participants = liveStream.participants;
const participant = participants.get("<participant-id>");

const unpinBtn = document.getElementById("unpinBtn");
unpinBtn.addEventListener("click", () => {
  participant?.unpin();
});
```

### Events associated with pin/unpin

Following callbacks are received when a host is pinned or unpinned in the livestream.

- All [participants-including all the hosts and audience members](/javascript/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a callback on the `pin-state-changed` event with the data object containg the peerid of the participant who was pinned, the state and pinnedBy values.

```js
let liveStream;

// Initialize LiveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

liveStream.on("pin-state-changed", (data) => {
  const { peerId, state, pinnedBy } = data;
  console.log("onPinStateChanged");
});
```

:::info

- Based on the `pin-state-changed` event, you should update your live stream layout for all participants (including the audience) to reflect the current pinned participant.
  This means conditionally rendering the pinned participant in the main view or spotlight area across all clients.

:::

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [pin](/javascript/api/sdk-reference/participant-class/methods#pin)
- [unpin](/javascript/api/sdk-reference/participant-class/methods#unpin)


---

# Rendering Host and Audience Views - JavaScript


This guide explains how developers can render host participants in a live streaming scenario where one or more hosts can broadcast to thousands of audience members.

### Participant Modes
Participants can join a meeting in one of two modes:

-   **SEND_AND_RECV**: Participants in this mode can both send and receive audio/video (typically hosts)
-   **RECV_ONLY**: Participants in this mode can only receive audio/video (typically audience members)


### Rendering Local Participant

When you join a meeting as a host (`SEND_AND_RECV` mode), you'll need to render your own video to see yourself during the broadcast:

```js
meeting.on("meeting-joined", () => {
  if (meeting?.localParticipant.mode === "SEND_AND_RECV") {
    let videoElement = meeting?.localParticipant.renderVideo({
      type: "video", // Options: "video" or "share" for screen sharing
      maxQuality: "auto", // Options: "auto", "high", "med", "low"
      containerStyle: {
        // Custom styling for container
        width: "300px",
        height: "168px",
      },
    });

    videoContainer.appendChild(videoElement);
  }
});
```

### Rendering Remote Participants

When remote participants join in `SEND_AND_RECV` mode (other hosts), you'll need to render their video and audio:

```js
meeting.on("participant-joined", (participant) => {
  if (participant.mode === "SEND_AND_RECV") {
    let videoElement = participant.renderVideo({
      type: "video", // Options: "video" or "share" for screen sharing
      maxQuality: "auto", // Options: "auto", "high", "med", "low"
      containerStyle: {
        // Custom styling for container
        width: "300px",
        height: "168px",
      },
    });

    let audioElement = participant.renderAudio({
      type: "audio", // Options: "audio" or "shareAudio" for screen share audio
    });

    videoContainer.appendChild(videoElement);
    videoContainer.appendChild(audioElement);
  }
});
```
This works on both the **host** and **audience** side. Audience users will be in `RECV_ONLY` mode and cannot publish media but can render the host’s media.

### Handling Participant Departure

To maintain a clean UI, you should remove video and audio elements when participants leave:
```js
meeting.on("participant-left", (participant) => {
let  vElement  =  document.getElementById(`f-${participant.id}`);
vElement.remove(vElement);

let  aElement  =  document.getElementById(`a-${participant.id}`);
aElement.remove(aElement);
});
```

### Monitoring Media Status Changes
You can listen for the `media-status-changed` event on each participant to detect when they toggle their camera or microphone:
```js
participant.on("media-status-changed", (data) => {
  const { kind, newStatus } = data;
  // kind can be "video" or "audio"  
  console.log(`Participant's ${kind} is now ${newStatus}`);
  // You can Update UI accordingly
});
```

## Tracking Participant Counts

### Counting Audience Members (RECV_ONLY)
To get the count of audience members (participants in `RECV_ONLY` mode):

```js
function getAudienceCount() {
  const participants = meeting.participants;
  const audience = [...participants.values()].filter((participant) => {
    return participant.mode === VideoSDK.Constants.modes.RECV_ONLY;
  });
  return audience.length || 0;
}
```
### Counting Hosts (SEND_AND_RECV)
To get the count of hosts (participants in `SEND_AND_RECV` mode):
```js
function getHostCount() {
  const participants = meeting.participants;
  const hosts = [...participants.values()].filter((participant) => {
    return participant.mode === VideoSDK.Constants.modes.SEND_AND_RECV;
  });
  return hosts.length || 0;
}
```

### Getting Total Participant Count
To get the total count of all participants (both hosts and audience):
```js
function getTotalParticipantCount() {
  return meeting.participants.size;
}
```

### Real-time Count Updates
To keep track of participant counts in real-time:
```js
// Initialize counters
let audienceCount = 0;
let hostCount = 0;

// Update counts when a participant joins
meeting.on("participant-joined", () => {
  audienceCount = getAudienceCount();
  hostCount = getHostCount();
  
  // Update UI
  updateParticipantCountsUI(audienceCount, hostCount);
});

// Update counts when a participant leaves
meeting.on("participant-left", () => {
  audienceCount = getAudienceCount();
  hostCount = getHostCount();
  
  // Update UI
  updateParticipantCountsUI(audienceCount, hostCount);
});

// Function to update the UI
function updateParticipantCountsUI(audienceCount, hostCount) {
  document.getElementById('audience-count').innerText = audienceCount;
  document.getElementById('host-count').innerText = hostCount;
  document.getElementById('total-count').innerText = audienceCount + hostCount;
}
```

## API Reference
The API references for all the methods and events utilized in this guide are provided below.

- [meeting-joined event](/javascript/api/sdk-reference/meeting-class/events#meeting-joined)
- [meeting-left event](/javascript/api/sdk-reference/meeting-class/events#meeting-left)
- [participant-joined event](/javascript/api/sdk-reference/meeting-class/events#participant-joined)
- [participant-left event](/javascript/api/sdk-reference/meeting-class/events#participant-left)



---

# Live Captioning for Livestreams - JavaScript

Live captioning enhances your livestreams by converting hosts' speech into text in real-time, boosting accessibility and engagement. Using the `startTranscription()` and `stopTranscription()` functions you can enable or disable captions on the fly, and display captions dynamically in your UI for all viewers.

Video SDK offers flexible configuration and event-driven updates to help you integrate captions seamlessly into your broadcast layout.

### `startTranscription()`

The `startTranscription()` method, is used to initiate live captions in a live stream. This method accepts the following two parameters:

- `1. webhookUrl (optional)`: This is the webhook URL where you can listen to events related to the recording, such as the start and stop of recording. It triggers when the recording is completed and stored on the server. You can learn more about webhooks [here](https://en.wikipedia.org/wiki/Webhook)

- `2. summary (optional)`:
  - `enabled`: Indicates whether realtime transcription summary generation is enabled. Summary will be available after realtime transcription stopped. Default: false.
  - `prompt`: provides guidelines or instructions for generating a custom summary based on the realtime transcription content.

### `stopTranscription()`

The `stopTranscription()` method, is used to stop the live captions in a live stream.

#### Example

```js
// LiveStream object
let liveStream;

// Initialize LiveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

// Get start button element
const startRealtimeTranscriptionBtn = document.getElementById(
  "startRealtimeTranscriptionBtn"
);

// Get stop button element
const stopRealtimeTranscriptionBtn = document.getElementById(
  "stopRealtimeTranscriptionBtn"
);

// Listen for click event
startRealtimeTranscriptionBtn.addEventListener("click", () => {
  // Configuration for realtime transcription
  let config = {
    webhookUrl: "https://example.com",
  };

  // Start realtime transcription
  liveStream?.startTranscription(config);
});

// Listen for click event
stopRealtimeTranscriptionBtn.addEventListener("click", () => {
  // Stop  realtime transcription
  liveStream?.stopTranscription();
});
```

### Events associated with live captioning

- All [participants-including all the hosts and audience members](/javascript/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a callback on the [transcription-state-changed](/javascript/api/sdk-reference/meeting-class/events#transcription-state-changed) event with the current state of the captioning.
- All [participants-including all the hosts and audience members](/javascript/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a callback on the [transcription-text](/javascript/api/sdk-reference/meeting-class/events#transcription-text) event with the latest captions whenever a host speaks.

```js
// LiveStream object
let liveStream;

// Initialize LiveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

// Listen for transcription state changed event
liveStream?.on("transcription-state-changed", (data) => {
  const { status, id } = data;

  // Check for starting event
  if (status === Constants.transcriptionEvents.TRANSCRIPTION_STARTING) {
    console.log("Realtime Transcription is starting", id);
  }
  // Check for started event
  else if (status === Constants.transcriptionEvents.TRANSCRIPTION_STARTED) {
    console.log("Realtime Transcription is started", id);
  }
  // Check for stopping event
  else if (status === Constants.transcriptionEvents.TRANSCRIPTION_STOPPING) {
    console.log("Realtime Transcription is stopping", id);
  }
  // Check for stopped event
  else if (status === Constants.transcriptionEvents.TRANSCRIPTION_STOPPED) {
    console.log("Realtime Transcription is stopped", id);
  }
});

// Listen for transcription text event
liveStream?.on("transcription-text", (data) => {
  // Destructuring data
  let { participantId, participantName, text, timestamp, type } = data;
  console.log(`${participantName}: ${text} ${timestamp}`);
});
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startTranscription()](/javascript/api/sdk-reference/meeting-class/methods#starttranscription)
- [stopTranscription()](/javascript/api/sdk-reference/meeting-class/methods#stoptranscription)
- [transcription-state-changed](/javascript/api/sdk-reference/meeting-class/events#transcription-state-changed)
- [transcription-text](/javascript/api/sdk-reference/meeting-class/events#transcription-text)


---

# Reactions during Live Stream - JavaScript

To enhance interaction between viewers and speakers during a livestream, a creative approach is to display viewers' reactions to everyone. This can be achieved by creating a lively atmosphere with flying emojis, similar to the experience seen in livestreams on platforms like Instagram.

This guide explains how to implement this engaging feature using the VideoSDK PubSub mechanism.

### Step 1: Creating a button to send reaction

To implement this functionality, start by creating a button that sends reactions to all users. When this button is clicked, publish a message with the emoji name to all participants using the VideoSDK PubSub mechanism. Additionally, dispatch browser `CustomEvents` to notify the local participant about the reaction.

```js
function sendEmoji(emoji) {
  // Let the local user see their own emoji
  window.dispatchEvent(
    new CustomEvent("reaction_added", { detail: { emoji } })
  );
}

// Create the 🎉 button
const confettiBtn = document.createElement("button");
confettiBtn.innerText = "Send 🎉 Reaction";
confettiBtn.onclick = () => {
  sendEmoji("confetti");
  liveStream?.pubSub.publish("REACTION", "confetti");
};

// Create the 👏 button
const clapBtn = document.createElement("button");
clapBtn.innerText = "Send 👏 Reaction";
clapBtn.onclick = () => {
  sendEmoji("clap");
  liveStream?.pubSub.publish("REACTION", "clap");
};

// Append to DOM
document.body.appendChild(confettiBtn);
document.body.appendChild(clapBtn);
```

### Step 2: Displaying the Reactions to all the users

`FlyingEmojiOverlay.js` will be utilized to display the reactions on the screen. Listen to the browser event sent on the button click to show the flying emoji and display all reactions sent by other participants

- Listening to local event and adding the `FlyingEmojiOverlay` component to the `ILSView`;

```js
function FlyingEmojisOverlay() {
  const EMOJI_MAP = {
    confetti: "🎉",
    clap: "👏",
  };

  const overlay = document.createElement("div");
  overlay.className = "flying-emojis";
  document.body.appendChild(overlay);

  function showFlyingEmoji(emojiKey) {
    const emoji = EMOJI_MAP[emojiKey];
    if (!emoji) return;

    const span = document.createElement("span");
    span.innerText = emoji;
    span.className = "emoji-fly"; // Add some CSS animation
    overlay.appendChild(span);

    // Remove emoji after animation (2s example)
    setTimeout(() => {
      overlay.removeChild(span);
    }, 2000);
  }

  function handleSendFlyingEmoji(e) {
    const { emoji } = e.detail;
    if (emoji) {
      showFlyingEmoji(emoji); // Show for local user
      liveStream?.pubSub.publish("REACTION", emoji); // Send to others
    }
  }

  window.addEventListener("reaction_added", handleSendFlyingEmoji);

  // Also listen for others' emojis
  liveStream?.pubSub.subscribe("REACTION", ({ message }) => {
    showFlyingEmoji(message);
  });

  return overlay;
}
```

- Next, implement the display and removal of flying emojis using simple CSS animations.

```js
function FlyingEmojisOverlay() {
  const EMOJI_MAP = {
    confetti: "🎉",
    clap: "👏",
  };

  const overlay = document.createElement("div");
  overlay.className = "flying-emojis";
  document.body.appendChild(overlay);

  // 🧹 Handler to remove flying emoji after animation
  function handleRemoveFlyingEmoji(node) {
    if (overlay.contains(node)) {
      overlay.removeChild(node);
    }
  }

  // ✨ Handler to display emoji with random animations
  function handleDisplayFlyingEmoji(emojiKey) {
    const emoji = EMOJI_MAP[emojiKey];
    if (!emoji) return;

    const node = document.createElement("div");
    node.appendChild(document.createTextNode(emoji));

    // Random animation and style
    node.className = Math.random() > 0.5 ? "emoji wiggle-1" : "emoji wiggle-2";
    node.style.position = "absolute";
    node.style.left = `${Math.random() * 100}%`;
    node.style.transform = `rotate(${-30 + Math.random() * 60}deg)`;

    overlay.appendChild(node);

    // Remove after animation ends
    node.addEventListener("animationend", () => {
      handleRemoveFlyingEmoji(node);
    });
  }

  // 🚀 Local user emoji trigger
  function handleSendFlyingEmoji(e) {
    const { emoji } = e.detail;
    if (emoji) {
      handleDisplayFlyingEmoji(emoji);
      liveStream?.pubSub.publish("REACTION", emoji);
    }
  }

  // 👂 Setup event listeners
  window.addEventListener("reaction_added", handleSendFlyingEmoji);

  const unsubscribe = liveStream?.pubSub.subscribe("REACTION", ({ message }) => {
    handleDisplayFlyingEmoji(message);
  });

  // 🧹 Cleanup on unload
  window.addEventListener("beforeunload", () => {
    window.removeEventListener("reaction_added", handleSendFlyingEmoji);
    if (typeof unsubscribe === "function") unsubscribe();
  });

  return overlay;
}
```

- Add the animations for the emojis in the `index.css` file.

```css
.flying-emojis {
  position: fixed;
  top: 0px;
  bottom: 0px;
  left: 0px;
  right: 0px;
  overflow: hidden;
  pointer-events: none;
  user-select: none;
  z-index: 99;
}
.emoji {
  position: absolute;
  bottom: 0px;
  left: 50%;
  font-size: 48px;
  line-height: 1;
  width: 48px;
  height: 48px;
}
.emoji.wiggle-1 {
  animation: emerge 3s forwards, wiggle-1 1s ease-in-out infinite alternate;
}
.emoji.wiggle-2 {
  animation: emerge 3s forwards, wiggle-2 1s ease-in-out infinite alternate;
}
@keyframes emerge {
  to {
    bottom: 85%;
    opacity: 0;
  }
}
@keyframes wiggle-1 {
  from {
    margin-left: -50px;
  }
  to {
    margin-left: 50px;
  }
}
@keyframes wiggle-2 {
  from {
    margin-left: 50px;
  }
  to {
    margin-left: -50px;
  }
}
```

- Finally add the listener to the PubSub topic so reactions from other participants can also be shown.

```js
function FlyingEmojisOverlay() {
  const EMOJI_MAP = {
    confetti: "🎉",
    clap: "👏",
  };

  const overlay = document.createElement("div");
  overlay.className = "flying-emojis";
  document.body.appendChild(overlay);

  // 🧹 Handler to remove flying emoji after animation
  function handleRemoveFlyingEmoji(node) {
    if (overlay.contains(node)) {
      overlay.removeChild(node);
    }
  }

  // ✨ Handler to display emoji with random animations
  function handleDisplayFlyingEmoji(emojiKey) {
    const emoji = EMOJI_MAP[emojiKey];
    if (!emoji) return;

    const node = document.createElement("div");
    node.appendChild(document.createTextNode(emoji));

    // Random animation and style
    node.className = Math.random() > 0.5 ? "emoji wiggle-1" : "emoji wiggle-2";
    node.style.position = "absolute";
    node.style.left = `${Math.random() * 100}%`;
    node.style.transform = `rotate(${-30 + Math.random() * 60}deg)`;

    overlay.appendChild(node);

    // Remove after animation ends
    node.addEventListener("animationend", () => {
      handleRemoveFlyingEmoji(node);
    });
  }

  // 🚀 Local user emoji trigger
  function handleSendFlyingEmoji(e) {
    const { emoji } = e.detail;
    if (emoji) {
      handleDisplayFlyingEmoji(emoji);
      liveStream?.pubSub.publish("REACTION", emoji); // Publish the reaction
    }
  }

  // 👂 Setup event listeners for the local user to trigger emoji reactions
  window.addEventListener("reaction_added", handleSendFlyingEmoji);

  // 🧑‍🤝‍🧑 Listen for reactions from other participants
  const unsubscribe = liveStream?.pubSub.subscribe("REACTION", ({ message }) => {
    handleDisplayFlyingEmoji(message); // Display the received emoji from others
  });

  // 🧹 Cleanup on unload (to avoid memory leaks)
  window.addEventListener("beforeunload", () => {
    window.removeEventListener("reaction_added", handleSendFlyingEmoji);
    if (typeof unsubscribe === "function") unsubscribe();
  });

  return overlay;
}
```


<div style={{textAlign: 'center'}}>



</div>

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [PubSub](/javascript/api/sdk-reference/meeting-class/pubsub)


---

Recording meetings is an essential feature that ensures all important discussions, decisions, and interactions are documented for future reference. VideoSDK offers three types of recordings: Meeting Recording, Participant Recording, and Participant Track Recording. Each type serves a specific purpose to cater to different recording needs during a meeting.

## Meeting Recording

Meeting Recording captures the entire meeting, including all participants, audio, video, and shared content. This comprehensive recording is ideal for reviewing the entire meeting, ensuring that nothing is missed. It provides a holistic view of the meeting, capturing every interaction and piece of information shared during the session.

![Meeting Recording](https://cdn.videosdk.live/website-resources/docs-resources/MeetingRecording.png)

## Participant Recording

Participant Recording focuses on individual participants, capturing both their audio and video into a single file. This type of recording is particularly useful for tracking the contributions of specific participants or for scenarios where detailed analysis of an individual’s participation is needed. When a participant mutes their audio or turns off their video, the recording continues but with silenced audio or a black screen, respectively. This ensures a continuous recording without interruptions, reflecting the participant's involvement throughout the meeting.

![Participant Recording](https://cdn.videosdk.live/website-resources/docs-resources/ParticipantRecording.png)

## Participant Track Recording

Participant Track Recording allows you to record specific tracks of a participant, either audio or video, based on user input. This targeted approach is perfect for capturing particular aspects of a participant’s contribution, such as only their audio or only their video. Multiple files are generated whenever there is a change in the track's status (e.g., starting after being muted ), ensuring focused documentation of each continuous segment. This method is especially useful in scenarios where detailed analysis of specific media (audio or video) is required.

![Participant Track Recording](https://cdn.videosdk.live/website-resources/docs-resources/TrackRecording.png)



---

# Geo Tag Meeting Recordings - JavaScript

To ensure compliance for BFSIs doing vKYC, it very important to include the co-ordinates(location) of the customer in the recordings. VideoSDK provides a very customizable solution to implement this feature. You will be using custom templates for this purpose.

We have created a ready to use template for this use case which can be found [here](https://github.com/videosdk-live/videosdk-rtc-react-prebuilt-ui/tree/template/geo-tag-watermark). To integrate this template with your recordings follow the below mentiond instructions.

### Host the template

1. Clone the template repository and switch to the branch `template/geo-tag-watermark`.

```bash
git clone https://github.com/videosdk-live/videosdk-rtc-react-prebuilt-ui.git
cd videosdk-rtc-react-prebuilt-ui
git checkout template/geo-tag-watermark
```

2. Install the dependencies and create a build of the project using below mentioned commands.

```bash
npm install
npm run build
```

3. Host the contents of the build folder on your server and check if the template is up and running.

:::note

If you want to create the complete template from scratch you can [follow this guide.](/javascript/guide/video-and-audio-calling-api-sdk/recording/custom-template)

:::

### Using the template for recording

1. To use the template that we deployed earlier, we will be using the `templateUrl` feature in the `startRecording` API.
   To generate the template URL, you will have to append the `meetingId`, and `token` has to be added in the query parameters. Also if you are using the template provided above you need to added a few extra paramters mentioned below. Here is the code snippet to generate the URL.

```js
async function main() {
  let meetingId = "Your MeetingID";
  let token = "Your Token";
  const templateUrl = `https://${YOUR Template URL}/?meetingId=${meetingId}&token=${token}&name=recorder&isRecorder=true&joinWithoutUserInteraction=true`;

  console.log(templateUrl);
}

main();
```

2. Now that we have the template URL, we will use this URL to start the recording using the below provided API call.

```js
async function main() {
  let meetingId = "Your MeetingID";
  let token = "Your Token";
  const templateUrl = `https://${YOUR Template URL}/?meetingId=${meetingId}&token=${token}&name=recorder&isRecorder=true&joinWithoutUserInteraction=true`;

  console.log(templateUrl);

  //Using the previouly created template URL and starting the recording using the API.
  const options = {
    method: "POST",
    headers: {
      Authorization: "$YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      roomId: "Your MeetingId",
      templateUrl: templateUrl,
    }),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();
```

### Updating the Geo Tagging Coordinates

We will be using the PubSub feature of VideoSDK to update the data of latitude and longitude. For the predefined template provided by us we are using `GEO_TAG` as topic name. We will be publishing the `participantName`, `latitude` and `longitude` of the participant for whom we want to show in the recording.

:::note

You will have to fetch the longitude and latitude of the participant before sending it using the pubsub.

:::

Here is the code how you will have to publish the message:

```js
function Watermark() {
  const sendCoordinates = () => {
    meeting.pubSub.publish(
      "GEO_TAG",
      "GEO TAG DATA",
      { persist: true },
      {
        latitude: "LATITUDE OF PARTICIPANT",
        longitude: "LONGITUDE OF PARTICIPANT",
        participantName: "NAME OF PARTICIPANT",
      }
    );
  };

  return <></>;
}
```

After implementing this, you should get the recording in the following format:

![Geo Tagging Recoridng](https://cdn.videosdk.live/website-resources/docs-resources/geo-tag-recording-template.png)

If you wish to change how UI looks on recording, you can change it by updating the layout in the template itself.

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)
- [Learn more about Custom Templates](./custom-template.md)


---

You have the option to create presigned URL, allowing you to upload your recordings to AWS, Azure, or GCP securely.
presigned URL provide a secure and temporary way to upload objects to your cloud storage. Instead of sharing your entire credentials, you can create a special URL that allows uploading a specific file for a limited time.

:::important

While presigned URL offer a convenient way to upload files securely, each cloud provider (AWS, Azure, and GCP) might have different restrictions on how they work. It's advisable to refer the respective documentation for **[<u>AWS</u>](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)**, **[<u>Azure</u>](https://learn.microsoft.com/en-us/rest/api/storageservices/delegate-access-with-shared-access-signature)**, and **[<u>GCP</u>](https://cloud.google.com/cdn/docs/using-signed-urls)** to gain a clearer understanding of presigned URL.

:::

### Code Sample

This guide will walk you through the process of generating a presigned URL for uploading recordings to your cloud storage of choice. You can use this generated presigned URL in [Start Recording API](/api-reference/realtime-communication/start-recording#preSignedUrl).



**AWS:**

```js
const { S3Client, PutObjectCommand } = require("@aws-sdk/client-s3");
const { getSignedUrl } = require("@aws-sdk/s3-request-presigner");

const region = <YOUR S3 REGION>;
const bucket = <YOUR S3 BUCKET NAME>;
const key = <YOUR FILE NAME>; // test/abc.mp4
const accessKeyId = <YOUR S3 ACCESS KEY ID>;
const secretAccessKey = <YOUR S3 SECRET ACCESS KEY>;
const expiresIn = <URL EXPIRY IN SECONDS>; // this number should be higher than duraion of recording

const s3Client = new S3Client({
credentials: {
    accessKeyId: accessKeyId,
    secretAccessKey: secretAccessKey,
},
region: region,
});

const createPresignedUrlWithClient = async () => {
const command = new PutObjectCommand({ Bucket: bucket, Key: key });
const preSignedUrl = await getSignedUrl(s3Client, command, { expiresIn: expiresIn });
return preSignedUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await createPresignedUrlWithClient();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

---

**AZURE:**

```js
const { BlobServiceClient, BlobSASPermissions } = require("@azure/storage-blob");

const connectionString = <YOUR AZURE STORAGE CONNECTION STRING>;
const containerName = <YOUR AZURE CONTAINER NAME>;
const blobName = <YOUR AZURE BLOB NAME>;
const startsOn = <YOUR SASURL START TIME>; // (optional, defaults to now)
const expiresOn = <YOUR SASURL EXPIRY TIME>; // expiry time should be higher than duration of recording

const generateSASUrl = async () => {
let blobServiceClient = BlobServiceClient.fromConnectionString(connectionString);
let containerClient = blobServiceClient.getContainerClient(containerName);

await containerClient.createIfNotExists({
    access: "container",
});

const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const sasUrl = await blockBlobClient.generateSasUrl({
    startsOn: startsOn, // sasUrl start time
    expiresOn: expiresOn, // sasUrl expiration time
    permissions: BlobSASPermissions.parse("write"),
});
return sasUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await generateSASUrl();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

---

**GCP:**

```js
const { Storage } = require("@google-cloud/storage");

const projectId = <YOUR GCP PROJECT ID>;
const clientEmail = <YOUR GCP CLIENT EMAIL>;
const privateKey = <YOUR GCP PRIVATE KEY>;
const expires =<URL EXPIRY IN SECONDS>; // this number should be higher than duraion of recording
const bucketName = <YOUR GCP BUCKET NAME>;
const fileName = <YOUR FILE NAME>; // test/abc.mp4

const storage = new Storage({
projectId: projectId,
credentials: {
    client_email: clientEmail,
    private_key: privateKey,
},
});

const generateSignedUrl = async () => {
const options = {
    version: "v4",
    action: "write",
    expires: expires,
    contentType: "video/mp4",
};

const [signedUrl] = storage.bucket(bucketName).file(fileName).getSignedUrl(options);
return signedUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await generateSignedUrl();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)



---

VideoSDK offers individual participant recording, generating a single, continuous file for a participant.

This recording captures the participant's audio and video streams throughout the meeting, regardless of whether they are muted or have their camera turned off. During periods of audio muting or video disengagement, the respective tracks will be silent or display a black screen, respectively.

You can access the recorded files in the developer dashboard or opt to store them in your own cloud storage.

This guide provides an overview of the start and stop functionality for individual participant recording through APIs.


## Start Individual Participant Recording

To start a participant recording, you will have to call `/v2/recordings/participant/start` API with following body parameters.

- `roomId`: RoomId for which the participant recording is to be started
- `participantId`: participantId of the participant to be recorder.
- `fileFormat`: Currently only `webm` is supported as file format. We will add the support for other formats in future.
- `webhookUrl`: The webhook URL where you would like to get the status updates of the recording. To learn more about webhooks refer [here](#participant-track-recording-starting).
- `bucketDirPath`: If you are using your own storage, you can provide the directory path where you want to store the recording. To configure the storage please [refere this quide](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config).

The usual recording path would look like `${sessionId}/${participantId}/${filename}`.

```js

const roomId = <YOUR ROOM ID>;
const participantId = <PARTICIPANT ID>;
const fileFormat = <YOUR FILE FORMAT>; // (Optional) default: webm
const bucketDirPath = <YOUR CLOUD STORAGE BUCKET PATH>; // (Optional) test/abc
const webhookUrl = <YOUR WEBHOOK URL>; // (Optional)

async function main() {
    const options = {
    method: "POST",
    headers: {
      Authorization: "$YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      roomId: roomId,
      participantId: participantId,
      fileFormat: fileFormat,
      bucketDirPath: bucketDirPath,
      webhookUrl: webhookUrl
    }),
  };

  const url = `https://api.videosdk.live/v2/recordings/participant/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();
```

## Stop Individual Participant Recording

To stop a participant recording, you will have to call `/v2/recordings/participant/stop` API with following body parameters.

- `roomId`: RoomId for which the participant recording is to be stopped
- `participantId`: participantId for which the recording is to be stopped.

```js

const roomId = <YOUR ROOM ID>;
const participantId = <PARTICIPANT ID>;

async function main() {
    const options = {
    method: "POST",
    headers: {
      Authorization: "$YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      roomId: roomId,
      participantId: participantId,
    }),
  };

  const url = `https://api.videosdk.live/v2/recordings/participant/stop`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();
```

## Webhook associated with Participant Recording

### participant-recording-starting

- A "Participant Recording Starting" webhook is triggered when the participant recording process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-started

- Participant Recording started webhook will be received when successfully participant recording is started in meeting

###### Example

```javascript
{
    "webhookType": "participant-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopping

- A "Participant Recording Stopping" webhook is triggered when the participant recording end process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopped

- Participant Recording stopped webhook will be received when participant recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "participant-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-recording-failed

- A "Participant Recording Failed" webhook is generated when the participant recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "participant-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
    },
}
```

---

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Participant Recording API](/api-reference/realtime-communication/start-participant-recording)
- [Stop Participant Recording API](/api-reference/realtime-communication/stop-participant-recording)



---

VideoSDK provides participant track recording, creating separate audio or video files for participant.

New files are generated when a participant starts their audio or video again after turning it off (e.g., unmuting the microphone or restarting the camera). This ensures that each file represents a continuous segment of audio or video content.

Once track recording is complete, all audio files for a participant are consolidated into a single directory, as are the video files.


## Start Participant Track Recording

To start a participant track recording, you will have to call `/v2/recordings/participant/track/start` API with following body parameters.

- `roomId`: RoomId for which the participant track recording is to be started
- `participantId`: participantId of the participant to be recorder.
- `kind`: The kind of tracks you want to record.
  - You can pass following values: _`audio`_ | _`video`_ | _`screen_audio`_ | _`screen_video`_
- `fileFormat`: Currently only `webm` is supported as file format. We will add the support for other formats in future.
- `webhookUrl`: The webhook URL where you would like to get the status updates of the recording. To learn more about webhooks refer [here](#participant-track-recording-starting).
- `bucketDirPath`: If you are using your own storage, you can provide the directory path where you want to store the recording. To configure the storage please [refere this quide](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config).

The usual recording path would look like `${sessionId}/${participantId}/${kind}/${filename}`.

```js

const roomId = <YOUR ROOM ID>;
const participantId = <PARTICIPANT ID>;
const kind = <YOUR STREAM KIND> // kind of track: audio, video etc.
const fileFormat = <YOUR FILE FORMAT>; // (Optional) default: webm
const bucketDirPath = <YOUR CLOUD STORAGE BUCKET PATH>; // (Optional) test/abc
const webhookUrl = <YOUR WEBHOOK URL>; // (Optional)

async function main() {
    const options = {
    method: "POST",
    headers: {
      Authorization: "$YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      roomId: roomId,
      participantId: participantId,
      kind: kind,
      fileFormat: fileFormat,
      bucketDirPath: bucketDirPath,
      webhookUrl: webhookUrl
    }),
  };

  const url = `https://api.videosdk.live/v2/recordings/participant/track/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();
```

## Stop Participant Track Recording

To stop a participant track recording, you will have to call `/v2/recordings/participant/track/stop` API with following body parameters.

- `roomId`: RoomId for which the participant track recording is to be stopped
- `participantId`: participantId for which the recording is to be stopped.
- `kind`: The kind of track recording you want to stop for the given participant.
  - You can pass following values: _`audio`_ | _`video`_ | _`screen_audio`_ | _`screen_video`_

```js

const roomId = <YOUR ROOM ID>;
const participantId = <PARTICIPANT ID>;
const kind = <YOUR STREAM KIND>; // kind of track: audio, video etc.

async function main() {
    const options = {
    method: "POST",
    headers: {
      Authorization: "$YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      roomId: roomId,
      participantId: participantId,
      kind: kind
    }),
  };

  const url = `https://api.videosdk.live/v2/recordings/participant/track/stop`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();
```

## Webhook associated with Participant Track Recording

### participant-track-recording-starting

- A "Participant Track Recording Starting" webhook is triggered when the track recording process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-started

- Participant Track Recording started webhook will be received when successfully track recording is started in meeting

###### Example

```javascript
{
    "webhookType": "participant-track-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopping

- A "Participant Track Recording Stopping" webhook is triggered when the track recording end process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopped

- Participant Track Recording stopped webhook will be received when track recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-track-recording-failed

- A "Participant Track Recording Failed" webhook is generated when the track recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Track Recording API](/api-reference/realtime-communication/start-track-recording)
- [Stop Track Recording API](/api-reference/realtime-communication/stop-track-recording)



---

### Storage Configuration

While recording your meetings, you have the flexibility to store them either on VideoSDK's storage or configure your own storage solution such as **`AWS S3 Storage, Azure Blob or GCP Cloud Storage`**. To set up your own storage, you can navigate to the [API section](https://app.videosdk.live/api-keys) in the VideoSDK Dashboard.

- This feature allows you to configure storage provider for your meeting recordings.

- You can configure multiple storage provider with multiple API Keys.

- Currently, we support `AWS S3`, `Azure Blob` and `GCP Cloud Storage`. We will add support for other storage provider soon !!

## Prerequisites

- An active [VideoSDK Developer Account](https://app.videosdk.live)
- `Aws S3`, `Azure Blob Storage` or `GCP Cloud Storage` Credentials

## How to setup ?

### Step 1 : Select Api Key

![Dashboard](/img/tutorial/dashboard/api-key-dashboard.png)

- Go to [VideoSDK Dashboard](https://app.videosdk.live/api-keys).
- Select API Key for which, you want to set storage configuration.
- Then click on `Storage Config` Icon in Actions.

### Step 2 : Choose Cloud Storage Provider

![Dashboard](/img/tutorial/dashboard/storage-config.png)

- As you can see in the image, there are 3 Cloud Storage Provider (`Aws`, `Azure`, `GCP`).
- You can select a Cloud Storage Provider as per your requirements.

### Step 3 : Configure Bucket or Container

<h4> For Aws S3 Storage </h4>

![Aws S3](/img/tutorial/dashboard/s3.png)

- You will need AWS S3 Bucket. [Learn to create S3 Bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html).

- As you can see in the image, you will need enter `accessKeyId`, `secretAccessKey`, `region`, `bucket`, and `ACL` to setup for Aws S3 Storage.

- Click on `Save` button.

<hr />

<h4> For Azure Blob Storage: </h4>

![Azure Blob](/img/tutorial/dashboard/blob.png)

- You will need Azure Blob Container. [Learn to create Blob Container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal#create-a-container).

- As you can see in the image, you will need to enter `connectionString` and `containerName` to setup for Azure Blob.

- Click on `Save` button.

<hr />

<h4> For Google Cloud Storage: </h4>

<img src="/img/tutorial/dashboard/gcp.png" alt="GCP Cloud Storage" width="436" height="632"/>

1. You will need Google Cloud Storage Bucket. [Learn to create Google Cloud Storage Bucket](https://cloud.google.com/storage/docs/creating-buckets).

2. After creation, click on the <b> &#xFE19; </b>button in the upper right corner and select **`Project settings`**.

3. Under **`IAM and Admin`**, select **`Service Accounts`**. In the service account list, click on the <b> &#xFE19; </b> button for the account just added or created before, and select **`Manage keys`**.

4. Click **`ADD KEY > Create new key`**. Select **`JSON`** in the pop-up box and click **`CREATE`**. A json file is downloaded with the name format `projectId-xxxxxxxx.json`.

5. Open the downloaded json file, which looks like the following example:

```
{
  "type": "service_account",
  "project_id": "videosdk-12345",
  "private_key_id": "yourprivateidkeyyourprivateidkeyyourprivateidkey",
  "private_key": "-----BEGIN PRIVATE KEY-----\nThisisYourPrivateKeyThisisYourPrivateKeyThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\n-----END PRIVATE KEY-----\n",
  "client_email": "xxxx-xxxx@videosdk-12345.iam.gserviceaccount.com",
  "client_id": "123456789012345678901",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/videosdk%40videosdk-404307.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}
```

- As you can see in the image, you will need to enter `Project Id`, `Client Email`, `Bucket`, `Private Key` to setup for Google Cloud Storage Bucket. You can retrieve these details from the json file.

- Click on `Save` button.

### Step 4 : Test

- It's time to test !!
- [Create Room](https://docs.videosdk.live/api-reference/realtime-communication/create-room) with token generated with the API Key, you have configured for.
- Start meeting with the roomId created and Start Recording !!
- Then, you can see that recording will be available in your Bucket or Container.

:::note

- Only a single Recording Storage Config can be possible for a particular Api Key at a time.
- In order to add new Recording Configuration, first you need to delete current configuration.

:::


---

# Recording in Live Stream - JavaScript

This guide will provide an overview of how to implement start and stop Recording during a live stream.

### `startRecording()`

The `startRecording()` method, is used to initiate the recording of a live stream. This method accepts the following four parameters:

- `1. webhookUrl (optional)`: This is the webhook URL where you can listen to events related to the recording, such as the start and stop of recording. It triggers when the recording is completed and stored on the server. You can learn more about webhooks [here](https://en.wikipedia.org/wiki/Webhook)

- `2. awsDirPath (optional)`: This parameter specifies the path to your S3 bucket where you intend to store the recordings. To enable the storage of recordings in your S3 bucket with VideoSDK, follow this guide ([VideoSDK Cloud (AWS S3, Azure Blob or GCP ) Integration](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config))

- `3. config (optional)`: This parameter defines how the recording should be conducted

- `4. transcription (optional)`: This parameter lets you start post transcription for the recording.

  :::caution

  If you don't have a value for `webhookUrl` or `awsDirPath` and wish to utilize the `config` property, you should pass `null` in place of the missing values. Failing to do so may result in the configuration not being applied to the recording.
  :::

  ```js
  const config = {
    // highlight-next-line
    // Layout Configuration
    layout: {
      type: "GRID", // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
      priority: "SPEAKER", // "PIN", Default : "SPEAKER"
      gridSize: 4, // MAX : 4
    },

    // highlight-next-line
    // Theme of recording
    theme: "DARK", //  "LIGHT" | "DEFAULT"

    // highlight-next-line
    // `mode` is used to either record video & audio both or only audio.
    mode: "video-and-audio", // "audio", Default : "video-and-audio"

    // highlight-next-line
    // Quality of recording and is only applicable to `video-and-audio` type mode.
    quality: "high", /* Default : "med"
   "low" (SD Recording) | "med" (HD Recording) | "high" (FHD Recording) */

    //highlight-start
    // This mode refers to orientation of recording.
    // landscape : Record the meeting in horizontally
    // portrait : Record the meeting in vertically (Best for mobile view)
    //highlight-end
    orientation: "landscape", // "portrait",  Default : "landscape"
  };

  // highlight-next-line
  // Post Transcription Configuration
  const transcription = {
    enabled: true, // Enables post transcription
    summary: {
      enabled: true, // Enables summary generation

      // Guides summary generation
      prompt:
        "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    },
  };

  startRecording(null, null, config, transcription);
  ```

### `stopRecording()`

The `stopRecording()` method, is used to stop the recording of a live stream.

#### Example

```js
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

const startRecordingBtn = document.getElementById("startRecordingBtn");
startRecordingBtn.addEventListener("click", () => {
  // Configuration for recording
  let config = {
    layout: {
      type: "GRID",
      priority: "SPEAKER",
      gridSize: 4,
    },
    theme: "DARK",
    mode: "video-and-audio",
    quality: "high",
    orientation: "landscape",
  };

  // Configuration for post transcription
  let transcription = {
    enabled: true,
    summary: {
      enabled: true,
      prompt:
        "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    },
  };

  // Start Recording
  liveStream?.startRecording(
    "YOUR WEB HOOK URL",
    "AWS Directory Path",
    config,
    transcription
  );
});

const stopRecordingBtn = document.getElementById("stopRecordingBtn");
stopRecordingBtn.addEventListener("click", () => {
  // Stop Recording
  meeting?.stopRecording();
});
```

:::important

To initiate automatic recording at the beginning of a `session`, simply provide the `autoStartConfig` feature `recording` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.

:::

### Events associated with recording

Following callback is received when recording state changes.

- All [participants-including all the hosts and audience members](/javascript/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a callback on the [recording-state-changed](/javascript/api/sdk-reference/meeting-class/events#recording-state-changed) event with the current state of the recording.

```js
let liveStream;

// Initialize Meeting
liveStream = VideoSDK.initMeeting({
  // ...
});

const Constants = VideoSDK.Constants;

liveStream.on("recording-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.recordingEvents.RECORDING_STARTING) {
    console.log("Meeting recording is starting");
  } else if (status === Constants.recordingEvents.RECORDING_STARTED) {
    console.log("Meeting recording is started");
  } else if (status === Constants.recordingEvents.RECORDING_STOPPING) {
    console.log("Meeting recording is stopping");
  } else if (status === Constants.recordingEvents.RECORDING_STOPPED) {
    console.log("Meeting recording is stopped");
  } else {
    //
  }
});
```

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [startRecording()](/javascript/api/sdk-reference/meeting-class/methods#startrecording)
- [stopRecording()](/javascript/api/sdk-reference/meeting-class/methods#stoprecording)
- [recording-state-changed](/javascript/api/sdk-reference/meeting-class/events#recording-state-changed)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

# Webhooks and Events - JavaScript

### Events associated with Recording

- **onRecordingStateChanged** - The `recording-state-changed` event is triggered whenever the state of meeting recording changes.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const Constants = VideoSDK.Constants;

meeting.on("recording-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.recordingEvents.RECORDING_STARTING) {
    console.log("Meeting recording is starting");
  } else if (status === Constants.recordingEvents.RECORDING_STARTED) {
    console.log("Meeting recording is started");
  } else if (status === Constants.recordingEvents.RECORDING_STOPPING) {
    console.log("Meeting recording is stopping");
  } else if (status === Constants.recordingEvents.RECORDING_STOPPED) {
    console.log("Meeting recording is stopped");
  } else {
    //
  }
});
```

:::important

You can access your recordings on our **[<u>Dashboard</u>](https://app.videosdk.live/meetings/recordings)**. Additionally, you can access your recordings using our **[<u>Recording API</u>](/api-reference/realtime-communication/fetch-recordings)**.

You can access your post transcriptions using our **[<u>Post Transcription API</u>](/api-reference/realtime-communication/fetch-post-transcriptions-summary)**

:::

## Webhook associated with Recording

### recording-starting

- A "Recording Starting" webhook is triggered when the recording process for a meeting is initiated.

###### Example

```javascript
{
    "webhookType": "recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-started

- Recording started webhook will be received when successfully recording is started in meeting

###### Example

```javascript
{
    "webhookType": "recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopping

- A "Recording Stopping" webhook is triggered when the recording end process for a meeting is initiated.

###### Example

```javascript
{
    "webhookType": "recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopped

- Recording stopped webhook will be received when recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
        "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",

    },
}
```

---

### recording-failed

- A "Recording Failed" webhook is generated when the recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```


---

# Recording in Live Stream - JavaScript

This guide will provide an overview of how to implement start and stop Recording during a live stream.

### `startRecording()`

The `startRecording()` method, is used to initiate the recording of a live stream. This method accepts the following four parameters:

- `1. webhookUrl (optional)`: This is the webhook URL where you can listen to events related to the recording, such as the start and stop of recording. It triggers when the recording is completed and stored on the server. You can learn more about webhooks [here](https://en.wikipedia.org/wiki/Webhook)

- `2. awsDirPath (optional)`: This parameter specifies the path to your S3 bucket where you intend to store the recordings. To enable the storage of recordings in your S3 bucket with VideoSDK, follow this guide ([VideoSDK Cloud (AWS S3, Azure Blob or GCP ) Integration](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config))

- `3. config (optional)`: This parameter defines how the recording should be conducted

- `4. transcription (optional)`: This parameter lets you start post transcription for the recording.

  :::caution

  If you don't have a value for `webhookUrl` or `awsDirPath` and wish to utilize the `config` property, you should pass `null` in place of the missing values. Failing to do so may result in the configuration not being applied to the recording.
  :::

  ```js
  const config = {
    // highlight-next-line
    // Layout Configuration
    layout: {
      type: "GRID", // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
      priority: "SPEAKER", // "PIN", Default : "SPEAKER"
      gridSize: 4, // MAX : 4
    },

    // highlight-next-line
    // Theme of recording
    theme: "DARK", //  "LIGHT" | "DEFAULT"

    // highlight-next-line
    // `mode` is used to either record video & audio both or only audio.
    mode: "video-and-audio", // "audio", Default : "video-and-audio"

    // highlight-next-line
    // Quality of recording and is only applicable to `video-and-audio` type mode.
    quality: "high", /* Default : "med"
   "low" (SD Recording) | "med" (HD Recording) | "high" (FHD Recording) */

    //highlight-start
    // This mode refers to orientation of recording.
    // landscape : Record the meeting in horizontally
    // portrait : Record the meeting in vertically (Best for mobile view)
    //highlight-end
    orientation: "landscape", // "portrait",  Default : "landscape"
  };

  // highlight-next-line
  // Post Transcription Configuration
  const transcription = {
    enabled: true, // Enables post transcription
    summary: {
      enabled: true, // Enables summary generation

      // Guides summary generation
      prompt:
        "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    },
  };

  startRecording(null, null, config, transcription);
  ```

### `stopRecording()`

The `stopRecording()` method, is used to stop the recording of a live stream.

#### Example

```js
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

const startRecordingBtn = document.getElementById("startRecordingBtn");
startRecordingBtn.addEventListener("click", () => {
  // Configuration for recording
  let config = {
    layout: {
      type: "GRID",
      priority: "SPEAKER",
      gridSize: 4,
    },
    theme: "DARK",
    mode: "video-and-audio",
    quality: "high",
    orientation: "landscape",
  };

  // Configuration for post transcription
  let transcription = {
    enabled: true,
    summary: {
      enabled: true,
      prompt:
        "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    },
  };

  // Start Recording
  liveStream?.startRecording(
    "YOUR WEB HOOK URL",
    "AWS Directory Path",
    config,
    transcription
  );
});

const stopRecordingBtn = document.getElementById("stopRecordingBtn");
stopRecordingBtn.addEventListener("click", () => {
  // Stop Recording
  meeting?.stopRecording();
});
```

:::important

To initiate automatic recording at the beginning of a `session`, simply provide the `autoStartConfig` feature `recording` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.

:::

### Events associated with recording

Following callback is received when recording state changes.

- All [participants-including all the hosts and audience members](/javascript/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive a callback on the [recording-state-changed](/javascript/api/sdk-reference/meeting-class/events#recording-state-changed) event with the current state of the recording.

```js
let liveStream;

// Initialize Meeting
liveStream = VideoSDK.initMeeting({
  // ...
});

const Constants = VideoSDK.Constants;

liveStream.on("recording-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.recordingEvents.RECORDING_STARTING) {
    console.log("Meeting recording is starting");
  } else if (status === Constants.recordingEvents.RECORDING_STARTED) {
    console.log("Meeting recording is started");
  } else if (status === Constants.recordingEvents.RECORDING_STOPPING) {
    console.log("Meeting recording is stopping");
  } else if (status === Constants.recordingEvents.RECORDING_STOPPED) {
    console.log("Meeting recording is stopped");
  } else {
    //
  }
});
```

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [startRecording()](/javascript/api/sdk-reference/meeting-class/methods#startrecording)
- [stopRecording()](/javascript/api/sdk-reference/meeting-class/methods#stoprecording)
- [recording-state-changed](/javascript/api/sdk-reference/meeting-class/events#recording-state-changed)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

# Relay Media (PK Host) - JavaScript

## Overview

The Relay Media feature enables hosts to relay their media (audio, video, screen share) to one or multiple other live streams. This creates cross-stream interactions similar to "PK battles" or collaborative broadcasts.

This feature allows audiences in one live stream to view and hear hosts from another live stream without changing rooms, creating powerful interactive experiences.

## Key Concepts

- **Media Relay**: The process of transmitting a host's audio/video from one live stream to another
- **Source Meeting**: The original live stream where the host is broadcasting
- **Destination Meeting**: The target live stream(s) where the host's media will be relayed
- **Relay Kinds**: The types of media that can be relayed (video, audio, screen share, etc.)

## Sequence Diagram



## Implementation Guide

### 1. Requesting Media Relay

### `requestMediaRelay()`

**Parameters:**

- `destinationMeetingId` (string): ID of the target liveStream
- `token` (string, optional): Authentication token for the destination liveStream
- `kinds` (array, optional): Array of media types to relay. Options:
  - `"video"`: Camera video
  - `"audio"`: Microphone audio
  - `"share"`: Screen share video
  - `"share_audio"`: Screen share audio

```javascript
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

liveStream.requestMediaRelay({
  destinationMeetingId: "liveStream-B",
  token: "VIDEOSDK_AUTHENTICATION_TOKEN",
  kinds: ["video", "audio"],
});
```

### 2. Handling Relay Requests (Destination liveStream)

In the destination liveStream, hosts (participants with `SEND_AND_RECV` mode) will receive relay requests:

```javascript
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

liveStream.on(
  "media-relay-request-received",
  ({ participantId, liveStreamId, displayName, accept, reject }) => {
    console.log(
      `Relay request from ${displayName} (${participantId}) in liveStream ${liveStreamId}`
    );

    // You can show UI to accept/reject the request
    showRelayRequestDialog(displayName, liveStreamId, accept, reject);
  }
);

// Example dialog handler
function showRelayRequestDialog(displayName, liveStreamId, accept, reject) {
  // Show custom UI dialog
  const confirmed = confirm(
    `${displayName} wants to relay their media to this live stream. Accept?`
  );

  if (confirmed) {
    accept(); // Accept the relay request
  } else {
    reject(); // Reject the relay request
  }
}
```

### 3. Handling Request Responses (Source Meeting)

In the source liveStream, track the response to your relay requests:

```javascript
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

liveStream.on(
  "media-relay-request-response",
  ({ decision, decidedBy, meetingId }) => {
    if (decision === "accepted") {
      console.log(`Relay request accepted by ${decidedBy}`);
      // Update UI to show relay is active
      updateRelayStatus(decidedBy, true);
    } else {
      console.log(`Relay request rejected by ${decidedBy}`);
      // Update UI to show relay was rejected
      showRelayRejectedMessage(decidedBy);
    }
  }
);
```

### 4. Tracking Active Relays

When a relay successfully starts:

```javascript
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});
liveStream.on("media-relay-started", ({ liveStreamId }) => {
  console.log(`Media relay started to ${liveStreamId}`);
  // Update UI to show active relay
  addActiveRelayToUI(liveStreamId);
});
```

### 5. Stopping Media Relay

To stop an ongoing relay:

### `stopMediaRelay()`

**Parameters:**

- `liveStreamId` (string): ID of the liveStream where the relay should stop

```javascript
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});
liveStream.stopMediaRelay("liveStream-B");
```

### 6. Handling Relay Stop Events

When a relay stops for any reason:

```javascript
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});
liveStream.on("media-relay-stopped", ({ meetingId, reason }) => {
  console.log(`Relay to ${meetingId} stopped. Reason: ${reason}`);

  // Update UI based on stop reason
  switch (reason) {
    case "user_stopped":
      showMessage(`You stopped relaying to ${meetingId}`);
      break;
    case "connection_lost":
      showMessage(`Relay to ${meetingId} ended due to connection issues`);
      break;
    default:
      showMessage(`Relay to ${meetingId} ended: ${reason}`);
  }

  // Remove from active relays in UI
  removeActiveRelayFromUI(meetingId);
});
```

### 7. Handling Relay Errors

To handle errors that may occur during relay:

```javascript
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});
liveStream.on("media-relay-error", ({ meetingId, error }) => {
  console.error(`Relay error to ${meetingId}: ${error}`);
  // Show error in UI
  showErrorNotification(`Couldn't relay to ${meetingId}: ${error}`);
});
```

## Use Cases

1.  **Guest Appearances:** Allow popular hosts to make guest appearances in other streams without leaving their audience
2.  **Cross-Stream Competitions:** Create "battles" or competitions between hosts in different streams
3.  **Multi-Location Broadcasting:** Connect hosts from different physical locations into a shared experience
4.  **Expert Commentary:** Bring in subject matter experts to comment on events in another stream

## Troubleshooting

### Common Issues

1.  **Relay Request Not Received**

    - Verify both meetings are active
    - Check that destination liveStream ID is correct
    - Ensure the token has proper permissions

2.  **Media Not Visible After Acceptance**

    - Verify network connectivity
    - Check that appropriate media kinds were specified
    - Ensure the host has enabled their camera/microphone

3.  **Unexpected Relay Termination**

    - Check for network connectivity issues
    - Verify that both meetings remain active
    - Look for error events with specific reasons

## API Reference

- [requestMediaRelay](/javascript/api/sdk-reference/meeting-class/methods#requestmediarelay)
- [stopMediaRelay](/javascript/api/sdk-reference/meeting-class/methods#stopmediarelay)
- [media-relay-request-received](/javascript/api/sdk-reference/meeting-class/events#media-relay-request-received)
- [media-relay-request-response](/javascript/api/sdk-reference/meeting-class/events#media-relay-request-response)
- [media-relay-started](/javascript/api/sdk-reference/meeting-class/events#media-relay-started)
- [media-relay-stopped](/javascript/api/sdk-reference/meeting-class/events#media-relay-stopped)
- [media-relay-error](/javascript/api/sdk-reference/meeting-class/events#media-relay-error)


---

# Release Notes - Javascript




---

# RTMP Livestream - Javascript

RTMP is a widely used protocol for live streaming video content from VideoSDK to platforms like YouTube, Twitch, Facebook, and others.

To initiate live streaming from VideoSDK to platforms supporting RTMP ingestion, you simply need to provide the platform-specific stream key and stream URL. This enables VideoSDK to connect to the platform's RTMP server and transmit the live video stream.

Furthermore, VideoSDK offers flexibility in configuring livestream layouts. You can achieve this by either selecting different prebuilt layouts in the configuration or by providing your custom template for livestreaming, catering to your specific layout preferences.

This guide will provide an overview of how to implement starting and stopping RTMP livestreaming with VideoSDK.

### `startLivestream()`

The `startLivestream()` method, is used to initiate the RTMP livestream. This method accepts the following two parameters:

- `1. outputs`: This parameter takes an array of objects containing the RTMP `url` and `streamKey` specific to the platform where you want to initiate the livestream.

- `2. config (optional)`: This parameter defines the layout configuration for the livestream.

- `3. transcription (optional)`: This parameter lets you start post transcription for the livestream.

:::important

Transcription requires recording to be enabled.

:::

```js
const config = {
  // highlight-next-line
  // Layout Configuration
  layout: {
    type: "GRID", // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
    priority: "SPEAKER", // "PIN", Default : "SPEAKER"
    gridSize: 4, // MAX : 4
  },

  // highlight-next-line
  // Theme of livestream layout
  theme: "DARK", //  "LIGHT" | "DEFAULT"

  // highlight-next-line
  // Recording Configuration
  recording = {
    enabled: true, // Enables recording of the livestream.
  };
};

const outputs = [
  {
    url: "<RTMP_URL>",
    streamKey: "<RTMP_STREAM_KEY>",
  },
];

// highlight-next-line
// Post Transcription Configuration (Transcription requires recording to be enabled.)
const transcription = {
  enabled: true, // Enables post transcription
  summary: {
    enabled: true, // Enables summary generation
    // Guides summary generation
    prompt:
      "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
  },
};

startLivestream(outputs, config, transcription);
```

### `stopLivestream()`

The `stopLivestream()` method, is used to stop the RTMP livestream.

#### Example

```js
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

const startLivestreamBtn = document.getElementById("startLivestreamBtn");
startLivestreamBtn.addEventListener("click", () => {
  // Start Livestream
  liveStream?.startLivestream(
    [
      {
        url: "rtmp://live-upload.instagram.com:80/rtmp/",
        streamKey: "key",
      },
    ],
    {
      layout: {
        type: "GRID",
        priority: "SPEAKER",
        gridSize: 4,
      },
      theme: "DARK",
    },
    {
      enabled: true,
      summary: {
        enabled: true,
        prompt:
          "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
      },
    }
  );
});

const stopLivestreamBtn = document.getElementById("stopLivestreamBtn");
stopLivestreamBtn.addEventListener("click", () => {
  // Stop Livestream
  liveStream?.stopLivestream();
});
```

### Event associated with Livestream

- **livestream-state-changed** - Whenever RTMP livestream state changes, then `livestream-state-changed` event will trigger.

```js
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

const Constants = VideoSDK.Constants;

liveStream.on("livestream-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.livestreamEvents.LIVESTREAM_STARTING) {
    console.log("RTMP livestream is starting");
  } else if (status === Constants.livestreamEvents.LIVESTREAM_STARTED) {
    console.log("RTMP livestream is started");
  } else if (status === Constants.livestreamEvents.LIVESTREAM_STOPPING) {
    console.log("RTMP livestream is stopping");
  } else if (status === Constants.livestreamEvents.LIVESTREAM_STOPPED) {
    console.log("RTMP livestream is stopped");
  } else {
    //
  }
});
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startLivestream()](/javascript/api/sdk-reference/meeting-class/methods#startlivestream)
- [stopLivestream()](/javascript/api/sdk-reference/meeting-class/methods#stoplivestream)
- [livestream-state-changed](/javascript/api/sdk-reference/meeting-class/events#livestream-state-changed)


---

# Sending Virtual Gifts - JavaScript

Virtual gifting is a powerful monetization and engagement feature that allows viewers to support hosts or speakers during a livestream by sending them digital tokens or "gifts." These gifts can be visually animated and even linked to leaderboards or reward systems.

This guide explains how to implement a secure and real-time virtual gifting experience using your backend server in combination with VideoSDK PubSub.

### How It Works

1. User Action: A viewer taps on a gift button to send a virtual gift to the host.

2. Server Verification:

   - A request is made to your business backend to process the gift.
   - The server authenticates the user, checks their wallet balance, deducts the gift value, and returns a success response.

3. Event Broadcast: Upon success, the client publishes a PubSub message to inform everyone in the live stream (host + other viewers) that a gift has been sent. Clients can then visually show an animation or notification.

### Backend Responsibility

Your backend plays a central role in verifying, validating, and processing gift transactions. It should:

- Authenticate the request (token/session)
- Verify if the user has sufficient balance
- Deduct the gift cost
- Store the transaction in a database (optional but recommended)
- Respond with success or failure

### Frontend Implementation

- Sending a Gift (Client to Backend + PubSub)

```js

const sendGift = async (giftType) => {
  try {
    const response = await axios.post("https://your-api.com/send-gift", {
      senderId: "<Sender ID>",
      hostId : "<HOST ID>",
      giftType,
    });

    if (response.data.success) {
      // Notify everyone in the live stream
      liveStream?.pubSub.publish("GIFT", {
        giftType,
        from: senderId,
        to: hostId,
      });
    } else {
      alert("Gift could not be sent: " + response.data.message);
    }
  } catch (error) {
    console.error("Error while sending gift:", error);
  }
};

// Create buttons dynamically (example for browser environment)
const roseButton = document.createElement("button");
roseButton.innerText = "🌹 Send Rose";
roseButton.onclick = () => sendGift("rose");

const diamondButton = document.createElement("button");
diamondButton.innerText = "💎 Send Diamond";
diamondButton.onclick = () => sendGift("diamond");

// Append buttons to the DOM
document.body.appendChild(roseButton);
document.body.appendChild(diamondButton);
```

- Displaying the Gift (All Clients)

```js
const gifts = [];

const giftContainer = document.createElement("div");
giftContainer.className = "gift-container";
document.body.appendChild(giftContainer);

const handleGiftMessage = ({ message }) => {
  const gift = {
    id: Date.now(),
    from: message.from,
    to: message.to,
    type: message.giftType,
  };

  gifts.push(gift);

  const toast = document.createElement("div");
  toast.className = "gift-toast";
  toast.innerText = `🎁 ${gift.from} sent a ${gift.type} to ${gift.to}`;
  giftContainer.appendChild(toast);

  // Optionally auto-remove the toast after a few seconds
  setTimeout(() => {
    giftContainer.removeChild(toast);
  }, 5000);
};

liveStream?.pubSub.subscribe("GIFT", handleGiftMessage);
```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [pubsub](/javascript/api/sdk-reference/meeting-class/pubsub)


---

# Initialize Live Stream - JavaScript

To configure livestreaming with VideoSDK you require two things, first the `token` which will be used for **Authentication** purpose and a `streamId` which will be used to specify where the hosts and audience will join.

### Generating Token

You can generate a `token` in two ways:

1. **`Temporary Token`** : You can visit [Dashboard's API Key section](https://app.videosdk.live/api-keys) and generate a temporary token from there.

2. **`Server`** : You can setup **JWT** in backend and make an API call to get the token from your server.

To learn more about **Authentication** and token in detail you can follow [this guide](/javascript/guide/video-and-audio-calling-api-sdk/authentication-and-token).

```js
// With Temporary Token
const getToken = async () => {
  // Update the token here from the VideoSDK dashboard
  // highlight-next-line
  let token = "YOUR_TOKEN";
};

// Server
const getToken = async () => {
  // highlight-start
  const response = await fetch(`http://localhost:3000/get-token`, {
    method: "GET",
    headers: {
      Accept: "application/json",
      "Content-Type": "application/json",
    },
  });
  const { token } = await response.json();
  // highlight-end
  return token;
};
```

### Generating Stream Id

With the token ready, you can now get the `streamId` from the [VideoSDK's rooms API](/api-reference/realtime-communication/create-room).

```js
const getStreamId = async (token) => {
  try {
    //Use VideoSDK rooms API endpoint to create a streamId
    //highlight-next-line
    const VIDEOSDK_API_ENDPOINT = `https://api.videosdk.live/v2/rooms`;
    const options = {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        // Pass the token in the headers
        // highlight-next-line
        Authorization: token,
      },
    };
    const streamId = await fetch(VIDEOSDK_API_ENDPOINT, options)
      .then(async (result) => {
        const { roomId } = await result.json();
        return roomId;
      })
      .catch((error) => console.log("error", error));

    //Return the streamId received from the response of the api
    //highlight-next-line
    return streamId;
  } catch (e) {
    console.log(e);
  }
};
```

### Initialization of Live Stream

You can initialize the live stream using the `initMeeting` method of the `VideoSDK` class. The `initMeeting` is responsible for initializing the live stream with the provided configuration, which includes the `token`, `meetingId`, `participantId` and many more.

```js
VideoSDK.config(token);
const liveStream = VideoSDK.initMeeting({
  meetingId: "<streamId>",
  mode: "SEND_AND_RECV", // "SEND_AND_RECV" for hosts/co-hosts, "RECV_ONLY" for audience
  name: "<Participant Name>",
  micEnabled: true, // Ignored for audience
  webcamEnabled: true, // Ignored for audience
  participantId: "<Unique Participant ID>", // Optional
  multistream: true, // Ignored for audience
});
```

- **`meetingId`** :

  - This is a unique identifier that allows participants to join a specific live stream.
  - It will be in the format of `xxx-yyy-zzz` and will be generated using the [VideoSDK's Room API](/api-reference/realtime-communication/create-room).

- **`mode`** :

  - This paramter defines the mode the participant will enter the live stream with.
  - `SEND_AND_RECV`: For hosts/co-hosts who can send and receive media.
  - `RECV_ONLY`: For audience members who can only receive media.​

- **`name`**:

  - This represents the name of the participant in the live streams.
  - It will accept `String` type value.

- **`micEnabled`**:

  - This is a `boolean` flag, indicating whether a participant's microphone will be automatically enabled when they join the live stream. This property will be completely ignored for Audience participants, as they are not allowed to publish their audio.

- **`webcamEnabled`**:

  - This is a `boolean` flag, indicating whether a participant's webcam will be automatically enabled when they join the live stream. This property will be completely ignored for Audience participants, as they are not allowed to publish their video.

- **`metaData`**:

  - If you want to provide additional details about the participants joining the live stream, such as their profile image, you can pass that information in this parameter.
  - It has to be of `Object` type.
  - This is an `OPTIONAL` parameter.

- **`participantId`**:

  - This is a unique identifier for the participant's inside the live stream.

    - It can be used to specify the **unique identifier** which can be linked with **your own database** service.
    - It has to be of `String` type.
    - This is an `OPTIONAL` parameter. By default VideoSDK will generate unique id for each participant.

- **`multistream`**:

  - This is a `boolean` flag, indicating whether the host's media stream should send multiple resolution layers or a single resolution layer.

:::caution
You must ensure that the `participantId` is not repeated in the same livestream. This will enable VideoSDK to eliminate any participant associated with that `participantId`.
:::

To know more about other properties, you can follow [our API Reference](/javascript/api/sdk-reference/initMeeting).

```js
// imports

const getToken = async () => {
  //highlight-next-line
  ...
};
const getStreamId = async () => {
  //highlight-next-line
  ...
};

async function startLiveStream() {
  const token = await getToken();
  const streamId = await getStreamId();

  // Configure authentication token
  VideoSDK.config(token);

  // Initialise meeting
  liveStream = VideoSDK.initMeeting({
    meetingId: meetingId,
    name: "YOUR_NAME",
    micEnabled: true,
    webcamEnabled: true,
  });
}

```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Meeting Class](/javascript/api/sdk-reference/meeting-class/introduction)



---

# Join Live Stream - JavaScript

Once, the live stream is configured, the next step is to join it. With our JS SDK, you can call the `join()` method. If you have not initialized the live stream yet, you can [follow the guide here.](/javascript/guide/interactive-live-streaming/setup-livestream/initialize-livestream)

### `join()`

- To join the live stream you can call the `join()` method wmethod on the created `liveStream` object.
- This method can be invoked after the ive stream is initialized using the `initMeeting` method.

### Events associated with the join() method

Following events are received when a participant successfully joins the livestream.

- The [Local Participant](/javascript/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive the [`meeting-joined`](/javascript/api/sdk-reference/meeting-class/events#meeting-joined) event, when the live stream is successfully joined.
- All the [Remote Participants](/javascript/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant)—including all the hosts and audience members—will receive the [`participant-joined`](/javascript/api/sdk-reference/meeting-class/events#participant-joined) event with the newly joined `Participant` object from the event callback.

```js
let liveStream;

// Initialize Meeting
liveStream = VideoSDK.initMeeting({
  // ...
});

const joinBtn = document.getElementById("joinBtn");

joinBtn.addEventListener("click", () => {
  // Joining Meeting
  liveStream?.join();
});

liveStream.on("meeting-joined", () => {
  console.log("liveStream Joined Successfully");
});

liveStream.on("participant-joined", (participant) => {
  console.log("New Participant Joined: ", participant.id);
});
```

### `leave()`

- To leave the live stream you can call the `leave()` method on the created `liveStream` object.

:::note
This method can be called only after the live stream is joined successfully.
:::

### Events associated with the leave() method

Following callbacks are received when a participant leaves the live stream.

- The [Local Participant](/react/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant) will receive the [`meeting-left`](/javascript/api/sdk-reference/meeting-class/events#meeting-left) event, once they have successfully left the livestream.
- All the [Remote Participants](/react/guide/video-and-audio-calling-api-sdk/concept-and-architecture#2-participant)—including all the hosts and audience members—will receive the [`participant-left`](/javascript/api/sdk-reference/meeting-class/events#participant-left) event with the `Participant` object of the user who left the livestream.

```js
let liveStream;

// Initialize Meeting
liveStream = VideoSDK.initMeeting({
  // ...
});

const leaveBtn = document.getElementById("leaveBtn");

leaveBtn.addEventListener("click", () => {
  liveStream?.leave();
});

liveStream.on("meeting-left", () => {
  console.log("liveStream left Successfully");
});

liveStream.on("participant-left", (participant) => {
  console.log("Participant left: ", participant.id);
});
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [join()](/javascript/api/sdk-reference/meeting-class/methods#join)
- [meeting-joined event](/javascript/api/sdk-reference/meeting-class/events#meeting-joined)
- [participant-joined event](/javascript/api/sdk-reference/meeting-class/events#participant-joined)
- [leave()](/javascript/api/sdk-reference/meeting-class/methods#leave)
- [meeting-left event](/javascript/api/sdk-reference/meeting-class/events#meeting-left)
- [participant-left event](/javascript/api/sdk-reference/meeting-class/events#participant-left)


---

# Waiting Screen - JavaScript

To create a smoother and more polished entry experience for audience members, it's important not to immediately render the meeting room when they join. Instead, show a waiting screen until at least one host is present in the room.

### Why This Matters?

- Hosts are typically responsible for driving the meeting, and their presence is essential before audience members should be able to view or interact in the room.

- Allowing audience members (in `RECV_ONLY` mode) to enter a meeting with no active hosts (in `SEND_AND_RECV` mode) can result in confusion and a poor user experience.

### Participant Modes

- Hosts must join the meeting with the `SEND_AND_RECV` mode.
- Audience members should join with the `RECV_ONLY` mode.

### Implementation Guide

You can achieve this behavior by using the participants list and onParticipantJoined event from the useMeeting hook.

1. Check if a Host is Present
   On initial render, use the participants object to determine if there's already a host in the room:

```js
const participants = liveStream.participants;

const hasHost = Array.from(participants.values()).some(
  (participant) => participant.mode === "SEND_AND_RECV"
);
```

If hasHost is true, render the meeting view. Otherwise, show the waiting screen.

2. Listen for Host Join
   Always listen for the onParticipantJoined event in case a host joins after the audience participant:

```js
meeting.on("participant-joined", (participant) => {
  if (participant.mode === "SEND_AND_RECV") {
    // Update your state to show the meeting view
  }
});
```

This ensures that as soon as a host joins, the waiting audience members are transitioned smoothly into the meeting view.

![Waiting Screen](/img/ils/waiting-screen.png)


---

# Supported Browsers

:::note
The following browser versions represent the minimum required versions to ensure full support for the listed features.
:::





---

# Switch Live Stream - JavaScript

## Overview

The **Switch Live Stream** feature enables users to **seamlessly transition** between live streams without needing to manually disconnect and reconnect. This drastically improves user experience by reducing latency and preserving media and socket connections.

### Previously

1.  Users had to **disconnect** from the current liveStream.
2.  Then **manually connect** to a new liveStream:
    - New socket connection created.
    - New media transports initialized.
    - Delays due to re-connection and media setup.

This led to:

- **Higher latency**
- **Socket transport downtime**
- **Poor experience** for users switching frequently between rooms

### New Behavior with `switchTo`

- Keeps the existing **socket connection** alive
- Reuses or reconfigures existing **media**
- Switches the server-side context to the **new liveStream**

### `switchTo()`

#### **Parameters**

- **meetingId** (`string`, required): ID of the new liveStream to join
- **token** (`string`, optional): VideoSDK token for authentication

```javascript
let liveStream;
let liveStreamId = "abcd-pqrs-xyzw";

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});
liveStream.switchTo({ meetingId: liveStreamId, token });
```

## Important Considerations

### Meeting Status

- **The destination liveStream must be active** before attempting to switch.
- If the destination liveStream is inactive or doesn't exist, the switch will fail.

### Token Management

- **Token Expiry**: Be careful with short-lived tokens when using the switch feature.
  - If you're using short-lived tokens for security reasons, always provide a new token in the `switchTo` method.
  - Tokens that expire during a liveStream can cause unexpected disconnections.
- **Best Practice**: For frequent switches, use tokens with reasonable expiry times or implement a token refresh mechanism.

## API Reference

- [switchTo](/javascript/api/sdk-reference/meeting-class/methods#switchto)


---

# Virtual Background - Javascript

Virtual backgrounds enhance the Live Stream experience by enabling participants to replace their physical background with a digital image or video. This feature offers several benefits, including maintaining privacy, reducing visual distractions, and adding an element of creativity or fun to the liveStream. Users can choose from preloaded images or upload their own backgrounds.

![virtual-background](/img/virtual-background.png)

### Install VideoSDK Media Processor package

**npm:**

```js
npm install --save "@videosdk.live/videosdk-media-processor-web"
```

---

**yarn:**

```js
yarn add "@videosdk.live/videosdk-media-processor-web"
```

### Instantiate Virtual Background Processor

After installing the library, initialize an instance of the `VirtualBackgroundProcessor`. 

```js
// Import package

let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

// Instantiate VirtualBackgroundProcessor Class
const videoProcessor = new VirtualBackgroundProcessor();
```

### Using Virtual Background

Utilize the processor by first initializing it, then start processing a stream, and finally, pass the processed video stream to VideoSDK.

#### Initializing

The first step is to initialize the virtual background processor if it's not already prepared.

```js
// Import package

let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

// Instantiate VirtualBackgroundProcessor Class
const videoProcessor = new VirtualBackgroundProcessor();

const StartVirtualBackgroundBtn = document.getElementById(
  "StartVirtualBackgroundBtn"
);
StartVirtualBackgroundBtn.addEventListener("click", async () => {
  //highlight-start
  // Initialize processor if not ready
  if (!videoProcessor.ready) {
    await videoProcessor.init();
  }
  //highlight-end
});
```

### Starting the Processor

To initiate the processing of a video stream, you need to provide a `MediaStream` that you want to process and a `config` to be used for processing. Once these parameters are passed to the processor, it will return a `MediaStream`.

1. **MediaStream** : [MediaStream](https://developer.mozilla.org/en-US/docs/Web/API/MediaStream) is essentially a video stream captured from the camera. You can use the `createCameraVideoTrack` method to generate a `MediaStream`.
2. **config** : This object accepts `type` and `imageUrl` property. `type` property accepts filter type `image` or `blur`. `imageUrl` is the path of the image and it will be ignored on `blur` filter type.

   **NOTE** : If you intend to display a specific background image, make sure it is uploaded on a CDN.

```js
// Import package

let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

// Instantiate VirtualBackgroundProcessor Class
const videoProcessor = new VirtualBackgroundProcessor();

const StartVirtualBackgroundBtn = document.getElementById(
  "StartVirtualBackgroundBtn"
);
StartVirtualBackgroundBtn.addEventListener("click", async () => {
  // Initialize processor if not ready
  if (!videoProcessor.ready) {
    await videoProcessor.init();
  }

  //highlight-start
  // Configuration for starting processor
  const config = {
    type: "image", // "blur"
    imageUrl: "https://cdn.videosdk.live/virtual-background/cloud.jpeg",
    // Here is a list of background images you can use for your project.
    // imageUrl: "https://cdn.videosdk.live/virtual-background/beach.jpeg",
    // imageUrl: "https://cdn.videosdk.live/virtual-background/san-fran.jpeg",
    // imageUrl: "https://cdn.videosdk.live/virtual-background/paper-wall.jpeg",
  };

  // Getting stream from webcam
  const stream = await VideoSDK.createCameraVideoTrack({});
  const processedStream = await videoProcessor.start(stream, config);
  //highlight-end
});
```

### Passing Processed Stream to VideoSDK

Once you have the processed stream, you can pass it to functions like `enableWebcam()` or `changeWebcam()` to apply the virtual background effect during your liveStream.

```js
// Import package

let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

// Instantiate VirtualBackgroundProcessor Class
const videoProcessor = new VirtualBackgroundProcessor();

const StartVirtualBackgroundBtn = document.getElementById(
  "StartVirtualBackgroundBtn"
);
StartVirtualBackgroundBtn.addEventListener("click", async () => {
  // Initialize processor if not ready
  if (!videoProcessor.ready) {
    await videoProcessor.init();
  }

  // Configuration for starting processor
  const config = {
    type: "image", // "blur"
    imageUrl: "https://cdn.videosdk.live/virtual-background/cloud.jpeg",
    // Here is a list of background images you can use for your project.
    // imageUrl: "https://cdn.videosdk.live/virtual-background/beach.jpeg",
    // imageUrl: "https://cdn.videosdk.live/virtual-background/san-fran.jpeg",
    // imageUrl: "https://cdn.videosdk.live/virtual-background/paper-wall.jpeg",
  };

  // Getting stream from webcam
  const stream = await VideoSDK.createCameraVideoTrack({});
  const processedStream = await videoProcessor.start(stream, config);

  //highlight-start
  liveStream?.changeWebcam(processedStream);
  //highlight-end
});
```

### Updating Video Processor Configuration

If you want to change the background while the Video Processor is running, you can call the `updateProcessorConfig` method to modify the filters or processing type. 

```js
// Import package

let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

// Instantiate VirtualBackgroundProcessor Class
const videoProcessor = new VirtualBackgroundProcessor();

const updateVirtualBackgroundBtn = document.getElementById(
  "updateVirtualBackgroundBtn"
);
updateVirtualBackgroundBtn.addEventListener("click", async () => {
  //highlight-start
  const config = {
    type: "image", // "blur"
    imageUrl: "https://cdn.videosdk.live/virtual-background/cloud.jpeg",
  };

  videoProcessor.updateProcessorConfig(config);
  //highlight-end
});
```

### Stopping Virtual Background Processor

Additionally, you can use the `stop()` method on the processor to halt the background processing and replace the video stream with a new plain video stream.

```js
// Import package

let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

// Instantiate VirtualBackgroundProcessor Class
const videoProcessor = new VirtualBackgroundProcessor();

const stopVirtualBackgroundBtn = document.getElementById(
  "stopVirtualBackgroundBtn"
);
stopVirtualBackgroundBtn.addEventListener("click", async () => {
  //highlight-start
  videoProcessor.stop();

  // Pass webcam MediaStream in VideoSDK `changeWebcam` method
  const stream = await VideoSDK.createCameraVideoTrack({});
  liveStream?.changeWebcam(stream);
  //highlight-end
});
```

### Extras

You can also pass the processed stream during initialization of the liveStream.

```js
// Import package

const videoProcessor = new VirtualBackgroundProcessor();

const stream = await VideoSDK.createCameraVideoTrack({});
if (!videoProcessor.ready) {
  await videoProcessor.init();
}
const processedStream = await videoProcessor.start(stream, {
  type: "image", // "blur"
  imageUrl: `https://cdn.videosdk.live/virtual-background/cloud.jpeg`,
});

let liveStream;
liveStream = VideoSDK.initMeeting({
  meetingId: "liveStreamId",
  micEnabled: true,
  webcamEnabled: true,
  name: "TestUser",
  customCameraVideoTrack: processedStream, // Pass processed MediaStream in VideoSDK
});
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [enableWebcam()](/javascript/api/sdk-reference/meeting-class/methods#enablewebcam)
- [disableWebcam()](/javascript/api/sdk-reference/meeting-class/methods#disablewebcam)


---



---

# Overview of SIP with VideoSDK - Javascript




SIP (Session Initiation Protocol) is extensively employed for setting up and controlling IP-based calls. It facilitates the initiation and termination of user sessions over IP networks, enabling SIP-based systems to connect and exchange voice communications over the internet.

With VideoSDK's SIP Connect feature, you can enable your users to join VideoSDK meetings via VOIP using third-party service providers. This allows for establishing a bridge between participants using our client SDKs and those joining via SIP, enhancing the accessibility and connectivity of your video meetings.

![SIP Architecture](https://cdn.videosdk.live/website-resources/docs-resources/sip-architechture.png)

### Getting SIP Credentials

To use SIP Connect, you will first need to generate the credentials for the SIP. Go to the [VideoSDK dashboard](https://app.videosdk.live) and under the [API Keys](https://app.videosdk.live/api-keys) sections, first enable the SIP for the desired API key after which you will be presented with the SIP `username` and `password` you can use to establish connection with our SIP servers.

![SIP Credentials](https://cdn.videosdk.live/website-resources/docs-resources/sip-get-credentials.gif)

### How to use SIP to join a particular meeting?

Once you have the credentials, you can use any of the softphones like Linphone, Zoiper etc. or use a third party service provider like twilio to connect with a VideoSDK meeting by initiating a SIP call to `sip:<meeting-id>@sip.videosdk.live`

For example if you want to connect to `abcd-abcd-abcd` meeting then the SIP address will look like `sip:abcd-abcd-abcd@sip.videosdk.live`

### Example of Twilio PSTN

To utilize third-party PSTN (Public Switched Telephone Network) providers like Twilio for making calls via SIP (Session Initiation Protocol), follow these steps:

1. Log in to your Twilio account and navigate to the Phone Numbers section.
2. Purchase a phone number and access its configuration settings.
3. Set up a Webhook handler that will initiate a call to the VideoSDK SIP endpoint whenever an incoming call is received on the selected phone number.

![SIP Configuration for Twilio](https://cdn.videosdk.live/website-resources/docs-resources/sip-twilio-config.png)

##### Example for creating Webhook using Express

```js
const express = require("express");
const VoiceResponse = require("twilio").twiml.VoiceResponse;
const urlencoded = require("body-parser").urlencoded;

const app = express();

// Parse incoming POST params with Express middleware
app.use(urlencoded({ extended: false }));

// Webhook route which will be called by twilio when a call is received
app.post("/incoming-call-handler", (request, response) => {
  console.log({ request });
  // Use the Twilio Node.js SDK to build an XML response
  const twiml = new VoiceResponse();

  const dial = twiml.dial();
  dial.sip(
    {
      username: "<User name generated for dashboard>",
      password: "<Password generated from dashboard>",
    },
    "sip:<meetingId>@sip.videosdk.live"
  );

  // Render the response as XML in reply to the webhook request
  response.type("text/xml");
  response.send(twiml.toString());
});

//Start the express app on port 8000
app.listen(8000, () => {
  console.log(`Server listening on port ${8000}.`);
});
```



---

# Build a SIP Integration: VideoSDK & Twilio for Inbound Outbound Calls! Step-by-Step


Imagine joining an online meeting using just your phone—no apps, no browsers, no internet. This powerful option allows participants to connect via traditional telephony, by creating a bridge between phone systems and modern video conferencing platforms. In this post, we’ll explore how to build a SIP integration using VideoSDK and Twilio for both inbound and outbound VoIP calls.



We’ll break down the flow of calls, set up the project, and show you how to bring this functionality to life using Next.js.

## What Is a SIP Integration?

SIP, or Session Initiation Protocol, enables voice and video communications over internet-based networks. With SIP integrations, traditional phone systems can connect to online platforms .

By integrating SIP with VideoSDK’s SIP address and Twilio, you can handle both inbound and outbound calls while linking them to video meetings. This integration is particularly helpful for situations where participants lack internet access, allowing them to simply dial in to join a meeting or receive phone calls initiated by meeting participants.

## Understanding Inbound and Outbound Call Flows

### Inbound Calls

![Inboud Call Flow](https://assets.videosdk.live/images/inbound.png)

Inbound calls are initiated by a user or customer dialing a phone number, such as a Twilio-provisioned number. Here’s how the process works:

1. **User Dialing**: A participant dials the Twilio number tied to the SIP integration.
2. **Call Routing**: Twilio receives the call and notifies your server with call details.
3. **Server Processing**: Your server processes the request and sends an invite SIP request to the VideoSDK SIP address.
4. **Connection Established**: Once validated, the caller is connected to the specific video meeting through VideoSDK.

For example, if a customer wants to join a video conference using their phone, they can call a designated number. Following this process, the integration connects them to the meeting.

### Outbound Calls

![Outbound Call Flow](https://assets.videosdk.live/images/outbound.png)

Outbound calls begin with a participant or agent in an online meeting initiating a call to a customer’s phone. The process involves the following steps:

1. **Call Request Initiated**: A participant requests your server to call a specific phone number.
2. **Server Action**: The server notifies Twilio to establish the call.
3. **User Accepts Call**: When the user accepts, the connection is forwarded to the video meeting through VideoSDK.

This two-way communication ensures smooth interaction between online participants and phone users.

## Step-by-Step Guide to Setting Up the Project

### Prepare the Project Files

1. Create a workspace for the SIP integration project (or open your existing project if you already have one).

```bash
mkdir videosdk-sip-integration && cd videosdk-sip-integration
```

1. Navigate to project directory

```javascript
cd videosdk-sip-integration
```

1. Install dependencies that are required for you application to work

```javascript
npm install
```

### Configure the Environment

1. **Set Up the `.env` File**: Copy the `.env.example` file in the repository and rename it to `.env`.
2. **Add VideoSDK Details**: Obtain the SIP username, password, and authentication token from the [VideoSDK dashboard](https://app.videosdk.live/).
   - Generate an authentication token under “API Keys.”
   - Get your SIP username and password from the “SIP Config” section.
   - Add these details to the `.env` file.
3. **Configure Twilio**: Sign in to your [Twilio console](https://console.twilio.com/).
   - Copy your Twilio phone number, Account SID, and Auth Token.
   - Paste these values into the `.env` file.

```javascript
TWILIO_ACCOUNT_SID=your-twilio-account-sid
TWILIO_AUTH_TOKEN=your-twilio-auth-token
VIDEOSDK_SIP_USERNAME=your-videosdk-sip-username
VIDEOSDK_SIP_PASSWORD=your-videosdk-sip-password
NEXT_PUBLIC_TWILIO_PHONE_NUMBER=your-twilio-phone-number
NEXT_APP_URL=http://localhost:3000 # Replace with your production URL
```

Your `.env` file should now contain all necessary credentials.

### Running the Application

Once the configurations are complete, start the project using the following command:

```bash
npm run dev
```

![demo home page](https://assets.videosdk.live/images/demo.png)

The application will run locally on port 3000.



## Setting Up Call Routing

### Inbound Call Setup

**Define the API URL**: In Twilio’s Active Numbers section, specify your API endpoint (e.g., `/api/webhook/inbound`). Twilio will send incoming call details to this URL.

If hosting locally, tools like `ngrok` or `pinggy` can expose your server to the internet for testing purposes. Replace the localhost URL with the public domain generated by these tools in the Twilio configuration.

![Twilio Dashboard](https://assets.videosdk.live/images/twilio-dashboard.png)

**Handle Calls with VideoSDK**: Once Twilio routes the call, your code forwards the meeting ID to VideoSDK’s SIP address. This connects the caller to the online meeting.

```javascript

// Environment variables
const accountSid = process.env.TWILIO_ACCOUNT_SID || "";
const authToken = process.env.TWILIO_AUTH_TOKEN || "";
const videosdkSipUsername = process.env.VIDEOSDK_SIP_USERNAME || "";
const videosdkSipPassword = process.env.VIDEOSDK_SIP_PASSWORD || "";

const client = twilio(accountSid, authToken);

export async function POST(request: Request): Promise<Response> {
  try {
    const url = new URL(request.url);
    const meetingId = url.searchParams.get("meetingId");

    const twiml = new twilio.twiml.VoiceResponse();
    twiml.say("Welcome to the Video sdk conference. Connecting you now.");
    twiml.dial().sip(
      {
        username: videosdkSipUsername,
        password: videosdkSipPassword,
      },
      `sip:${meetingId}@sip.videosdk.live`
    );

    return new Response(twiml.toString(), {
      headers: {
        "Content-Type": "text/xml",
      },
    });
  } catch (error) {
    console.error("Error processing Twilio webhook:", error);

    // Return TwiML error response
    const twiml = new twilio.twiml.VoiceResponse();
    twiml.say("Sorry, there was an error connecting your call.");

    return new Response(twiml.toString(), {
      headers: {
        "Content-Type": "text/xml",
      },
    });
  }
}
```

### Outbound Call Setup

For outbound calls, the meeting participant in the web app interacts with an API endpoint that sends a request to Twilio. Twilio establishes the call with the provided number, connecting the phone user back to the meeting through VideoSDK.

```javascript

// Environment variables
const accountSid = process.env.TWILIO_ACCOUNT_SID || "";
const authToken = process.env.TWILIO_AUTH_TOKEN || "";
const twilioPhoneNumber = process.env.NEXT_PUBLIC_TWILIO_PHONE_NUMBER || "";

const client = twilio(accountSid, authToken);

export const dynamic = "force-dynamic";

export async function POST(request: Request): Promise<Response> {
  try {
    const { phoneNumber, meetingId } = await request.json();

    if (!phoneNumber) {
      throw new Error("phone number is required!");
    }

    // Make the outbound call
    const call = await client.calls.create({
      to: phoneNumber,
      from: twilioPhoneNumber,
      url: `${process.env.NEXT_APP_URL}/api/webhook/inbound?meetingId=${meetingId}`,
      method: "POST",
    });

    return new Response(JSON.stringify({ success: true, callSid: call.sid }), {
      headers: {
        "Content-Type": "application/json",
      },
    });
  } catch (error) {
    console.error("Error making outbound call:", error);

    return new Response(
      JSON.stringify({
        success: false,
        error: "Failed to initiate call",
      }),
      {
        status: 500,
        headers: {
          "Content-Type": "application/json",
        },
      }
    );
  }
}
```

**Create an Outbound API**: Write an API function to trigger calls using Twilio’s client instancee.g., `/api/webhook/outbound`)

**Trigger Outbound Calls**: Use this API in your application to handle requests for dialing specific numbers.

When the call is accepted, the system routes it to the VideoSDK SIP address, establishing a connection to the meeting.

## Testing the Integration

To test the setup:

1. Make a call to the Twilio number for inbound calls.
   - Ensure the meeting ID and SIP configurations are correctly passed.
2. Initiate an outbound call from a meeting participant to a phone number.
   - Validate that the phone user is successfully connected to the meeting.

Both inbound and outbound calls should work smoothly, demonstrating the bridged connection between telephony and video conferencing.

## Conclusion

Integrating SIP functionality into your project using VideoSDK and Twilio unlocks new possibilities for communication. By enabling inbound and outbound VoIP calls, you can connect traditional phone systems with modern video conferencing platforms.

This guide covered the basics of setting up the integration, routing calls, and ensuring smooth connectivity. If you encounter any issues or need further help, join the VideoSDK Discord community.

Simplify your users’ communication experience—embrace the power of SIP integration.



---

# Quick Start for Conference in Angular 2

VideoSDK empowers you to seamlessly integrate the video calling feature into your Angular 2 application within minutes.

In this quickstart, you'll explore the group calling feature of VideoSDK. Follow the step-by-step guide to integrate it within your application.

## Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

- Video SDK Developer Account (Not having one, follow **[Video SDK Dashboard](https://app.videosdk.live/)**)
- Have Node and NPM installed on your device.

:::important

One should have a VideoSDK account to generate token.
Visit VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate token

:::

## Getting Started with the Code!

Follow the steps to create the environment necessary to add video calls into your app. You can also find the code sample for [quickstart here](https://github.com/videosdk-live/quickstart/tree/main/angular-rtc/videosdk_angular_2_quickstart).

### Install Video SDK

Import VideoSDK using the `<script>` tag or Install it using the following npm command. Make sure you are in your app directory before you run this command.



**Tab:**

" label="<script>" default>

```html
<html>
  <head>
....
  </head>
  <body>
.....
<script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
  </body>
</html>
```

---

**npm:**

```bash
npm install @videosdk.live/js-sdk
```

---

**yarn:**

```bash
yarn add @videosdk.live/js-sdk
```

## Structure of the project

Your project structure should look like this.

```jsx title="Project Structure"
  root
   ├── node_modules
   ├── src
   │    ├── app
   │        ├── join-screen
   │             ├── join-screen.component.html
   │             ├── join-screen.component.ts
   │         ├── top-bar
   │             ├── top-bar.component.html
   │             ├── top-bar.component.ts
   │    ├── app-routing.module.ts // Default
   │    ├── app.component.html // Default
   │    ├── app.component.ts // Default
   │    ├── app.module.ts // Default
   │    ├── meeting.service.ts
   │    ├── enviroments
   │        ├── enviroment.ts
   │    ├── styles.css // Default
   │    ├── index.html // Default
```

You will be working on the following files:

- enviroment.ts: Responsible for storing the token.
- meeting.service.ts: Responsible for handling API calls such as generating a unique meetingId, validating a meetingId and a token.
- join-screen.component.html: Responsible for creating a basic UI for the joinScreen functionality.
- top-bar.component.html: Responsible for creating a basic topbar with webcam, mic and leave meeting buttons.
- app.component.html: Responsible for rendering components such as `Joinscreen`, `Topbar` and `ParticipantGrid`.
- join-screen.component.ts: Responsible for handling the logic and functionality related to the `join-screen.component.html` template.
- top-bar.component.ts : Responsible for handling the logic and functionality related to the `top-bar.component.html` template.
- app.component.ts: Handles various meeting and participant-related events, including `joinMeeting` and `createMeeting`. Additionally, responsible for rendering components such as `join-screen`, `top-bar`, and `participantGrid`.

### Step 1: Get started with Meeting.service.ts

Prior to moving on, you must create an API request to generate a unique meetingId. You will need an authentication token, which you can create either through the [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples) or directly from the [VideoSDK Dashboard](https://app.videosdk.live/api-keys) for developers.

Configure the token in the `enviroment.ts` file, which you can obtain from the [VideoSDK Dashbord](https://app.videosdk.live/login).

```js title="enviroment.ts"
// We will use Auth token to generate a meetingId and connect to it
export const environment = {
  token: "YOUR_TOKEN_HERE",
};
```

```js title="meeting.service.ts"





@Injectable({
  providedIn: "root",
})
export class MeetingService {
  private authToken = environment.token;

  constructor(private http: HttpClient) {}

  createMeeting(): Observable<string> {
    const apiUrl = "https://api.videosdk.live/v2/rooms";
    const headers = new HttpHeaders({
      authorization: this.authToken,
      "Content-Type": "application/json",
    });

    return this.http
      .post<{ roomId: string }>(apiUrl, {}, { headers })
      .pipe(map((response) => response.roomId));
  }

  validateMeeting(meetingId: string): Observable<boolean> {
    const url = `https://api.videosdk.live/v2/rooms/validate/${meetingId}`;
    const headers = new HttpHeaders({
      authorization: this.authToken,
      "Content-Type": "application/json",
    });

    return this.http
      .get<{ roomId: string }>(url, {
        headers,
      })
      .pipe(map((response) => response.roomId === meetingId));
  }

  ngOnInit() {}
}
```

- Once the meeting service is successfully created, import it into the `app.module.ts` file.

```js title="app.module.ts"









@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  declarations: [AppComponent, JoinScreenComponent, TopBarComponent],
  imports: [BrowserModule, AppRoutingModule, HttpClientModule, FormsModule],
  //highlight-next-line
  providers: [MeetingService],
  bootstrap: [AppComponent],
})
export class AppModule {}
```


### Step 2: Design the user interface (UI)

Create an HTML file that will render the `join-screen` and `top-bar` components.

- First, Create the UI for the `joinScreen` functionality..

```html title="joinScreen.html"
<div id="joinPage" class="main-bg" style="display: flex">
  <div style="display: flex; flex-direction: column">
    <h3>Angular 2 quickstart with Videosdk</h3>
    <form name="myForm" style="display: flex">
      <button (click)="fireCreateMeeting()">Create a meeting</button>
      <p
        style="
          margin-left: 8px;
          margin-right: 8px;
          font-size: 14px;
          margin-top: 2px;
          margin-bottom: 0px;
        "
      >
        OR
      </p>
      <input
        name="meetingId"
        type="text"
        placeholder="Enter meeting id"
        [(ngModel)]="meetingId"
      />

      <button (click)="fireValidateMeeting()" style="margin-left: 8px">
        Join a meeting
      </button>
    </form>
  </div>
</div>
```

#### Output

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/angular/angular2-joinscreen.png' />

</center>

- Next, Create the `topBar` UI.

```html title="topBar.html"
<div
  style="height: 70px; background-color: lightgray"
  ng-controller="myController"
  ng-show="showMeetingScreen"
  id="top-bar"
>
  <div class="top-bar-div">
    <div>
      <p style="margin-top: 0px; margin-bottom: 0px; font-weight: 700">
        MeetingId: {{meetingId}}
      </p>
    </div>
    <div style="display: flex; align-items: center; margin-top: 8px">
      <button style="cursor: pointer" ng-click="toggleWebcam()">
        Toggle Webcam
      </button>
      <button style="margin-left: 4px; cursor: pointer" ng-click="toggleMic()">
        Toggle Mic
      </button>
      <button class="leave-btn" ng-click="leaveMeeting()">Leave Meeting</button>
    </div>
  </div>
</div>
```

#### Output

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/angular/angular2-topbar.png' />

</center>

<br/>

- Finally, assemble the components by creating the `app.component.html` file and incorporating the previously created components into it. Additionally, create the `meeting-container` here.

```html title="app.component.html"
<div *ngIf="showJoinScreen">
  
  // highlight-next-line
  <app-join-screen></app-join-screen>
  
</div>
<div *ngIf="showMeetingScreen">
  
  // highlight-next-line
  <app-top-bar></app-top-bar>
  

  
  // highlight-start
  <div
    style="
      display: flex;
      flex-direction: column;
      overflow-y: auto;
      max-height: calc(100vh - 85px);
    "
  >
    <div class="container">
      <div
        #participantGridContainer
        id="participant-grid-container"
        class="row"
      ></div>
    </div>
  </div>
  // highlight-end
</div>

<router-outlet></router-outlet>
```


### Step 3: Implement Join Screen

Subsequently, implement the `createMeeting` and `validateMeeting` function sin `app.component.ts` to call the respective APIs.

```js title="app.component.ts"




@Component({
  selector: "app-root",
  templateUrl: "./app.component.html",
  styleUrls: ["./app.component.css"],
})
export class AppComponent {
  title = "videosdk_angular_2_quickstart";

  meeting: any;
  participantName: string = "";
  meetingId: string = "";
  showJoinScreen: boolean = true;
  showMeetingScreen: boolean = false;
  showTopBar: boolean = false;

  constructor(
    private renderer: Renderer2,
    private meetingService: MeetingService
  ) {
    this.participantName = "Homi J. Bhabha";
  }

  createMeeting() {
    this.meetingService.createMeeting().subscribe(
      (roomId) => {
        this.meetingId = roomId;
        this.joinMeeting();
      },
      (error) => {
        console.error("Failed to create meeting:", error);
      }
    );
  }

  validateMeeting(meetingId: any) {
    this.meetingService.validateMeeting(meetingId).subscribe(
      (isValid) => {
        if (isValid) {
          this.meetingId = meetingId;
          this.joinMeeting();
        } else {
          alert("Invalid meeting id");
        }
      },
      (error) => {
        console.error("Failed to validate meeting:", error);
        // Handle the error
      }
    );
  }
}
```

- After creating the above functions, pass them to the `join-screen` component as follows:

```html title="app.component.html"
<div *ngIf="showJoinScreen">
  <app-join-screen
    (validateMeeting)="validateMeeting($event)"
    (createMeeting)="createMeeting()"
  ></app-join-screen>
</div>
```

- Next in the `join-screen.component.ts` file, run the function.

```js ="join-screen.component.ts"

@Component({
  selector: "app-join-screen",
  templateUrl: "./join-screen.component.html",
  styleUrls: ["./join-screen.component.css"],
})
export class JoinScreenComponent {
  @Output() createMeeting = new EventEmitter();
  @Output() validateMeeting = new EventEmitter<string>();
  @Input() meetingId: string = "";

  fireValidateMeeting() {
    this.validateMeeting.emit(this.meetingId);
  }

  fireCreateMeeting() {
    this.createMeeting.emit();
  }

  constructor() {}

  ngOnInit() {}
}
```


### Step 4: Initialize meeting

Following that, initialize the meeting using the `initMeeting()` function and proceed to join the meeting.

```js title="startMeeting app.component.ts"
// Initialize meeting
 async initMeeting() {
    VideoSDK.config(environment.token);

    this.meeting = VideoSDK.initMeeting({
      meetingId: this.meetingId, // required
      name: this.participantName, // required
      micEnabled: true, // optional, default: true
      webcamEnabled: true, // optional, default: true
    });
  }

  joinMeeting() {
    this.initMeeting();
    this.meeting.join();

    this.handleMeetingEvents(this.meeting);
    const showJoinScreenMessage = this.renderer.createElement("div");

    this.renderer.setAttribute(
      showJoinScreenMessage,
      "id",
      "show-join-screen-message"
    );
    this.renderer.setProperty(
      showJoinScreenMessage,
      "innerHTML",
      "Please wait to join meeting..."
    );
    this.renderer.setStyle(showJoinScreenMessage, "color", "black");
    this.renderer.setStyle(showJoinScreenMessage, "fontSize", "20px");
    this.renderer.setStyle(showJoinScreenMessage, "fontWeight", "bold");
    this.renderer.setStyle(showJoinScreenMessage, "marginTop", "20px");
    this.renderer.setStyle(showJoinScreenMessage, "marginLeft", "20px");
    this.renderer.appendChild(document.body, showJoinScreenMessage);
  }

 // for handle meeting events
  handleMeetingEvents(meeting: any) {}
```

#### Output

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/angular/angular2-initMeeting.png' />

</center>

<br/>


### Step 5: Handle Meeting Events

Once the meeting is successfully initialized, create the participant grid and manage events such as `meeting-joined`, `meeting-left`, and participant events.

```js ="app.component.ts"
export class AppComponent {
  handleMeetingEvents(meeting: any) {
    this.localParticipant = meeting.localParticipant;
    this.participants = meeting.participants;

    if (meeting) {
      this.showJoinScreen = false;
      this.showMeetingScreen = true;
    }

    // meeting joined event
    meeting.on("meeting-joined", () => {
      var showJoinScreenMessage = document.getElementById(
        "show-join-screen-message"
      );
      this.renderer.removeChild(document.body, showJoinScreenMessage);
      const { participantMediaElement } = this.participantGridGenerator(
        this.meeting.localParticipant
      );
      this.showTopBar = true;

      meeting.localParticipant.on("stream-enabled", (stream: any) => {
        console.log("Stream Enabled: ");
        this.handleStreamEnabled(
          stream,
          meeting.localParticipant,
          true,
          participantMediaElement
        );
      });
      meeting.localParticipant.on("stream-disabled", (stream: any) => {
        console.log("Stream Disabled: ");
        this.handleStreamDisabled(
          stream,
          meeting.localParticipant,
          true,
          participantMediaElement
        );
      });
    });

    // meeting left event
    meeting.on("meeting-left", () => {
      while (this.participantGridContainer.nativeElement.firstChild) {
        this.participantGridContainer.nativeElement.removeChild(
          this.participantGridContainer.nativeElement.firstChild
        );
      }
      this.showMeetingScreen = false;
      this.showJoinScreen = true;
    });

    //remote participant events
    // participant joined
    meeting.on("participant-joined", (participant) => {
      console.log("New Participant Joined: ", participant.id);

      participant.on("stream-enabled", (stream) => {
        //...
      });
      participant.on("stream-disabled", (stream) => {
        //...
      });
    });

    // participant left
    meeting.on("participant-left", (participant) => {
      //...
    });
  }
}
```


### Step 6: Create Media Elements

In this step, Create a function to generate audio and video elements for displaying both local and remote participants. Set the corresponding media track based on whether it's a video or audio stream.

```js title=app.component.ts
export class AppComponent {
  isWebcamOn: boolean = true;
  isMicOn: boolean = true;
  // creating video element
  createVideoElement(
    stream: any,
    participant: any,
    participantMediaElement: any
  ) {
    const video = this.renderer.createElement("video");
    const mediaStream = new MediaStream();
    mediaStream.addTrack(stream.track);
    this.renderer.setAttribute(video, "id", `v-${participant.id}`);
    this.renderer.setAttribute(video, "autoplay", "true");
    this.renderer.setAttribute(video, "playsinline", "true");
    this.renderer.setAttribute(video, "muted", "true");
    this.renderer.setAttribute(
      video,
      "style",
      "width: 100%; height: 100%;position: absolute;top: 0;left: 0;object-fit: cover;"
    );
    this.renderer.setProperty(video, "srcObject", mediaStream);
    const videoElement = this.renderer.createElement("div");
    this.renderer.setAttribute(
      videoElement,
      "id",
      `video-container-${participant.id}`
    );

    this.renderer.setAttribute(
      videoElement,
      "style",
      "width: 100%; height: 100%;"
    );
    this.renderer.setStyle(videoElement, "position", "relative");
    this.renderer.appendChild(participantMediaElement, videoElement);
    this.renderer.appendChild(videoElement, video);
    const cornerDisplayName = this.renderer.createElement("div");
    this.renderer.setAttribute(
      cornerDisplayName,
      "id",
      `name-container-${participant.id}`
    );
    this.renderer.setStyle(cornerDisplayName, "position", "absolute");
    this.renderer.setStyle(cornerDisplayName, "bottom", "16px");
    this.renderer.setStyle(cornerDisplayName, "left", "16px");
    this.renderer.setStyle(cornerDisplayName, "color", "white");
    this.renderer.setStyle(
      cornerDisplayName,
      "backgroundColor",
      "rgba(0, 0, 0, 0.5)"
    );
    this.renderer.setStyle(cornerDisplayName, "padding", "2px");
    this.renderer.setStyle(cornerDisplayName, "borderRadius", "2px");
    this.renderer.setStyle(cornerDisplayName, "fontSize", "12px");
    this.renderer.setStyle(cornerDisplayName, "fontWeight", "bold");
    this.renderer.setStyle(cornerDisplayName, "zIndex", "1");
    this.renderer.setStyle(cornerDisplayName, "padding", "4px");
    cornerDisplayName.innerHTML =
      participant.displayName.length > 15
        ? participant.displayName.substring(0, 15) + "..."
        : participant.displayName;
    this.renderer.appendChild(videoElement, cornerDisplayName);
  }

  // creating audio element
  createAudioElement(
    stream: any,
    participant: any,
    participantMediaElement: any
  ) {
    const audio = this.renderer.createElement("audio");
    const mediaStream = new MediaStream();
    mediaStream.addTrack(stream.track);
    this.renderer.setAttribute(audio, "id", `audio-${participant.id}`);
    this.renderer.setAttribute(audio, "autoplay", "true");
    this.renderer.setAttribute(audio, "playsinline", "true");
    this.renderer.setAttribute(audio, "muted", "true");
    this.renderer.setProperty(audio, "srcObject", mediaStream);

    const audioElement = this.renderer.createElement("div");
    this.renderer.setAttribute(
      audioElement,
      "id",
      `audio-container-${participant.id}`
    );
    this.renderer.appendChild(participantMediaElement, audioElement);
    this.renderer.appendChild(audioElement, audio);
  }

  // creating name element
  createNameElemeent(participant: any) {
    var nameElement = this.renderer.createElement("div");
    this.renderer.setAttribute(
      nameElement,
      "id",
      `name-container-${participant.id}`
    );
    nameElement.innerHTML = participant.displayName.charAt(0).toUpperCase();
    this.renderer.setStyle(nameElement, "backgroundColor", "black");
    this.renderer.setStyle(nameElement, "color", "white");
    this.renderer.setStyle(nameElement, "textAlign", "center");
    this.renderer.setStyle(nameElement, "padding", "32px");
    this.renderer.setStyle(nameElement, "borderRadius", "100%");
    this.renderer.setStyle(nameElement, "fontSize", "20px");
    return nameElement;
  }

  // handle streams
  handleStreamEnabled(
    stream: any,
    participant: any,
    isLocal: any,
    participantMediaElement: any
  ) {
    if (stream.kind == "video") {
      var nameElement = document.getElementById(
        `name-container-${participant.id}`
      );
      participantMediaElement.removeChild(nameElement);
      this.createVideoElement(stream, participant, participantMediaElement);
    }
    if (!isLocal) {
      if (stream.kind == "audio") {
        this.createAudioElement(stream, participant, participantMediaElement);
      }
    }
  }

  handleStreamDisabled(
    stream: any,
    participant: any,
    isLocal: any,
    participantMediaElement: any
  ) {
    if (stream.kind == "video") {
      var videoElement = document.getElementById(
        `video-container-${participant.id}`
      );

      var nameElement = this.createNameElemeent(participant);
      this.renderer.removeChild(participantMediaElement, videoElement);
      this.renderer.appendChild(participantMediaElement, nameElement);
    }
    if (!isLocal) {
      if (stream.kind == "audio") {
        var audioElement = document.getElementById(
          `audio-container-${participant.id}`
        );
        this.renderer.removeChild(participantMediaElement, audioElement);
      }
    }
  }

  // generate participant grid
  participantGridGenerator(participant: any) {
    var participantGridItem = this.renderer.createElement("div");
    this.renderer.setStyle(participantGridItem, "backgroundColor", "lightgrey");
    this.renderer.setStyle(participantGridItem, "borderRadius", "10px");
    this.renderer.setStyle(participantGridItem, "aspectRatio", 16 / 9);
    this.renderer.setStyle(participantGridItem, "width", "360px");
    this.renderer.setStyle(participantGridItem, "marginTop", "8px");
    this.renderer.setStyle(participantGridItem, "display", "flex");
    this.renderer.setStyle(participantGridItem, "alignItems", "center");
    this.renderer.setStyle(participantGridItem, "justifyContent", "center");
    this.renderer.setStyle(participantGridItem, "overflow", "hidden");

    this.renderer.setAttribute(
      participantGridItem,
      "id",
      `participant-grid-item-${participant.id}`
    );

    this.renderer.setAttribute(participantGridItem, "class", "col-4");

    var participantMediaElement = this.renderer.createElement("div");
    this.renderer.setAttribute(
      participantMediaElement,
      "id",
      `participant-media-container-${participant.id}`
    );
    this.renderer.setStyle(participantMediaElement, "position", "relative");
    this.renderer.setStyle(participantMediaElement, "width", "100%");
    this.renderer.setStyle(participantMediaElement, "height", "100%");
    this.renderer.setStyle(participantMediaElement, "display", "flex");
    this.renderer.setStyle(participantMediaElement, "alignItems", "center");
    this.renderer.setStyle(participantMediaElement, "justifyContent", "center");

    var nameElement = this.createNameElemeent(participant);
    this.renderer.appendChild(
      this.participantGridContainer.nativeElement,
      participantGridItem
    );
    this.renderer.appendChild(participantGridItem, participantMediaElement);
    this.renderer.appendChild(participantMediaElement, nameElement);

    var getParticipantMediaElement = document.getElementById(
      `participant-media-container-${participant.id}`
    );

    return {
      getParticipantMediaElement,
    };
  }
}
```


### Step 7: Handle participant events

Thereafter, implement the events related to the participants and the stream.

Following are the events to be executed in this step:

1. `participant-joined`: When a remote participant joins, this event will trigger. In the event callback, create video and audio elements previously defined for rendering their video and audio streams.

2. `participant-left`: When a remote participant leaves, this event will trigger. In the event callback, remove the corresponding video and audio elements.

3. `stream-enabled`: This event manages the media track of a specific participant by associating it with the appropriate video or audio element.

4. `stream-disabled`: This event manages the media track of a specific participant, when they toggle their camera or mic by associating it with the appropriate video or audio element.

```js title="app.component.ts"
// participant joined
//remote participant
meeting.on("participant-joined", (participant: any) => {
  console.log("New Participant Joined: ", participant.id);

  var { getParticipantMediaElement } =
    this.participantGridGenerator(participant);
  participant.setQuality("high");
  participant.on("stream-enabled", (stream: any) => {
    this.handleStreamEnabled(
      stream,
      participant,
      false,
      getParticipantMediaElement
    );
  });
  participant.on("stream-disabled", (stream: any) => {
    this.handleStreamDisabled(
      stream,
      participant,
      false,
      getParticipantMediaElement
    );
  });
});

// participants left
meeting.on("participant-left", (participant: any) => {
  console.log("Participant Left: ", participant.id);
  var participantGridItem = document.getElementById(
    `participant-grid-item-${participant.id}`
  );
  this.participantGridContainer.nativeElement.removeChild(participantGridItem);
});
```

#### Output

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/angular/participantContainer.png' />

</center>


### Step 8: Implement Controls

Next, implement meeting functionalities such as toggleMic, toggleWebcam and leave meeting function in `app.component.ts` to call the respective APIs.

```js title="app.component.ts"
export class AppComponent {
  //..
  toogleWebcam() {
    if (this.isWebcamOn) {
      this.meeting.disableWebcam();
    } else {
      this.meeting.enableWebcam();
    }
    this.isWebcamOn = !this.isWebcamOn;
  }

  toogleMic() {
    if (this.isMicOn) {
      this.meeting.muteMic();
    } else {
      this.meeting.unmuteMic();
    }
    this.isMicOn = !this.isMicOn;
  }

  leaveMeeting() {
    this.meeting.leave();
    this.showMeetingScreen = false;
    this.showJoinScreen = true;
  }
}
```

- After creating the above function, pass it to the `top-bar` component as follows:

```html ="app.component.html"
<app-top-bar
  [meetingId]="meetingId"
  [showTopBar]="showTopBar"
  (toogleWebcam)="toogleWebcam()"
  (toogleMic)="toogleMic()"
  (leaveMeeting)="leaveMeeting()"
></app-top-bar>
```

- Next in the `top-bar.component.ts` file, run this function:

```js ="top-bar.component.ts"

@Component({
  selector: "app-top-bar",
  templateUrl: "./top-bar.component.html",
})
export class TopBarComponent {
  @Input() showTopBar: boolean = false;
  @Output() toogleWebcam = new EventEmitter();
  @Output() toogleMic = new EventEmitter();
  @Output() leaveMeeting = new EventEmitter();
  @Input() meetingId: string = "";

  constructor() {}

  fireToggleWebcam() {
    this.toogleWebcam.emit();
  }

  fireToggleMic() {
    this.toogleMic.emit();
  }

  fireLeaveMeeting() {
    this.leaveMeeting.emit();
  }
}
```


## Run your code

Once you have completed all the steps mentioned above, run your application using the code block below.

```bash
ng serve
```

## Final Output

You have completed the implementation of a customized video calling app in Angular 2 using VideoSDK. To explore more features, go through Basic and Advanced features.




<br/>

:::tip
You can checkout the complete [quick start example here](https://github.com/videosdk-live/quickstart/tree/main/angular-rtc/videosdk_angular_2_quickstart).
:::


---

# Quick Start for Conference in Angular JS

VideoSDK empowers you to seamlessly integrate the video calling feature into your Angular JS application within minutes.

In this quickstart, you'll explore the group calling feature of VideoSDK. Follow the step-by-step guide to integrate it within your application.

## Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

- Video SDK Developer Account (Not having one, follow **[Video SDK Dashboard](https://app.videosdk.live/)**)
- Have Node and NPM installed on your device.

:::important

One should have a VideoSDK account to generate token.
Visit VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate token

:::

## Getting Started with the Code!

Follow the steps to create the environment necessary to add video calls into your app. You can also find the code sample for [quickstart here](https://github.com/videosdk-live/quickstart/tree/main/angular-rtc/videosdk_angular_js_quickstart).

### Install Video SDK

Import VideoSDK using the `<script>` tag or Install it using the following npm command. Make sure you are in your app directory before you run this command.



**Tab:**

" label="<script>" default>

```html
<html>
  <head>
....
  </head>
  <body>
.....
<script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
  </body>
</html>
```

---

**npm:**

```bash
npm install @videosdk.live/js-sdk
```

---

**yarn:**

```bash
yarn add @videosdk.live/js-sdk
```

## Structure of the project

Your project structure should look like this.

```jsx title="Project Structure"
  root
   ├── app
   │    ├── lib
   │        ├── angular.min.js
   │    ├── app.js
   ├── content
   │    ├── css
   │        ├── styles.css
   ├── views
   │     ├── joinScreen.html
   │     ├── meetingContainer.html
   │     ├── topBar.html
   ├── config.js
   ├── index.js
```

You will be working on the following files:

- joinScreen.html: Responsible for creating a basic UI for the joinScreen functionality.
- meetingContainer.html: Responsible for creating a simple grid-screen for the meeting.
- topBar.html: Responsible for creating a basic topbar with webcam, mic and leave meeting buttons.
- config.js: Responsible for storing the token.
- app.js: Responsible for rendering components such as meeting view, joinscreen and topbar.

### Step 1: Design the user interface (UI)

  Create an HTML file that will render the `join-screen`, `top-bar` and `meeting-container` components.

  1.1 First, Create the UI for the `joinScreen` functionality.

  ```html title="joinScreen.html"
  <div
    id="joinPage"
    class="main-bg"
    style="display: flex"
    ng-controller="myController"
  >
    <div style="display: flex; flex-direction: column; margin-left: 8px">
      <h3>AngularJS quickstart with Videosdk</h3>
      <form name="myForm" style="display: flex">
        <div style="margin-right: 8px">
          <button
            class="btn secondary text-white"
            id="meetingStartButton"
            ng-click="createMeeting()"
          >
            Create Meeting
          </button>
        </div>
        <p>OR</p>
        <div style="margin-left: 10px; margin-right: 16px">
          <input
            class="text-input"
            type="text"
            ng-model="meetingId"
            placeholder="Enter meeting id"
          />
          <p ng-show="showMeetingIdError" class="input-err">
            Please enter valid meeting Id
          </p>
        </div>
        <div>
          <button
            class="btn secondary text-white"
            id="meetingJoinButton"
            ng-click="validateMeeting()"
          >
            Join Meeting
          </button>
        </div>
      </form>
    </div>
  </div>
  ```

  #### Output

  <center>

  <img src='https://cdn.videosdk.live/website-resources/docs-resources/angular/joinscreen.png' />

  </center>

  1.2 Next, Create the `topBar` UI.

  ```html title="topBar.html"
  <div
    style="height: 70px; background-color: lightgray"
    ng-controller="myController"
    ng-show="showMeetingScreen"
    id="top-bar"
  >
    <div class="top-bar-div">
      <div>
        <p style="margin-top: 0px; margin-bottom: 0px; font-weight: 700">
          MeetingId: {{meetingId}}
        </p>
      </div>
      <div style="display: flex; align-items: center; margin-top: 8px">
        <button style="cursor: pointer" ng-click="toggleWebcam()">
          Toggle Webcam
        </button>
        <button style="margin-left: 4px; cursor: pointer" ng-click="toggleMic()">
          Toggle Mic
        </button>
        <button class="leave-btn" ng-click="leaveMeeting()">Leave Meeting</button>
      </div>
    </div>
  </div>
  ```

  #### Output

  <center>

  <img src='https://cdn.videosdk.live/website-resources/docs-resources/angular/topbar.png' />

  </center>

  1.3 Subsequently, create the `meetingContainer.html` file.

  ```html ="meetingContainer.html"
  <div
    style=" display: flex; flex-direction: column; overflow-y: auto; max-height: calc(100vh - 90px);
    "
    ng-controller="myController"
  >
    <div class="container">
      <div id="participant-grid-container" class="row"></div>
    </div>
  </div>
  ```

  Finally, assemble the components by creating the `index.html` file and incorporating all the previously created components into it.

  ```html ="index.html"
  <!DOCTYPE html>
  <html lang="en" ng-app="myApp">
    <head>
      <base href="/" />
      <title>Angular JS - Videosdk</title>
      <link href="content/css/styles.css" rel="stylesheet" type="text/css" />
      <script src="app/lib/angular.min.js"></script>
      <script src="config.js"></script>
      <script src="app/app.js"></script>
    </head>

    <body>
      //highlight-start
      <top-bar />
      //highlight-end
      <div ng-show="showJoinScreen">
        //highlight-start
        <join-screen />
        //highlight-end
      </div>
      <div ng-show="showMeetingScreen">
        //highlight-start
        <meeting-container />
        //highlight-end
      </div>
      <script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
    </body>
  </html>
  ```


### Step 2: Implement Join Screen

  Configure the token in the `config.js` file, which you can obtain from the [VideoSDK Dashbord](https://app.videosdk.live/login).

  ```js title="config.js"
  // Auth token will be used to generate a meeting and connect to it
  "use strict";
  angular.module("config", []).constant("ENV", {
    token: "YOUR_TOKEN", // Add token here
  });
  ```

  Next, retrieve all the elements from the DOM and declare the following variables in the `app.js` file. Then, add an event listener to the join and create meeting buttons.

  ```js title="app.js"
  var myApp = angular.module("myApp", ["config"]);

  myApp.config(function () {});

  myApp.run(function () {});

  // create directives of component
  myApp.directive("joinScreen", [
    function () {
      return {
        restrict: "E",
        templateUrl: "views/joinScreen.html",
        transclude: true,
        controller: "myController",
        replace: true,
      };
    },
  ]);

  myApp.directive("topBar", [
    function () {
      return {
        restrict: "E",
        templateUrl: "views/topBar.html",
        transclude: true,
        controller: "myController",
        replace: true,
      };
    },
  ]);

  myApp.directive("meetingContainer", [
    function () {
      return {
        restrict: "E",
        templateUrl: "views/meetingContainer.html",
        transclude: true,
        controller: "myController",
        replace: true,
      };
    },
  ]);

  myApp.controller("myController", function ($scope, ENV) {
    // variable initialization
    $scope.name = "Homi J. Bhabha";
    $scope.meetingId = "";
    $scope.showMeetingIdError = false;
    $scope.showMeetingScreen = false;
    $scope.showJoinScreen = true;
    $scope.meeting = null;

    // Getting Elements from DOM
    $scope.participantGridContainer = document.getElementById(
      "participant-grid-container"
    );

    // API request for create meeting
    $scope.createMeeting = function () {
      const url = "https://api.videosdk.live/v2/rooms";
      const config = {
        headers: {
          Authorization: ENV.token,
          "Content-Type": "application/json",
        },
      };

      $http
        .post(url, { name: $scope.name }, config)
        .then(function (response) {
          const { roomId } = response.data;
          $scope.meetingId = roomId;
          $scope.initMeeting();
        })
        .catch(function (error) {
          alert("error", error);
        });
    };

    // API request for validate meeting
    $scope.validateMeeting = function () {
      const url = `https://api.videosdk.live/v2/rooms/validate/${$scope.meetingId}`;
      const config = {
        headers: {
          Authorization: ENV.token,
          "Content-Type": "application/json",
        },
      };

      $http
        .get(url, config)
        .then(function (response) {
          if (response.data.roomId === $scope.meetingId) {
            $scope.showMeetingIdError = false;
            $scope.initMeeting();
          }
        })
        .catch(function (error) {
          $scope.showMeetingIdError = true;
          console.log("error", error);
        });
    };
  });


### Step 3: Initialize meeting

  Following that, initialize the meeting using the `initMeeting()` function and proceed to join the meeting.

  ```js title="app.js"
  // Initialize meeting
  $scope.initMeeting = function () {
    window.VideoSDK.config(ENV.token); // required;

    var meeting = window.VideoSDK.initMeeting({
      meetingId: $scope.meetingId, // required
      name: $scope.name, // required
      micEnabled: true, // optional, default: true
      webcamEnabled: true, // optional, default: true
    });
    meeting.join();
    $scope.meeting = meeting;

    if ($scope.meeting) {
      $scope.handleMeetingEvents($scope.meeting);
      var showJoinScreenMessage = document.createElement("div");
      var topBar = document.getElementById("top-bar");
      topBar.style.display = "none";

      showJoinScreenMessage.setAttribute("id", "show-join-screen-message");
      showJoinScreenMessage.innerHTML = "Please wait to join meeting...";
      showJoinScreenMessage.style.color = "black";
      showJoinScreenMessage.style.fontSize = "20px";
      showJoinScreenMessage.style.fontWeight = "bold";
      showJoinScreenMessage.style.marginTop = "20px";
      showJoinScreenMessage.style.marginLeft = "20px";
      $scope.participantGridContainer.appendChild(showJoinScreenMessage);
    }
  };
  ```

  #### Output

  <center>

  <img src='https://cdn.videosdk.live/website-resources/docs-resources/angular/initMeeting.png' />

  </center>


### Step 4: Handle Meeting Events

  Once the meeting is successfully initialized, create the participant grid and manage events such as `meeting-joined`, `meeting-left`, and participant events.

  ```js ="app.js"
  // variable initialization
  $scope.localParticipant = null;
  $scope.participants = [];

  // creating Name Element
  $scope.createNameElement = function (participant) {
    var nameElement = document.createElement("div");
    nameElement.setAttribute("id", `name-container-${participant.id}`);
    nameElement.innerHTML = participant.displayName.charAt(0).toUpperCase();
    nameElement.style.backgroundColor = "black";
    nameElement.style.color = "white";
    nameElement.style.textAlign = "center";
    nameElement.style.padding = "32px";
    nameElement.style.borderRadius = "100%";
    nameElement.style.fontSize = "20px";
    return nameElement;
  };

  // for handle meeting events
  $scope.handleMeetingEvents = function (meeting) {
    $scope.localParticipant = meeting.localParticipant;
    $scope.participants = meeting.participants;

    // creating participant Grid
    $scope.participantGridGenerator = function ({ participant }) {
      var participantGridItem = document.createElement("div");
      participantGridItem.style.backgroundColor = "lightgrey";
      participantGridItem.style.borderRadius = "10px";
      participantGridItem.style.height = "300px";
      participantGridItem.style.width = "320px";
      participantGridItem.style.marginTop = "8px";
      participantGridItem.style.display = "flex";
      participantGridItem.style.alignItems = "center";
      participantGridItem.style.justifyContent = "center";
      participantGridItem.style.position = "relative";
      participantGridItem.setAttribute(
        "id",
        `participant-grid-item-${participant.id}`
      );
      participantGridItem.setAttribute("class", "col-4");
      var participantMediaElement1 = document.createElement("div");
      participantMediaElement1.setAttribute(
        "id",
        `participant-media-container-${participant.id}`
      );
      var nameElement = $scope.createNameElement(participant);
      $scope.participantGridContainer.appendChild(participantGridItem);
      participantGridItem.appendChild(participantMediaElement1);
      participantMediaElement1.appendChild(nameElement);

      var participantMediaElement = document.getElementById(
        `participant-media-container-${participant.id}`
      );

      return {
        participantMediaElement,
      };
    };

    if (meeting) {
      $scope.showJoinScreen = false;
      $scope.showMeetingScreen = true;
    }

    // meeting joined event
    meeting.on("meeting-joined", function () {
      var showJoinScreenMessage = document.getElementById(
        "show-join-screen-message"
      );
      var topBar = document.getElementById("top-bar");
      showJoinScreenMessage.style.display = "none";
      topBar.style.display = "block";

      const { participantMediaElement } = $scope.participantGridGenerator({
        participant: meeting.localParticipant,
      });

      meeting.localParticipant.on("stream-enabled", (stream) => {
        $scope.handleStreamEnabled(
          stream,
          meeting.localParticipant,
          true,
          participantMediaElement
        );
      });
      meeting.localParticipant.on("stream-disabled", (stream) => {
        $scope.handleStreamDisabled(
          stream,
          meeting.localParticipant,
          true,
          participantMediaElement
        );
      });
    });

    // meeting left event
    meeting.on("meeting-left", () => {
      // remove all children nodes from participant grid container
      while ($scope.participantGridContainer.firstChild) {
        $scope.participantGridContainer.removeChild(
          $scope.participantGridContainer.firstChild
        );
      }
      $scope.showMeetingScreen = false;
      $scope.showJoinScreen = true;
    });

    //remote participant events
    // participant joined
    meeting.on("participant-joined", (participant) => {
      console.log("New Participant Joined: ", participant.id);

      participant.on("stream-enabled", (stream) => {
        //...
      });
      participant.on("stream-disabled", (stream) => {
        //...
      });
    });

    // participant left
    meeting.on("participant-left", (participant) => {
      //...
    });
  };


### Step 5: Create the Media Elements

  In this step, Create a function to generate audio and video elements for displaying both local and remote participants. Set the corresponding media track based on whether it's a video or audio stream.

  ```js title=app.js
  myApp.controller("myController", function ($scope, $http, ENV) {
    // creating video element
    $scope.createVideoElement = function (
      stream,
      participant,
      participantMediaElement
    ) {
      var video = document.createElement("video");
      var mediaStream = new MediaStream();
      mediaStream.addTrack(stream.track);
      video.srcObject = mediaStream;
      video.autoplay = true;
      video.id = `v-${participant.id}`;
      video.style.marginTop = "6px";
      video.style.marginLeft = "4px";
      video.style.marginRight = "4px";
      video.style.width = "320px";
      video.style.height = "300px";
      video.style.objectFit = "cover";
      video.style.transform = "rotate('90')";
      video.style.borderRadius = "10px";
      video.setAttribute("playsinline", true);
      var videoElement = document.createElement("div");
      videoElement.setAttribute("id", `video-container-${participant.id}`);
      participantMediaElement.appendChild(videoElement);
      videoElement.appendChild(video);

      var cornerDisplayName = document.createElement("div");
      cornerDisplayName.setAttribute("id", `name-container-${participant.id}`);
      cornerDisplayName.style.position = "absolute";
      cornerDisplayName.style.bottom = "16px";
      cornerDisplayName.style.left = "16px";
      cornerDisplayName.style.color = "white";
      cornerDisplayName.style.backgroundColor = "rgba(0, 0, 0, 0.5)";
      cornerDisplayName.style.padding = "2px";
      cornerDisplayName.style.borderRadius = "2px";
      cornerDisplayName.style.fontSize = "12px";
      cornerDisplayName.style.fontWeight = "bold";
      cornerDisplayName.style.zIndex = "1";
      cornerDisplayName.style.padding = "4px";
      cornerDisplayName.innerHTML =
        participant.displayName.length > 15
          ? participant.displayName.substring(0, 15) + "..."
          : participant.displayName;
      videoElement.appendChild(cornerDisplayName);
    };

    // creating audio element
    $scope.createAudioElement = function (
      stream,
      participant,
      participantMediaElement
    ) {
      var audio = document.createElement("audio");
      var mediaStream = new MediaStream();
      mediaStream.addTrack(stream.track);
      audio.srcObject = mediaStream;
      audio.autoplay = true;
      audio.muted;
      audio.id = `audio-${participant.id}`;
      var audioElement = document.createElement("div");
      audioElement.setAttribute("id", `audio-container-${participant.id}`);
      participantMediaElement.appendChild(audioElement);
      audioElement.appendChild(audio);
    };

    // handle streams
    $scope.handleStreamEnabled = function (
      stream,
      participant,
      isLocal,
      participantMediaElement
    ) {
      if (stream.kind == "video") {
        var nameElement = document.getElementById(
          `name-container-${participant.id}`
        );
        participantMediaElement.removeChild(nameElement);
        $scope.createVideoElement(stream, participant, participantMediaElement);
      }
      if (!isLocal) {
        if (stream.kind == "audio") {
          $scope.createAudioElement(stream, participant, participantMediaElement);
        }
      }
    };

    $scope.handleStreamDisabled = function (
      stream,
      participant,
      isLocal,
      participantMediaElement
    ) {
      if (stream.kind == "video") {
        var videoElement = document.getElementById(
          `video-container-${participant.id}`
        );
        var nameElement = $scope.createNameElement(participant);
        participantMediaElement.removeChild(videoElement);
        participantMediaElement.appendChild(nameElement);
      }
      if (!isLocal) {
        if (stream.kind == "audio") {
          var audioElement = document.getElementById(
            `audio-container-${participant.id}`
          );
          participantMediaElement.removeChild(audioElement);
        }
      }
    };
  });


### Step 6: Handle participant events

  Thereafter, implement the events related to the participants and the stream.

  Following are the events to be executed in this step:

  1. `participant-joined`: When a remote participant joins, this event will trigger. In the event callback, create video and audio elements previously defined for rendering their video and audio streams.

  2. `participant-left`: When a remote participant leaves, this event will trigger. In the event callback, remove the corresponding video and audio elements.

  3. `stream-enabled`: This event manages the media track of a specific participant by associating it with the appropriate video or audio element.

  4. `stream-disabled`: This event manages the media track of a specific participant, when they toggle their camera or mic by associating it with the appropriate video or audio element.

  ```js title="index.js"
  $scope.handleMeetingEvents = function (meeting) {
    //...
    // participant joined
    meeting.on("participant-joined", (participant) => {
      console.log("New Participant Joined: ", participant.id);

      var { participantMediaElement } = $scope.participantGridGenerator({
        participant: participant,
      });
      participant.setQuality("high");
      participant.on("stream-enabled", (stream) => {
        $scope.handleStreamEnabled(
          stream,
          participant,
          false,
          participantMediaElement
        );
      });
      participant.on("stream-disabled", (stream) => {
        $scope.handleStreamDisabled(
          stream,
          participant,
          false,
          participantMediaElement
        );
      });
    });

    // participants left
    meeting.on("participant-left", (participant) => {
      var participantGridItem = document.getElementById(
        `participant-grid-item-${participant.id}`
      );
      $scope.participantGridContainer.removeChild(participantGridItem);
    });
  };
  ```

  #### Output

  <center>

  <img src='https://cdn.videosdk.live/website-resources/docs-resources/angular/angularJS_participant_container.png' />

  </center>


### Step 7: Implement Controls

  Next, implement the meeting controls such as toggleMic, toggleWebcam and leave meeting.

  ```js title="app.js"
  myApp.controller("myController", function ($scope, $http, ENV) {
    //...
    $scope.isWebcamOn = true;
    $scope.isMicOn = true;

    $scope.handleMeetingEvents = function (meeting) {
      //..
      // Toggle Webcam in Meeting
      $scope.toggleWebcam = function () {
        if ($scope.isWebcamOn) {
          $scope.meeting.disableWebcam();
        } else {
          $scope.meeting.enableWebcam();
        }
        $scope.isWebcamOn = !$scope.isWebcamOn;
      };

      // Toggle Webcam in Meeting
      $scope.toggleMic = function () {
        if ($scope.isMicOn) {
          $scope.meeting.muteMic();
        } else {
          $scope.meeting.unmuteMic();
        }
      };

      // leave meeting
      $scope.leaveMeeting = function () {
        $scope.meeting.leave();
        $scope.showMeetingScreen = false;
        $scope.showJoinScreen = true;
      };
    };
  });
```


## Run your code

Once you have completed all the steps mentioned above, run your application using the code block below.

```bash
live-server --port=8000
```

## Final Output

You have completed the implementation of a customized video calling app in Angular JS using VideoSDK. To explore more features, go through Basic and Advanced features.




<br/>

:::tip
You can checkout the complete [quick start example here](https://github.com/videosdk-live/quickstart/tree/main/angular-rtc/videosdk_angular_js_quickstart).
:::


---

# Setting Audio Volume - Javascript

- Providing the ability to adjust the volume of participants in a meeting enhances the overall audio quality and ensures that everyone can be heard clearly.

- In meetings with multiple participants, variations in the volume of each person's voice are common. Some may speak more softly or have a quieter microphone, while others may speak louder or have a microphone that picks up more background noise.

- By allowing hosts or participants to adjust the volume of individual participants, it becomes easier to balance out these differences and ensure that everyone can be heard clearly. This can lead to more productive and efficient meetings, as people will be able to communicate more effectively.

## Meeting Volume

- To set the audio volume for the meeting, adjust the volume property for each `<audio>` element used, to render the paricipant audio.

- Value for the `volume` property for the `<audio>` can be between `0` and `1`.

```js
const setAudioVolume = (volume) => {
  const audioTags = document.getElementsByTagName("audio");
  audioTags.forEach((tag) => {
    tag.volume = volume;
  });
};
```

:::note
To learn more about changing the audio volume [check this documentation](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/volume).
:::

## Participant Volume

- This operation can be performed for individual participants as well by providing a unique ID for each participant's `<audio>` element and then setting the volume for them.

- Assuming you provide `<audio>` element IDs like `a-<participantId>`, you can set the volume for a specific participant as shown below.

```js
const setAudioVolume = (volume, participantId) => {
  const audioTag = document.getElementById(`a-${participantId}`);
  audioTag.volume = volume;
};
```


---

<h1> {props.title} </h1>{" "}

### Why we are using JWT based Token ?

Token based authentication allows users to verify their identity by providing generated API key and secret.

We use JWT token for the authentication purpose because Token-based authentication is **widely used** in modern web applications and APIs because it offers several benefits over traditional authentication. For example, it can **reduce the risk of the credentials being misused**, and it allows for **more fine-grained control** over access to resources. Additionally, tokens can be easily revoked or expired, making it easier to manage access rights.

### How to generate Token ?

To manage secured communication, every participant that connects to the meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key` which you can get from [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

#### 1. Generating token from Dashboard

If you are looking to do **testing or for development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for getting token includes generating it from your backend server which will help in **keeping your credentials safe**.
:::

#### 2. Generating token in your backend

- Your server will generate access token using your API key and secret.
  - While generating a token, you can provide **expiration time, permissions and roles** which are discussed later in this section.
- Your client obtains token from your backend server.
- For token validation, client will pass this token to VideoSDK server.
- VideoSDK server will only allow entry in the meeting if the token is valid.

![img2.png](../../static/img/authentication-and-token.png)




Follow our official example repositories to setup token API [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)

### Payload while generating token

```js
{
 apikey: API_KEY, //MANDATORY
 permissions: [`allow_join`], //`ask_join` || `allow_mod` //MANDATORY
 version: 2, //OPTIONAL
 roomId: ROOM_ID, //OPTIONAL,
 participantId: PARTICIPANT_ID, //OPTIONAL
 roles: ['crawler', 'rtc'], //OPTIONAL
}
```

- **`apikey`(Mandatory)**: This must be the API Key generated from the VideoSDK Dashboard. You can get it from [here](https://app.videosdk.live/api-keys).

- **`permissions`(Mandatory)**: By providing the permissions, you can control what a participant can do in the meeting and whether he can join the meeting directly.

  Available permissions are:

  - **`allow_join`**: The participant is **allowed to join** the meeting directly.
  - **`ask_join`**: The participant is required to **ask for permission to join** the meeting. The participant having the permission `allow_join` can accept or reject a participant whenever someone wants to join.
  - **`allow_mod`**: The participant is **allowed to toggle** webcam & mic of other participants.

- **`version`(optional)**: For accessing the [v2 API](/api-reference/realtime-communication/intro), you need to provide `2` as the version value.

  - For passing `roomId`, `participantId` or `roles` parameters in payload, it is essential to set the version value to `2`.

- **`roomId`(optional)**: To provide customised access control, you can make the token applicable to a particular room by including the `roomId` in the payload.

- **`participantId`(optional)**: You can include the `participantId` in the payload to limit the token's access to a particular participant.

- **`roles`(optional)**:

  - **`crawler`**: This role is only for accessing [v2 API](/api-reference/realtime-communication/intro), you can not use this token for running the `Meeting`/`Room`.
  - **`rtc`**: This role is only allowed for running the `Meeting` / `Room`, with this role you can not use [server-side APIs](/api-reference/realtime-communication/intro).

Then, you have to sign this payload with your **`SECRET KEY`** and `jwt` options using the **`HS256 algorithm`**.

### Expiration time

You can set any expiration time to the token. But in the **production environment**, it is recommended to generate a token with **short expiration time** because by any chance if someone gets hold of the token, it won't be valid for a longer period of time.

### What happens if token is expired?

If your token is expired, the user won't be able to join the meeting and all the API calls will give error with message `Token is invalid or expired`.

:::note
Token is validated only once while joining the meeting, so if a person joins the meeting and the token gets expired after that, there won't be any issue in the current meeting.
:::

## How to check validity of token?

1. After generating the token, visit [jwt.io](https://jwt.io) and paste your token in the given area.
2. You will be able to see the payload you passed while generating the token and also be able to see the expiration time and token creation time.

![img1.png](../../static/img/validate-token.png)

## API Settings & Controls

The VideoSDK Dashboard provides a powerful [API Settings](https://app.videosdk.live/api-keys) section where you can configure various services and controls for your meetings. These settings allow you to customize the behavior of different features directly from the dashboard without requiring code changes.

## Audio/Video Configurations

:::note
Runtime configuration from the dashboard has higher precedence than static SDK configurations.
If a value is modified in the dashboard, it will override any previously defined SDK settings for that session.

Example:
Code: Video = HD → Dashboard: Video = Full HD → Applied: Full HD
:::

### Maximum Send Bitrate Per Participant

Control the maximum total upload bandwidth for all media streams from a single participant.

![Maximum Send Bitrate](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.00.11%E2%80%AFPM.png)

**Available Options:**
- **Auto**: Removes the upload bitrate limit (recommended for best quality)
- **SD (800kbps)**: Standard definition bitrate
- **HD (1500kbps)**: High definition bitrate
- **Full HD (3000kbps)**: Full high definition bitrate

:::tip
Setting this to **Auto** provides the best video quality as it removes upload bitrate constraints, allowing adaptive streaming based on network conditions.
:::

## Recording & Streaming Configuration

:::note
Recording and HLS follow a precedence-based configuration model:

API/SDK configuration → Highest priority
Dashboard configuration → Used only when no API values are defined

Any parameters explicitly set via the API will not be overridden by dashboard changes.
:::

### Recording Configuration

Configure recording settings for your meetings including layout, quality, and auto-start options.

![Recording Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.01.00%E2%80%AFPM.png)

**Recording Controls:**
- **Enabled**: Toggle to enable/disable recording functionality
- **Enabled Modes**: Choose between Video & Audio or Audio Only recording
- **Start Recording Automatically**: Auto-start recording when meeting begins
- **Layout Style**: Select Grid layout for recording composition
- **Maximum Tiles In Grid**: Set the number of participants visible in grid (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme for recordings
- **Video Orientation**: Choose between Landscape or Portrait mode
- **Recording Quality**: Select quality level (e.g., HD Medium)
- **Recording Mode**: Choose between Video & Audio or Audio Only

### HLS Streaming Configuration

Configure HTTP Live Streaming (HLS) settings for broadcasting your meetings.

![HLS Streaming Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.02.18%E2%80%AFPM.png)

**HLS Streaming Controls:**
- **Enabled**: Toggle to enable/disable HLS streaming
- **Enabled Modes**: Choose between Video & Audio or Audio Only streaming
- **Auto Start HLS**: Automatically start HLS when meeting begins
- **Record HLS Stream**: Enable recording of the HLS stream
- **Layout Style**: Select Grid layout for stream composition
- **Maximum Tiles In Grid**: Set the number of participants visible (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme
- **HLS Orientation**: Choose between Landscape or Portrait mode
- **HLS Quality**: Select streaming quality (e.g., HD Medium)
- **HLS Streaming Mode**: Choose between Video & Audio or Audio Only

### Additional Service Controls

Enable or disable additional services for your API key.

![Service Controls](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.08%E2%80%AFPM.png)

**Available Services:**
- **RTMP Output**: Enable RTMP streaming to external platforms
- **SIP Integration**: Enable SIP (Session Initiation Protocol) integration for telephony
- **Realtime Translation**: Enable real-time language translation in meetings

### Transcription & Summary

Configure transcription and domain whitelisting for your API key.

![Transcription Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.50%E2%80%AFPM.png)

**Transcription Controls:**
- **Enabled**: Toggle to enable/disable transcription and summary features
- **Whitelist Domain**: Add domain restrictions for API key usage
  - Enter domain names in the format `https://domain.name`
  - Click "Add Domain" to whitelist specific domains
  - Only whitelisted domains can use this API key
  - When no domains are whitelisted, the API key can be used from any domain


---

# Authentication and Token

VideoSDK uses access tokens for authentication. Using our dashboard ([app.videosdk.live](https://app.videosdk.live/)), anyone can generate access tokens tokens with an API key and secret pair.

- Your backend server will generate access tokens using API Key and secret.
- Your client obtains token from your backend server.
- Your client will pass the token to VideoSDK server.
- VideoSDK client sdk will conncts to the VideoSDK server with available token.
- VideoSDK server will validate the token and accpets your incoming connection.

Here is the simple sequence diagram represents the authentication.


## Generate API Key and Secret

Visit, [app.videosdk.live](https://app.videosdk.live/) to gererate API Key and secret.

![Generate API Key from Dashboard](/img/tutorial/generate-api-key.jpg)

## Generate Access Token

For security, every participant that connects to meeting needs a access token. By substituting `apikey` and `permissions` in it.



**node:**

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

// Need to generate from app.videosdk.live
const API_KEY = "API_KEY_GENERATED";
const SECRET_KEY = "API_SECRET_KEY_GENERATED";

jwt.sign(
  {
apikey: API_KEY,
permissions: ["allow_join"], // Permission to join the meeting
  },
  SECRET_KEY,
  {
algorithm: "HS256",
expiresIn: "24h",
jwtid: uuid4(),
  },
  function (err, token) {
console.log(token);
  }
);
```

---

**python:**

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

api_key = 'api_key_generated'
secret_key = 'secret_key_generated'


def generateToken():
expires = 24 * 3600
now = datetime.datetime.utcnow()
exp = now + datetime.timedelta(seconds=expires)
return jwt.encode(payload={
      'apikey': api_key,
      permissions: ["allow_join"]
    }, key=secret_key).decode('utf-8')

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

---

**java:**

```js
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("apikey", "<api_key_generated>");
payload.put("permissions", ["allow_join"]);
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, "<secret_key_generated>".getBytes()).compact();
  }
```

---

**ruby:**

```js
require 'jwt'
require 'securerandom'

$api_key = "api_key_generated"
$secret_key = "secret_key_generated"

def generateToken()
payload = {
  apikey: $api_key,
  permissions: ["allow_join"]
}
token = JWT.encode(payload, $secret_key, 'HS256')
return token
end

puts generateToken
```

---

**php:**

```js
<?php

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

$api_key = "api_key_generated";
$secret_key = "secret_key_generated"

$payload = [
'apikey' => api_key,
'permissions': ["allow_join"],
];

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

Available permissions are:

- **allow_join**: The participant will be permitted entry without request.
- **ask_join**: The participant will not be permitted entry without request.
- **allow_mod**: Allow participant to enable/disable other participant's mic/webcam.


---

# Monitoring Call Quality - Javascript

Monitoring the local participant’s call quality is essential to ensure a smooth and uninterrupted meeting experience. Changes in network conditions or device performance can directly affect audio and video quality. By subscribing to the **`quality-limitation`** event, your app can detect these changes in real-time and provide immediate feedback to the participant.

## Why It Matters

Even brief network congestion, low bandwidth, or high CPU usage can impact the meeting experience. Monitoring these limitations allows your app to:

- Notify the local participant of potential issues affecting audio or video quality.
- Empower the participant to take action, like switching networks or closing other heavy applications.

## Example Usage

```js
meeting.on("quality-limitation", ({ type, state, timestamp }) => {
  const time = new Date(timestamp).toLocaleTimeString();
  console.log(`[${time}] quality-limitation : ${type}-${state}`);
  
  if (state === "detected") {
    alert(`Your ${type} may be affecting call quality.`);
  } else if (state === "resolved") {
    console.log(`${type} limitation has been resolved.`);
  }
});
```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [quality-limitation](/javascript/api/sdk-reference/meeting-class/events#quality-limitation)



---

# Monitoring Remote Participants' Stream - JavaScript

Monitoring the state of a remote participant’s stream helps ensure a consistent and high-quality meeting experience. The **`state`** event on the stream object provides real-time updates whenever the condition of a remote video or screenshare video stream changes — allowing your app to detect issues and respond accordingly.

By subscribing to this event, you can track when a stream becomes active, stuck, or experiences a freeze, and take corrective actions or inform users as needed.

:::note
This event is emitted exclusively for remote participants, specifically for their video and screen share video streams.
:::

## Why It Matters

Stream state monitoring is crucial for maintaining call reliability and diagnosing issues that affect the remote participant’s media. Using this event, you can:

- Detect when a remote participant’s video freezes or becomes stuck.
- Notify local participants about possible issues.
- Log state transitions for diagnostics or quality metrics.

## Example Usage

```javascript
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // Configuration options
});

meeting.on("participant-joined", (participant) => {
  participant.on("stream-enabled", (stream) => {
    stream.on("state", ({ state, timestamp }) => {});
  });
});
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [state](/javascript/api/sdk-reference/stream-class/events#state)


---

# Chat using PubSub - Javascript

For communication or any kind of messaging between participants, VideoSDK provides the `pubSub` property, which utilizes the Publish-Subscribe mechanism. It can be employed to develop a wide variety of functionalities. For example, participants could use it to send chat messages to each other, share files or other media, or even trigger actions like muting or unmuting audio or video.

This guide focuses on using PubSub to implement Chat functionality. If you are not familiar with the PubSub mechanism and `pubSub`, you can [follow this guide](./pubsub).

## Implementing Chat

### `Group Chat`

1. The initial step in setting up a group chat involves selecting a topic to which all participants will publish and subscribe, facilitating the exchange of messages. In the following example, `CHAT` is used as the topic. 
Next step is to create a message input and a send button to publish the messages using the `pubSub` method from the `meeting` object.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const msgSendBtn = document.getElementById("msgSendBtn");

//publish chat meesage on button click
msgSendBtn.addEventListener("click", async () => {
  const message = document.getElementById("txtChat").value;

  document.getElementById("txtChat").value = "";

  meeting.pubSub
    .publish("CHAT", message, { persist: true })
    .then((res) => console.log(`response of publish : ${res}`))
    .catch((err) => console.log(`error of publish : ${err}`));
});
```

2. The final step in the group chat is to display the messages sent by others. For this use the `messages` array and display all the messages.

```js
//subscribe to the 'CHAT' on meeting join
meeting.on("meeting-joined", async () => {
  let oldMessages = await meeting.pubSub.subscribe("CHAT", (data) => {
    let { message, senderId, senderName, timestamp } = data;

    const chatBox = document.getElementById("chatArea");

    const chatTemplate = `
        <div style="margin-bottom: 10px; ${
          meeting.localParticipant.id == senderId && "text-align : right"
        }">
          <span style="font-size:12px;">${senderName}</span>
          <div style="margin-top:5px">
            <span style="background:${
              meeting.localParticipant.id == senderId ? "grey" : "crimson"
            };color:white;padding:5px;border-radius:8px">${message}<span>
          </div>
        </div>
        `;

    chatBox.insertAdjacentHTML("beforeend", chatTemplate);
  });

  // Getting Old messages for upcoming participant
  console.log("OLD Message", oldMessages);
});
```

### `Private Chat`

In the above example, to convert the chat into a private one between two participants, set the `sendOnly` property.

```js
  // ... 
  //publish chat meesage on button click
  msgSendBtn.addEventListener("click", async () => {
    const message = document.getElementById("txtChat").value;

    document.getElementById("txtChat").value = "";

    // Pass the participantId of the participant to whom you want to send the message.
    meeting.pubSub
      //highlight-next-line
      .publish("CHAT", message, { persist: true , sendOnly : ['XYZ']} )
      .then((res) => console.log(`response of publish : ${res}`))
      .catch((err) => console.log(`error of publish : ${err}`));
  });
```

## Downloading Chat Messages

All the messages from PubSub published with `persist : true` can be downloaded as an `.csv` file. This file will be available in the VideoSDK dashboard as well as throught the [Sessions API](/api-reference/realtime-communication/fetch-session-using-sessionid).

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [PubSub](/javascript/api/sdk-reference/meeting-class/pubsub)


---

# DataStream - Javascript

DataStream enables participants in a meeting to exchange arbitrary data—such as text, signals, or binary payloads—directly alongside audio and video. Unlike PubSub (which is topic-based), DataStream provides a lightweight, low-level way to send messages, files, or binary data between participants.

This is particularly useful when you need **low-latency communication**, such as collaborative tools, quick signals, or real-time updates.

To utilize a DataStream in a meeting, VideoSDK provides methods and events on the `meeting` object. You can send messages via the `send()` method, and listen for incoming messages with the `data` event.

## `send()`

The `send()` method is used to transmit data directly over the DataStream to all connected participants in a meeting. It supports both **textual data** (like strings) and **binary data** (like ArrayBuffer, Blob), making it suitable for chat messages, control signals, file chunks, or real-time data.

### Key Notes

- Works at the **transport layer**, bypassing topics/persistence (unlike PubSub).
- Supports two reliability modes: `"reliable"` (guaranteed delivery, may increase latency) and `"unreliable"` (best effort, lower latency).
- The maximum payload size is **15 KiB** per message. Larger data (like files) should be chunked before sending.
- If the connection cannot send the message or payload type is invalid, the method will throw an error.

### Parameters

- **`payload`** (`string | Blob | ArrayBuffer | ArrayBufferView`)
  The message/data to send.
  Examples:

  - String: `"Hello world!"`
  - Binary: `new Uint8Array([72, 101, 108, 108, 111])`

- **`options`** (`object`, optional)

  - **`reliability`** (`"reliable" | "unreliable"`)

    - `"reliable"`: Ensures the data eventually arrives, even under poor network conditions.
    - `"unreliable"`: Prioritizes low-latency; packets may drop during loss.

### Returns

- **`Promise<boolean>`**

  - Resolves to `true` → The message send request was made.
  - Resolves to `false` → Sending failed (payload too large, invalid type, or network issue).

### Example

```js
try {
  window.VideoSDK.config(TOKEN);

  const meeting = window.VideoSDK.initMeeting({
    meetingId: meetingId, // required
    name: "Thomas Edison", // required
    micEnabled: true, // optional, default: true
    webcamEnabled: true, // optional, default: true
  });

  const sent = await meeting.send("Hello world!", {
    reliability: window.VideoSDK.Constants.reliabilityMode.RELIABLE,
  });

  if (sent) {
    console.log("Message send request was made");
  } else {
    console.log("Message could not be sent");
  }
} catch (e) {
  console.log("Something went wrong while sending data", e);
}
```

---

## `data` Event

The `data` event is emitted whenever a message is received over the DataStream.
It provides both the **content** and **metadata** so you can process messages accordingly.

### Callback Parameters

- **`payload`** (`Uint8Array` | `string`)  
  The actual data received from the sender.

  - If the sender transmitted a string, the payload will already be a string.
  - If the sender transmitted binary data (ArrayBuffer, Blob, etc.), the payload will be a `Uint8Array` that you can process directly or decode.

- **`timestamp`** (`number`)
  The time (in milliseconds since epoch) when the message was sent. Useful for ordering or debugging delays.

- **`from`** (`string`)
  The unique identity (`participantId`) of the sender.

- **`reliability`** (`"reliable" | "unreliable"`)
  Indicates whether the sender used reliable or unreliable delivery mode.

### Example

```js
// Example Usage

meeting.on("data", (dataMessage) => {
  const { payload, timestamp, from, reliability } = data;
});
```

:::note
- Participants in **`send_and_recv`** mode can both **send and receive** DataStream messages. However, they are the only ones permitted to send.  
- Participants in **`recv_only`** mode (as well as those in **`send_and_recv`**) can **receive** messages.  
:::


## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [send()](/javascript/api/sdk-reference/meeting-class/methods#send)
- ["data"](/javascript/api/sdk-reference/meeting-class/events#data)




---

# Image Uplaod Using Pubsub - Javascript

This guide will show you how to upload an image using Pubsub. To do so, we first create an input with the file type, then select an image and upload it using Pubsub.

If you are not familiar with the PubSub mechanism, you can [follow this guide](https://docs.videosdk.live/javascript/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

We will achieve this using the following steps.

### Step 1 : Create input with file type

- Firstly, we place input for the upload file.

```html title="index.html"
<div>
  <input
    type="file"
    id="myFile"
    name="filename"
    onchange="handleImageUpload(event)"
  />
</div>
```

### Step 2 : Send image using PubSub

- In this step, we will create `handleImageUpload()` In this, we will convert the image into `base64`, and then we divide that data into chunks.

- After that, we will publish image using `IMAGE_TRANSFER` pubsub topic.

:::note

If you want to send a image that is larger than 3 MB, you must increase the chunkSize.

:::

```js title="index.js"
function uploadImage({ data }) {
  // Chunk size, you can change it according to your requirements
  const chunkSize = 100; // bits

  // Total Chunks
  const chunks = splitStringIntoChunks(data, chunkSize);

  // Random String
  const result = Math.random().toString(36).substring(2, 7);

  // Iterate chunk
  for (let i = 0; i < chunks.length; i++) {
    const element = chunks[i];

    // Payload
    const data = {
      index: i,
      totalChunk: chunks.length,
      chunkdata: element,
      id: result.toString(),
    };

    // publish on `IMAGE_TRANSFER` topic
    meeting.pubSub.publish("IMAGE_TRANSFER", data);
  }
}

// splits data into chunks
function splitStringIntoChunks(str, chunkSize) {
  const chunks = [];
  let index = 0;

  while (index < str.length) {
    chunks.push(str.substring(index, index + chunkSize));
    index += chunkSize;
  }

  return chunks;
}

const handleImageUpload = (event) => {
  const file = event.target.files[0];
  var reader = new FileReader();
  reader.readAsDataURL(file);
  reader.onloadend = function () {
    var base64data = reader.result;
    uploadImage({ data: base64data });
  };
};
```

### Step 3 : Create Pubsub topic

- Firstly, we will create `IMAGE_TRANSFER` Pubsub topic at receiver end for receiving image.

- Now, we will create `handleImageTransfer()` for storing sender chunks data and generate an image on the basis of that data.

```js title="index.js"
const generateImage = (messages) => {
  // Getting src of image
  const srcImage = messages
    .sort((a, b) => parseInt(a.index) - parseInt(b.index))
    .map(({ chunkdata }) => chunkdata)
    .join("");

  // Creating image element
  const imgElement = document.createElement("img");
  imgElement.src = srcImage;
  imgElement.height = 300;
  imgElement.width = 300;

  const textElement = document.createElement("p");
  textElement.textContent = "Selected Image";

  // Appending image element to image container
  document.getElementById("imageContainer").appendChild(textElement);
  document.getElementById("imageContainer").appendChild(imgElement);
};

const handleImageTransfer = ({ message }) => {
  const { id, index, totalChunk } = message;

  // If you select multiple images, then it will store images on basis of id in imagesMessages object
  if (imagesMessages[id]) {
    imagesMessages[id].push(message);
  } else {
    imagesMessages[id] = [message];
  }

  if (index + 1 === totalChunk) {
    generateImage(imagesMessages[id]);
  }
};
```

- Now, we will subscribe to `IMAGE_TRANSFER` topic on `meeting-joined` event for receiving image.

```js title="index.js"
meeting.on("meeting-joined", () => {
  //...

  // subscribe to IMAGE_TRANSFER topic
  meeting.pubSub.subscribe("IMAGE_TRANSFER", handleImageTransfer);
});
```

- After that, we will unsubscribe this topic on meeting-left event for cleanup data.

```js title="index.js"
meeting.on("meeting-left", () => {
  //...

  // clearing images
  meeting.pubSub.unsubscribe("IMAGE_TRANSFER", handleImageTransfer);
});
```


---

# PubSub - Javascript

PubSub is a concise acronym for the Publish-Subscribe mechanism. This mechanism is employed to send and receive messages within a specified topic. As the name implies, to send a message, one must specify the topic and the message to be published. Similarly, to receive a message, a subscriber must be connected to that particular topic.

Here is a visual to better understand the publish-subscribe mechanism.

![pubsub](/img/pubsub.png)

To utilize PubSub in a meeting, VideoSDK provides a property called `pubSub`. This enables you to subscribe to any topic and publish to any topic, facilitating the exchange of messages and instructions seamlessly during the meeting.

### `publish()`

- This method is used for publishing a message for a specific topic.
- It can be accessed from the `pubSub` property by specifying the `topic` for which `publish()` will be used.
- It will accept following parameters as input:
  - `message`: This parameter represents the actual message to be published and should be in `String` format.
  - `options`: This object specifies the options for publishing. You can set following properties :
    - `persist` : When set to true, this option retains the message for the duration of the session. If persist is true, the message will be available for upcoming participants and can be accessed in the [VideoSDK Session Dashboard](https://app.videosdk.live/meetings/sessions) in CSV format after the session is completed.
    - `sendOnly`: If you want to send a message to specific participants, you can pass their respective `participantId` in the form of `Array<String>` here. If you don't provide any IDs, the message will be sent to all participants by default.
  - `payload`: If you need to include additional information along with a message, you can pass it here as an `object`.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const topic = "CHAT";

const publishChat = (message) => {
  //
  try {
   await  meeting?.pubSub.publish(topic, message, { persist: true });
  } catch (e) {
    console.log("Error while sending message through pubsub", e);
  }
};

publishChat("Hello world!");
```

### `subscribe()`

- This method serves a dual purpose. Firstly, it is employed to retrieve all previously sent messages associated with a particular `topic`. Additionally, it can be used to subscribe to a particular `topic`.

- By providing the topic to be subscribed to and a callback function, it ensures that all future messages related to the subscribed topic are received and processed when they arrive.

- The callback function will contain the following properties:
- `senderId`: Represents the `participantId` of the participant who sent the message.
- `senderName`: Represents the `displayName` of the participant who sent the message.
- `message`: The actual message that was sent.
- `timestamp`: The timestamp for when the message was published.
- `topic`: The name of the topic the message was published to.
- `payload`: The data that was sent along with message.

## Example

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

// Callback function
function onMessageReceived(data) {
  let { message, senderId, senderName, timestamp } = data;
  console.log(`New message received: ${message}`);
}

async function subscribe() {
  // Subscribe 'CHAT' topic
  let oldMessages = await meeting?.pubSub?.subscribe("CHAT", onMessageReceived);

// Getting Old messages for upcoming participant
  console.log(oldMessages);

```

## Applications of PubSub

PubSub is a very powerful mechanism which can be used to do a lot of things which can make your meeting experience much more interactive. Some of the most common usecase that we have come across for the PubSub during a meeting are listed below:

1. [`Chat`](./chat-using-pubsub): You can utilise this to develop features, like Private Chat or Group Chat. You can follow our chat [integration guide here](./chat-using-pubsub).
2. `Raise Hand`: You can allow attendees to raise their hands at any point during the meeting, informing everyone else that someone has a question or input.
3. `Layout Switching`: You can change the meeting's layout for every participant at once during the meeting, such as from Grid layout to Spotlight or from Grid Layout to Sidebar, etc.
4. [`Whiteboard`](/react/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/canvas-drawing-using-pubsub): You can develop an interactive whiteboard functionality that is completely functional. You can follow our canvas drawing [guide here](/react/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/canvas-drawing-using-pubsub).
5. `Poll`: You can make polls, let users respond to them, and display the results at the end of a poll.
6. `Question Answer Session`: You can also design interactive features based on a question-and-answer format.

## Downloading PubSub Messages

All the messages from PubSub published with `persist : true` can be downloaded as an `.csv` file. This file will be accessible in the VideoSDK dashboard and through the [Sessions API](/api-reference/realtime-communication/fetch-session-using-sessionid).

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [PubSub](/javascript/api/sdk-reference/meeting-class/pubsub)


---

# Realtime Store - JavaScript

The **Realtime Store** allows you to store, update, retrieve, and observe custom key-value data within a meeting — in real time. It acts as a shared data layer across all connected participants, ensuring synchronized states throughout the session.

This is particularly useful for collaborative or stateful meeting experiences such as:

- Pinned messages and flags
- Moderation data (e.g., blocked users)
- Collaborative notes or polls

## `setValue()`

The `setValue()` method is used to store or update data in the RealtimeStore. If a key already exists, it will be overwritten with the new value. Passing `null` as the value deletes the key.

### Key Notes

- Supports **string** values only.
- Each key can store up to **1 KB** of data.
- A maximum of **100 keys** are allowed per session.
- Deletion is performed by setting the value to `null`.
- Throws an error if:
  - The key or value is missing or not of type **string**.
  - The request fails.
  - The session exceeds the 100-key limit.

### Parameters

- **`key`** (`string`)  
  The unique key to store the data under.

- **`value`** (`string | null`)  
  The string value to be stored. Pass `null` to delete the key.

### Returns

- **`Promise<void>`**

### Example

```js
try {
  await meeting.realtimeStore.setValue("Blocked_Students", "[Halima,Rajan]");
  console.log("Data set successfully!");
} catch (error) {
  console.error("Failed to set data:", error);
}
```

---

## `getValue()`

The `getValue()` method retrieves the current value associated with a given key.

### Key Notes

- Returns the current string value for the given key
- Useful for fetching shared state when joining a meeting or reloading a view.
- Throws an error if the key is missing or if the request fails.

### Parameters

- **`key`** (`string`)
  The key whose value you want to retrieve.

### Returns

- **`Promise<string | null>`** — The stored value or `null` if there was a problem fetching the value.

### Example

```js
try {
  const value = await meeting.realtimeStore.getValue("Blocked_Students");
  console.log("Current value:", value);
} catch (error) {
  console.error("Failed to get data:", error);
}
```

---

## `observe()`

The `observe()` method subscribes to real-time updates for a given key. When the key’s value changes, the callback is automatically triggered for all connected participants.

### Key Notes

- Returns an `observerId` which you can later use to stop observing.
- The callback receives the new value and information about who updated it.
- Ideal for syncing live data like timers, shared notes, or agendas.

### Parameters

- **`key`** (`string`)
  The key to observe.

- **`callback`** (`function`)
  Function triggered on each update. Receives:

  - `value` (`string | null`) → Updated value or `null` if deleted
  - `updatedBy` (`string`) → ID of the participant who made the update

### Returns

- **`Promise<string>`** — Unique observer ID.

### Example

```js
try {
  const observerId = await meeting.realtimeStore.observe(
    "Blocked_Students",
    (value, updatedBy) => {
      console.log("Value updated:", value, "by", updatedBy);
    }
  );
} catch (error) {
  console.error("Failed to observe key:", error);
}
```

---

## `stopObserving()`

Stops receiving updates for a specific observer ID.

### Key Notes

- Should be called when the listener is no longer needed (e.g., component unmount).

### Parameters

- **`observerId`** (`string`)
  The observer ID returned from `observe()`.

### Returns

- **`Promise<void>`**

### Example

```js
try {
  await meeting.realtimeStore.stopObserving(observerId);
  console.log("Stopped observing successfully!");
} catch (error) {
  console.error("Failed to stop observing:", error);
}
```

---

### ⚠️ Error Handling & Constraints

| Property           | Description                                                           |
| ------------------ | --------------------------------------------------------------------- |
| **Error Handling** | All RealtimeStore methods throw directly; wrap them in `try...catch`. |
| **Payload Size**   | Maximum **1 KB per key**.                                             |
| **Supported Type** | Only `string` values are supported. Use `null` to delete key.         |
| **Concurrency**    | The latest write overwrites previous values (last write wins)         |
| **Key Limit**      | A maximum of 100 keys are allowed in a single session.        |

## API Reference

The API references for all the methods utilized in this guide are provided below:

- [setValue()](/javascript/api/sdk-reference/meeting-class/realtimeStore#setvalue)
- [getValue()](/javascript/api/sdk-reference/meeting-class/realtimeStore#getvalue)
- [observe()](/javascript/api/sdk-reference/meeting-class/realtimeStore#observe)
- [stopObserving()](/javascript/api/sdk-reference/meeting-class/realtimeStore#stopobserving)


---

---
title: Upload & Fetch Temporary File | Video SDK
hide_title: true
hide_table_of_contents: false
description: Upload & Fetch Temporary File.
sidebar_label: File Sharing
pagination_label: Upload-Fetch Temporary File
keywords:
  - upload temporary file
  - fetch temporary file
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: upload-fetch-temporary-file
--- 

# Upload and Retrieve the Temporary File - Javascript

This guide demonstrates how to upload and retrieve files from VideoSDK's temporary file storage system.

### `uploadBase64File()`

- By using the `uploadBase64File()` function of the `Meeting` class, you can upload your file to Videosdk's Temporary storage.

- The `uploadBase64File()` function only works with `base64`. Therefore, it is necessary to convert your file into `base64` format.

- You have to pass `base64Data`,`token`,`fileName` as parameter in `uploadBase64File()` function.

- The function will return the corresponding `fileUrl`, which you can then use to retrieve the file.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const fileUrl = await meeting.uploadBase64File({
  base64Data: "<Your File's base64>", // Convert your file to base64 and pass here
  token: "<VIDEOSDK_TOKEN>",
  fileName: "myImage.jpeg", // Provide name with extension here,
});
```

### `fetchBase64File()`

- By using the `fetchBase64File()` method of the `Meeting` class, you can retrieve your file from the Videosdk's Temporary storage.

- You have to pass the `fileUrl` which is returned by `uploadBase64File()` function, and the `token` as parameters to retrieve a file.

- This method will return the image in the form of `base64`.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

let base64 = await meeting.fetchBase64File({
  url: "<Your FileUrl>"; // Provide fileUrl which is returned by uploadBase64File(),
  token :"<VIDEOSDK_TOKEN>",
});

console.log("base64", base64);
```

:::note

The file stored in the system will be automatically deleted once the current room/meeting comes to an end.

:::


---

# Whiteboard - JavaScript

A whiteboard is a digital canvas that allows users to collaborate in real-time by drawing, writing, and sharing ideas visually, making it ideal for brainstorming, presentations, and teamwork.

Before initiating a whiteboard session, it is essential to have an active **VideoSDK Meeting** in progress.

## Starting the Whiteboard

To start the whiteboard during a meeting, invoke the `startWhiteboard()` method on the `meeting` object. This will trigger the `whiteboard-started` event.

Upon successful execution, the `whiteboard-started` event will return a `url`.

You can embed the `url` into an `<iframe>` or integrate it as a component in your application to display the whiteboard session.

## Stopping the Whiteboard

To stop the whiteboard session, call the `stopWhiteboard()` method on the `meeting` object. This will trigger the `whiteboard-stopped` event, halting the whiteboard for all participants.

## Example

```javascript
let meeting;

meeting = VideoSDK.initMeeting({
  //... Initialization parameters
});

const startWhiteboardBtn = document.getElementById("startWhiteboard");
const stopWhiteboardBtn = document.getElementById("stopWhiteboard");

// Start Whiteboard
startWhiteboardBtn.addEventListener("click", () => {
  meeting?.startWhiteboard();
});

// Handle Whiteboard Start Event
meeting.on("whiteboard-started", (data) => {
  const { url } = data;
  const iframe = document.createElement("iframe");
  iframe.src = url;
  iframe.width = "500px";
  iframe.height = "500px";
  iframe.frameBorder = "0";

  const container = document.getElementById("whiteboard-container");
  if (container) {
    container.innerHTML = "";
    container.appendChild(iframe);
  } else {
    console.error("Whiteboard container not found");
  }
});

// Stop Whiteboard
stopWhiteboardBtn.addEventListener("click", () => {
  meeting?.stopWhiteboard();
});

// Handle Whiteboard Stop Event
meeting.on("whiteboard-stopped", () => {
  const container = document.getElementById("whiteboard-container");
  if (container) {
    container.innerHTML = "";
    document.body.removeChild(container);
  } else {
    console.error("Whiteboard container not found");
  }
});
```

#### Events Associated with `startWhiteboard()` and `stopWhiteboard()`

- **`whiteboard-started`**: Fired when the whiteboard is successfully started and it will return the url.

- **`whiteboard-stopped`**: Fired when the whiteboard session is stopped for all participants.

```js
meeting.on("whiteboard-started", (data) => {
  const { url } = data;
  console.log("Whiteboard Started Successfully", url);
});

meeting.on("whiteboard-stopped", () => {
  console.log("Whiteboard Stopped Successfully");
});
```

## Final Output


<div style={{textAlign: 'center'}}>



</div>

## API Reference

- [startWhiteboard()](../../../api/sdk-reference/meeting-class/methods.md#startwhiteboard)
- [stopWhiteboard()](../../../api/sdk-reference/meeting-class/methods.md#stopwhiteboard)
- [whiteboard-started event](../../../api/sdk-reference/meeting-class/events.md#whiteboard-started)
- [whiteboard-stopped event](../../../api/sdk-reference/meeting-class/events.md#whiteboard-stopped)


---

# Concept and Architecture - Javascript

Before diving into the concept, it's essential to understand the VideoSDK. VideoSDK is a software development kit that offers tools and APIs for creating apps that are based on video and audio. It typically includes features such as video and audio calls, chat, cloud recording, simulcasting (RTMP), interactive live streaming (HLS), and many more across a wide range of platforms and devices.

## Concepts

![img.png](../../../../static/img/room-concept.png)

### `1. Meeting / Room`

- Meeting or Room object in the VideoSDK provides a virtual place for participants to interact and engage in real-time voice, video, and screen-sharing sessions. The object is in charge of handling media streams and participant communication.

- Meeting or Room can be uniquely identified by `meetingId` or `roomId`.

### `2. Participant`

- Participant is a VideoSDK object that represents each user/client in the meeting or room and allows them to share audio/video assets.

- `2.1 Local Participant` :
  The local participant is the one that runs on the user's device. The local participant has control over their own media streams, including the ability to start and stop audio and video.

  - The local participant in a meeting/room can also connect with other participants by transmitting and receiving audio and video streams, exchanging chat messages, and more.

- `2.2 Remote Participant` :
  The remote participant receives audio and video streams from both the local participant and other remote participants. Additionally, they have the ability to exchange audio, video, and chat messages with the local participant.

- Each participant in VideoSDK can be uniquely identified by `participantId`.

### `3. MediaStream & Track`

- A mediastream is a collection of audio & video tracks that can be transmitted between participants in real-time.

- A track is a continuous flow of audio or video data and can be thought of as a stream of media frames.

- A mediastream can contain multiple tracks. One video track for the video feed from the camera and one audio track for the audio feed from the microphone. These tracks can be transmitted between participants in VideoSDK Meeting / Room.

### `4. Events / Notifications`

- Events / Notifications can be used to inform users about various activities happening in a Meeting / Room, including participant join/leave and new messages. They can also be used to alert users about any SDK-level errors that occur during a call.

### `5. Session`

- A Session is the instance of an ongoing meeting/room which has one or more participants in it. A single room or meeting can have multiple sessions.
- Each session can be uniquely identified by `sessionId`.

![img.png](../../../../static/img/meeting-session.jpg)

---

![img.png](../../../../static/img/recording-hls-rtmp.png)

### `6. Cloud Recording`

- Cloud recording in VideoSDK refers to the process of recording audio or video content and storing it on a remote server or VideoSDK server.

### `7. Simulcasting (RTMP)`

- RTMP is a popular protocol for live streaming video content from the VideoSDK to platforms such as YouTube, Twitch, Facebook, and others.
- By providing the platform-specific `stream key` and `stream URL`, the VideoSDK can connect to the platform's RTMP server and transmit the live video stream.

### `8. Http Live Streaming (HLS)`

- Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

- In an interactive live stream (HLS), viewers can participate in various activities, such as live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

## Architecture

This diagram illustrates the comprehensive flow for implementing video and audio calls, recording calls, and broadcasting live on social media platforms.

![Video-sdk-architecture!](/img/video-sdk-archietecture.svg)


---

# Mute All Participants - Javascript

When hosting a meeting, it's essential for the host to have the capability to mute all the participants at once. This can be useful in various scenarios, such as when the host wants to deliver a presentation or when there is background noise causing distractions. This guide focuses on this very aspect of muting all other participants' microphone.

- To achieve this, iterate over the list of all participants from the `meeting` object and call the `disableMic` method.

```javascript
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const muteAllBtn = document.getElementById("muteAllBtn");

muteAllBtn.addEventListener("click", () => {
  const participants = meeting.participants;
  const participant = participants.get("<participant-id>");

  participants.forEach((participant, participantId) => {
    participant?.disableMic();
  });
});
```

:::note
The Participant with the capability to mute all other participants' microphones, should have permission **`allow_mod`** passed in the token. To know more about permissions [**visit here**](/javascript/guide/video-and-audio-calling-api-sdk/authentication-and-token).
:::

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [disableMic()](/javascript/api/sdk-reference/participant-class/methods#disablemic)


---

# Toggle Remote Participant Media - Javascript

When hosting a meeting, it's essential for the host to have the capability to request that someone's microphone or camera be turned on, or to turn them off as needed. This guide focuses on this very aspect of controlling other participant's media.

:::note
The Participant with the capability to control other participant's media should have permission **`allow_mod`** passed in the token. To know more about permissions [**visit here**](/javascript/guide/video-and-audio-calling-api-sdk/authentication-and-token).
:::

Before delving into the methods and events associated with this functionality, explore how the flow would unfold.

![img1](../../../../../static/img/toggle-remote-media.png)

## Methods

### `enableMic()`

- If the host wishes to activate a participant's microphone, the `enableMic()` method from the `Participant` object should be employed. 

- Upon invoking this method, the participant whose microphone is requested for, will receive the `mic-requested` event. This event contains the `participantId` of the host making the request, along with two callback functions—`accept` and `reject`. The participant can decide to accept or reject the incoming request.

- For instance, if a meeting involves **Participant A** and **Participant B**, and the host (**Participant A**) desires to enable the microphone of **Participant B**, the host will utilize the `enableMic()` function to send a request to **Participant B**. Subsequently, **Participant B** will receive the `mic-requested` event and can choose to either accept or reject the incoming request.

### `enableWebcam()`

- If the host wishes to activate a participant's camera, the `enableWebcam()` method from the `Participant` hook should be employed.

- Upon invoking this method, the participant whose camera is requested for, will receive the `webcam-requested` event. This event contains the `participantId` of the host making the request, along with two callback functions—`accept` and `reject`. The participant can decide to accept or reject the incoming request.

- For instance, if a meeting involves **Participant A** and **Participant B**, and the host (**Participant A**) desires to enable the camera of **Participant B**, the host will utilize the `enableWebcam()` function to send a request to **Participant B**. Subsequently, **Participant B** will receive the `webcam-requested` event and can choose to either accept or reject the incoming request.

### `disableMic()`

- If the host wishes to deactivate a participant's microphone, the `disableMic()` method from the `Participant` object should be employed.

- This will automatically disable the microphone of the participant.

### `disableWebcam()`

- If the host wishes to deactivate a participant's camera, the `disableWebcam()` method from the `Participant` object should be employed.

- This will automatically disable the camera of the participant.

#### Example

```js
const participants = meeting.participants;
const participant = participants.get("<participant-id>");

// Enable remote participant mic
participant?.enableMic();

// Disable remote participant mic
participant?.disableMic();

// Enable remote Webcam mic
participant?.enableWebcam();

// Disable remote Webcam mic
participant?.enableWebcam();
```

## Events

### `mic-requested`

This event is triggered for a participant (`Participant B`) when the host (`Participant A`), requests to enable their microphone. The event handler for this event will receive the following three arguments:

- `accept()` - Callback function to accept the request.
- `reject()` - Callback function to reject the request.
- `participantId` - ParticipantId of the requesting participant.

### `webcam-requested`

This event is triggered for a participant (`Participant B`) when the host (`Participant A`), requests to enable their webcam. The event handler for this event will receive the following three arguments:

- `accept()` - Callback function to accept the request.
- `reject()` - Callback function to reject the request.
- `participantId` - ParticipantId of the requesting participant.

###### Usage

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

meeting.on("webcam-requested", (data) => {
  const { participantId, accept, reject } = data;

  // participantId, will be the id of participant who requested to enable webcam

  // callback function to accept the request
  accept();

  // callback function to reject the request
  reject();
});

meeting.on("mic-requested", (data) => {
  const { participantId, accept, reject } = data;

  // participantId, will be the id of participant who requested to enable webcam

  // callback function to accept the request
  accept();

  // callback function to reject the request
  reject();
});
```


<div style={{textAlign: 'center'}}>



</div>

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [enableMic()](/javascript/api/sdk-reference/participant-class/methods#enablemic)
- [enableWebcam()](/javascript/api/sdk-reference/participant-class/methods#enablewebcam)
- [disableMic()](/javascript/api/sdk-reference/participant-class/methods#disablemic)
- [disableWebcam()](/javascript/api/sdk-reference/participant-class/methods#disablewebcam)
- [webcam-requested](/javascript/api/sdk-reference/meeting-class/events#webcam-requested)
- [mic-requested](/javascript/api/sdk-reference/meeting-class/events#mic-requested)


---

# Remove Participant - Javascript

When hosting a meeting, it's essential for the host to have the capability to to remove a participant from the meeting. This can be useful in various scenarios where a participant is causing disturbance, behaving inappropriately, or is not following meeting guidelines. This guide focuses on this very aspect of removing a particpant from a meeting.

VideoSDK provides three ways to do so:

1. [Using SDK](#1-using-sdk)
2. [Using VideoSDK Dashboard](#2-using-videosdk-dashboard)
3. [Using Rest API](#3-using-rest-api)

## 1. Using SDK

### `remove()`

The `remove()` method allows for the removal of a participant during an on-going session. This can be helpful when moderation is required in a particular meeting.

```js
const participants = meeting.participants;
const participant = participants.get("<participant-id>");

// remove remote participant
participant?.remove();
```

### Events associated with remove()

Following callbacks are received when a participant is removed from the meeting.

- The participant who was removed from the meeting will receive a callback on [`meeting-left`](/javascript/api/sdk-reference/meeting-class/events#meeting-left) event of the **Meeting** Class.
- All other [remote participants](../concept-and-architecture#2-participant) will receive a callback on [`participant-left`](/javascript/api/sdk-reference/meeting-class/events#participant-left) event with the Participant object.

## 2. Using VideoSDK Dashboard

- For removing a participant using the VideoSDK Dashboard, navigate to the session page on [VideoSDK Dashboard](https://app.videosdk.live/meetings/sessions). Select the specific meeting, and from the list of participants, choose the participant you wish to remove. Utilize the provided options to remove the selected participant from the meeting.


<div style={{textAlign: 'center'}}>



</div>

## 3. Using Rest API

- You can also remove a particular participant from the meeting [using the REST API](/api-reference/realtime-communication/remove-participant).
- To employ this method, you need the `sessionId` of the meeting and the `participantId` of the individual you intend to remove.

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [remove()](/javascript/api/sdk-reference/participant-class/methods#remove)
- [meeting-left](/javascript/api/sdk-reference/meeting-class/events#meeting-left)
- [participant-left](/javascript/api/sdk-reference/meeting-class/events#participant-left)


---

# Camera Controls - Javascript

Whenever any participant wants to start/stop broadcasting their video to other participant in a meeting, they can simply do it with VideoSDK Meeting.

This guide will provide an overview of how to implement enable, disable and switch webcam features in a meeting.

1. **Enable Camera** - By using `enableWebcam()` function, a participant can publish camera stream to other participants.
2. **Disable Camera** - By using `disableWebcam()` function, a participant can stop publishing camera stream to other participants.
3. **Switch Camera** - By using `changeWebcam()` function, a participant can stream from front / rear camera during the meeting.This function is only applicable for Mobile devices.

### Enable, Disable And Switch Webcam



```js
const onPress = async () => {
  // Enable Webcam in Meeting
  meeting?.enableWebcam();

  // Disable Webcam in Meeting
  meeting?.disableWebcam();

  // Change Webcam in Meeting
  const webcams = await meeting?.getWebcams(); // returns all webcams

  const { deviceId, label } = webcams[0];

  meeting?.changeWebcam(deviceId);
};
```

### Events

**Events associated with `enableWebcam()`:**

- [`stream-enabled`](../../../api/sdk-reference/participant-class/events.md#stream-enabled) event will be emitted with [`stream`](../../../api/sdk-reference/stream-class/introduction.md) object from the event callback, inside that [participant](../../../api/sdk-reference/participant-class/introduction.md) object.

**Events associated with `disableWebcam()`:**

- [`stream-disabled`](../../../api/sdk-reference/participant-class/events.md#stream-disabled) event will be emitted with [`stream`](../../../api/sdk-reference/stream-class/introduction.md) object from the event callback, inside that [participant](../../../api/sdk-reference/participant-class/introduction.md) object.

```js
participant.on("stream-enabled", (stream) => {
  if (stream.kind === "video") {
    //particiapnt turned on video
    //Render Participant video logic here
  }
});

participant.on("stream-disabled", (stream) => {
  if (stream.kind === "video") {
    //particiapnt turned off video
    //remove Participant video logic here
  }
});
```


---

# Close Connection - Javascript

### Method

- **close** - If you want to close connections with meeting, `connection.close` method is used. This method will not end the connected meetings.

### Event

- **connection-close** - Whenever connection is close between two rooms successfully, this event will trigger in both meeting participants and return `connectionId`.

```js
// Get meeting B connection
const connection = meeting.connections.get("<meeting-B-id>");

// Close Connection with Meeting B
const onClick = () => {
  connection.close();
};

//  This event will be emitted to participants of both meetings.
meeting.on("connection-close", (connectionId) => {
  console.log("ConnectionId", connectionId);
});
```


---

# End Connection Meeting - Javascript

### Method

- **end** - If you want to end connected meetings, `connection.meeting.end` method is used. After executing this method, all participants of that meeting will leave automatically.

### Example

**Meeting_A** is connected with **Meeting_B**, participant of **Meeting_A** wants to end **Meeting_B**, now **Meeting_A** participant will use `connection.meeting.end` to end **Meeting_B** and all the participants joined in **Meeting_B** will leave.

```js
// Get meeting B connection
const connection = meeting.connections.get("<meeting-B-id>");

// End Meeting B
const onClick = () => {
  connection.meeting.end();
};
```


---

# Establish Connection between Meetings - Javascript

### Methods

- **connectTo** - This method is used for establishing connection between rooms.
  This method accept `meetingId` and `payload` as an object.

### Event

- **connection-open** - Whenever connection between two rooms established successfully, this event will trigger and return [Connection](/javascript/guide/video-and-audio-calling-api-sdk/features/connection/overview#1-connection) list.

### Example

**Meeting_A** wants to connect with **Meeting_B**, now in this case **Meeting_A** will use `connectTo` method and pass `meeintgId` and `payload`.

`connectTo({ meetingId: "Meeting_B_ID", payload: "Hello Everyone." });`

After using this method, `connection-open` event will be emitted at both meetings and then **Meeting_A** & **Meeting_B** gets connected to each other.

#### **Method and Event Code**

```js
// Create Connection to Meeting B
meeting.connectTo({ meetingId: "Meeting_B_ID", payload: "Hello Everyone." });

//  This event will be emitted to participants of both meetings, Meeting A & Meeting B
meeting.on("connection-open", (connection) => {
  console.log("Connection", connection);
});
```


---

# Get Connection - Javascript

## Get all Connection meetings

After successfully established connections, you will be able to get all the connected meetings from `Meeting` class parameter called `connections`.

```js
console.log(meeting.connections);
// In response, you will get Map of all connected meetings
```

## Get single connection meeting

You can get single meeting connection object by passing `id`.
However, you can also consider connected `meetingId` as a `connectionId`.

:::note
For React and ReactNative developer, videosdk.live introduce new hook called `useConnection`, which can handle single connected meeting by passing id.
:::

```js
const connection = meeting.connections.get("<connection-id>"); // <meeting-id> || <connection-id>

console.log(connection);
// In response, you will get single meeting connection
```


---

# List out Participants of Connected Meeting - Javascript

After getting a single meeting connection, all joined participants of that meeting can be fetched using `connection.meeting.participants`.

### Events

- **participant-joined** - Whenever a new participant joined that connected meeting, this event will be emitted. For example, **Meeting_A** is connected with **Meeting_B**, there are participants `M1P1` and `M1P2` in **Meeting_A** and participant `M2P1` in **Meeting_B**, now a new participant `M2P2` joined **Meeting_B**, then `connection.meeting.on("participant-joined")` will be emitted to all participants of **Meeting_A**.

- **participant-left** - Whenever any participant left that connected meeting, this event will be emitted. For example, **Meeting_A** is connected with **Meeting_B**, there are participants `M1P1` and `M1P2` in **Meeting_A** and participants `M2P1` and `M2P2` in **Meeting_B**, now a participant `M2P2` left **Meeting_B**, then `connection.meeting.on("participant-left")` will be emitted to all participants of **Meeting_A**.

### **Method and Event Code**

```js
const connection = meeting.connections.get("<connection-id>");

console.log(connection.meeting.participants);
// Here you will get all joined participants of that connected meeting

connection.meeting.on("participant-joined", (participant) => {
  console.log(participant); // Joined participant of that connected meeting
});
connection.meeting.on("participant-left", (participantId) => {
  console.log(participantId); // participantId who left that connected meeting
});
```

:::info
Participant you get from `connection.meeting.participants`, will only contain `id` and `displayName`. Any video, audio or share streams will not be provided.
:::


---

# Overview

This feature allows participant for establishing connection and getting information from other meetings. Also, a participant will have basic control over other running meetings.

For example, there are two meetings running parallelly **Meeting A** and **Meeting B**, in case one of the participant from **Meeting A** wants to access information of **Meeting B** without joining it, now this can be achieved by establishing connection between meetings, so that participants of **Meeting A** and **Meeting B** will get all the updates from each other.

For This feature, we introduce three new entities/classes :

1. [Connection](/javascript/guide/video-and-audio-calling-api-sdk/features/connection/overview#1-connection)
2. [ConnectionMeeting](/javascript/guide/video-and-audio-calling-api-sdk/features/connection/overview#2-connectionmeeting)
3. [ConnectionParticipants](/javascript/guide/video-and-audio-calling-api-sdk/features/connection/overview#3-connectionparticipants)

### 1. Connection

Whenever new connection establish between meetings, **Connection** instance is created inside Meeting class property `connections`.

#### **Connection object properties** :

| Property Name | Type                                                                                                                    | Description                                   |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| id            | string                                                                                                                  | Unique id of the connection.                  |
| payload       | string                                                                                                                  | The payload you define during the connection. |
| meeting       | [ConnectionMeeting](/javascript/guide/video-and-audio-calling-api-sdk/features/connection/overview#2-connectionmeeting) | Connected Meeting Instance.                   |

### 2. ConnectionMeeting

This entity is the instance of connected Meeting.

#### **ConnectionMeeting object properties** :

| Property Name | Type                                                                                                                                     | Description                          |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| id            | string                                                                                                                                   | Unique id of the connection meeting. |
| participants  | Map of [ConnectionParticipants](/javascript/guide/video-and-audio-calling-api-sdk/features/connection/overview#3-connectionparticipants) | Participants of connected meeting.   |

:::note

- This ConnectionMeeting instance will provide only limited functionality and controls over the connected meetings.
- You will not able to access each and every control of that connected meetings.

:::

### 3. ConnectionParticipants

#### **ConnectionParticipants object properties** :

| Property Name | Type   | Description                   |
| ------------- | ------ | ----------------------------- |
| id            | string | Unique id of the participant. |
| displayname   | string | Displayname of Participant.   |


---

# Send Message to Connected Meeting - Javascript

### Method

- **sendChatMessage** - If you want to communicate participants of connected meetings, it can be achieved by this. This method accepts **messageText** as an argument.

### Event

- **chat-message** - When any participant of **Meeting A** sends a chat message to **Meeting B**, then this event will be emitted to all participants of **Meeting B**.

### **Method and Event Code**

```js
const connection = meeting.connections.get("<connection-id>");

// This will be called from Meeting A
const onClick = () => {
  connection.meeting.sendChatMessage("Hi there, from MARS!");
};

// This event will be emitted to all participants of Meeting B
connection.meeting.on("chat-message", ({ message, participantId }) => {
  alert(`${participantId} says: ${message}`);
});
```


---

# Switch Particpant from Connected Meeting - Javascript

### Method

- **switchTo** - If you want a participant from a connected meeting to be switched from one meeting to another meeting, `switchTo` method is used.
  This method accept `meetingId`, `token` and `payload` as an object.

  - `meetingId` - This should be the `meetingId` where you want to switch that participant from the joined meeting.

### Event

- **switch-meeting** - This event will emit at participant side who is going to be switch with arguments `meetingId`, `payload`, `token`, `connectionParticipantId` and `connectionMeetingId`

:::note

- While calling `switchTo()`, you need to pass a pre-generated token so that participant can reinitialize and join that meeting with the latest token on `switch-meeting` event.
- `switch-meeting` event will not switch that participant without any action.

:::

### Example

**Meeting_A** is connected with **Meeting_B**, there are participants `P1` in **Meeting_A** and `P2` in **Meeting_B**, now **Meeting_A** participant `P1` wants to switch `P2` participant from **Meeting_B** to **Meeting_A**, then participant `P1` will call:

`connectionParticipant.switchTo({ meetingId, token, payload })`

after that `P2` from **Meeting_B** will receive an event `switch-meeting`.

### **Method and Event Code**

```js
// Get meeting B connection
const connection = meeting.connections.get("<meeting-B-id>");

// Get participant of meeting B
const connectionParticipant =
  connection.meeting.participants.get("<participant-id>");

// Here participant from meeting A requests to switch particpant from meeting B to A
const onClick = () => {
  const meetingId = "<meeting-A-id>";
  const token = "JWT";
  const payload = "payload";

  connectionParticipant.switchTo({ meetingId, token, payload });
};

// This event will be emitted to participant of Meeting B
meeting.on(
  "switch-meeting",
  ({
    meetingId,
    payload,
    token,
    connectionParticipantId,
    connectionMeetingId,
  }) => {}
);
```

`reInitialiseMeetingOnConfigChange` prop help you to update token and meeting id at run time, you don't have to rejoin or reinitialize the meeting.

The reason we are using this props is we are resetting meetingId and token at participant side [switch-meeting](/javascript/guide/video-and-audio-calling-api-sdk/features/connection/switch-connection-participant#event) event.

If you not specify this props, MeetingProvider will not able to reset meetingId and token at run time.


---

# Error Event - Javascript

This event is helpful for development level troubleshooting while integrating SDK.

Whenever any invalid configuration provided or server/network errors arise, this event will trigger with a specific error code and message.

This event can ease your development process.

We have depicted a specific constant with code and message in the below table.

| Constant                                      | Code | Message                                                                                                                     |
| --------------------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------- |
| **INVALID_API_KEY**                           | 4001 | `apikey` provided in the token is empty or invalid, please verify it on the dashboard.                                      |
| **INVALID_TOKEN**                             | 4002 | `token` is empty or invalid or might have expired.                                                                          |
| **INVALID_MEETING_ID**                        | 4003 | `meetingId` is empty or invalid, please verify it or generate new meetingId using the API.                                  |
| **INVALID_PARTICIPANT_ID**                    | 4004 | `participantId` is empty or invalid, it shouldn't contain any whitespaces.                                                  |
| **DUPLICATE_PARTICIPANT**                     | 4005 | Leaving meeting, since this `participantId` joined from another device.                                                     |
| **ACCOUNT_DEACTIVATED**                       | 4006 | It seems your account is deactivated by VideoSDK for some reason, you can reach out to us at `support@videosdk.live`.       |
| **ACCOUNT_DISCONTINUED**                      | 4007 | _Server will respond you with specific message._                                                                            |
| **INVALID_PERMISSIONS**                       | 4008 | `permissions` provided in the token are invalid, please don't use `allow_join` or `allow_mod` with `ask_join`.              |
| **MAX_PARTICIPANT_REACHED**                    | 4009 | You have reached max participant limit in a meeting.                                                                         |
| **MAX_SPEAKER_REACHED**                       | 4010 | You have reached max speaker limit in a meeting.                                                                            |
| **START_RECORDING_FAILED**                    | 4011 | Recording start request failed due to an unknown error.                                                                     |
| **STOP_RECORDING_FAILED**                     | 4012 | Recording stop request failed due to an unknown error.                                                                      |
| **START_LIVESTREAM_FAILED**                   | 4013 | Livestream start request failed due to an unknown error.                                                                    |
| **STOP_LIVESTREAM_FAILED**                    | 4014 | Livestream stop request failed due to an unknown error.                                                                     |
| **INVALID_LIVESTREAM_CONFIG**                 | 4015 | Livestream 'outputs' configuration provided was invalid.                                                                    |
| **START_HLS_FAILED**                          | 4016 | HLS start request failed due to an unknown error.                                                                           |
| **STOP_HLS_FAILED**                           | 4017 | HLS stop request failed due to an unknown error.                                                                            |
| **PREV_RECORDING_PROCESSING**                 | 4018 | Previous recording session is being processed, please try again after few seconds!                                          |
| **PREV_RTMP_RECORDING_PROCESSING**            | 4019 | Previous RTMP recording session is being processed, please try again after few seconds!                                     |
| **PREV_HLS_STREAMING_PROCESSING**             | 4020 | Previous HLS streaming session is being processed, please try again after few seconds!                                      |
| **MAX_SPEAKER_LIMIT_REACHED_ON_ORGANIZATION**    | 4026 | You have reached max speaker limit on organization. To increase contact at support@videosdk.live".                                                               |
| **MAX_VIEWER_LIMIT_REACHED_ON_ORGANIZATION**    | 4027 | You have reached max viewer limit on organization. To increase contact at support@videosdk.live".                                                               |
| **MAX_RECORDING_LIMIT_REACHED_ON_ORGANIZATION**    | 4028 | You have reached max limit of recording on organization. To increase contact at support@videosdk.live.                                                               |
| **MAX_HLS_LIMIT_REACHED_ON_ORGANIZATION**    | 4029 | You have reached max limit of hls on organization. To increase contact at support@videosdk.live.                                                               |
| **MAX_LIVESTREAM_LIMIT_REACHED_ON_ORGANIZATION**    | 4030 | You have reached max limit of livestream on organization. To increase contact at support@videosdk.live.                                                               |
| **RECORDING_FAILED**                          | 5001 | Recording stopped due to an unknown error.                                                                                  |
| **LIVESTREAM_FAILED**                         | 5002 | Livestream stopped due to an unknown error.                                                                                 |
| **HLS_FAILED**                                | 5003 | HLS stopped due to an unknown error.                                                                                        |
| **RECORDING_DURATION_LIMIT_REACHED**          | 5004 | Recording has been automatically stopped by the system, due to max duration limit of 2 hours reached for a single Recording |
| **LIVESTREAM_DURATION_LIMIT_REACHED**         | 5005 | Livestream has been automatically stopped by the system, due to max duration limit of 2 hours reached for a single RTMP     |
| **HLS_DURATION_LIMIT_REACHED**                | 5006 | Hls has been automatically stopped by the system, due to max duration limit of 2 hours reached for a single HLS             |
| **ERROR_GET_VIDEO_MEDIA**                     | 3011 | Your browser/Device does not support Video.                                                                                 |
| **ERROR_GET_AUDIO_MEDIA**                     | 3012 | Your browser/Device does not support Audio.                                                                                 |
| **ERROR_GET_DISPLAY_MEDIA**                   | 3013 | Your browser/Device does not support Screen Sharing.                                                                        |
| **ERROR_GET_VIDEO_MEDIA_PERMISSION_DENIED**   | 3014 | Video capture permission denied.                                                                                            |
| **ERROR_GET_AUDIO_MEDIA_PERMISSION_DENIED**   | 3015 | Audio capture permission denied.                                                                                            |
| **ERROR_GET_DISPLAY_MEDIA_PERMISSION_DENIED** | 3016 | Screen sharing permission denied.                                                                                           |

### Event Code



```js

meeting.on("error", (data) => {
  const { code, message } = data;

  // Get Constant from SDK which contain value of error Code
  const { INVALID_TOKEN, INVALID_MEETING_ID } = VideoSDK.constants.errors;

  switch (code) {
    case INVALID_TOKEN:
      console.log(`Error is ${message}`);
      break;

    case INVALID_MEETING_ID:
      console.log(`Error is ${message}`);
      break;

    default:
      break;
  }
});
```


---

# Go Live On Social Media - Javascript

This feature allows participant to broadcast meeting on various social media platforms such as Facebook or Youtube.
This guide will provide an overview of how participant can start and stop broadcasting meeting.

1. **Start LiveStream** - By using `startLivestream()` function, a participant can start broadcasting meeting on various platforms by provding url and stream keys as an argument.
2. **Stop LiveStream** - By using `stopLivestream()` function, a participant can stop broadcasting on all platforms.

### Start And Stop Live Stream



```js
const onPress = () => {
  // Start Live Stream
  meeting?.startLivestream([
    {
      url: "rtmp://a.rtmp.youtube.com/live2",
      streamKey: "key",
    },
  ]);

  // Stop Live Stream
  meeting?.stopLivestream();
};
```

### Events

1. **livestream-state-changed** - Whenever broadcasting of meeting started / stopped, `livestream-state-changed` event will trigger.

```js

const Constants = VideoSDK.Constants;

meeting.on("livestream-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.livestreamEvents.LIVESTREAM_STARTING) {
    console.log("Meeting livestream is starting");
  } else if (status === Constants.livestreamEvents.LIVESTREAM_STARTED) {
    console.log("Meeting livestream is started");
  } else if (status === Constants.livestreamEvents.LIVESTREAM_STOPPING) {
    console.log("Meeting livestream is stopping");
  } else if (status === Constants.livestreamEvents.LIVESTREAM_STOPPED) {
    console.log("Meeting livestream is stopped");
  } else {
    //
  }
});
```


---

# Leave or End Meeting - Javascript

Whenever participant wishes to end their communication in the meeting, they can simply leave the meeting.

This guide will provide an overview of how to implement leave or end feature in VideoSDK meetings.

1. **Leave** - By using `leave()` function, only a participant will leave/exit the meeting, the rest of the meeting will continue with other participants.
2. **End** - By using `end()` function, meeting will end for each and every participant. So, use this function according to your use cases.

### Leave And End Meeting



```js
const onPress = () => {
  // Leave Meeting
  meeting?.leave();

  // Exit Meeting
  meeting?.end();
};
```

## Events

**Events associated with `leave()`:**

- Local participant will receive a [`meeting-left`](../../../api/sdk-reference/meeting-class/events.md#meeting-left) event.
- All remote participants will receive a [`participant-left`](../../../api/sdk-reference/meeting-class/events.md#participant-left) event with `participantId`.

**Event associated with `end()`:**

- All [participants](../../../api/sdk-reference/participant-class/introduction.md) and [localParticipant](../../../api/sdk-reference/participant-class/introduction.md), will be emitted with [`meeting-left`](../../../api/sdk-reference/meeting-class/events.md#meeting-left) event.

```js
meeting.on("meeting-left", () => {
  //Meeting Left
});

meeting.on("participant-left", (participant) => {
  //Participant Left the meeting
});
```


---

# Manage Participants - Javascript

## 1. Local Participant (self)

Local participant is used to consume your video & audio streams.
it contains information about local participant such as displayName, id, quality and streams Map.

You can acces localParticipant from the [meeting object](/javascript/guide/video-and-audio-calling-api-sdk/features/start-join-meeting#2-initialization).

### Participant object properties

| Property Name | Type          | Description                                            |
| ------------- | ------------- | ------------------------------------------------------ |
| id            | string        | Unique id of the participant.                          |
| displayName   | string        | The name you define during the meeting initialization. |
| local         | boolean       | Indicates the participant is local or not.             |
| quality       | string        | Indicates the participant streams quality.             |
| Streams       | Map of Stream | Returns Video & Audio Streams.                         |

### Stream Object properties

| Property Name | Type   | Description        |
| ------------- | ------ | ------------------ |
| id            | string | Unique id          |
| codec         | string | Video/Audio codec. |
| kind          | string | Stream Kind.       |
| track         | string | MediaStreamTrack   |

## 2. Other Participants (Except You)

Other participants Map is used to get all the participants (except you) in the meeting at any given time.

Other participants Map contains same properties as [LocalParticipant](/javascript/guide/video-and-audio-calling-api-sdk/features/manage-participants#participant-object-properties).

### Local And Other Participants



```js
/** localParticipant contains Participant object
  as displayed above local participant section */
const localParticipant = meeting.localParticipant;

localParticipant.streams.forEach((stream) => {
  setTrack(stream, videoElement, audioElement, participant.id);
});

const participants = meeting.participants;

/** to play other participants video & audio */
function loadOtherParticipants() {
  meeting.participants.forEach((participant) => {
    let videoElement = createVideoElement(participant.id);
    let audioElement = createAudioElement(participant.id);

    participant.streams.forEach((stream) => {
      setTrack(stream, videoElement, audioElement, participant.id);
    });

    videoContainer.appendChild(videoElement);
    videoContainer.appendChild(audioElement);
  });
}

// creating video element
function createVideoElement(pId) {
  let videoElement = document.createElement("video");
  videoElement.setAttribute("id", `v-${pId}`);
  return videoElement;
}

// creating audio element
function createAudioElement(pId) {
  let audioElement = document.createElement("audio");
  audioElement.setAttribute("autoPlay", "false");
  audioElement.setAttribute("playsInline", "true");
  audioElement.setAttribute("controls", "false");
  audioElement.setAttribute("id", `a-${pId}`);
  return audioElement;
}

//setting up tracks
function setTrack(stream, videoElem, audioElement, id) {
  if (stream.kind == "video") {
    const mediaStream = new MediaStream();
    mediaStream.addTrack(stream.track);
    videoElem.srcObject = mediaStream;
    videoElem
      .play()
      .catch((error) =>
        console.error("videoElem.current.play() failed", error)
      );
  }
  if (stream.kind == "audio") {
    if (id == meeting.localParticipant.id) return;
    const mediaStream = new MediaStream();
    mediaStream.addTrack(stream.track);
    audioElement.srcObject = mediaStream;
    audioElement
      .play()
      .catch((error) => console.error("audioElem.play() failed", error));
  }
}
```

## 3. Participant Related Events

1. **participant-joined** - Whenever any new participant join the meeting, `participant-joined` event will trigger. For example, the meeting is running with **Alice** and **Bob**, then **Eve** join that meeting, after that `participant-joined` event trigger and return the [participant object](/javascript/guide/video-and-audio-calling-api-sdk/features/manage-participants#participant-object-properties).

2. **participant-left** - Whenever any participant leave/exit the meeting, `participant-left` event will trigger.For example, the meeting is running with **Alice** and **Bob**, then **Bob** leave that meeting, after that `participant-left` event trigger and return the [participant object](/javascript/guide/video-and-audio-calling-api-sdk/features/manage-participants#participant-object-properties)

3. **presenter-changed** - Whenever any participant present/screenshare their screen/window in meeting, `presenter-changed` event will trigger and return the presenter `participantId`.

4. **stream-enabled** - Whenever any participant enabled mic/webcam in meeting, `stream-enabled` event will trigger and return [Stream](/javascript/guide/video-and-audio-calling-api-sdk/features/manage-participants#stream-object-properties).

5. **stream-disabled** - Whenever any participant disabled mic/webcam in meeting, `stream-disabled` event will trigger and return [Stream](/javascript/guide/video-and-audio-calling-api-sdk/features/manage-participants#stream-object-properties).

```js
meeting.on("participant-joined", (participant) => {
  participant.on("stream-enabled", (stream) => {
    // You can find this setTrack() helper function on previous code snippet
    setTrack(stream, videoElement, audioElement, participant.id);
  });
});
meeting.on("participant-left", (participant) => {
  participant.on("stream-disabled", (stream) => {
    // You can find this setTrack() helper function on previous code snippet
    setTrack(stream, videoElement, audioElement, participant.id);
  });
});
meeting.on("presenter-changed", (participantId) => {});
```


---

# Mic Controls - Javascript

Whenever any participant wants to start / stop broadcasting their audio to other participant in meeting, they can simply do it with VideoSDK Meeting.

This guide will provide an overview of how to use enable and disable Mic in a meeting.

1. **Enable Mic** - By using `unmuteMic()` function, a participant can publish audio to other participants.
2. **Disable Mic** - By using `muteMic()` function, a participant can stop publishing audio to other participants.
3. **Change Mic** - By using `changeMic()` function, a participant can change mic.

### Enable, Disable, Change Mic

:::note

For Javascript, we will use `unmuteMic()` function for publish audio to other participants and `muteMic()` function for stop publishing audio to other participants.
:::

### Enable, Disable Mic



```js
const onPress = () => {
  // Enable Mic in Meeting
  meeting?.unmuteMic();

  // Disable Mic in Meeting
  meeting?.muteMic();

  // Change Mic in Meeting
  const mics = await meeting?.getMics(); // returns all mics

  const { deviceId, label } = mics[0];

  meeting?.changeMic(deviceId);
};
```

### Events

**Event associated with `unmuteMic()`:**

- [`stream-enabled`](../../../api/sdk-reference/participant-class/events.md#stream-enabled) event will be emitted with [`stream`](../../../api/sdk-reference/stream-class/introduction.md) object from the event callback, inside that [participant](../../../api/sdk-reference/participant-class/introduction.md) object.

**Event associated with `muteMic()`:**

- [`stream-disabled`](../../../api/sdk-reference/participant-class/events.md#stream-disabled) event will be emitted with [`stream`](../../../api/sdk-reference/stream-class/introduction.md) object from the event callback, inside that [participant](../../../api/sdk-reference/participant-class/introduction.md) object.

```js
participant.on("stream-enabled", (stream) => {
  if (stream.kind === "audio") {
    //particiapnt turned on audio
    //Render Participant audio logic here
  }
});

participant.on("stream-disabled", (stream) => {
  if (stream.kind === "audio") {
    //particiapnt turned off audio
    //remove Participant audio logic here
  }
});
```


---

# Noise Suppresion (BETA) - Javascript

This feature allows participant to removes background noise from meetings and keep only particpant voice in the communication.

:::important

- This feature is in Beta release, so feel free to reach out to us on Discord. We'd love to hear feedback from you.

:::

### 1. Install VideoSDK Media Processor package

**npm:**

```js
npm install --save @videosdk.live/videosdk-media-processor-web
```

---

**yarn:**

```js
yarn add @videosdk.live/videosdk-media-processor-web
```

### 2. Implement Noise suppressor with SDK

- `getNoiseSuppressedAudioStream` - This method accepts source of [MediaStream](https://developer.mozilla.org/en-US/docs/Web/API/MediaStream), return processed `MediaStream`.

```js
// Meeting Initializer
meeting = window.VideoSDK.initMeeting({...});

const onNoiseSuppressor = async () => {
  try {
    // Instantiate VideoSDKNoiseSuppressor Class
    const noiseProcessor = new window.VideoSDKNoiseSuppressor();

    // Getting stream from mic
    const stream = await window.VideoSDK.createMicrophoneAudioTrack({});
    const processedStream = await noiseProcessor.getNoiseSuppressedAudioStream(
      stream
    );

    // Pass `processedStream` in VideoSDKs `changeMic` method
    meeting.changeMic(processedStream);
  } catch (error) {
    console.log(error);
  }
};
```

For disabling noise suppression, you can pass mic stream in VideoSDKs `changeMic` method.

```js
const disableNoiseSuppressor = async () => {
  // Pass mic MediaStream in VideoSDK `changeMic` method
  const stream = await window.VideoSDK.createMicrophoneAudioTrack({});
  changeMic(stream);
};
```


---

# Pin Participants - Javascript

In any meeting with large number of participants, if you want to show only one or two participant(s) on main screen then you can pin that perticipants so that viewers can only focus upon that participants only.

This guide will provide an overview of how to pin or unpin any participants in a meeting.

## Participant Pin State



```js
const { cam, share } = participant?.pinState;
```

:::note
`pin()` and `unpin()` functions will take `string` or `null` as an argument. Pin will be effective for both webcam and screenshare of that participant.

Suppose you want to pin or unpin only webcam of that participant then you can pass `CAM`, else if you want to pin or unpin only screenshare of that participant then you can pass `SHARE`.

You can also pass `SHARE_AND_CAM` if you want to `pin` or `unpin` both webcam and screenshare media of that user, or passing `null` or nothing as an argument will also work in the same way.

If any participant's webcam is pinned but not screenshare, then calling `pin("SHARE")` the new pinState of that participant will be `{ cam: true, share: true }`.  
:::

### Pin And Unpin a Participant

```js
const onPress = () => {
  // Pin both webcam and screenshare of that participant
  participant.pin();

  // Pin webcam of that participant
  participant.pin("CAM");

  // Pin screenshare of that participant
  participant.pin("SHARE");

  //
  // Unpin both webcam and screenshare of that participant
  participant.unpin();

  // Unpin webcam of that participant
  participant.unpin("CAM");

  // Unpin screenshare of that participant
  participant.unpin("SHARE");
};
```

### pin-state-changed Event

Whenever any participant got pinned or unpinned by any participant, `pin-state-changed` event will be triggered.

```js
meeting.on("pin-state-changed", ({ participantId, state, pinnedBy }) => {
  console.log({
    participantId, // id of participant who were pinned
    state, // { cam: true, share: true }
    pinnedBy, // id of participant who pinned that participant
  });
});
```


---

# Play External Video - Javascript

This feature allows participants to broadcast any external video by providing video link.
Like screen share feature, one participant is broadcasting and other participants are receivers.

This guide will provide an overview of how participant can start, stop, resume and seek external video during the meeting.

1. **Start** : By using `startVideo()` function, the broadcaster can start external video by providing video link in argument.
2. **Stop** : By using `stopVideo()` function, a broadcaster can stop external video.
3. **Pause** : By using `pauseVideo()` function, a broadcaster can pause external video by providing `{ currentTime: 5 }` object as an argument.
4. **Resume** : By using `resumeVideo()` function, a broadcaster can resume external video from last pause video duration.
5. **Seek** : By using `seekVideo()` function, a broadcaster can seek external video to any given duration by providing `{ currentTime: 5 }` object as an argument.

### Start, Stop, Pause, Resume, and Seek External Video



```js
const onPress = () => {
  // Start Video
  meeting?.startVideo({
    link: "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4",
  });

  // Stop Video
  meeting?.stopVideo();

  // Pause Video
  meeting?.pauseVideo({ currentTime: 5 });

  // Resume Video
  meeting?.resumeVideo();

  // Seek Video
  meeting?.seekVideo({ currentTime: 10 });
};
```


---

# PubSub - Javascript

PubSub feature allows the participant to send and receive messages of the topics which he has subscribed.

## Methods

### publish()

This method is use for publishing message of specific topic.

#### Syntax

```js
function publish(topic: String, message: String, { persist : Boolean });
```

| Parameter Name | Type   | Description                                                                                                               |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| topic          | String | This should be the topic for which you are publishing a message.                                                          |
| message        | String | This is the actual message, which will be published to participants, who had subscribed to a particular topic.            |
| options        | Object | This is an object, which provides an option, such as `persist`, which persists message history for upcoming participants. |

#### Example

```js
function sendMessage() {
  meeting?.pubSub?.publish(topic: "CHAT", message: "Hello Everyone!", { persist: true })
}
```

<br />

### subscribe()

This method is used to subscribe for particular topic. This method returns a list of messages which were sent earlier.

#### Syntax

```js
function subscribe(topic: String, onMessageReceived: function);
```

| Parameter Name    | Type     | Description                                                                   |
| ----------------- | -------- | ----------------------------------------------------------------------------- |
| topic             | String   | This should be the topic to be subscribed.                                    |
| onMessageReceived | function | This is a callback function, which will be called, when new message received. |

#### Example

```js
// Callback function
function onMessageReceived(data) {
  console.log(`New message received: ${data.message}`);
}

function subscribe() {
  // Subscribe 'CHAT' topic
  meeting?.pubSub?.subscribe("CHAT", onMessageReceived);
}
```

### unsubscribe()

This method is used to unsubscribe the message topic.

#### Syntax

```js
function unsubscribe(topic:String, onMessageReceived: function);
```

| Parameter Name    | Type     | Description                                                     |
| ----------------- | -------- | --------------------------------------------------------------- |
| topic             | String   | This should be the topic to be unsubscribed.                    |
| onMessageReceived | function | This is a callback function, which was passed in `subscribe()`. |

#### Example

```js
function unsubscribe() {
  // Unsubscribe 'CHAT' topic
  meeting?.pubSub?.unsubscribe("CHAT", onMessageReceived);
}
```

## Sample Code

```js
//subscribe to the 'CHAT' on meeting join
meeting.on("meeting-joined", () => {
  meeting.pubSub.subscribe("CHAT", (data) => {
    let { message, senderId, senderName, timestamp } = data;
    const chatBox = document.getElementById("chatArea");
    const chatTemplate = `
        <div style="margin-bottom: 10px; ${
          meeting.localParticipant.id == senderId && "text-align : right"
        }">
          <span style="font-size:12px;">${senderName}</span>
          <div style="margin-top:5px">
            <span style="background:${
              meeting.localParticipant.id == senderId ? "grey" : "crimson"
            };color:white;padding:5px;border-radius:8px">${message}<span>
          </div>
        </div>
        `;
    chatBox.insertAdjacentHTML("beforeend", chatTemplate);
  });
});

//publish chat meesage on button click
btnSend.addEventListener("click", async () => {
  const message = document.getElementById("txtChat").value;
  console.log("publish : ", message);
  document.getElementById("txtChat").value = "";
  meeting.pubSub
    .publish("CHAT", message, { persist: true })
    .then((res) => console.log(`response of publish : ${res}`))
    .catch((err) => console.log(`error of publish : ${err}`));
});
```


---

# Record Meeting - Javascript

Record meeting allows participants to record video & audio during the meeting. The recording files are available in developer dashboard.
Any participant can start / stop recording any time during the meeting.

This guide will provide an overview of how to implement start and stop Meeting Recording.

1. **Start Recording** - By using `startRecording()` function, a participant can start meeting recording.
2. **Stop Recording** - By using `stopRecording()` function, a participant can stop meeting recording.

### Start And Stop Recording



```js
const onPress = () => {
  // Start Recording
  meeting?.startRecording(webhookUrl, awsDirPath, config);

  // Stop Recording
  meeting?.stopRecording();
};
```

### Events

1. **recording-state-changed** - Whenever any participant starts / stops meeting recording, then `recording-state-changed` event will trigger.

```js

const Constants = VideoSDK.Constants;

meeting.on("recording-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.recordingEvents.RECORDING_STARTING) {
    console.log("Meeting recording is starting");
  } else if (status === Constants.recordingEvents.RECORDING_STARTED) {
    console.log("Meeting recording is started");
  } else if (status === Constants.recordingEvents.RECORDING_STOPPING) {
    console.log("Meeting recording is stopping");
  } else if (status === Constants.recordingEvents.RECORDING_STOPPED) {
    console.log("Meeting recording is stopped");
  } else {
    //
  }
});
```


---

# Remove Participant - Javascript

Remove participant allows removing participant while session is on-going. This can be helpful when moderation in particular meeting is required.



```js
const onPress = () => {
  // Remove participant from active session
  // This will emit an event called "onParticipantLeft" to that particular participant
  meeting?.remove();
};
```

### Events

**meeting-left** - Removing participant will trigger `meeting-left` event.

```js
meeting.on("participant-left", (participant) => {
  // Triggers when a participant is removed or leaves the meeting.
});
```


---

# Share Your Screen - Javascript

Whenever any participant wants to share either the complete screen, a specific window or, a browser tab, they can simply do it with VideoSDK Meeting.

This guide will provide an overview of how to use enable and disable Screen Share in a meeting.

1. **Enable Screen Share** - By using `enableScreenShare()` function, a participant can publish screen stream to other participants.
2. **Disable Screen Share** - By using `disableScreenShare()` function, a participant can stop publishing screen stream to other participants.

### Enable, Disable Screen Share



```js
const onPress = () => {
  // Enabling ScreenShare
  meeting?.enableScreenShare();

  // Disabling ScreenShare
  meeting?.disableScreenShare();
};
```

### Events

**Events associated with `enableScreenShare()`:**

- [`stream-enabled`](../../../api/sdk-reference/participant-class/events.md#stream-enabled) event will be emitted with [`stream`](../../../api/sdk-reference/stream-class/introduction.md) object from the event callback, inside that [participant](../../../api/sdk-reference/participant-class/introduction.md) object.

- [`presenter-changed`](./../../../api/sdk-reference/meeting-class/events#presenter-changed) will also receive a callback with the `presenterId`.

**Events associated with `disableScreenShare()`:**

- [`stream-disabled`](../../../api/sdk-reference/participant-class/events.md#stream-disabled) event will be emitted with [`stream`](../../../api/sdk-reference/stream-class/introduction.md) object from the event callback, inside that [participant](../../../api/sdk-reference/participant-class/introduction.md) object.

- [`presenter-changed`](./../../../api/sdk-reference/meeting-class/events#presenter-changed) will also receive a callback with `null` value.

```js
participant.on("stream-enabled", (stream) => {
  if (stream.kind === "share") {
    //particiapnt turned on screen share
    //Render screenshare logic here
  }
});

participant.on("stream-disabled", (stream) => {
  if (stream.kind === "share") {
    //particiapnt turned off screenshare
    //remove screenshare logic here
  }
});

meeting.on("presenter-changed", (presenterId) => {
  if (presenterId) {
    //someone start presenting
  } else {
    //someone stopped presenting
  }
});
```

### Screen Share with Audio

To do screen share with audio, select the **Share tab audio** option when sharing the chrome tab as shown below.

<center>

![Screen Share with Audio](/img/screenshare-with-audio.png)

</center>



After clicking `Share` button, you will receive a selected tab audio stream in the participant `stream-enabled` callback with kind as `shareAudio`.

```js
participant.on("stream-enabled", (stream) => {
  if (stream.kind == "shareAudio") {
    const audioElem = createShareAudioElement(participant.id, stream);

    //add audioElem to your container
    container.appendChild(audioElem);
  }
});

// creating audio element
function createShareAudioElement(pId, stream) {
  if (pId == meeting.localParticipant.id) return;

  let audioElement = document.createElement("audio");
  audioElement.setAttribute("autoPlay", false);
  audioElement.setAttribute("playsInline", "false");
  audioElement.setAttribute("controls", "false");
  audioElement.setAttribute("id", `a-share-${pId}`);
  audioElement.style.display = "none";

  const mediaStream = new MediaStream();
  mediaStream.addTrack(stream.track);
  audioElement.srcObject = mediaStream;
  audioElement
    .play()
    .catch((error) => console.error("audioElem.play() failed", error));
  return audioElement;
}
```

:::note

Screen Share with Audio feature is only supported while **sharing chrome tab on Google Chrome** browser only.

:::


---

# Send Messages - Javascript

Whenever any participant wants to notify other participants via chat messages or Raise hand, they can simply do it with VideoSDK Meeting.

This guide will provide an overview of how to implement chat in a meeting using the PubSub mechanisum.

1. **Chat Message** - If a participant wants to inform or notify something in current meeting, they can use `meeting.pubSub.publish()` function by providing `{topic: 'CHAT', message:"Anything they wish to send" , {persist:true}}` object argument.

2. **Raised Hand** - If a participant has some doubts during the meeting and wants to raise hand, they can use `sendChatMessage()` function by providing `{topic: 'RAISED_HAND', message:"" , {persist:true}}` object argument.

:::note
`message` property can only take string as an argument.
:::

### Send Message And Raised Hand



```js
const onPress = () => {
  // Sending Message
  meeting?.pubSub?.publish(topic: "CHAT", message: "Hello Everyone!", { persist: true })

  // Raising Hand
  meeting?.pubSub?.publish(topic: "RAISED_HAND", message: "", { persist: false })
};
```

### Receiving the message

Whenever any participant sending message/raise hand in the meeting, then the message will be received to everyone how has subscribed to the `topic` which will contain senderId, senderName, timeStamp, message.

```js
meeting.pubSub.subscribe("CHAT", (data) => {
  let { message, senderId, senderName, timestamp } = data;
  const chatBox = document.getElementById("chatArea");
  const chatTemplate = `
        <div style="margin-bottom: 10px; ${
          meeting.localParticipant.id == senderId && "text-align : right"
        }">
          <span style="font-size:12px;">${senderName}</span>
          <div style="margin-top:5px">
            <span style="background:${
              meeting.localParticipant.id == senderId ? "grey" : "crimson"
            };color:white;padding:5px;border-radius:8px">${message}<span>
          </div>
        </div>
        `;
  chatBox.insertAdjacentHTML("beforeend", chatTemplate);
});

meeting.pubSub.subscribe("RAISED_HAND", (data) => {
  let { message, senderId, senderName, timestamp } = data;
  console.log(senderName, " raised Hand");
});
```

:::note
Check a detailed description of PubSub [here](./pubsub.md).
:::


---

# Set Video Quality - Javascript

- Set Video Quality feature allows participants to set other participant's video quality during the meeting.

- `Participant` class provides the `setQuality()` method to set participant's video quality.

```js
const participant = meeting.participants.get("PARTICIPANT_ID");

const onPressed = () => {
  // Set low quality
  participant.setQuality("low");
  // Set medium quality
  participant.setQuality("med");
  // Set high quality
  participant.setQuality("high");
};
```

:::note

If the quality is set to high, but there is not enough network bandwidth available, quality will reduce untill the newtwork quality improves.

:::

## Event

### video-quality-changed

- `video-quality-changed` is a callback which gets triggered whenever a participant's video quality changes.

- `currentQuality` and `prevQuality` can have values `HIGH` | `MEDIUM` | `LOW`.

#### Example

```js
participant.on("video-quality-changed", (data) => {
  const { currentQuality, prevQuality } = data;
  //
});
```


---

# Set Viewport - Javascript

When you are working with Video Calling, video quality is the most important part of communication. When a participant is shown on the screen, consuming multiple high quality although not required, will result in more memory and CPU usage of the device, eventually degrading quality.

The way to optimze around these situation is to consume the video quality which is required to fit the view of a particular participant, resulting in better quality, less usage of network bandwith and providing a better experience.

Viewport is the size of window or visible area in which video for the participant is shown. We can optimize the consuming video quality based on the viewport size of the participant. For example if the viewport size of a particular participant view is `480x360`, VideoSDK will download a `480x360` stream. If a participant on screen is present in bigger size, VideoSDK will provide a higher quality video for that particular participant only.


<div style={{textAlign: 'center'}}>



</div>

### setViewPort()

`setViewPort()` can be used to achieve the best optimization of the video. This method is called with the `width` and `height` of the participant view on the `Participant` object and VideoSDK will handle the rest.

##### Parameters

- `width`

  - type: `int`
  - Width of the participant view for which the quliaty of video is to be adjusted.

- `height`
  - type: `int`
  - Height of the participant view for which the quliaty of video is to be adjusted.

### Example

```js
//videoElem is the <div> which hold the participant video
participant.setViewPort(videoElem.offsetWidth, videoElem.offsetHeight);
```


---

# Speaker Indication - Javascript

Speaker indication feature in VideoSDK let you know, which participant in a meeting is active speaker.

Whenever any participant speaks in meeting, `speaker-changed` event will trigger.

For example, the meeting is running with **Alice** and **Bob**. Whenever any of them speaks, `speaker-changed` event will trigger and return the speaker `participantId`.

We can access `speaker-changed` event through [meeting object](/javascript/guide/video-and-audio-calling-api-sdk/features/start-join-meeting#2-initialization).

### speaker-changed Event



```js
meeting.on("speaker-changed", (activeSpeakerId) => {
  console.log("participantId", activeSpeakerId);
});
```


---

# Start or Join Meeting - Javascript

<div style={{display:'flex',flexDirection:'row',alignItems:'stretch',}}>
<div style={{}}>
<p>After the successful installation of VideoSDK, the next step is to integrate VideoSDK features with your webApp/MobileApp.</p>

<p>To Communicate with other participant's audio or video call, you will need to join the meeting.</p>

<p>This guide will provide an overview of how to configure, initialize and join a VideoSDK meeting.</p>

</div>
<div>
<img src="/img/gif/new-meeting.gif"/>
</div>

</div>

## 1. Configuration

To configure a meeting, you will need [generated token](/javascript/guide/video-and-audio-calling-api-sdk/server-setup) and [meetingId](/api-reference/realtime-communication/create-room), we had discussed in [Server Setup](/javascript/guide/video-and-audio-calling-api-sdk/server-setup).
This code snippet calls API from local server

**Scenario 1** - Suppose you **don't have** any meetingId, you can simply generate meetingId by invoking `create-meeting` API.

**Scenario 2** - Suppose you **have** meetingId, now you don't have to call `create-meeting` API to generate meetingId, instead you can call `validate-meeting` API to validate meetingId.

**Token generation API is necessary for both scenario.**



```js
const getToken = async () => {
  try {
    const response = await fetch(`${LOCAL_SERVER_URL}/get-token`, {
      method: "GET",
      headers: {
        Accept: "application/json",
        "Content-Type": "application/json",
      },
    });
    const { token } = await response.json();
    return token;
  } catch (e) {
    console.log(e);
  }
};

const getMeetingId = async (token) => {
  try {
    const VIDEOSDK_API_ENDPOINT = `${LOCAL_SERVER_URL}/create-meeting`;
    const options = {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ token }),
    };
    const response = await fetch(VIDEOSDK_API_ENDPOINT, options)
      .then(async (result) => {
        const { meetingId } = await result.json();
        return meetingId;
      })
      .catch((error) => console.log("error", error));
    return response;
  } catch (e) {
    console.log(e);
  }
};

/** This API is for validate the meeting id  */
/** Not require to call this API after create meeting API  */
const validateMeeting = async (token, meetingId) => {
  try {
    const VIDEOSDK_API_ENDPOINT = `${LOCAL_SERVER_URL}/validate-meeting/${meetingId}`;
    const options = {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ token }),
    };
    const response = await fetch(VIDEOSDK_API_ENDPOINT, options)
      .then(async (result) => {
        const { meetingId } = await result.json();
        return meetingId;
      })
      .catch((error) => console.log("error", error));
    return response;
  } catch (e) {
    console.log(e);
  }
};

const access_token = await getToken();
const meetingId = await getMeetingId(access_token);
```

## 2. Initialization

<div style={{display:'flex',flexDirection:'row',alignItems:'stretch',}}>
<div style={{}}>
<p>
After configuration, you will have to Initialize 
<p>
meeting by providing name, meetingId, micEnabled, webcamEnabled & maxResolution.
</p>
</p>

<p>
NOTE : For React & React native developer, you have

<p>to be familiar with hooks concept. You can understand hooks concept on <a href={'https://reactjs.org/docs/hooks-intro.html'}>React Hooks</a>.</p>

</p>
</div>
<div>
<img src="/img/gif/add-participant.gif"/>
</div>

</div>

```js

// Configure authentication token
VideoSDK.config("
</div>

</div>

```js
const onPress = () => {
  // Joining Meeting
  meeting?.join();
};
```

## Events

Following events are emitted on the `meeting` when it is successfully joined.

- Local Participant will receive a [`meeting-joined`](../../../api/sdk-reference/meeting-class/events.md#meeting-joined) event when successfully joined.
- Remote Participant will receive a [`participant-joined`](../../../api/sdk-reference/meeting-class/events.md#participant-joined) event with the newly joined [`Participant`](../../../api/sdk-reference/participant-class/introduction.md) object from the event callback.

```js
meeting.on("meeting-joined", () => {
  console.log("Meeting Joined Successfully");
});

meeting.on("participant-joined", (participant) => {
  console.log("New Participant Joined: ", participant.id);
});
```


---

# Switch Participant - Javascript

If you are running more than one meeting concurrently and want to switch particular participant over meetings, VideoSDK Provide `switchTo` method to achieve this kind of setup.

### Method

- **switchTo** - This method is used for switching participant of one meeting to another meeting.
  This method accept `meetingId`, `token` and `payload` as an object.

  - `meetingId` - This should be the `meetingId` where you want to switch that participant from the joined meeting.

### Event

- **switch-meeting** - This event will emit at participant side who is going to be switch with arguments `meetingId`, `payload` and `token`.

:::note

- While calling `switchTo()`, you need to pass a pre-generated token so that participant can reinitialize and join that meeting with the latest token on `switch-meeting` event.
- `switch-meeting` event will not switch that participant without any action.

:::

### Example

**Meeting_A** and **Meeting_B** are running paralleley, there are participants `P1`, `P2` in **Meeting_A** and `P3` in **Meeting_B**, now **Meeting_A** participant `P1` wants to switch `P2` participant from **Meeting_A** to **Meeting_B** or other meeting, then participant `P1` will call:

`switchTo({ meetingId, token, payload })`

after that `P2` from **Meeting_A** will receive an event `switch-meeting` with **Meeting_B** Id .

### **Method and Event Code**

```js
// Get participant of meeting A
const Participant = meeting.participants.get("<participant-id>");

const onClick = () => {
  const meetingId = "<meeting-B-id>"; // <meeting-B-id> || <other-meeting-id>
  const token = "JWT";
  const payload = "payload";

  Participant.switchTo({ meetingId, token, payload });
};

// This event will be emitted to participant P2 of Meeting A.
meeting.on("switch-meeting", ({ meetingId, payload, token }) => {});
```


---

# Toggle Participant Media - Javascript

Control other participant's webcam and mic.
For better idea, let's understand this with a real case scenario

**Scenario 1 (Online Class)** - In this scenario, the lecturer(Local Participant) will control the student's(Other Participant) webcam and mic as per his/her needs.

**Scenario 2 (Online Events)** - In this scenario, the event hosts will control the audience webcam and mic when someone wants to speak.

This guide will provide an overview of how to control other participant webcam and mic in a meeting.

1. **Enable Webcam of Participant** - By using `enableWebcam()` function, a `webcam-requested` event will trigger on requested participant side.

   **Example** : Meeting is running with **User A** and **User B**. Now **User A** wants to Enable Webcam of **User B**, so **User A** will use `enableWebcam()` function to request **User B**, after that **User B** recieve the `webcam-requested` event, from there user can either accept or reject the incoming request.

2. **Disable Webcam of Participant** - By using `disableWebcam()` function, webcam of that participant will be turned off.

   **Example** : **User A** wants to Disable Webcam of **User B**, so **User A** will use `disableWebcam()` function to Disable it without any request.

3. **Enable Mic of Participant** - By using `enableMic()` function, a `mic-requested` event will trigger on requested participant side.

   **Example** : Meeting is running with **User A** and **User B**. Now **User A** wants to Enable Mic of **User B**, so **User A** will use `enableMic()` function to request **User B**, after that **User B** will receive the `Mic-requested` event, from there user can either accept or reject the incoming request.

4. **Disable Mic of Participant** - By using `disableMic()` function, Mic of that participant will disable.

   **Example** : **User A** wants to Disable Mic of **User B**, so **User A** will use `disableMic()` function to Disable it without any request.

:::note

To achieve this feature, you need to pass `allow_join` persmission while genearting token for meeting initialization. After that you will be able to access participant media methods.

[How to apply permission while generating token?](/docs/guide/video-and-audio-calling-api-sdk/server-setup)

:::

### Request Media Methods



```js
const participants = meeting.participants;
const participant = participants.get("<participant-id>");

// This will emit an event called "webcam-requested" to that particular participant
participant.enableWebcam();

// This will directly disable webcam of particular participant
participant.disableWebcam();

// This will emit an event called "mic-requested" to that particular participant
participant.enableMic();

// This will directly disable mic of particular participant
participant.disableMic();
```

### Manage Requested Media Events

1. **webcam-requested** - This event will be emitted to the participant `B` when any other participant `A` requests to enable webcam of that participant `B`. This event handler will receieve following three arguments:

   - `accept()` - Callback function to accept the request.
   - `reject()` - Callback function to reject the request.

<div style={{height: "10px"}}></div>

2. **mic-requested** - This event will be emitted to the participant `B` when any other participant `A` requests to enable mic of that participant `B`. This event handler will receieve following three arguments:

   - `accept()` - Callback function to accept the request.
   - `reject()` - Callback function to reject the request.

```js
// Handle Webcam Requested
meeting.on("webcam-requested", ({ accept, reject }) {
    // callback function to accept the request
    accept();

    // callback function to reject the request
    reject();
}, );

// Handle Mic Requested
meeting.on("mic-requested", ({ accept, reject }) {
    // callback function to accept the request
    accept();

    // callback function to reject the request
    reject();
}, );
```


---

# Virtual Background- Javascript

This feature allows participants to blur own Video Background or set custom image backgrounds for increasing best productivity and protect personal privacy during Video communication.

:::important

- Currently, This feature is only available on Google Chrome, Safari, Firefox and Brave browser.
- This feature is in Beta release, so feel free to reach out to us on Discord. We'd love to hear feedback from you.

:::

### 1. Install VideoSDK Media Processor package

**npm:**

```js
npm install --save @videosdk.live/videosdk-media-processor-web
```

---

**yarn:**

```js
yarn add @videosdk.live/videosdk-media-processor-web
```

### 2. Start, Update and Stop Virtual Background

Three major method is used for handling Virtual Background Processor.

- #### Start

This method accepts two parameters `MediaStram` and `config`, return processed `MediaStream`.

1. **MediaStream** : Source of [MediaStream](https://developer.mozilla.org/en-US/docs/Web/API/MediaStream).

2. **config** : This object accepts `type` and `imageUrl` property. `type` property accepts filter type `image` or `blur`. `imageUrl` is the path of the image and will ignore on `blur` filter type.

   **NOTE** : If you want to display specific background image, do make sure it is uploaded on CDN.

```js
// Meeting Initializer
meeting = window.VideoSDK.initMeeting({...});

const startVirtualBackground = async () => {
  // Instantiate VirtualBackgroundProcessor Class
  const videoProcessor = new window.VirtualBackgroundProcessor();

  // Initialize processor if not ready
  if (!videoProcessor.ready) {
    await videoProcessor.init();
  }

  // Configuration for starting processor
  const config = {
    type: "image", // "blur"
    imageUrl: "https://cdn.videosdk.live/virtual-background/cloud.jpeg",
    // Here is a list of background images you can use for your project.
    // imageUrl: "https://cdn.videosdk.live/virtual-background/beach.jpeg",
    // imageUrl: "https://cdn.videosdk.live/virtual-background/san-fran.jpeg",
    // imageUrl: "https://cdn.videosdk.live/virtual-background/paper-wall.jpeg",
  };

  // Getting stream from webcam
  const stream = await window.VideoSDK.createCameraVideoTrack({});
  const processedStream = await videoProcessor.start(stream, config);

  // Pass `processedStream` in VideoSDKs `changeWebcam` method
  meeting.changeWebcam(processedStream);
};
```

- #### Update Processor

This method is used for updating filter as well as virtual background image during meeting.

```js
const config = {
  type: "image", // "blur"
  imageUrl: "https://cdn.videosdk.live/virtual-background/cloud.jpeg",
};

videoProcessor.updateProcessorConfig(config);
```

- #### Stop

This method is used to stop virtual background processor.

```js
const videoProcessor = new VirtualBackgroundProcessor();

const stopVirtualBackground = async () => {
  videoProcessor.stop();

  // Pass webcam MediaStream in VideoSDK `changeWebcam` method
  const stream = await window.VideoSDK.createCameraVideoTrack({});
  meeting.changeWebcam(stream);
};
```


---

# Cloud Proxy - JavaScript


Our SDK features a Cloud Proxy that allows you to manage how your streaming content is routed through different network paths. This feature ensures compliance with various regional internet regulations by restricting traffic to specified proxy servers, based on your needs and the geographical location of users.

This capability is crucial for adhering to local data protection laws and optimizes the streaming experience by overcoming geographical network constraints. By directing user connections to appropriate regional servers, Cloud Proxy enhances overall service performance and reliability.

Cloud Proxy offers three straightforward operating modes to fit different business and firewall requirements:

- **UDP_OVER_TCP (Default)**: In this mode, the connection starts by attempting to establish a UDP connection for media transmission. If that fails, it will automatically shifts to a secure TCP connection, which is compatible with most firewalls.

- **Force UDP**: This mode uses only UDP to send media, ensuring high-quality streams. It's ideal for environments where media quality is critical and the firewall can be configured accordingly.

- **Force TCP**: Only uses TCP for secure media transmission, suitable for strict firewall settings that only permit TCP traffic over centain ports. This might require additional firewall configuration and could affect media quality under poor network conditions.




### In this sequence diagram:
- Client to Proxy Server: The client sends a request to the proxy server, which processes and forwards it based on predefined rules.
- Proxy Server to Destination Server: The proxy server sends the request to the destination server, receives the response, and relays it back to the client.

:::info

Cloud Proxy is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Implementation

```js

meeting = VideoSDK.initMeeting({
  meetingId: "<Id-of-meeting>",
  name: "<Name-of-participant>",
  preferredProtocol: "UDP_ONLY",
  signalingBaseUrl: "proxy.yourwebsite.com",
});
```

### Parameters

- preferredProtocol:
  - UDP_OVER_TCP (default): Initially the server attempts to establish a connection using UDP, if that fails it automatically switches to TCP protocol.
  - UDP_ONLY: Force UDP protocol
  - TCP_ONLY: Force TCP protocol
- signalingBaseUrl: Proxy URL to origin signaling and media.

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [initMeeting](/javascript/api/sdk-reference/initMeeting#initmeeting)


---

# Geo Fencing - JavaScript


Our SDK includes a region geofencing feature to comply with local laws and regulations worldwide. It restricts connections to servers within specified regions, ensuring users connect only to designated areas, regardless of their location. 

This helps meet regional data protection requirements and enhances user experience by addressing geographical network limitations.




### In this sequence diagram:
- User 1 (India) tries to connect to a meeting. In a regular scenario, the meeting would connect to the India region, but due to the geofence configuration, the meeting will connect to North America.

## Considerations
- If the user’s location differs from the chosen region, the network quality between these locations may be poor, affecting audio and video quality.
- Avoid using geofencing unless your scenario requires regional compliance.

:::info

Geo Fencing is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Available Regions
- INDIA
- USA
- UAE
- EUROPE
- SINGAPORE
- AUSTRALIA

---

# Geo IP Restrictions  - JavaScript


Our SDK features Geo IP Restriction to ensure adherence to location-based access controls. It determines the user's location using their IP address and allows or restricts content based on geographic rules. This is essential for businesses needing to comply with international content distribution laws or provide localized services.

By implementing Geo IP Restriction, you can control who accesses your services based on where they are, ensuring compliance with legal regulations and enhancing security. This feature also improves the user experience by ensuring content relevance and availability is tailored to the user's location.




### In this sequence diagram:
- User 1 (India) attempts to connect to a meeting that is geo-restricted to only allow connections from North America. The server denies the connection due to the geographic restrictions.
- User 2 (North America) successfully connects because their location complies with the geo-restricted rules set on the meeting.


## Considerations
- Avoid using geo ip restriction unless your scenario requires regional or VPN/Proxy restrictions.

:::info

Geo IP Restriction is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Available Regions
- INDIA
- USA
- UAE
- EUROPE
- SINGAPORE
- AUSTRALIA

---

# Error Events - Javascript

VideoSDK provides the `error` event, which informs you about any error happening during the meeting.

### error

- This event is triggered whenever an invalid configuration is provided or server/network errors arise. In such cases, the event will trigger with a specific error code and message.
- It is particularly useful for development-level troubleshooting during SDK integration.
- It can be subscribed to using the `meeting` object.

### Example

Here is an example demonstrating the usage of the event mentioned on this page.

```javascript

let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const Constants = VideoSDK.Constants;

meeting.on("error", (data) => {
  const { code, message } = data;
});
```

### Error Codes

We have provided a specific constant along with the corresponding code and message in the table below.



### 1. Errors associated with Organization 

This table lists errors that occur due to the configuration and limitations within your organization’s account. These include account status, participant limits, and add-on service availability.

| Type                                   | Code  | Message                                             |
|----------------------------------------|-------|-----------------------------------------------------|
| ACCOUNT_DEACTIVATED                   | 4006  | Your account has been deactivated. Please contact VideoSDK support. |
| ACCOUNT_DISCONTINUED                  | 4007  | Your account has been discontinued. Please reach out to support for more details. |
| MAX_PARTICIPANT_REACHED               | 4009  | You have reached the maximum participant limit for this meeting. |
| MAX_SPEAKER_REACHED                   | 4010  | The maximum number of speakers for this meeting has been reached. |
| MAX_SPEAKER_LIMIT_REACHED_ON_ORGANIZATION | 4026  | Your organization has reached the maximum number of speakers allowed. |
| MAX_VIEWER_LIMIT_REACHED_ON_ORGANIZATION | 4027  | Your organization has reached the maximum number of viewers allowed. |
| ADD_ON_SERVICES_DISABLED              | 4021  | Add-On services have been disabled. Please contact support to enable them. |
| MAX_RECORDING_LIMIT_REACHED_ON_ORGANIZATION              | 4028  | You have reached max limit of recording on organization. To increase contact at support@videosdk.live |
| MAX_HLS_LIMIT_REACHED_ON_ORGANIZATION  | 4029  | You have reached max limit of hls on organization. To increase contact at support@videosdk.live |
| MAX_LIVESTREAM_LIMIT_REACHED_ON_ORGANIZATION  | 4030  | You have reached max limit of livestream on organization. To increase contact at support@videosdk.live |

### 2. Errors associated with Token

Errors listed here are related to issues with the API key, authentication tokens, or permissions assigned to users. These errors can occur when tokens are missing, expired, or improperly configured.

| Type                                    | Code  | Message                                                |
|-----------------------------------------|-------|--------------------------------------------------------|
| INVALID_API_KEY                        | 4001  | The provided API key is either missing or invalid. |
| INVALID_TOKEN                          | 4002  | The provided token is empty, invalid, or has expired. |
| INVALID_PERMISSIONS                    | 4008  | The permissions in the token are incorrect. Please verify them. |
| UNAUTHORIZED_MEETING_ID                | 4022  | The provided token is not authorized for this meeting ID. |
| UNAUTHORIZED_PARTICIPANT_ID            | 4023  | The provided token is not authorized for this participant ID. |
| UNAUTHORIZED_ROLE                      | 4024  | The role specified in the token is not valid for joining this meeting. |
| UNAUTHORIZED_REQUEST                      | 4025 | Your request does not match the security configuration. |

### 3. Errors associated with Meeting and Participant

This table lists errors resulting from invalid or missing meeting or participant details, including cases where a participant attempts to join with a duplicate ID.

| Type                    | Code  | Message                                         |
|-------------------------|-------|-------------------------------------------------|
| INVALID_MEETING_ID      | 4003  | The meeting ID provided is either invalid or missing. |
| INVALID_PARTICIPANT_ID  | 4004  | The participant ID is either invalid or missing. |
| DUPLICATE_PARTICIPANT   | 4005  | This participant has joined from another device. |

### 4. Errors associated with Add-on Service

This section addresses errors that occur while using VideoSDK's add-on services such as recording, livestreaming, HLS streaming, and transcription.

### Recording-related errors

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_RECORDING_FAILED      | 4011  | Failed to start recording. Please try again.   |
| STOP_RECORDING_FAILED       | 4012  | Failed to stop recording. Please try again.    |
| RECORDING_FAILED            | 5001  | Recording was stopped due to an error.         |
| START_PARTICIPANT_RECORDING_FAILED | 4035 | Failed to start participant recording. Please check the request. |
| STOP_PARTICIPANT_RECORDING_FAILED  | 4036 | Failed to stop participant recording. |
| PARTICIPANT_RECORDING_FAILED       | 5012 | Participant recording has stopped due to an error. |
| START_TRACK_RECORDING_FAILED | 4037 | Failed to start track recording.                |
| STOP_TRACK_RECORDING_FAILED  | 4038 | Failed to stop track recording.                 |
| TRACK_RECORDING_FAILED  | 5013 | Track recording stopped due to an unknown error.                 |
| PREV_RECORDING_PROCESSING  | 4018 | Previous recording session is being processed, please try again after few seconds.                 |
| RECORDING_DURATION_LIMIT_REACHED | 5004 | Recording stopped due to maximum duration being reached. |

### Livestream-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| INVALID_LIVESTREAM_CONFIG           | 4015  | Livestream 'outputs' configuration provided was invalid            |
| START_LIVESTREAM_FAILED     | 4013  | Failed to start livestream. Please try again.  |
| STOP_LIVESTREAM_FAILED      | 4014  | Failed to stop livestream. Please try again.   |
| LIVESTREAM_FAILED           | 5002  | Livestream stopped due to an error.            |
| PREV_RTMP_RECORDING_PROCESSING | 4019 | Previous RTMP recording session is being processed, please try again after few seconds! |
| LIVESTREAM_DURATION_LIMIT_REACHED | 5005 | Livestream stopped due to maximum duration being reached. |

### HLS-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_HLS_FAILED            | 4016  | Failed to start HLS stream.                    |
| STOP_HLS_FAILED             | 4017  | Failed to stop HLS stream.                     |
| HLS_FAILED                  | 5003  | HLS streaming stopped due to an error.         |
| PREV_HLS_STREAMING_PROCESSING | 4020 | Previous HLS streaming session is still being processed. |
| HLS_DURATION_LIMIT_REACHED  | 5006  | HLS stream stopped due to maximum duration being reached. |

### Transcription-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_TRANSCRIPTION_FAILED  | 4031  | Failed to start transcription. Please try again. |
| STOP_TRANSCRIPTION_FAILED   | 4032  | Failed to stop transcription.                  |
| TRANSCRIPTION_FAILED        | 5007  | Transcription stopped due to an error.         |

### 5.Errors associated with Media

These errors involve media access, device availability, or permission-related issues affecting camera, microphone, and screen sharing.

### Device permission-related errors
| Type                                      | Code  | Message                                          |
|-------------------------------------------|-------|--------------------------------------------------|
| ERROR_GET_VIDEO_MEDIA_PERMISSION_DENIED  | 3014  | Permission for video capture has been denied. |
| ERROR_GET_AUDIO_MEDIA_PERMISSION_DENIED  | 3015  | Permission for audio capture has been denied. |
| ERROR_GET_DISPLAY_MEDIA_PERMISSION_DENIED | 3016 | Permission for screen sharing has been denied. |
| ERROR_CAMERA_ACCESS_DENIED_OR_DISMISSED      | 3017  | Oops! It seems like camera access was denied or dismissed. To proceed, kindly grant access through your browser settings. |
| ERROR_MICROPHONE_ACCESS_DENIED_OR_DISMISSED      | 3018  | Oops! It seems like microphone access was denied or dismissed. To proceed, kindly grant access through your browser settings. |
| ERROR_CAMERA_ACCESS_UNAVAILABLE          | 3033  | Camera access is unavailable.                 |
| ERROR_MICROPHONE_ACCESS_UNAVAILABLE      | 3034  | Microphone access is unavailable.             |
| ERROR_CAMERA_PERMISSION_DENIED_BY_OS     | 3019  | Camera permission has been denied by the operating system. |
| ERROR_MICROPHONE_PERMISSION_DENIED_BY_OS | 3020  | Microphone permission has been denied by the operating system. |
| ERROR_CAMERA_PERMISSION_OR_AUTOPLAY_ISSUE      | 3025  | It seems like there's an issue with camera permission or video autoplay, you can check out this link for details: http://tinyurl.com/autoplay-issue |
| ERROR_VIDEO_SOURCE_INITIATION_FAILED      | 3026  | Unable to initiate video source. Please verify browser settings for video permissions. |


### Device-related errors
| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| ERROR_GET_VIDEO_MEDIA      | 3011  | Your browser/Device does not support Video. |
| ERROR_GET_AUDIO_MEDIA      | 3012  | Your browser/Device does not support Audio. |
| ERROR_GET_DISPLAY_MEDIA      | 3013  | Your browser/Device does not support Screen Sharing. |
| ERROR_CAMERA_NOT_FOUND       | 3021  | Camera not found. Please ensure it's properly connected. |
| ERROR_MICROPHONE_NOT_FOUND   | 3022  | Microphone not found. Please ensure it's properly connected. |
| ERROR_CAMERA_IN_USE          | 3023  | Camera is already in use by another application. |
| ERROR_MICROPHONE_IN_USE      | 3024  | Microphone is already in use by another application. |


### 6.Errors associated with Track

These errors occur when there are issues with video or audio tracks, such as disconnections or invalid custom tracks.

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| ERROR_WEBCAM_TRACK_ENDED      | 3027  | Webcam track has ended or the webcam is disconnected. Please ensure your webcam is properly connected and try restarting it. |
| ERROR_MICROPHONE_TRACK_ENDED      | 3028  | Microphone track has ended or the microphone is disconnected. Please check your microphone connection and try again. |
| ERROR_INVALID_CUSTOM_VIDEO_TRACK      | 3029  | The provided custom video track is invalid; reverting to the default video track. Please ensure that the video track meets the required specifications. |
| ERROR_INVALID_CUSTOM_AUDIO_TRACK      | 3030  | The provided custom audio track is invalid; reverting to the default audio track. Please ensure that the audio track meets the required specifications. |
| ERROR_CUSTOM_VIDEO_TRACK_ENDED      | 3031  | The provided custom video track is in an ended state. Please verify the video track's status, and try again. |
| ERROR_CUSTOM_AUDIO_TRACK_ENDED     | 3032  | The provided custom audio track is in an ended state. Please verify the audio track's status, and try again. |

### 7.Errors associated with Actions

Below error is triggered when an action is attempted before joining a meeting.

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| ERROR_ACTION_PERFORMED_BEFORE_MEETING_JOINED     | 3035  | Oops! Something went wrong. The room was in a connecting state, and during that time, an action encountered an issue. Please try again after joining a meeting. |

---

# HLS Events - Javascript

VideoSDK provides the `hls-state-changed` event, which informs you about the current state of HLS for the meeting.

### hls-state-changed

- This event is triggered when the HLS status of the meeting changes.
- It can be subscribed to using the `meeting` object.

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

### Example

Here is an example demonstrating the usage of the event mentioned on this page.

```javascript
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const Constants = VideoSDK.Constants;

meeting.on("hls-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.hlsEvents.HLS_STARTING) {
    console.log("Meeting Hls is starting");
  } else if (status === Constants.hlsEvents.HLS_STARTED) {
    // when hls is started you will receive playbackHlsUrl and livestreamUrl.
    const { playbackHlsUrl } = data;

    console.log("Meeting Hls is started");
  } else if (status === Constants.hlsEvents.HLS_STOPPING) {
    console.log("Meeting Hls is stopping");
  } else if (status === Constants.hlsEvents.HLS_STOPPED) {
    console.log("Meeting Hls is stopped");
  } else {
    //
  }
});
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [hls-state-changed](/javascript/api/sdk-reference/meeting-class/events#hls-state-changed)


---

# Media Events - Javascript

VideoSDK offers various events that can be monitored to obtain information about the media status of participants in the meeting.

Here are the events specifically related to the stream:

### stream-enabled

- This event is triggered whenever a participant's video, audio or screen share stream is enabled.
- This event can be subscribed from the `Participant` object.

### stream-disabled

- This event is triggered whenever a participant's video, audio or screen share stream is disabled.
- This event can be subscribed from the `Participant` object.

### media-status-changed

- This event will be triggered whenever a participant's video or audio is disabled or enabled.
- This event can be subscribed from the `Participant` object.

### Example

Here is an example demonstrating the usage of all the events mentioned on this page.

```js
const participants = meeting.participants;
const participant = participants.get("<participant-id>");

participant.on("stream-enabled", (stream) => {
  //
});

participant.on("stream-disabled", (stream) => {
  //
});

participant.on("media-status-changed", (data) => {
  const { kind, newStatus } = data;
  //
});
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [stream-enabled](/javascript/api/sdk-reference/participant-class/events#stream-enabled)
- [stream-disabled](/javascript/api/sdk-reference/participant-class/events#stream-disabled)
- [media-status-changed](/javascript/api/sdk-reference/participant-class/events#media-status-changed)


---

# Meeting Connection Events - Javascript

VideoSDK offers the `meeting-state-changed` event, providing information about the current connection state of the meeting.

### meeting-state-changed

- This event is triggered when the state of a meeting changes.
- The event callback will include the current state of the meeting, which can be one of the following: `CONNECTING`, `CONNECTED`, `FAILED`, `RECONNECTING`, `DISCONNECTED`.
- It can be subscribed to using the `meeting` object.

### Example

Here is an example demonstrating the usage of the event mentioned on this page.

```javascript
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // Configuration options
});

// Subscribe to the meeting-state-changed event
meeting.on("meeting-state-changed", (data) => {
  const { state } = data;

  switch (state) {
    case "CONNECTING":
      console.log("Meeting is Connecting");
      break;
    case "CONNECTED":
      console.log("Meeting is Connected");
      break;
    case "DISCONNECTED":
      console.log("Meeting connection disconnected abruptly");
      break;
    case "RECONNECTING":
      console.log("Meeting is Reconnecting");
      break;
    case 'FAILED':
      console.log("Meeting is in Failed State");
      break;
    default:
      console.log("Unknown state:", state);
      break;
  }
});
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [meeting-state-changed](/javascript/api/sdk-reference/meeting-class/events#meeting-state-changed)


---

# Meeting Events - Javascript

VideoSDK provides several types of events that can be listened to in order to determine the current state of the meeting. 

Here are the events which specifically relate to the meeting:

### meeting-joined

- This event is triggered when the meeting is successfully joined.
- It can be subscribed to using the `meeting` object.

### meeting-left

- This event is triggered when the meeting is left with a specified reason. You can refer to the reason details [here](/javascript/api/sdk-reference/meeting-class/events#meeting-left).
- It can be subscribed to using the `meeting` object.

### speaker-changed

- This event is triggered when there is a change in the active speaker during the meeting.
- It can be subscribed to using the `meeting` object.

### presenter-changed

- This event is triggered when there is a change in the presenter during the meeting.
- It can be subscribed to using the `meeting` object.

### Example

Here is an example demonstrating the usage of the event mentioned on this page.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

meeting.on("meeting-joined", () => {
  //
});

meeting.on("meeting-left", (reason) => {
  //
});

meeting.on("speaker-changed", (activeSpeakerId) => {
  //
});

meeting.on("presenter-changed", (activePresenterId) => {
  //
});
```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [meeting-joined](/javascript/api/sdk-reference/meeting-class/events#meeting-joined)
- [meeting-left](/javascript/api/sdk-reference/meeting-class/events#meeting-left)
- [speaker-changed](/javascript/api/sdk-reference/meeting-class/events#speaker-changed)
- [presenter-changed](/javascript/api/sdk-reference/meeting-class/events#presenter-changed)


---

# Network Events - Javascript

VideoSDK offers the `quality-limitation` event, providing information about any quality limitations detected or resolved during the meeting.

### quality-limitation

- This callback is triggered when a quality limitation is detected or resolved during the meeting.
- Limitations may occur due to congestion, bandwidth issues, or CPU constraints.
- Developers can use this event to gracefully adjust media settings (like reducing video resolution) and restore them once the limitation is resolved.
- It can be subscribed to using the `meeting` object.

### Example

Here is an example demonstrating the usage of the event mentioned on this page.

```javascript
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // Configuration options
});

// Subscribe to the quality-limitation event
meeting.on("quality-limitation", ({ type, state, timestamp }) => {
});
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [quality-limitation](/javascript/api/sdk-reference/meeting-class/events#quality-limitation)


---

# Participant Events - Javascript

VideoSDK provides various events that can be utilized to gather information about the participants in the meeting.

Here are the events specifically related to the participant:

### participant-joined

- This event is triggered when someone joins the meeting, returning the `Participant` object as parameter.
- It can be subscribed to using the `meeting` object.

### participant-left

- This event is triggered when the meeting is left with a specified reason. You can refer to the reason details [here](/javascript/api/sdk-reference/meeting-class/events#participant-left).
- It can be subscribed to using the `meeting` object.

### webcam-requested

- This event is triggered for participant `B`, when another participant, `A` requests to enable their webcam.
- Upon accepting the request, participant `B`'s webcam will be enabled.
- It can be subscribed to using the `meeting` object.

### mic-requested

- This event is triggered for participant `B`, when another participant, `A` requests to enable their mic.
- Upon accepting the request, participant `B`'s mic will be enabled.
- It can be subscribed to using the `meeting` object.

### Example

Here is an example demonstrating the usage of the event mentioned on this page.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

meeting.on("participant-joined", (participant) => {
  //
});

meeting.on("participant-left", (participant, reason) => {
  //
});

meeting.on("webcam-requested", (data) => {
  const { participantId, accept, reject } = data;

  // participantId, will be the id of participant who requested to enable webcam

  // if accept request
  accept();

  // if reject request
  reject();
});

meeting.on("mic-requested", (data) => {
  const { participantId, accept, reject } = data;

  // participantId, will be the id of participant who requested to enable webcam

  // if accept request
  accept();

  // if reject request
  reject();
});
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [participant-joined](/javascript/api/sdk-reference/meeting-class/events#participant-joined)
- [participant-left](/javascript/api/sdk-reference/meeting-class/events#participant-left)
- [webcam-requested](/javascript/api/sdk-reference/meeting-class/events#webcam-requested)
- [mic-requested](/javascript/api/sdk-reference/meeting-class/events#mic-requested)


---

# Recording Events - Javascript

VideoSDK provides the `recording-state-changed` event, which notifies you of the current state of recording for the meeting.

### recording-state-changed

- This event is triggered when the recording status of the meeting changes. 
- It can be subscribed to using the `meeting` object.

### Example

Here is an example demonstrating the usage of the event mentioned on this page.

```javascript
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const Constants = VideoSDK.Constants;

meeting.on("recording-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.recordingEvents.RECORDING_STARTING) {
    console.log("Meeting recording is starting");
  } else if (status === Constants.recordingEvents.RECORDING_STARTED) {
    console.log("Meeting recording is started");
  } else if (status === Constants.recordingEvents.RECORDING_STOPPING) {
    console.log("Meeting recording is stopping");
  } else if (status === Constants.recordingEvents.RECORDING_STOPPED) {
    console.log("Meeting recording is stopped");
  } else {
    //
  }
});
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [recording-state-changed](/javascript/api/sdk-reference/meeting-class/events#recording-state-changed)


---

# RTMP Events - Javascript

VideoSDK provides the `livestream-state-changed` event, which informs you about the current state of the livestream for the meeting.

### livestream-state-changed

- This event is triggered when the  livestream status of the meeting changes.
- It can be subscribed to using the `meeting` object.

### Example

Here is an example demonstrating the usage of the event mentioned on this page.

```javascript
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const Constants = VideoSDK.Constants;

meeting.on("livestream-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.livestreamEvents.LIVESTREAM_STARTING) {
    console.log("Meeting livestream is starting");
  } else if (status === Constants.livestreamEvents.LIVESTREAM_STARTED) {
    console.log("Meeting livestream is started");
  } else if (status === Constants.livestreamEvents.LIVESTREAM_STOPPING) {
    console.log("Meeting livestream is stopping");
  } else if (status === Constants.livestreamEvents.LIVESTREAM_STOPPED) {
    console.log("Meeting livestream is stopped");
  } else {
    //
  }
});
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [livestream-state-changed](/javascript/api/sdk-reference/meeting-class/events#livestream-state-changed)


---

# Stream Events - Javascript

### state

- This event is triggered when the state of a stream changes.
- The event callback will include the current state of the stream, which can be one of the following: `active`, `stuck`, `freeze-detected`, `freeze-resolved`, `stuck`.
- It can be subscribed to using the `stream` object.

:::note
This event is emitted exclusively for remote participants, specifically for their video and screen share video streams.
:::

#### Parameters

- **`state`**: Specifies the current state of the stream.

    - **Type**: `String`
    - **Possible values**:
        - `"active"`: Stream is working normally.
        - `"stuck"`: Stream is not progressing as expected.
        - `"freeze-detected"`: Video freeze has been detected.
        - `"freeze-resolved"`: Video freeze has been resolved.
        - `"ended"`: Stream has ended.

- **`timestamp`**: The time (in milliseconds since epoch) when the state change occurred.
    - **Type**: `Number`

### Example

Here is an example demonstrating the usage of the event mentioned on this page.

```javascript
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // Configuration options
});

meeting.on("participant-joined", (participant) => {
  participant.on("stream-enabled", (stream) => {
    stream.on("state", ({ state, timestamp }) => {});
  });
});
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [state](/javascript/api/sdk-reference/stream-class/events#state)


---

<h1> {props.title} </h1>{" "}

Building applications with real-time voice, video, and interaction are just plain hard. It is complex and it takes a lot of time to build.

Video SDK provides developers with simple-to-use, highly customisable, and widely compatible APIs to embed real-time video, voice, and interaction functionalities into their applications without the need to develop the technology or the underlying infrastructure for real-time engagement themselves.


## Steps


<div class="container guide-steps-block">
  <div class="row ">
    <div class="col col--6">
      
    </div>
     <div class="col col--6">
      
    </div>
  </div>
  <div class="row ">
   <div class="col col--6" >
      
    </div>
    <div class="col col--6">
      
    </div>
  </div>
  <div class="row ">
   <div class="col col--6" >
      
    </div>
    <div class="col col--6">
      
    </div>
  </div>
</div>

## Architecture

This diagram demonstrates end-to-end flow to implement video & audio calling, record calls and go-live on social media.

![Video-sdk-architecture!](/img/video-sdk-archietecture.svg)


---

---
title: Active Speaker Indication | Video SDK Docs
hide_title: false
hide_table_of_contents: false
description: Speaker Indication features quick integrate in Javascript, React JS, Android, IOS, React Native, Flutter with Video SDK to add live video & audio conferencing to your applications.
sidebar_label: Active Speaker Indication
pagination_label: Active Speaker Indication
keywords:
  - Active Speaker
  - audio calling
  - video calling
  - real-time communication
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: active-speaker-indication
--- 

# Active Speaker Indication - Javascript

The Active Speaker Indication feature in VideoSDK allows you to identify the participant who is currently the active speaker in a meeting. This feature proves especially valuable in larger meetings or webinars, where numerous participants can make it challenging to identify the active speaker.

Whenever any participant speaks in a meeting, the `onSpeakerChanged` event will trigger, providing the participant ID of the active speaker.

For example, the meeting is running with **Alice** and **Bob**. Whenever any of them speaks, `onSpeakerChanged` event will trigger and return the speaker's `participantId`.

### Event

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

meeting.on("speaker-changed", (activeSpeakerId) => {
  console.log("participantId", activeSpeakerId);
  //
});
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [speaker-changed](/javascript/api/sdk-reference/meeting-class/events#speaker-changed)


---

# Change Audio Output Device - Javascript

During the meeting, at any point, a participant wishing to switch their output audio device, such as from headphones to speakers, can do so using the below-mentioned methods.

#### Getting Output device

- To get all the available audio output devices, you can use the `navigator.mediaDevices`, and then filter it based on the device kind as `audiooutput`.


```js
const getAudioOutputDevice = () => {
  const audioOutputDevice = new Map();
  const devices = await navigator.mediaDevices.enumerateDevices();
  for (const device of devices) {
    if (device.kind == "audiooutput") audioOutputDevice.set(device.deviceId, device);
  }
  return audioOutputDevice;
}
```

#### Changing Output Device

- To change the output audio device, you need to set the `sinkId` for each `<audio>` element used to render the audio in the meeting.

```js
const setAudioOutputDevice = (deviceId) => {
  const audioTags = document.getElementsByTagName("audio");
  audioTags.forEach((tag) => {
    tag.setSinkId(deviceId);
  });
};
```

:::note
To learn more about changing the audio output device [check this documentation](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/setSinkId).
:::

### Setting Audio Volume

- To set the audio volume for the meeting, you need to adjust the volume property for each `<audio>` element used to render the paricipant audio.

- Value for the `volume` property for the `<audio>` can be between `0` and `1`.

```js
const setAudioVolume = (volume) => {
  const audioTags = document.getElementsByTagName("audio");
  audioTags.forEach((tag) => {
    tag.volume = volume;
  });
};
```

:::note
To learn more about adjusting the audio volume [check this documentation](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/volume).
:::


---

# Change Input Device - Javascript

During the meeting, at any point, a participant wishing to switch their input audio or video device, can do so using the below-mentioned methods.

## Changing Audio Input Device

### `getMics()`

- This method of the **Meeting** class will provide you with a list of all the available mics, which can be displayed in a dropdown list.

- It will return an array of objects, which will contain the `deviceId` and  the `label` of the audio input device.

### `changeMic()`

- Once you know which device you want to switch the audio input to, you can pass the `deviceId` to this method to change the audio input device.

#### Example

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const mics = await meeting?.getMics();

const { deviceId, label } = mics[0];

meeting?.changeMic(deviceId);
```

## Getting the Audio Input Device currently in use.

- You can get the audio device that is currently in use in the meeting,using the `selectedMicrophoneDevice` property of the `Meeting` class.

#### Example

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

// ...

console.log("Currently used Audio Input Device : ", meeting?.selectedMicrophoneDevice);
```

## Changing Camera Input Device

### `getWebcams()`

- This method of the **Meeting** class will provide you with a list of all the available cameras, which can be displayed in a dropdown list.

- This method will return an array of objects which will contain the `deviceId` and `label` of the camera input device.

### `changeWebcam()`

- Once you know which device you want to switch the camera input to, you can pass the `deviceId` to this method to change the camera input device.

#### Example

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const webcams = await meeting?.getWebcams();

const { deviceId, label } = webcams[0];

meeting?.changeWebcam(deviceId);
```

## Getting the Camera Device currently in use.

- You can get the camera device that is currently in use in the meeting, using the `selectedCameraDevice` property of the `Meeting` class.

#### Example

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

// ...

console.log("Currently used Webcam : ", meeting?.selectedCameraDevice);
```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [getMics()](/javascript/api/sdk-reference/meeting-class/methods#getmics)
- [getWebcams()](/javascript/api/sdk-reference/meeting-class/methods#getwebcams)
- [changeMic()](/javascript/api/sdk-reference/meeting-class/methods#changemic)
- [changeWebcam()](/javascript/api/sdk-reference/meeting-class/methods#changewebcam)


---

# Image Capturer - Javascript

This guide provides instructions on capturing images of participants from a video stream.

This capability proves particularly valuable in Video KYC scenarios, enabling the capture of images where users can hold up their identity for verification.

:::note

The `captureImage()` function is supported from version `0.0.75` onward.

:::

### `captureImage()`

- By using the `captureImage()` method of the `Participant` class, you can capture image of a local participant from their video stream.
- You have the option to specify the desired height and width in the `captureImage()` function; however, these parameters are optional. If not provided, the VideoSDK will automatically use the dimensions of the local participant's webcamStream.
- The `captureImage()` function returns the image in the form of a `base64` string.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

let isWebcamOn; // status of your webcam, true/false

async function imageCapture() {
  if (isWebcamOn) {
    const base64Data = await meeting.localParticipant.captureImage(); // captureImage will return base64 string
    console.log("base64", base64);
  } else {
    console.error("Camera must be on to capture an image");
  }
}
```

:::tip

Rather than utilizing the `participants.get(participantId).captureImage()` method to capture an image of a remote participant, it is advisable to refer to the provided documentation for a more effective approach. The `participants.get(participantId).captureImage()` method captures an image from the current video stream being consumed from the remote participant. The alternative documentation is likely to provide a better and more appropriate method to achieve the desired result.

:::

### How to capture image of remote participant ?

- Before proceeding, it's crucial to understand [VideoSDK's temporary file storage system](/javascript/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/upload-fetch-temporary-file) and the underlying [pubsub mechanism](/javascript/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

- Here's a break down of the steps, using the names Participant A and Participant B for clarity:

#### Step 1 : Initiate Image Capture Request

- In this step, you have to first send a request to Participant B, whose image you want to capture, using pubsub.
- In order to do that, you have to create a pubsub topic called `IMAGE_CAPTURE` in the `index.js` File.​
- Here, you will be using the `sendOnly` property of the `publish()` method. Therefore, the request will be sent to that participant only.

```js title="index.js"
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

function sendRequest({ participantId }) {
  // Pass the participantId of the participant twhose image you want to capture
  // Here, it will be Participant B's id, as you want to capture the the image of Participant B
  let message = "Sending request to capture image";
  meeting.pubSub
    .publish("IMAGE_CAPTURE", message, {
      persist: false,
      sendOnly: [participantId],
    })
    .then((res) => console.log(`response of publish : ${res}`))
    .catch((err) => console.log(`error of publish : ${err}`));
}
```

#### Step 2 : Capture and Upload File

- To capture an image from the remote participant [Participant B], you have to subscribe to the pubsub topic on the `meeting-joined` event of the `Meeting` class. When a participant receives an image capture request, this component uses the `captureImage` method of the `Participant` class to capture the image.

```js title="index.js"
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

async function captureAndStoreImage() {
  // capture image
  const base64Data = await meeting.localParticipant.captureImage();
  console.log("base64Data", base64Data);
}

const _handleOnImageCaptureMessageReceived = (message) => {
  try {
    if (message.senderId !== meeting.localParticipant.id) {
      // capture and store image when message received
      captureAndStoreImage();
    }
  } catch (err) {
    console.log("error on image capture", err);
  }
};

meeting.on("meeting-joined", () => {
  // ...
  meeting.pubSub.subscribe("IMAGE_CAPTURE", (data) => {
    _handleOnImageCaptureMessageReceived(data);
  });
});
```

- The captured image is then stored in VideoSDK's temporary file storage system using the `uploadBase64File()` function of the `Meeting` class. This operation returns a unique `fileUrl` of the stored image.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

async function captureAndStoreImage() {
  // capture image
  const base64Data = await meeting.localParticipant.captureImage();
  // upload image to videosdk storage system
  const fileUrl = await meeting.uploadBase64File({
    base64Data,
    token: "VIDEOSDK_TOKEN",
    fileName: "myImage.jpeg", // specify a name for image file with extension
  });

  console.log("fileUrl", fileUrl);
}
```

- Next, the `fileUrl` is sent back to the participant who initiated the request using the `IMAGE_TRANSFER` topic.

```js
async function captureAndStoreImage() {
  // ...

  const fileUrl = await meeting.uploadBase64File({
    base64Data,
    token: "VIDEOSDK_TOKEN",
    fileName: "myImage.jpeg", // specify a name for image file with extension
  });

  // publish image Transfer
  //highlight-start
  meeting.pubSub
    .publish("IMAGE_TRANSFER", fileUrl, {
      persist: false,
      sendOnly: [senderId],
    })
    .then((res) => console.log(`response of publish : ${res}`))
    .catch((err) => console.log(`error of publish : ${err}`));
  //highlight-end
}
```

#### Step 2 : Fetch and Display Image

- Upon publishing on the `IMAGE_TRANSFER` topic, subscribe to the same topic within the `meeting-joined` event of the `Meeting` class. This will provide access to the `fileUrl` associated with the captured image. Once obtained, use the `fetchBase64File()` method of the `Meeting` class to retrieve the file in `base64` format from VideoSDK's temporary storage.

```js
async function captureImageAndDisplay(message) {
  const token = "VIDEOSDK_TOKEN";
  let base64 = await meeting.fetchBase64File({
    url: message.message,
    token,
  });
  console.log("base64", base64); // here is your image in a form of base64
}

meeting.on("meeting-joined", () => {
  // ...
  meeting.pubSub.subscribe("IMAGE_TRANSFER", (data) => {
    if (data.senderId !== meeting.localParticipant.id) {
      captureImageAndDisplay(data);
    }
  });
});
```

- With the `base64` data in hand, you can now display the image.

```js
let captureImage = document.getElementById("captureImage");

async function captureImageAndDisplay(message) {
  const token = "VIDEOSDK_TOKEN";
  let base64 = await meeting.fetchBase64File({
    url: message.message,
    token,
  });
  console.log("base64", base64); // here is your image in a form of base64

  base64 = "data:data:image/jpeg;base64," + base64;
  captureImage.src = base64;
}
```

```html

<img id="captureImage" />
```

:::note

The file stored in the [VideoSDK's temporary file storage system](/javascript/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/upload-fetch-temporary-file) will be automatically deleted once the current room/meeting comes to an end.

:::

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [captureImage](/javascript/api/sdk-reference/participant-class/methods#captureimage)
- [pub-sub](/javascript/api/sdk-reference/meeting-class/properties#pubsub)
- [uploadbase64file](/javascript/api/sdk-reference/meeting-class/methods#uploadbase64file)
- [fetchbase64file](/javascript/api/sdk-reference/meeting-class/methods#fetchbase64file)


---

# Mute / Unmute Mic - Javascript

Muting and Unmuting your microphone refers to turning your microphone off and on, respectively.

Muting your microphone prevents the transmission of any sound from your microphone to other meeting participants, while unmuting allows them to hear you.

### `unmuteMic()`

- By using the `unmuteMic()` function of the `meeting` object, the local participant can publish their audio to other participants.

  - You can only call this method when the local participant is not broadcasting audio to others.

- You can also pass a customised audio track in `unmuteMic()` by using [Custom Audio Track](/javascript/guide/video-and-audio-calling-api-sdk/render-media/optimize-audio-track).

- Audio stream of the participant can be accessed from the `streams` property of the `Participant` object.

### `muteMic()`

- By using the `muteMic()` function of the `meeting` object, the local participant can stop publishing their audio to other participants.

- You can only call this method when the local participant is broadcasting audio to others.

#### Example

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const unmuteMicBtn = document.getElementById("unmuteMicBtn");
unmuteMicBtn.addEventListener("click", () => {
  // unmuteMic Meeting
  meeting?.unmuteMic();
});

const muteMicBtn = document.getElementById("muteMicBtn");
muteMicBtn.addEventListener("click", () => {
  // unmuteMic Meeting
  meeting?.muteMic();
});
```

:::note
To learn, how to render a audio in the meeting, follow this detailed [guide](/javascript/guide/video-and-audio-calling-api-sdk/render-media/display-audio-video#3-rendering-audio).
:::

### Events associated with unmuteMic

- Every Participant will receive a callback on [`stream-enabled`](/javascript/api/sdk-reference/participant-class/events#stream-enabled) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object with the `Stream` object.

- Every Participant will receive a callback on [`media-status-changed`](/javascript/api/sdk-reference/participant-class/events#media-status-changed) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object with the type of media and its status.

### Events associated with muteMic

- Every Participant will receive a callback on [`stream-disabled`](/javascript/api/sdk-reference/participant-class/events#stream-disabled) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object with the `Stream` object.

- Every Participant will receive a callback on [`media-status-changed`](/javascript/api/sdk-reference/participant-class/events#media-status-changed) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object with the type of media and its status.

```js
const participants = meeting.participants;
const participant = participants.get("<participant-id>");

participant.on("stream-enabled", (stream) => {
  if (stream.kind === "audio") {
    //particiapnt turned on audio
    //Render Participant audio logic here
  }
});

participant.on("stream-disabled", (stream) => {
  if (stream.kind === "audio") {
    //particiapnt turned off audio
    //remove Participant audio logic here
  }
});

participant.on("media-status-changed", (data) => {
  const { kind, newStatus } = data;
  if (kind === "audio") {
    //particiapnt media status changed
  }
});
```

### Audio Permissions

- By default, VideoSDK will request audio permission when a participant attempts to turn on the mic. Once the permission is granted, the mic is activated. If the permission is denied, VideoSDK will send an error message in the `onError` event callback of the `meeting` object.


<div style={{textAlign: 'center'}}>



</div>

### Troubleshoot Audio Permissions

- If a participant denies the microphone permission, they can **manually grant** it by following the below shown steps.

<div style={{textAlign: 'center'}}>



</div>

:::caution
To use the audio and video communications in the web browser, your site must be **`SSL enabled`** i.e. it must be secured and **`running on https`**.
:::

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [unmuteMic()](/javascript/api/sdk-reference/meeting-class/methods#unmutemic)
- [muteMic()](/javascript/api/sdk-reference/meeting-class/methods#mutemic)
- [stream-enabled event](/javascript/api/sdk-reference/participant-class/events#stream-enabled)
- [stream-disabled event](/javascript/api/sdk-reference/participant-class/events#stream-disabled)
- [media-status-changed](/javascript/api/sdk-reference/participant-class/events#media-status-changed)


---

---
title: On / Off Camera | Video SDK
hide_title: true
hide_table_of_contents: false
description: Camera Controls features quick integrate in Javascript, React JS, Android, IOS, React Native, Flutter with Video SDK to add live video & audio conferencing to your applications.
sidebar_label: On / Off Camera
pagination_label: On / Off Camera
keywords:
  - audio calling
  - video calling
  - real-time communication
  - collaboration
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: on-off-camera
--- 

# On / Off Camera - Javascript

Participants in the meeting have the ability to toggle their cameras on or off using the methods outlined below.

### `enableWebcam()`

- By using the `enableWebcam()` function of the `meeting` object, the local participant can publish their video to other participants.

- You can only call this method when the local participant is not broadcasting video to others.

- You can also pass a customised video track in `enableWebcam()` by using [Custom Video Track](/javascript/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track).

- The video stream of a participant can be accessed from the `streams` property of the `Participant` object.

### `disableWebcam()`

- By using the `disableWebcam()` function of the `meeting` object, the local participant can stop publishing their video to other participants.

- You can only call this method when the local participant is broadcasting video to others.

#### Example

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const enableWebcamBtn = document.getElementById("enableWebcamBtn");
enableWebcamBtn.addEventListener("click", () => {
  // Enable Webcam in Meeting
  meeting?.enableWebcam();
});

const disableWebcamBtn = document.getElementById("disableWebcamBtn");
disableWebcamBtn.addEventListener("click", () => {
  // Disable Webcam in Meeting
  meeting?.disableWebcam();
});
```

:::note
To learn, how to render video in the meeting, follow this detailed [guide](/javascript/guide/video-and-audio-calling-api-sdk/render-media/display-audio-video#2-rendering-video).
:::

### Events associated with enableWebcam

- Every Participant will receive a callback on[`stream-enabled`](/javascript/api/sdk-reference/participant-class/events#stream-enabled) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object with the `Stream` object.

- Every Participant will receive a callback on [`media-status-changed`](/javascript/api/sdk-reference/participant-class/events#media-status-changed) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object with the type of media and its status.

### Events associated with disableWebcam

- Every Participant will receive a callback on [`stream-disabled`](/react/api/sdk-reference/use-participant/events#onstreamdisabled) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object with `Stream` object.

- Every Participant will receive a callback on [`media-status-changed`](/javascript/api/sdk-reference/participant-class/events#media-status-changed) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object with the type of media and its status.

```js
const participants = meeting.participants;
const participant = participants.get("<participant-id>");

participant.on("stream-enabled", (stream) => {
  if (stream.kind === "video") {
    //particiapnt turned on video
    //Render Participant video logic here
  }
});

participant.on("stream-disabled", (stream) => {
  if (stream.kind === "video") {
    //particiapnt turned off video
    //remove Participant video logic here
  }
});

participant.on("media-status-changed", (data) => {
  const { kind, newStatus } = data;
  if (kind === "video") {
    //particiapnt media status changed
  }
});
```

### Video Permissions

- By default, VideoSDK will request video permission when the participants attempts to turn on the camera. Once the permission is granted the camera gets turned on. If the permission is denied, VideoSDK will send an error message in the `onError` event callback of the `meeting` object.


<div style={{textAlign: 'center'}}>



</div>

### Troubleshoot Video Permissions

- If a participant denies the camera permission, they can **manually grant** it by following below shown steps.

<div style={{textAlign: 'center'}}>



</div>

:::caution
To use the audio and video communications in the web browser, your site must be **`SSL enabled`** i.e. it must be secured and **`running on https`**.
:::

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [enableWebcam()](/javascript/api/sdk-reference/meeting-class/methods#enablewebcam)
- [disableWebcam()](/javascript/api/sdk-reference/meeting-class/methods#disablewebcam)
- [stream-enabled event](/javascript/api/sdk-reference/participant-class/events#stream-enabled)
- [stream-disabled event](/javascript/api/sdk-reference/participant-class/events#stream-disabled)
- [media-status-changed event](/javascript/api/sdk-reference/participant-class/events#media-status-changed)


---

# Screen Share - Javascript

Screen sharing in a meeting is the process of sharing your computer screen with other participants in the meeting. It allows everyone in the meeting to see exactly what you are seeing on your screen, which can be helpful for presentations, demonstrations, or collaborations.

### `enableScreenShare()`

- By using the `enableScreenShare()` function of the `meeting` object, the local participant can share their desktop screen to other participants.

- You can also pass a customised screenshare track in `enableScreenShare()` by using [Custom Screen Share Track](/javascript/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track#custom-screen-share-track).

- The Screen Share stream of a participant can be accessed from the `streams` property of the `Participant` object.

### `disableScreenShare()`

- By using `disableScreenShare()` function of the `meeting` object, the local participant can stop sharing their desktop screen to other participants.

:::note
Screen Sharing is only supported in the **Desktop browsers** and **not in mobile/tab browser**.
:::

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const enableScreenShareBtn = document.getElementById("enableScreenShareBtn");
enableScreenShareBtn.addEventListener("click", () => {
  // Enabling ScreenShare
  meeting?.enableScreenShare();
});

const disableScreenShareBtn = document.getElementById("disableScreenShareBtn");
disableScreenShareBtn.addEventListener("click", () => {
  // Disabling ScreenShare
  meeting?.disableScreenShare();
});
```

### Events associated with enableScreenShare

- Every Participant will receive a callback on [`stream-enabled`](/javascript/api/sdk-reference/participant-class/events#stream-enabled) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object with `Stream` object.

- Every Participant will receive a callback on [`presenter-changed`](/javascript/api/sdk-reference/meeting-class/events#presenter-changed) event of the meeting object with `presenterId`.

### Events associated with disableScreenShare

- Every Participant will receive a callback on [`stream-disabled`](/react/api/sdk-reference/use-participant/events#onstreamdisabled) event of the [`participant`](/javascript/api/sdk-reference/participant-class/introduction) object with the `Stream` object.

- Every Participant will receive a callback on [`presenter-changed`](/javascript/api/sdk-reference/meeting-class/events#presenter-changed) event of the meeting object with `null` value indicating there is no current presenter.

```js
const participants = meeting.participants;
const participant = participants.get("<participant-id>");

participant.on("stream-enabled", (stream) => {
  if (stream.kind === "share") {
    //particiapnt turned on screen share
    //Render screenshare logic here
  }
});

participant.on("stream-disabled", (stream) => {
  if (stream.kind === "share") {
    //particiapnt turned off screenshare
    //remove screenshare logic here
  }
});

let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

meeting.on("presenter-changed", (presenterId) => {
  if (presenterId) {
    //someone start presenting
  } else {
    //someone stopped presenting
  }
});
```

### Screen Share with Audio

To enable screen sharing with audio, select the **Share tab audio** option when sharing the chrome tab as shown below.

<center>

![Screen Share with Audio](/img/screenshare-with-audio.png)

</center>

After clicking the `Share` button, you will receive the selected tab's audio stream in the participant's `screenShareAudioStream`.

:::note
Screen Share with Audio is only supported while sharing **Chrome Tab** in a **Chromium based browser** like Google Chrome, Brave etc.
:::

### Rendering Screen Share and Screen Share Audio

1. To display the screenshare video stream, you will receive it in the participant's stream-enabled callback with the stream kind set as "share".


```js
const participants = meeting.participants;
const participant = participants.get("<participant-id>");

participant.on("stream-enabled", (stream) => {
  if (stream.kind == "share") {
    const videoElem = createShareVideoElement(participant.id, stream);

    //add audioElem to your container
    container.appendChild(videoElem);
  }

  if (stream.kind == "shareAudio") {
  }
});

// creating video element
function createShareVideoElement(pId, stream) {
  if (pId == meeting.localParticipant.id) return;

  let videoElement = document.createElement("video");
  videoElement.setAttribute("autoPlay", false);
  videoElement.setAttribute("controls", "false");
  videoElement.setAttribute("id", `v-share-${pId}`);

  const mediaStream = new MediaStream();
  mediaStream.addTrack(stream.track);
  videoElement.srcObject = mediaStream;
  videoElement
    .play()
    .catch((error) => console.error("audioElem.play() failed", error));
  return videoElement;
}

// creating audio element
function createShareAudioElement(pId, stream) {}
```

2. Now to render the screenshare audio stream, you will receive it in the participant's stream-enabled callback with the stream kind set as "shareAudio".

```js
const participants = meeting.participants;
const participant = participants.get("<participant-id>");

participant.on("stream-enabled", (stream) => {
  if (stream.kind == "share") {
  }
  if (stream.kind == "shareAudio") {
    const audioElem = createShareAudioElement(participant.id, stream);

    //add audioElem to your container
    container.appendChild(audioElem);
  }
});

// creating video element
function createShareVideoElement(pId, stream) {}

// creating audio element
function createShareAudioElement(pId, stream) {
  if (pId == meeting.localParticipant.id) return;

  let audioElement = document.createElement("audio");
  audioElement.setAttribute("autoPlay", false);
  audioElement.setAttribute("playsInline", "false");
  audioElement.setAttribute("controls", "false");
  audioElement.setAttribute("id", `a-share-${pId}`);
  audioElement.style.display = "none";

  const mediaStream = new MediaStream();
  mediaStream.addTrack(stream.track);
  audioElement.srcObject = mediaStream;
  audioElement
    .play()
    .catch((error) => console.error("audioElem.play() failed", error));
  return audioElement;
}
```

### Troubleshoot MacOS Screen Share Permissions

- If you are using MacOS, you will have to allow the browser to do screen share. You can follow the steps shown in the video to do so.


<div style={{textAlign: 'center'}}>



</div>

:::caution
To use the audio and video communications in the web browser, your site must be **`SSL enabled`** i.e. it must be secured and **`running on https`**.
:::

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [enableScreenShare()](/javascript/api/sdk-reference/meeting-class/methods#enablescreenshare)
- [disableScreenShare()](/javascript/api/sdk-reference/meeting-class/methods#disablescreenshare)
- [stream-enabled event](/javascript/api/sdk-reference/participant-class/events#stream-enabled)
- [stream-disabled event](/javascript/api/sdk-reference/participant-class/events#stream-disabled)
- [presenter-changed event](/javascript/api/sdk-reference/meeting-class/events#presenter-changed)


---



---

# Known Issues




---

https://sdk.videosdk.live/js-sdk/0.2.6/videosdk.jsVideoSDK offers a range of video streaming tools and solutions for content creators, publishers, and developers.

- A custom template is a specialized layout for a live stream that allows users to integrate real-time graphics into their broadcasts.

- With custom templates, users can enhance their video content by overlaying graphics, text, images, and animations onto their live streams. These elements can be customized to align with specific branding requirements.

- By leveraging custom templates, users can craft dynamic and engaging video experiences. Whether incorporating live scoreboards, social media feeds, or other personalized elements, users have the flexibility to create visually appealing streams that stand out and capture audience attention.

:::note

Custom templates can also be used with recordings and RTMP service provided by VideoSDK.

:::

### What you can do with Custom Template

By utilizing a custom template, you have the flexibility to create various modes for your live stream. Here are some popular modes that you can design:

- **`PK Host:`** The host can organize a player vs. player battle, as illustrated in the example of a gaming battle shown below.

![pk host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_pk_battle.png)

- **`Watermark:`** The host has the ability to add and update watermarks anywhere in the template; for instance, the image below features a VideoSDK watermark on the top right side of the screen.

![watermark host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_water_mark.png)

- **`News Mode:`** Additionally, the host can incorporate dynamic text in the lower third banner, as demonstrated by the sample text in the bottom left of the screen.

![news mode](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_news_live.png)

### Custom template with VideoSDK

In this section, we will discuss how Custom Templates work with VideoSDK.

- **`Host`**: The host initiates live streaming by providing the `templateURL`. The `templateURL` is the URL of the hosted template webpage. The host is also responsible for managing the template, including tasks such as altering text, logos, and switching template layouts.

- **`VideoSDK Template Engine`** : The VideoSDK Template Engine accepts and opens the templateURL in the browser, actively listening to all events initiated by the Host. It facilitates the customization of the template in accordance with the host's preferences.

- **`Viewer`**: Viewers can stream the content, experiencing the live stream with added real-time graphics. This feature contributes to a distinctive and engaging viewing experience.

![custom template](https://cdn.videosdk.live/website-resources/docs-resources/custom_template.png)

### Understanding Template URL

The template URL is a webpage that VideoSDK Template Engine will open while composing the live stream.

It will appear as shown below.

![template url](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_url.png)

The Template URL comprises of two essential parts:

- Your actual page URL, resembling something like `https://example.com/videosdk-template`.
- Query parameters, designed to enable the VideoSDK Template Engine to seamlessly join the meeting upon opening the URL. There are three key query parameters in total:
  - `token`: Your token, serving as the authentication key to join the meeting.
  - `meetingId`: The meeting Id of the meeting that the VideoSDK Template Engine will join.
  - `participantId`: The participant ID of the VideoSDK Template Engine. This should be included when joining the template engine in your template, ensuring that the template engine participant remains invisible to other participants. **This parameter is automatically added by the VideoSDK**.

:::info

Above mentioned query parameters are mandatory. Apart from these parameters, you can pass any other extra parameters which are required according to your use-case.

:::

### **Creating Template**

**`Step 1:`** Import VideoSDK using `<script>` tag or install it using the below-mentioned npm command.
Make sure you are in your app directory before you run this command.



**Tab:**

" label="<script>" default>

```html
<html>
  <head></head>
  <body>
// highlight-next-line
<script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
  </body>
</html>
```

---

**npm:**

```bash
npm install @videosdk.live/js-sdk
```

---

**yarn:**

```bash
yarn add @videosdk.live/js-sdk
```

:::note

You can use VideoSDK's React or JavaScript SDK to create custom template. Following is the example of building custom template with JavaScript SDK.

:::

###### Structure of the Project

```jsx title="Project Structure"
  root
   ├── index.html
   ├── index.js
```

**`Step 2:`** Craft a user interface (UI) tailored for your live stream presentation.

```html title="index.html"
<!DOCTYPE html>
<html>
  <head> </head>

  <body>
    <div id="textDiv">Starting live stream...</div>

    
    <div class="row" id="videoContainer"></div>

    <script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
    <script src="index.js"></script>
  </body>
</html>
```

**`Step 3:`** Next, fetch the query parameters, from the URL which will be later used to initialize the meeting and get the elements from DOM.

```js title=index.js
const url = window.location;
const urlParams = new URLSearchParams(url.search);

const meetingId = urlParams.get("meetingId");
const token = urlParams.get("token");
const participantId = urlParams.get("participantId");

const videoContainer = document.getElementById("videoContainer");
const textDiv = document.getElementById("textDiv");
```

**`Step 4:`** Subsequently, initialize the meeting with the parameters that were extracted from the URL. Ensure direct initialization so that the template engine seamlessly joins the meeting upon page load.

```js title=index.js
window.VideoSDK.config(token);

const meeting = window.VideoSDK.initMeeting({
  meetingId: meetingId, // required
  name: "recorder", // required
  micEnabled: false,
  webcamEnabled: false,
  participantId: participantId,
});

meeting.join();

meeting.on("meeting-joined", () => {
  textDiv.style.display = "none";
});
```

**`Step 5:`** Next step is to create the container that will render the meeting view on the `participant-joined` event.

```js title=index.js
//  participant joined
meeting.on("participant-joined", (participant) => {
  let videoElement = createVideoElement(
    participant.id,
    participant.displayName
  );
  let audioElement = createAudioElement(participant.id);

  participant.on("stream-enabled", (stream) => {
    setTrack(stream, audioElement, participant, false);
  });
  videoContainer.appendChild(videoElement);
  videoContainer.appendChild(audioElement);
});

// participants left
meeting.on("participant-left", (participant) => {
  let vElement = document.getElementById(`f-${participant.id}`);
  vElement.remove(vElement);

  let aElement = document.getElementById(`a-${participant.id}`);
  aElement.remove(aElement);
});

// creating video element
function createVideoElement(pId, name) {
  let videoFrame = document.createElement("div");
  videoFrame.setAttribute("id", `f-${pId}`);

  //create video
  let videoElement = document.createElement("video");
  videoElement.classList.add("video-frame");
  videoElement.setAttribute("id", `v-${pId}`);
  videoElement.setAttribute("playsinline", true);
  videoElement.setAttribute("width", "300");
  videoElement.muted = true;
  videoFrame.appendChild(videoElement);

  let displayName = document.createElement("div");
  displayName.innerHTML = `Name : ${name}`;
  videoFrame.appendChild(displayName);

  return videoFrame;
}

// creating audio element
function createAudioElement(pId) {
  let audioElement = document.createElement("audio");
  audioElement.setAttribute("autoPlay", "false");
  audioElement.setAttribute("playsInline", "true");
  audioElement.setAttribute("controls", "false");
  audioElement.setAttribute("id", `a-${pId}`);
  audioElement.style.display = "none";
  return audioElement;
}

// setting media track
function setTrack(stream, audioElement, participant, isLocal) {
  if (stream.kind == "video") {
    isWebCamOn = true;
    const mediaStream = new MediaStream();
    mediaStream.addTrack(stream.track);
    let videoElm = document.getElementById(`v-${participant.id}`);
    videoElm.srcObject = mediaStream;
    videoElm
      .play()
      .catch((error) =>
        console.error("videoElem.current.play() failed", error)
      );
  }
  if (stream.kind == "audio") {
    if (isLocal) {
      isMicOn = true;
    } else {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(stream.track);
      audioElement.srcObject = mediaStream;
      audioElement
        .play()
        .catch((error) => console.error("audioElem.play() failed", error));
    }
  }
}
```

**`Step 6:`** Now, listen to PubSub messages from the `CHANGE_BACKGROUND` topic, triggering a change in the meeting's background color accordingly.

:::note

The PubSub mechanism is utilized to communicate with the template. You can learn more about [PubSub from here](/javascript/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

:::

```js title=index.js
meeting.on("meeting-joined", () => {
  //  ...

  meeting.pubSub.subscribe("CHANGE_BACKGROUND", (data) => {
    let { message } = data;
    document.body.style.backgroundColor = message;
  });
});
```

**`Step 7:`** Once tested, you can deploy it using your backend or host it on services like [firebase](https://www.geeksforgeeks.org/how-to-deploy-react-project-on-firebase/) or vercel.

:::tip

You can checkout the github repository for sample custom template [created here](https://github.com/videosdk-live/videosdk-custom-recording-template-js-example).

:::

### Setup Livestream Using Custom Template

- To utilize Custom Templates with Livestream, you need to establish both the Host and Viewer setups. The Host initiates the livestream, while Viewers can watch the broadcast.

![template manager](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_manager.png)

- To understand custom templates, clone this example and run it on your system.

```bash
git clone https://github.com/videosdk-live/videosdk-custom-recording-template-js-example.git
```

- You can utilize this custom template in [Start Recording API](/api-reference/realtime-communication/start-recording), [Start HLS API](/api-reference/realtime-communication/start-hlsStream) and [Start Livestream API](/api-reference/realtime-communication/start-livestream). Here is the example of HLS.
- To utilize the custom template that has been deployed, invoke the [Start HLS API](https://docs.videosdk.live/api-reference/realtime-communication/start-hlsStream) instead of the `startHls` method from the `Meeting` class. The necessary code has already been incorporated in the cloned example above.

:::important

You can create your own custom template manager in JavaScript. In this example, we are using one for better understanding.

:::

```js
<button
  onClick={async () => {
    const url = `https://api.videosdk.live/v2/hls/start`;
    //Update your Custom Template URL here if you have deployed your own, if not deployed you can use this template from our URL.
    //highlight-next-line
    const templateUrl = `https://lab.videosdk.live/js-template-demo/?meetingId=${meetingId}&token=${authToken}`;
    const options = {
      method: "POST",
      headers: {
        Authorization: authToken,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        roomId: meetingId,
        templateUrl: templateUrl,
      }),
    };

    const result = await fetch(url, options)
      .then((response) => response.json()) // result will have playbackHlsUrl and livestreamUrl
      .catch((error) => console.error("error", error));
  }}
>
  Start HLS
</button>
```

- In this example, the host has two options on their side, enabling them to change the background and send messages to the viewers.

- Given below is a test run of the example.


<div style={{textAlign: 'center'}}>



</div>

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)
- [Start HLS API](/api-reference/realtime-communication/start-hlsStream)
- [Start Livestream API](/api-reference/realtime-communication/start-livestream)
- [recordingState](/react/api/sdk-reference/use-meeting/properties#recordingstate)
- [hlsState](/react/api/sdk-reference/use-meeting/properties#hlsstate)
- [livestreamState](/react/api/sdk-reference/use-meeting/properties#livestreamstate)
- [hlsUrls](/react/api/sdk-reference/use-meeting/properties#hlsurls)
- [onRecordingStateChanged](/react/api/sdk-reference/use-meeting/events#onrecordingstatechanged)
- [onHlsStateChanged](/react/api/sdk-reference/use-meeting/events#onhlsstatechanged)
- [onLivestreamStateChanged](/react/api/sdk-reference/use-meeting/events#onlivestreamstatechanged)



---

# Interactive Livestream (HLS) - Javascript

Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

In an interactive live stream (HLS), viewers can participate in various activities, such as live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

<center>

![VideoSDK-HLS](/img/VideoSDK-HLS.png)

</center>

VideoSDK enables you to configure the interactive livestream layout in various ways, either by setting different prebuilt layouts in the configuration or by providing your own custom template for livestreaming according to your layout choice.

This guide provides an overview of how to implement starting and stopping Http Live Streaming (HLS).

:::important

To initiate automatic Interactive live streaming (HLS) at the beginning of a `session`, simply provide the `autoStartConfig` feature `hls` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.

:::

### `startHls()`

The `startHls()` method, accessible from the `meeting` object, is used to initiate interactive livestream of a meeting. This method accepts the following parameter:

- `config (optional)`: This parameter defines how the interactive livestream layout should look like.

- `transcription (optional)`: This parameter lets you start post transcription for the HLS.

  ```js
  const config = {
    // highlight-next-line
    // Layout Configuration
    layout: {
      type: "GRID", // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
      priority: "SPEAKER", // "PIN", Default : "SPEAKER"
      gridSize: 4, // MAX : 25
    },

    // highlight-next-line
    // Theme of livestream
    theme: "DARK", //  "LIGHT" | "DEFAULT"

    // highlight-next-line
    // `mode` is used to either interactive livestream video & audio both or only audio.
    mode: "video-and-audio", // "audio", Default : "video-and-audio"

    // highlight-next-line
    // Quality of livestream and is only applicable to `video-and-audio` type mode.
    quality: "high", /* Default : "med"
   "low" (SD HLS) | "med" (HD HLS) | "high" (FHD HLS) */

    //highlight-start
    // This mode refers to orientation of recording.
    // landscape : Livestream the meeting in horizontally
    // portrait : Livestream the meeting in vertically (Best for mobile view)
    //highlight-end
    orientation: "landscape", // "portrait",  Default : "landscape"

    // highlight-next-line
    // Recording Configuration
    recording = {
      enabled: true, // Enables recording of HLS
    };
  };

  // highlight-next-line
  // Post Transcription Configuration
  const transcription = {
    enabled: true, // Enables post transcription
    summary: {
      enabled: true, // Enables summary generation
      // Guides summary generation
      prompt:
        "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    },
  };

  startHls(config, transcription);
  ```

### `stopHls()`

- The `stopHls()` method, accessible from the `meeting` object, is used to stop the interactive livestream of a meeting.

#### Example

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const startHlsBtn = document.getElementById("startHlsBtn");
startHlsBtn.addEventListener("click", () => {
  const config = {
    layout: {
      type: "GRID",
      priority: "SPEAKER",
      gridSize: 4,
    },
    theme: "DARK",
    mode: "video-and-audio",
    quality: "high",
    orientation: "landscape",
    recording = {
      enabled: true,
    };
  };

  // Configuration for post transcription
  const transcription = {
    enabled: true,
    summary: {
      enabled: true,
      prompt:
        "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    },
  };

  // Start HLS
  meeting?.startHls(config, transcription);
});

const stopHlsBtn = document.getElementById("stopHlsBtn");
stopHlsBtn.addEventListener("click", () => {
  // Stop HLS
  meeting?.stopHls();
});
```

### Event associated with HLS

- **hls-state-changed** - The `hls-state-changed` event is triggered whenever the state of meeting HLS changes.

- You can get the `playbaclHlsUrl` and `livestreamUrl` of the HLS to play it on the Viewer side when the state changes to `Constants.hlsEvents.HLS_STARTED`

- when you receive `HLS_PLAYABLE` status you will receive 2 urls in response
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const Constants = VideoSDK.Constants;

meeting.on("hls-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.hlsEvents.HLS_STARTING) {
    console.log("Meeting Hls is starting");
  } else if (status === Constants.hlsEvents.HLS_STARTED) {
    // when hls is started you will receive playbaclHlsUrl and livestreamUrl.
    const { playbackHlsUrl } = data;

    console.log("Meeting Hls is started");
  } else if (status === Constants.hlsEvents.HLS_STOPPING) {
    console.log("Meeting Hls is stopping");
  } else if (status === Constants.hlsEvents.HLS_STOPPED) {
    console.log("Meeting Hls is stopped");
  } else {
    //
  }
});
```

:::important

You can access your post transcriptions using our **[<u>Post Transcription API</u>](/api-reference/realtime-communication/fetch-post-transcriptions-summary)**

:::

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [startHls()](/javascript/api/sdk-reference/meeting-class/methods#starthls)
- [stopHls()](/javascript/api/sdk-reference/meeting-class/methods#stophls)
- [hls-state-changed](/javascript/api/sdk-reference/meeting-class/events#hls-state-changed)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

# RTMP Livestream - Javascript

RTMP is a widely used protocol for live streaming video content from VideoSDK to platforms like YouTube, Twitch, Facebook, and others.

To initiate live streaming from VideoSDK to platforms supporting RTMP ingestion, you simply need to provide the platform-specific stream key and stream URL. This enables VideoSDK to connect to the platform's RTMP server and transmit the live video stream.

Furthermore, VideoSDK offers flexibility in configuring livestream layouts. You can achieve this by either selecting different prebuilt layouts in the configuration or by providing your custom template for livestreaming, catering to your specific layout preferences.

This guide will provide an overview of how to implement starting and stopping RTMP livestreaming with VideoSDK.

### `startLivestream()`

The `startLivestream()` method, accessible from the `meeting` object, is used to initiate the RTMP livestream of a meeting. This method accepts the following two parameters:

- `1. outputs`: This parameter takes an array of objects containing the RTMP `url` and `streamKey` specific to the platform where you want to initiate the livestream.

- `2. config (optional)`: This parameter defines the layout configuration for the livestream.

- `3. transcription (optional)`: This parameter lets you start post transcription for the livestream.

:::important

Transcription requires recording to be enabled.

:::

```js
const config = {
  // highlight-next-line
  // Layout Configuration
  layout: {
    type: "GRID", // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
    priority: "SPEAKER", // "PIN", Default : "SPEAKER"
    gridSize: 4, // MAX : 4
  },

  // highlight-next-line
  // Theme of livestream layout
  theme: "DARK", //  "LIGHT" | "DEFAULT"

  // highlight-next-line
  // Recording Configuration
  recording = {
    enabled: true, // Enables recording of the livestream.
  };
};

const outputs = [
  {
    url: "<RTMP_URL>",
    streamKey: "<RTMP_STREAM_KEY>",
  },
];

// highlight-next-line
// Post Transcription Configuration (Transcription requires recording to be enabled.)
const transcription = {
  enabled: true, // Enables post transcription
  summary: {
    enabled: true, // Enables summary generation
    // Guides summary generation
    prompt:
      "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
  },
};

startLivestream(outputs, config, transcription);
```

### `stopLivestream()`

The `stopLivestream()` method, accessible from the `meeting` object, is used to stop the RTMP livestream of a meeting.

#### Example

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const startLivestreamBtn = document.getElementById("startLivestreamBtn");
startLivestreamBtn.addEventListener("click", () => {
  // Start Livestream
  meeting?.startLivestream(
    [
      {
        url: "rtmp://a.rtmp.youtube.com/live2",
        streamKey: "key",
      },
    ],
    {
      layout: {
        type: "GRID",
        priority: "SPEAKER",
        gridSize: 4,
      },
      theme: "DARK",
    },
    {
      enabled: true,
      summary: {
        enabled: true,
        prompt:
          "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
      },
    }
  );
});

const stopLivestreamBtn = document.getElementById("stopLivestreamBtn");
stopLivestreamBtn.addEventListener("click", () => {
  // Stop Livestream
  meeting?.stopLivestream();
});
```

### Event associated with Livestream

- **livestream-state-changed** - Whenever meeting livestream state changes, then `livestream-state-changed` event will trigger.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const Constants = VideoSDK.Constants;

meeting.on("livestream-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.livestreamEvents.LIVESTREAM_STARTING) {
    console.log("Meeting livestream is starting");
  } else if (status === Constants.livestreamEvents.LIVESTREAM_STARTED) {
    console.log("Meeting livestream is started");
  } else if (status === Constants.livestreamEvents.LIVESTREAM_STOPPING) {
    console.log("Meeting livestream is stopping");
  } else if (status === Constants.livestreamEvents.LIVESTREAM_STOPPED) {
    console.log("Meeting livestream is stopped");
  } else {
    //
  }
});
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startLivestream()](/javascript/api/sdk-reference/meeting-class/methods#startlivestream)
- [stopLivestream()](/javascript/api/sdk-reference/meeting-class/methods#stoplivestream)
- [livestream-state-changed](/javascript/api/sdk-reference/meeting-class/events#livestream-state-changed)


---

# Noise Suppresion (BETA) - Javascript

Noise suppression is a feature that identifies and filters out background noise from an audio input during a meeting or call. This feature can be particularly useful in noisy environments or when participants are using low-quality microphones.

:::important

This feature is in Beta release, so feel free to reach out to us on Discord. We'd love to hear your feedback.

:::

### Install VideoSDK Media Processor package

**npm:**

```js
npm install --save "@videosdk.live/videosdk-media-processor-web"
```

---

**yarn:**

```js
yarn add "@videosdk.live/videosdk-media-processor-web"
```

### Instantiate `VideoSDKNoiseSuppressor`

After installing the library, initialize an instance of the `VideoSDKNoiseSuppressor`. 

```js
// Import package

let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

// Instantiate VideoSDKNoiseSuppressor Class
const noiseProcessor = new VideoSDKNoiseSuppressor();
```

### Getting Processed Stream

You can obtain the processed stream using the `getNoiseSuppressedAudioStream` method, which takes a `MediaStream` as input and returns the noise-suppressed stream.

```js
// Import package

let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

// Instantiate VideoSDKNoiseSuppressor Class
const noiseProcessor = new VideoSDKNoiseSuppressor();

const startNoiseSuppressionBtn = document.getElementById(
  "startNoiseSuppressionBtn"
);
startNoiseSuppressionBtn.addEventListener("click", async () => {
  //highlight-start
  // Getting stream from mic
  const stream = await VideoSDK.createMicrophoneAudioTrack({});
  const processedStream = await noiseProcessor.getNoiseSuppressedAudioStream(
    stream
  );
  //highlight-end
});
```

### Passing Processed Stream to VideoSDK

Once you have the processed stream, you can pass it to functions like `enableMic()`, `changMic()` or `toggleMic()` to apply the noise suppresion effect during your meeting.

```js
// Import package

let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

// Instantiate VideoSDKNoiseSuppressor Class
const noiseProcessor = new VideoSDKNoiseSuppressor();

const startNoiseSuppressionBtn = document.getElementById(
  "startNoiseSuppressionBtn"
);
startNoiseSuppressionBtn.addEventListener("click", async () => {
  // Getting stream from mic
  const stream = await createMicrophoneAudioTrack({});
  const processedStream = await noiseProcessor.getNoiseSuppressedAudioStream(
    stream
  );

  //highlight-start
  meeting?.changeMic(processedStream);
  //highlight-end
});
```

### Stopping Noise Suppression

You can stop the noise suppression by replacing the audio stream with a new plain audio stream.

```js
// Import package

let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

// Instantiate VideoSDKNoiseSuppressor Class
const noiseProcessor = new VideoSDKNoiseSuppressor();

const stopNoiseSuppressionBtn = document.getElementById(
  "stopNoiseSuppressionBtn"
);
stopNoiseSuppressionBtn.addEventListener("click", async () => {
  //highlight-start
  // Pass mic MediaStream in VideoSDK `changeMic` method
  const stream = await VideoSDK.createMicrophoneAudioTrack({});
  meeting?.changeMic(stream);
  //highlight-end
});
```

### Extras

You can also pass this processed stream during initialization of the meeting.

```js
// Import package

// Instantiate VideoSDKNoiseSuppressor Class
const noiseProcessor = new VideoSDKNoiseSuppressor();

// Getting stream from mic
const stream = await VideoSDK.createMicrophoneAudioTrack({});
const processedStream = await noiseProcessor.getNoiseSuppressedAudioStream(
  stream
);

let meeting;
meeting = VideoSDK.initMeeting({
  meetingId: "meetingId",
  micEnabled: true,
  webcamEnabled: true,
  name: "TestUser",
  customMicrophoneAudioTrack: processedStream, // Pass processed MediaStream in VideoSDK
});
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [unmuteMic()](/javascript/api/sdk-reference/meeting-class/methods#unmutemic)
- [muteMic()](/javascript/api/sdk-reference/meeting-class/methods#mutemic)


---

# Virtual Background- Javascript

Virtual backgrounds enhance the video call or meeting experience by enabling participants to replace their physical background with a digital image or video. This feature offers several benefits, including maintaining privacy, reducing visual distractions, and adding an element of creativity or fun to the meeting. Users can choose from preloaded images or upload their own backgrounds.

:::important

- Currently, this feature is only available on Google Chrome, Firefox and Brave browser.
- This feature is in Beta release, so feel free to reach out to us on Discord. We'd love to hear your feedback.

:::

![virtual-background](/img/virtual-background.png)

### Install VideoSDK Media Processor package

**npm:**

```js
npm install --save "@videosdk.live/videosdk-media-processor-web"
```

---

**yarn:**

```js
yarn add "@videosdk.live/videosdk-media-processor-web"
```

### Instantiate Virtual Background Processor

After installing the library, initialize an instance of the `VirtualBackgroundProcessor`. 

```js
// Import package

let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

// Instantiate VirtualBackgroundProcessor Class
const videoProcessor = new VirtualBackgroundProcessor();
```

### Using Virtual Background

Utilize the processor by first initializing it, then start processing a stream, and finally, pass the processed video stream to VideoSDK.

#### Initializing

The first step is to initialize the virtual background processor if it's not already prepared.

```js
// Import package

let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

// Instantiate VirtualBackgroundProcessor Class
const videoProcessor = new VirtualBackgroundProcessor();

const StartVirtualBackgroundBtn = document.getElementById(
  "StartVirtualBackgroundBtn"
);
StartVirtualBackgroundBtn.addEventListener("click", async () => {
  //highlight-start
  // Initialize processor if not ready
  if (!videoProcessor.ready) {
    await videoProcessor.init();
  }
  //highlight-end
});
```

### Starting the Processor

To initiate the processing of a video stream, you need to provide a `MediaStream` that you want to process and a `config` to be used for processing. Once these parameters are passed to the processor, it will return a `MediaStream`.

1. **MediaStream** : [MediaStream](https://developer.mozilla.org/en-US/docs/Web/API/MediaStream) is essentially a video stream captured from the camera. You can use the `createCameraVideoTrack` method to generate a `MediaStream`.
2. **config** : This object accepts `type` and `imageUrl` property. `type` property accepts filter type `image` or `blur`. `imageUrl` is the path of the image and it will be ignored on `blur` filter type.

   **NOTE** : If you intend to display a specific background image, make sure it is uploaded on a CDN.

```js
// Import package

let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

// Instantiate VirtualBackgroundProcessor Class
const videoProcessor = new VirtualBackgroundProcessor();

const StartVirtualBackgroundBtn = document.getElementById(
  "StartVirtualBackgroundBtn"
);
StartVirtualBackgroundBtn.addEventListener("click", async () => {
  // Initialize processor if not ready
  if (!videoProcessor.ready) {
    await videoProcessor.init();
  }

  //highlight-start
  // Configuration for starting processor
  const config = {
    type: "image", // "blur"
    imageUrl: "https://cdn.videosdk.live/virtual-background/cloud.jpeg",
    // Here is a list of background images you can use for your project.
    // imageUrl: "https://cdn.videosdk.live/virtual-background/beach.jpeg",
    // imageUrl: "https://cdn.videosdk.live/virtual-background/san-fran.jpeg",
    // imageUrl: "https://cdn.videosdk.live/virtual-background/paper-wall.jpeg",
  };

  // Getting stream from webcam
  const stream = await VideoSDK.createCameraVideoTrack({});
  const processedStream = await videoProcessor.start(stream, config);
  //highlight-end
});
```

### Passing Processed Stream to VideoSDK

Once you have the processed stream, you can pass it to functions like `enableWebcam()`, `changeWebcam()` or `toggleWebcam()` to apply the virtual background effect during your meeting.

```js
// Import package

let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

// Instantiate VirtualBackgroundProcessor Class
const videoProcessor = new VirtualBackgroundProcessor();

const StartVirtualBackgroundBtn = document.getElementById(
  "StartVirtualBackgroundBtn"
);
StartVirtualBackgroundBtn.addEventListener("click", async () => {
  // Initialize processor if not ready
  if (!videoProcessor.ready) {
    await videoProcessor.init();
  }

  // Configuration for starting processor
  const config = {
    type: "image", // "blur"
    imageUrl: "https://cdn.videosdk.live/virtual-background/cloud.jpeg",
    // Here is a list of background images you can use for your project.
    // imageUrl: "https://cdn.videosdk.live/virtual-background/beach.jpeg",
    // imageUrl: "https://cdn.videosdk.live/virtual-background/san-fran.jpeg",
    // imageUrl: "https://cdn.videosdk.live/virtual-background/paper-wall.jpeg",
  };

  // Getting stream from webcam
  const stream = await VideoSDK.createCameraVideoTrack({});
  const processedStream = await videoProcessor.start(stream, config);

  //highlight-start
  meeting?.changeWebcam(processedStream);
  //highlight-end
});
```

### Updating Video Processor Configuration

If you want to change the background while the Video Processor is running, you can call the `updateProcessorConfig` method to modify the filters or processing type. 

```js
// Import package

let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

// Instantiate VirtualBackgroundProcessor Class
const videoProcessor = new VirtualBackgroundProcessor();

const updateVirtualBackgroundBtn = document.getElementById(
  "updateVirtualBackgroundBtn"
);
updateVirtualBackgroundBtn.addEventListener("click", async () => {
  //highlight-start
  const config = {
    type: "image", // "blur"
    imageUrl: "https://cdn.videosdk.live/virtual-background/cloud.jpeg",
  };

  videoProcessor.updateProcessorConfig(config);
  //highlight-end
});
```

### Stopping Virtual Background Processor

Additionally, you can use the `stop()` method on the processor to halt the background processing and replace the video stream with a new plain video stream.

```js
// Import package

let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

// Instantiate VirtualBackgroundProcessor Class
const videoProcessor = new VirtualBackgroundProcessor();

const stopVirtualBackgroundBtn = document.getElementById(
  "stopVirtualBackgroundBtn"
);
stopVirtualBackgroundBtn.addEventListener("click", async () => {
  //highlight-start
  videoProcessor.stop();

  // Pass webcam MediaStream in VideoSDK `changeWebcam` method
  const stream = await VideoSDK.createCameraVideoTrack({});
  meeting?.changeWebcam(stream);
  //highlight-end
});
```

### Extras

You can also pass the processed stream during initialization of the meeting.

```js
// Import package

const videoProcessor = new VirtualBackgroundProcessor();

const stream = await VideoSDK.createCameraVideoTrack({});
if (!videoProcessor.ready) {
  await videoProcessor.init();
}
const processedStream = await videoProcessor.start(stream, {
  type: "image", // "blur"
  imageUrl: `https://cdn.videosdk.live/virtual-background/cloud.jpeg`,
});

let meeting;
meeting = VideoSDK.initMeeting({
  meetingId: "meetingId",
  micEnabled: true,
  webcamEnabled: true,
  name: "TestUser",
  customCameraVideoTrack: processedStream, // Pass processed MediaStream in VideoSDK
});
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [enableWebcam()](/javascript/api/sdk-reference/meeting-class/methods#enablewebcam)
- [disableWebcam()](/javascript/api/sdk-reference/meeting-class/methods#disablewebcam)


---

# Quick Start for Http Live Streaming(HLS) in Javascript




---

# Quick Start for Interactive Live Streaming (ILS) in Javascript




---

# Quick Start for Conference in Javascript

VideoSDK empowers you to seamlessly integrate the video calling feature into your Javascript application within minutes.

In this quickstart, you'll explore the group calling feature of VideoSDK. Follow the step-by-step guide to integrate it within your application.

## Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

- Video SDK Developer Account (Not having one, follow **[Video SDK Dashboard](https://app.videosdk.live/)**)
- Have Node and NPM installed on your device.

:::important

One should have a VideoSDK account to generate token.
Visit VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate token

:::

## Getting Started with the Code!

Follow the steps to create the environment necessary to add video calls into your app. You can also find the code sample for [quickstart here](https://github.com/videosdk-live/quickstart/tree/main/js-rtc).

First create one empty project using `mkdir folder_name` on your preferable location.

### Install Video SDK

Import VideoSDK using the `<script>` tag or Install it using the following npm command. Make sure you are in your app directory before you run this command.



**Tab:**

" label="<script>" default>

```html
<html>
  <head>

  </head>
  <body>

<script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
  </body>
</html>
```

---

**npm:**

```bash
npm install @videosdk.live/js-sdk
```

---

**yarn:**

```bash
yarn add @videosdk.live/js-sdk
```

## Structure of the project

Your project structure should look like this.

```jsx title="Project Structure"
  root
   ├── index.html
   ├── config.js
   ├── index.js
```

You will be working on the following files:

- index.html: Responsible for creating a basic UI.
- config.js: Responsible for storing the token.
- index.js: Responsible for rendering the meeting view and the join meeting functionality.

### Step 1: Design the user interface (UI)

Create an HTML file containing the screens, `join-screen` and `grid-screen`.

```html title="index.html"
<!DOCTYPE html>
<html>
  <head> </head>

  <body>
    <div id="join-screen">
      
      <button id="createMeetingBtn">New Meeting</button>
      OR
      
      <input type="text" id="meetingIdTxt" placeholder="Enter Meeting id" />
      <button id="joinBtn">Join Meeting</button>
    </div>

    
    <div id="textDiv"></div>

    <div id="grid-screen" style="display: none">
      
      <h3 id="meetingIdHeading"></h3>

      
      <button id="leaveBtn">Leave</button>
      <button id="toggleMicBtn">Toggle Mic</button>
      <button id="toggleWebCamBtn">Toggle WebCam</button>

      
      <div class="row" id="videoContainer"></div>
    </div>

    
    //highlight-next-line
    <script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
    <script src="config.js"></script>
    <script src="index.js"></script>
  </body>
</html>
```

#### Output

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/js_join_screen.png' />

</center>


### Step 2: Implement Join Screen

Configure the token in the `config.js` file, which you can obtain from the [VideoSDK Dashbord](https://app.videosdk.live/login).

```js title="config.js"
// Auth token will be used to generate a meeting and connect to it
TOKEN = "Your_Token_Here";
```

Next, retrieve all the elements from the DOM and declare the following variables in the `index.js` file. Then, add an event listener to the join and create meeting buttons.

```js title="index.js"
// Getting Elements from DOM
const joinButton = document.getElementById("joinBtn");
const leaveButton = document.getElementById("leaveBtn");
const toggleMicButton = document.getElementById("toggleMicBtn");
const toggleWebCamButton = document.getElementById("toggleWebCamBtn");
const createButton = document.getElementById("createMeetingBtn");
const videoContainer = document.getElementById("videoContainer");
const textDiv = document.getElementById("textDiv");

// Declare Variables
let meeting = null;
let meetingId = "";
let isMicOn = false;
let isWebCamOn = false;

function initializeMeeting() {}

function createLocalParticipant() {}

function createVideoElement() {}

function createAudioElement() {}

function setTrack() {}

// Join Meeting Button Event Listener
joinButton.addEventListener("click", async () => {
  document.getElementById("join-screen").style.display = "none";
  textDiv.textContent = "Joining the meeting...";

  roomId = document.getElementById("meetingIdTxt").value;
  meetingId = roomId;

  initializeMeeting();
});

// Create Meeting Button Event Listener
createButton.addEventListener("click", async () => {
  document.getElementById("join-screen").style.display = "none";
  textDiv.textContent = "Please wait, we are joining the meeting";

  //highlight-start
  // API call to create meeting
  const url = `https://api.videosdk.live/v2/rooms`;
  const options = {
    method: "POST",
    headers: { Authorization: TOKEN, "Content-Type": "application/json" },
  };

  const { roomId } = await fetch(url, options)
    .then((response) => response.json())
    .catch((error) => alert("error", error));
  meetingId = roomId;
  //highlight-end

  initializeMeeting();
});
```


### Step 3: Initialize meeting

Following that, initialize the meeting using the `initMeeting()` function and proceed to join the meeting.

```js title="index.js"
// Initialize meeting
function initializeMeeting() {
  window.VideoSDK.config(TOKEN);

  meeting = window.VideoSDK.initMeeting({
    meetingId: meetingId, // required
    name: "Thomas Edison", // required
    micEnabled: true, // optional, default: true
    webcamEnabled: true, // optional, default: true
  });

  meeting.join();

  // Creating local participant
  createLocalParticipant();

  // Setting local participant stream
  meeting.localParticipant.on("stream-enabled", (stream) => {
    setTrack(stream, null, meeting.localParticipant, true);
  });

  // meeting joined event
  meeting.on("meeting-joined", () => {
    textDiv.style.display = "none";
    document.getElementById("grid-screen").style.display = "block";
    document.getElementById(
      "meetingIdHeading"
    ).textContent = `Meeting Id: ${meetingId}`;
  });

  // meeting left event
  meeting.on("meeting-left", () => {
    videoContainer.innerHTML = "";
  });

  // Remote participants Event
  // participant joined
  meeting.on("participant-joined", (participant) => {
    //  ...
  });

  // participant left
  meeting.on("participant-left", (participant) => {
    //  ...
  });
}
```

#### Output

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/js_init_meeting.png' />

</center>


### Step 4: Create the Media Elements

In this step, Create a function to generate audio and video elements for displaying both local and remote participants. Set the corresponding media track based on whether it's a video or audio stream.

```js title=index.js
// creating video element
function createVideoElement(pId, name) {
  let videoFrame = document.createElement("div");
  videoFrame.setAttribute("id", `f-${pId}`);

  //create video
  let videoElement = document.createElement("video");
  videoElement.classList.add("video-frame");
  videoElement.setAttribute("id", `v-${pId}`);
  videoElement.setAttribute("playsinline", true);
  videoElement.setAttribute("width", "300");
  videoFrame.appendChild(videoElement);

  let displayName = document.createElement("div");
  displayName.innerHTML = `Name : ${name}`;

  videoFrame.appendChild(displayName);
  return videoFrame;
}

// creating audio element
function createAudioElement(pId) {
  let audioElement = document.createElement("audio");
  audioElement.setAttribute("autoPlay", "false");
  audioElement.setAttribute("playsInline", "true");
  audioElement.setAttribute("controls", "false");
  audioElement.setAttribute("id", `a-${pId}`);
  audioElement.style.display = "none";
  return audioElement;
}

// creating local participant
function createLocalParticipant() {
  let localParticipant = createVideoElement(
    meeting.localParticipant.id,
    meeting.localParticipant.displayName
  );
  videoContainer.appendChild(localParticipant);
}

// setting media track
function setTrack(stream, audioElement, participant, isLocal) {
  if (stream.kind == "video") {
    isWebCamOn = true;
    const mediaStream = new MediaStream();
    mediaStream.addTrack(stream.track);
    let videoElm = document.getElementById(`v-${participant.id}`);
    videoElm.srcObject = mediaStream;
    videoElm
      .play()
      .catch((error) =>
        console.error("videoElem.current.play() failed", error)
      );
  }
  if (stream.kind == "audio") {
    if (isLocal) {
      isMicOn = true;
    } else {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(stream.track);
      audioElement.srcObject = mediaStream;
      audioElement
        .play()
        .catch((error) => console.error("audioElem.play() failed", error));
    }
  }
}
```


### Step 5: Handle participant events

Thereafter, implement the events related to the participants and the stream.

Following are the events to be executed in this step:

1. `participant-joined`: When a remote participant joins, this event will trigger. In the event callback, create video and audio elements previously defined for rendering their video and audio streams.

2. `participant-left`: When a remote participant leaves, this event will trigger. In the event callback, remove the corresponding video and audio elements.

3. `stream-enabled`: This event manages the media track of a specific participant by associating it with the appropriate video or audio element.

```js title="index.js"
// Initialize meeting
function initializeMeeting() {
  // ...

  // participant joined
  meeting.on("participant-joined", (participant) => {
    let videoElement = createVideoElement(
      participant.id,
      participant.displayName
    );
    let audioElement = createAudioElement(participant.id);
    // stream-enabled
    participant.on("stream-enabled", (stream) => {
      setTrack(stream, audioElement, participant, false);
    });
    videoContainer.appendChild(videoElement);
    videoContainer.appendChild(audioElement);
  });

  // participants left
  meeting.on("participant-left", (participant) => {
    let vElement = document.getElementById(`f-${participant.id}`);
    vElement.remove(vElement);

    let aElement = document.getElementById(`a-${participant.id}`);
    aElement.remove(aElement);
  });
}
```

#### Output

<center>

<img src='https://cdn.videosdk.live/website-resources/docs-resources/js_grid_screen.png' />

</center>


### Step 6: Implement Controls

Next, implement the meeting controls such as toggleMic, toggleWebcam and leave meeting.

```js title="index.js"
// leave Meeting Button Event Listener
leaveButton.addEventListener("click", async () => {
  meeting?.leave();
  document.getElementById("grid-screen").style.display = "none";
  document.getElementById("join-screen").style.display = "block";
});

// Toggle Mic Button Event Listener
toggleMicButton.addEventListener("click", async () => {
  if (isMicOn) {
    // Disable Mic in Meeting
    meeting?.muteMic();
  } else {
    // Enable Mic in Meeting
    meeting?.unmuteMic();
  }
  isMicOn = !isMicOn;
});

// Toggle Web Cam Button Event Listener
toggleWebCamButton.addEventListener("click", async () => {
  if (isWebCamOn) {
    // Disable Webcam in Meeting
    meeting?.disableWebcam();

    let vElement = document.getElementById(`f-${meeting.localParticipant.id}`);
    vElement.style.display = "none";
  } else {
    // Enable Webcam in Meeting
    meeting?.enableWebcam();

    let vElement = document.getElementById(`f-${meeting.localParticipant.id}`);
    vElement.style.display = "inline";
  }
  isWebCamOn = !isWebCamOn;
});
```


## Run your code

Once you have completed all the steps mentioned above, run your application using the code block below.

```bash
live-server --port=8000
```

## Final Output

You have completed the implementation of a customized video calling app in Javascript using VideoSDK. To explore more features, go through Basic and Advanced features.




<br/>

:::tip
You can checkout the complete [quick start example here](https://github.com/videosdk-live/quickstart/tree/main/js-rtc).
:::


---

## Understanding Usage Quota Limits - Javascript

In this documentation, you will find detailed information about the quotas associated with each plan, including usage limits for various features and functionalities. Understanding these quotas will help you optimize your usage, selecting the best pricing plan and make the most of your VideoSDK experience.

## How VideoSDK limits concurrent usage quota

VideoSDK's approach to limiting usage focuses on concurrent usage rather than overall usage. Concurrent usage refers to the number of participants or requests that can be hosted or processed simultaneously. 

For example, if there's a limit of 50 concurrent participants per organization, users can run multiple calls (sessions) simultaneously, with a maximum of 50 participants across all sessions combined.

## How to view my current plan’s quota limits?

To view the current quota limits on your organization, simply navigate to the [VideoSDK Dashboard](https://app.videosdk.live/), go to your Profile section, and click on the Billing tab.

## Free Plan

Since, we’ve designed Free Plan for developers who are just exploring, we’ve kept the limits that would get you started without a hitch.

Organisations on Free Plan have the following limits on concurrent usage:

| Feature | Concurrent Limit |
| --- | --- |
| Participants in Video Calls | 50 concurrent participants |
| Viewers in Live Streams | 100 concurrent viewers |
| Recording Request | 1 concurrent request at a time |
| HLS Encoding Request | 1 concurrent request at a time |
| RTMP-Out Request | 1 concurrent request at a time |

 
### How to increase my limits?

To increase your limits, simply upgrade your plan by providing billing details and credit card information.

## Pay-as-you-Go Plan

We've increased participant limits for this paid plan. This way, it won't significantly impact users heavily involved in production or integration.

Organisations on Pay-as-you-Go have the following limits on concurrent usage:

| Feature | Concurrent Limit |
| --- | --- |
| Participants in Video Calls | 100 concurrent participants |
| Viewers in Live Streams | 500 concurrent viewers |
| Recording Request | 5 concurrent request at a time |
| HLS Encoding Request | 5 concurrent request at a time |
| RTMP-Out Request | 5 concurrent request at a time |

### How to increase my limits?

To increase your limits further more, simply get in touch with us. [Contact us](https://www.videosdk.live/contact) directly or reach out via email at [support@videosdk.live](mailto:support@videosdk.live), and we'll handle the rest gladly.

## Enterprise Plan

For Enterprise users, all limits are tailored to the specific needs. Customised limits ensure optimal performance for your unique requirements.

To get started as an Enterprise user, simply get in touch with us, explain your requirements and use case, and we’ll customise the quota and limits according to your needs.

## Examples to understand concurrent limits

**Example #1**

Let's say you're using video callings (RTC) in your organization on the Free Plan. In this scenario, you can concurrently host up to 50 participants. However, the number of calls (sessions) you initiate is unrestricted.

To simplify, you can run multiple sessions simultaneously, but concurrently, you can only accommodate a maximum of 50 participants across all sessions. If a 51st participant attempts to join, they won't be able to access the session until you upgrade your plan to increase your participant limits.

**Example #2**

Let’s say you're using live streaming in your organization on the Free Plan. In this setup, you can concurrently host up to 100 viewers joining the sessions. While you have the flexibility to host multiple live streaming sessions, the number of viewers joining session concurrently is restricted.

**Example #3**

Lets say you’re using video callings (RTC) in your organization on the Pay-as-you-Go Plan and you're hosting 5 concurrent calls (sessions), all of which are being recorded. Now, when you initiate the 6th call (session) and request recording, VideoSDK will not process your recording request. Instead, it will throw an error because you've reached your recording request limit.

If you have any questions regarding quota limits and pricing plan, post in our [Discord community](https://discord.com/invite/Qfm8j4YAUJ), [contact us](https://www.videosdk.live/contact) directly, or reach out to us on [support@videosdk.live](mailto:support@videosdk.live).

---

Recording meetings is an essential feature that ensures all important discussions, decisions, and interactions are documented for future reference. VideoSDK offers three types of recordings: Meeting Recording, Participant Recording, and Participant Track Recording. Each type serves a specific purpose to cater to different recording needs during a meeting.

## Meeting Recording

Meeting Recording captures the entire meeting, including all participants, audio, video, and shared content. This comprehensive recording is ideal for reviewing the entire meeting, ensuring that nothing is missed. It provides a holistic view of the meeting, capturing every interaction and piece of information shared during the session.

![Meeting Recording](https://cdn.videosdk.live/website-resources/docs-resources/MeetingRecording.png)

## Participant Recording

Participant Recording focuses on individual participants, capturing both their audio and video into a single file. This type of recording is particularly useful for tracking the contributions of specific participants or for scenarios where detailed analysis of an individual’s participation is needed. When a participant mutes their audio or turns off their video, the recording continues but with silenced audio or a black screen, respectively. This ensures a continuous recording without interruptions, reflecting the participant's involvement throughout the meeting.

![Participant Recording](https://cdn.videosdk.live/website-resources/docs-resources/ParticipantRecording.png)

## Participant Track Recording

Participant Track Recording allows you to record specific tracks of a participant, either audio or video, based on user input. This targeted approach is perfect for capturing particular aspects of a participant’s contribution, such as only their audio or only their video. Multiple files are generated whenever there is a change in the track's status (e.g., starting after being muted ), ensuring focused documentation of each continuous segment. This method is especially useful in scenarios where detailed analysis of specific media (audio or video) is required.

![Participant Track Recording](https://cdn.videosdk.live/website-resources/docs-resources/TrackRecording.png)



---

https://sdk.videosdk.live/js-sdk/0.2.6/videosdk.jsVideoSDK offers a range of video streaming tools and solutions for content creators, publishers, and developers.

- A custom template is a specialized layout for a live stream that allows users to integrate real-time graphics into their broadcasts.

- With custom templates, users can enhance their video content by overlaying graphics, text, images, and animations onto their live streams. These elements can be customized to align with specific branding requirements.

- By leveraging custom templates, users can craft dynamic and engaging video experiences. Whether incorporating live scoreboards, social media feeds, or other personalized elements, users have the flexibility to create visually appealing streams that stand out and capture audience attention.

:::note

Custom templates can also be used with recordings and RTMP service provided by VideoSDK.

:::

### What you can do with Custom Template

By utilizing a custom template, you have the flexibility to create various modes for your live stream. Here are some popular modes that you can design:

- **`PK Host:`** The host can organize a player vs. player battle, as illustrated in the example of a gaming battle shown below.

![pk host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_pk_battle.png)

- **`Watermark:`** The host has the ability to add and update watermarks anywhere in the template; for instance, the image below features a VideoSDK watermark on the top right side of the screen.

![watermark host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_water_mark.png)

- **`News Mode:`** Additionally, the host can incorporate dynamic text in the lower third banner, as demonstrated by the sample text in the bottom left of the screen.

![news mode](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_news_live.png)

### Custom template with VideoSDK

In this section, we will discuss how Custom Templates work with VideoSDK.

- **`Host`**: The host initiates live streaming by providing the `templateURL`. The `templateURL` is the URL of the hosted template webpage. The host is also responsible for managing the template, including tasks such as altering text, logos, and switching template layouts.

- **`VideoSDK Template Engine`** : The VideoSDK Template Engine accepts and opens the templateURL in the browser, actively listening to all events initiated by the Host. It facilitates the customization of the template in accordance with the host's preferences.

- **`Viewer`**: Viewers can stream the content, experiencing the live stream with added real-time graphics. This feature contributes to a distinctive and engaging viewing experience.

![custom template](https://cdn.videosdk.live/website-resources/docs-resources/custom_template.png)

### Understanding Template URL

The template URL is a webpage that VideoSDK Template Engine will open while composing the live stream.

It will appear as shown below.

![template url](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_url.png)

The Template URL comprises of two essential parts:

- Your actual page URL, resembling something like `https://example.com/videosdk-template`.
- Query parameters, designed to enable the VideoSDK Template Engine to seamlessly join the meeting upon opening the URL. There are three key query parameters in total:
  - `token`: Your token, serving as the authentication key to join the meeting.
  - `meetingId`: The meeting Id of the meeting that the VideoSDK Template Engine will join.
  - `participantId`: The participant ID of the VideoSDK Template Engine. This should be included when joining the template engine in your template, ensuring that the template engine participant remains invisible to other participants. **This parameter is automatically added by the VideoSDK**.

:::info

Above mentioned query parameters are mandatory. Apart from these parameters, you can pass any other extra parameters which are required according to your use-case.

:::

### **Creating Template**

**`Step 1:`** Import VideoSDK using `<script>` tag or install it using the below-mentioned npm command.
Make sure you are in your app directory before you run this command.



**Tab:**

" label="<script>" default>

```html
<html>
  <head></head>
  <body>
// highlight-next-line
<script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
  </body>
</html>
```

---

**npm:**

```bash
npm install @videosdk.live/js-sdk
```

---

**yarn:**

```bash
yarn add @videosdk.live/js-sdk
```

:::note

You can use VideoSDK's React or JavaScript SDK to create custom template. Following is the example of building custom template with JavaScript SDK.

:::

###### Structure of the Project

```jsx title="Project Structure"
  root
   ├── index.html
   ├── index.js
```

**`Step 2:`** Craft a user interface (UI) tailored for your live stream presentation.

```html title="index.html"
<!DOCTYPE html>
<html>
  <head> </head>

  <body>
    <div id="textDiv">Starting live stream...</div>

    
    <div class="row" id="videoContainer"></div>

    <script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
    <script src="index.js"></script>
  </body>
</html>
```

**`Step 3:`** Next, fetch the query parameters, from the URL which will be later used to initialize the meeting and get the elements from DOM.

```js title=index.js
const url = window.location;
const urlParams = new URLSearchParams(url.search);

const meetingId = urlParams.get("meetingId");
const token = urlParams.get("token");
const participantId = urlParams.get("participantId");

const videoContainer = document.getElementById("videoContainer");
const textDiv = document.getElementById("textDiv");
```

**`Step 4:`** Subsequently, initialize the meeting with the parameters that were extracted from the URL. Ensure direct initialization so that the template engine seamlessly joins the meeting upon page load.

```js title=index.js
window.VideoSDK.config(token);

const meeting = window.VideoSDK.initMeeting({
  meetingId: meetingId, // required
  name: "recorder", // required
  micEnabled: false,
  webcamEnabled: false,
  participantId: participantId,
});

meeting.join();

meeting.on("meeting-joined", () => {
  textDiv.style.display = "none";
});
```

**`Step 5:`** Next step is to create the container that will render the meeting view on the `participant-joined` event.

```js title=index.js
//  participant joined
meeting.on("participant-joined", (participant) => {
  let videoElement = createVideoElement(
    participant.id,
    participant.displayName
  );
  let audioElement = createAudioElement(participant.id);

  participant.on("stream-enabled", (stream) => {
    setTrack(stream, audioElement, participant, false);
  });
  videoContainer.appendChild(videoElement);
  videoContainer.appendChild(audioElement);
});

// participants left
meeting.on("participant-left", (participant) => {
  let vElement = document.getElementById(`f-${participant.id}`);
  vElement.remove(vElement);

  let aElement = document.getElementById(`a-${participant.id}`);
  aElement.remove(aElement);
});

// creating video element
function createVideoElement(pId, name) {
  let videoFrame = document.createElement("div");
  videoFrame.setAttribute("id", `f-${pId}`);

  //create video
  let videoElement = document.createElement("video");
  videoElement.classList.add("video-frame");
  videoElement.setAttribute("id", `v-${pId}`);
  videoElement.setAttribute("playsinline", true);
  videoElement.setAttribute("width", "300");
  videoElement.muted = true;
  videoFrame.appendChild(videoElement);

  let displayName = document.createElement("div");
  displayName.innerHTML = `Name : ${name}`;
  videoFrame.appendChild(displayName);

  return videoFrame;
}

// creating audio element
function createAudioElement(pId) {
  let audioElement = document.createElement("audio");
  audioElement.setAttribute("autoPlay", "false");
  audioElement.setAttribute("playsInline", "true");
  audioElement.setAttribute("controls", "false");
  audioElement.setAttribute("id", `a-${pId}`);
  audioElement.style.display = "none";
  return audioElement;
}

// setting media track
function setTrack(stream, audioElement, participant, isLocal) {
  if (stream.kind == "video") {
    isWebCamOn = true;
    const mediaStream = new MediaStream();
    mediaStream.addTrack(stream.track);
    let videoElm = document.getElementById(`v-${participant.id}`);
    videoElm.srcObject = mediaStream;
    videoElm
      .play()
      .catch((error) =>
        console.error("videoElem.current.play() failed", error)
      );
  }
  if (stream.kind == "audio") {
    if (isLocal) {
      isMicOn = true;
    } else {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(stream.track);
      audioElement.srcObject = mediaStream;
      audioElement
        .play()
        .catch((error) => console.error("audioElem.play() failed", error));
    }
  }
}
```

**`Step 6:`** Now, listen to PubSub messages from the `CHANGE_BACKGROUND` topic, triggering a change in the meeting's background color accordingly.

:::note

The PubSub mechanism is utilized to communicate with the template. You can learn more about [PubSub from here](/javascript/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

:::

```js title=index.js
meeting.on("meeting-joined", () => {
  //  ...

  meeting.pubSub.subscribe("CHANGE_BACKGROUND", (data) => {
    let { message } = data;
    document.body.style.backgroundColor = message;
  });
});
```

**`Step 7:`** Once tested, you can deploy it using your backend or host it on services like [firebase](https://www.geeksforgeeks.org/how-to-deploy-react-project-on-firebase/) or vercel.

:::tip

You can checkout the github repository for sample custom template [created here](https://github.com/videosdk-live/videosdk-custom-recording-template-js-example).

:::

### Setup Livestream Using Custom Template

- To utilize Custom Templates with Livestream, you need to establish both the Host and Viewer setups. The Host initiates the livestream, while Viewers can watch the broadcast.

![template manager](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_manager.png)

- To understand custom templates, clone this example and run it on your system.

```bash
git clone https://github.com/videosdk-live/videosdk-custom-recording-template-js-example.git
```

- You can utilize this custom template in [Start Recording API](/api-reference/realtime-communication/start-recording), [Start HLS API](/api-reference/realtime-communication/start-hlsStream) and [Start Livestream API](/api-reference/realtime-communication/start-livestream). Here is the example of HLS.
- To utilize the custom template that has been deployed, invoke the [Start HLS API](https://docs.videosdk.live/api-reference/realtime-communication/start-hlsStream) instead of the `startHls` method from the `Meeting` class. The necessary code has already been incorporated in the cloned example above.

:::important

You can create your own custom template manager in JavaScript. In this example, we are using one for better understanding.

:::

```js
<button
  onClick={async () => {
    const url = `https://api.videosdk.live/v2/hls/start`;
    //Update your Custom Template URL here if you have deployed your own, if not deployed you can use this template from our URL.
    //highlight-next-line
    const templateUrl = `https://lab.videosdk.live/js-template-demo/?meetingId=${meetingId}&token=${authToken}`;
    const options = {
      method: "POST",
      headers: {
        Authorization: authToken,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        roomId: meetingId,
        templateUrl: templateUrl,
      }),
    };

    const result = await fetch(url, options)
      .then((response) => response.json()) // result will have playbackHlsUrl and livestreamUrl
      .catch((error) => console.error("error", error));
  }}
>
  Start HLS
</button>
```

- In this example, the host has two options on their side, enabling them to change the background and send messages to the viewers.

- Given below is a test run of the example.


<div style={{textAlign: 'center'}}>



</div>

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)
- [Start HLS API](/api-reference/realtime-communication/start-hlsStream)
- [Start Livestream API](/api-reference/realtime-communication/start-livestream)
- [recordingState](/react/api/sdk-reference/use-meeting/properties#recordingstate)
- [hlsState](/react/api/sdk-reference/use-meeting/properties#hlsstate)
- [livestreamState](/react/api/sdk-reference/use-meeting/properties#livestreamstate)
- [hlsUrls](/react/api/sdk-reference/use-meeting/properties#hlsurls)
- [onRecordingStateChanged](/react/api/sdk-reference/use-meeting/events#onrecordingstatechanged)
- [onHlsStateChanged](/react/api/sdk-reference/use-meeting/events#onhlsstatechanged)
- [onLivestreamStateChanged](/react/api/sdk-reference/use-meeting/events#onlivestreamstatechanged)



---

# Geo Tag Meeting Recordings - JavaScript

To ensure compliance for BFSIs doing vKYC, it very important to include the co-ordinates(location) of the customer in the recordings. VideoSDK provides a very customizable solution to implement this feature. You will be using custom templates for this purpose.

We have created a ready to use template for this use case which can be found [here](https://github.com/videosdk-live/videosdk-rtc-react-prebuilt-ui/tree/template/geo-tag-watermark). To integrate this template with your recordings follow the below mentiond instructions.

### Host the template

1. Clone the template repository and switch to the branch `template/geo-tag-watermark`.

```bash
git clone https://github.com/videosdk-live/videosdk-rtc-react-prebuilt-ui.git
cd videosdk-rtc-react-prebuilt-ui
git checkout template/geo-tag-watermark
```

2. Install the dependencies and create a build of the project using below mentioned commands.

```bash
npm install
npm run build
```

3. Host the contents of the build folder on your server and check if the template is up and running.

:::note

If you want to create the complete template from scratch you can [follow this guide.](./custom-template.md)

:::

### Using the template for recording

1. To use the template that we deployed earlier, we will be using the `templateUrl` feature in the `startRecording` API.
   To generate the template URL, you will have to append the `meetingId`, and `token` has to be added in the query parameters. Also if you are using the template provided above you need to added a few extra paramters mentioned below. Here is the code snippet to generate the URL.

```js
async function main() {
  let meetingId = "Your MeetingID";
  let token = "Your Token";
  const templateUrl = `https://${YOUR Template URL}/?meetingId=${meetingId}&token=${token}&name=recorder&isRecorder=true&joinWithoutUserInteraction=true`;

  console.log(templateUrl);
}

main();
```

2. Now that we have the template URL, we will use this URL to start the recording using the below provided API call.

```js
async function main() {
  let meetingId = "Your MeetingID";
  let token = "Your Token";
  const templateUrl = `https://${YOUR Template URL}/?meetingId=${meetingId}&token=${token}&name=recorder&isRecorder=true&joinWithoutUserInteraction=true`;

  console.log(templateUrl);

  //Using the previouly created template URL and starting the recording using the API.
  const options = {
    method: "POST",
    headers: {
      Authorization: "$YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      roomId: "Your MeetingId",
      templateUrl: templateUrl,
    }),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();
```

### Updating the Geo Tagging Coordinates

We will be using the PubSub feature of VideoSDK to update the data of latitude and longitude. For the predefined template provided by us we are using `GEO_TAG` as topic name. We will be publishing the `participantName`, `latitude` and `longitude` of the participant for whom we want to show in the recording.

:::note

You will have to fetch the longitude and latitude of the participant before sending it using the pubsub.

:::

Here is the code how you will have to publish the message:

```js
function Watermark() {
  const sendCoordinates = () => {
    meeting.pubSub.publish(
      "GEO_TAG",
      "GEO TAG DATA",
      { persist: true },
      {
        latitude: "LATITUDE OF PARTICIPANT",
        longitude: "LONGITUDE OF PARTICIPANT",
        participantName: "NAME OF PARTICIPANT",
      }
    );
  };

  return <></>;
}
```

After implementing this, you should get the recording in the following format:

![Geo Tagging Recoridng](https://cdn.videosdk.live/website-resources/docs-resources/geo-tag-recording-template.png)

If you wish to change how UI looks on recording, you can change it by updating the layout in the template itself.

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)
- [Learn more about Custom Templates](./custom-template.md)


---

You have the option to create presigned URL, allowing you to upload your recordings to AWS, Azure, or GCP securely.
presigned URL provide a secure and temporary way to upload objects to your cloud storage. Instead of sharing your entire credentials, you can create a special URL that allows uploading a specific file for a limited time.

:::important

While presigned URL offer a convenient way to upload files securely, each cloud provider (AWS, Azure, and GCP) might have different restrictions on how they work. It's advisable to refer the respective documentation for **[<u>AWS</u>](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)**, **[<u>Azure</u>](https://learn.microsoft.com/en-us/rest/api/storageservices/delegate-access-with-shared-access-signature)**, and **[<u>GCP</u>](https://cloud.google.com/cdn/docs/using-signed-urls)** to gain a clearer understanding of presigned URL.

:::

### Code Sample

This guide will walk you through the process of generating a presigned URL for uploading recordings to your cloud storage of choice. You can use this generated presigned URL in [Start Recording API](/api-reference/realtime-communication/start-recording#preSignedUrl).



**AWS:**

```js
const { S3Client, PutObjectCommand } = require("@aws-sdk/client-s3");
const { getSignedUrl } = require("@aws-sdk/s3-request-presigner");

const region = <YOUR S3 REGION>;
const bucket = <YOUR S3 BUCKET NAME>;
const key = <YOUR FILE NAME>; // test/abc.mp4
const accessKeyId = <YOUR S3 ACCESS KEY ID>;
const secretAccessKey = <YOUR S3 SECRET ACCESS KEY>;
const expiresIn = <URL EXPIRY IN SECONDS>; // this number should be higher than duraion of recording

const s3Client = new S3Client({
credentials: {
    accessKeyId: accessKeyId,
    secretAccessKey: secretAccessKey,
},
region: region,
});

const createPresignedUrlWithClient = async () => {
const command = new PutObjectCommand({ Bucket: bucket, Key: key });
const preSignedUrl = await getSignedUrl(s3Client, command, { expiresIn: expiresIn });
return preSignedUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await createPresignedUrlWithClient();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

---

**AZURE:**

```js
const { BlobServiceClient, BlobSASPermissions } = require("@azure/storage-blob");

const connectionString = <YOUR AZURE STORAGE CONNECTION STRING>;
const containerName = <YOUR AZURE CONTAINER NAME>;
const blobName = <YOUR AZURE BLOB NAME>;
const startsOn = <YOUR SASURL START TIME>; // (optional, defaults to now)
const expiresOn = <YOUR SASURL EXPIRY TIME>; // expiry time should be higher than duration of recording

const generateSASUrl = async () => {
let blobServiceClient = BlobServiceClient.fromConnectionString(connectionString);
let containerClient = blobServiceClient.getContainerClient(containerName);

await containerClient.createIfNotExists({
    access: "container",
});

const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const sasUrl = await blockBlobClient.generateSasUrl({
    startsOn: startsOn, // sasUrl start time
    expiresOn: expiresOn, // sasUrl expiration time
    permissions: BlobSASPermissions.parse("write"),
});
return sasUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await generateSASUrl();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

---

**GCP:**

```js
const { Storage } = require("@google-cloud/storage");

const projectId = <YOUR GCP PROJECT ID>;
const clientEmail = <YOUR GCP CLIENT EMAIL>;
const privateKey = <YOUR GCP PRIVATE KEY>;
const expires =<URL EXPIRY IN SECONDS>; // this number should be higher than duraion of recording
const bucketName = <YOUR GCP BUCKET NAME>;
const fileName = <YOUR FILE NAME>; // test/abc.mp4

const storage = new Storage({
projectId: projectId,
credentials: {
    client_email: clientEmail,
    private_key: privateKey,
},
});

const generateSignedUrl = async () => {
const options = {
    version: "v4",
    action: "write",
    expires: expires,
    contentType: "video/mp4",
};

const [signedUrl] = storage.bucket(bucketName).file(fileName).getSignedUrl(options);
return signedUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await generateSignedUrl();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)



---

# Start and Stop - Javascript

This guide will provide an overview of how to implement start and stop Meeting Recording.

### `startRecording()`

The `startRecording()` method, accessible from the `meeting` object, is used to initiate the recording of a meeting. This method accepts the following four parameters:

- `1. webhookUrl (optional)`: This is the webhook URL where you can listen to events related to the recording, such as the start and stop of recording. It triggers when the recording is completed and stored on the server. You can learn more about webhooks [here](https://en.wikipedia.org/wiki/Webhook)

- `2. awsDirPath (optional)`: This parameter specifies the path to your S3 bucket where you intend to store the recordings. To enable the storage of recordings in your S3 bucket with VideoSDK, follow this guide ([VideoSDK Cloud (AWS S3, Azure Blob or GCP ) Integration](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config))

- `3. config (optional)`: This parameter defines how the recording should be conducted

- `4. transcription (optional)`: This parameter lets you start post transcription for the recording.

  :::caution

  If you don't have a value for `webhookUrl` or `awsDirPath` and wish to utilize the `config` property, you should pass `null` in place of the missing values. Failing to do so may result in the configuration not being applied to the recording.
  :::

  ```js
  // URL for webhook
  const webhookUrl = "https://example.com";

  // directory path to store recording
  const awsDirPath = "path/to/file";

  const config = {
    // highlight-next-line
    // Layout Configuration
    layout: {
      type: "GRID", // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
      priority: "SPEAKER", // "PIN", Default : "SPEAKER"
      gridSize: 4, // MAX : 4
    },

    // highlight-next-line
    // Theme of recording
    theme: "DARK", //  "LIGHT" | "DEFAULT"

    // highlight-next-line
    // `mode` is used to either record video & audio both or only audio.
    mode: "video-and-audio", // "audio", Default : "video-and-audio"

    // highlight-next-line
    // Quality of recording and is only applicable to `video-and-audio` type mode.
    quality: "high", /* Default : "med"
   "low" (SD Recording) | "med" (HD Recording) | "high" (FHD Recording) */

    //highlight-start
    // This mode refers to orientation of recording.
    // landscape : Record the meeting in horizontally
    // portrait : Record the meeting in vertically (Best for mobile view)
    //highlight-end
    orientation: "landscape", // "portrait",  Default : "landscape"
  };

  // highlight-next-line
  // Post Transcription Configuration
  const transcription = {
    enabled: true, // Enables post transcription
    summary: {
      enabled: true, // Enables summary generation

      // Guides summary generation
      prompt:
        "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    },
  };
  ```

### `stopRecording()`

- The `stopRecording()` method, accessible from the `meeting` object, is used to stop the recording of a meeting.

#### Example

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const startRecordingBtn = document.getElementById("startRecordingBtn");
startRecordingBtn.addEventListener("click", () => {
  // Configuration for recording
  let config = {
    layout: {
      type: "GRID",
      priority: "SPEAKER",
      gridSize: 4,
    },
    theme: "DARK",
    mode: "video-and-audio",
    quality: "high",
    orientation: "landscape",
  };

  // Configuration for post transcription
  let transcription = {
    enabled: true,
    summary: {
      enabled: true,
      prompt:
        "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    },
  };

  // Start Recording
  meeting?.startRecording(
    "YOUR WEB HOOK URL",
    "AWS Directory Path",
    config,
    transcription
  );
});

const stopRecordingBtn = document.getElementById("stopRecordingBtn");
stopRecordingBtn.addEventListener("click", () => {
  // Stop Recording
  meeting?.stopRecording();
});
```

:::important

To initiate automatic recording at the beginning of a `session`, simply provide the `autoStartConfig` feature `recording` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.

:::

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [startRecording()](/javascript/api/sdk-reference/meeting-class/methods#startrecording)
- [stopRecording()](/javascript/api/sdk-reference/meeting-class/methods#stoprecording)
- [recording-state-changed](/javascript/api/sdk-reference/meeting-class/events#recording-state-changed)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

VideoSDK offers individual participant recording, generating a single, continuous file for a participant.

This recording captures the participant's audio and video streams throughout the meeting, regardless of whether they are muted or have their camera turned off. During periods of audio muting or video disengagement, the respective tracks will be silent or display a black screen, respectively.

You can access the recorded files in the developer dashboard or opt to store them in your own cloud storage.

This guide provides an overview of the start and stop functionality for individual participant recording through APIs.


## Start Individual Participant Recording

To start a participant recording, you will have to call `/v2/recordings/participant/start` API with following body parameters.

- `roomId`: RoomId for which the participant recording is to be started
- `participantId`: participantId of the participant to be recorder.
- `fileFormat`: Currently only `webm` is supported as file format. We will add the support for other formats in future.
- `webhookUrl`: The webhook URL where you would like to get the status updates of the recording. To learn more about webhooks refer [here](#participant-track-recording-starting).
- `bucketDirPath`: If you are using your own storage, you can provide the directory path where you want to store the recording. To configure the storage please [refere this quide](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config).

The usual recording path would look like `${sessionId}/${participantId}/${filename}`.

```js

const roomId = <YOUR ROOM ID>;
const participantId = <PARTICIPANT ID>;
const fileFormat = <YOUR FILE FORMAT>; // (Optional) default: webm
const bucketDirPath = <YOUR CLOUD STORAGE BUCKET PATH>; // (Optional) test/abc
const webhookUrl = <YOUR WEBHOOK URL>; // (Optional)

async function main() {
    const options = {
    method: "POST",
    headers: {
      Authorization: "$YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      roomId: roomId,
      participantId: participantId,
      fileFormat: fileFormat,
      bucketDirPath: bucketDirPath,
      webhookUrl: webhookUrl
    }),
  };

  const url = `https://api.videosdk.live/v2/recordings/participant/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();
```

## Stop Individual Participant Recording

To stop a participant recording, you will have to call `/v2/recordings/participant/stop` API with following body parameters.

- `roomId`: RoomId for which the participant recording is to be stopped
- `participantId`: participantId for which the recording is to be stopped.

```js

const roomId = <YOUR ROOM ID>;
const participantId = <PARTICIPANT ID>;

async function main() {
    const options = {
    method: "POST",
    headers: {
      Authorization: "$YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      roomId: roomId,
      participantId: participantId,
    }),
  };

  const url = `https://api.videosdk.live/v2/recordings/participant/stop`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();
```

## Webhook associated with Participant Recording

### participant-recording-starting

- A "Participant Recording Starting" webhook is triggered when the participant recording process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-started

- Participant Recording started webhook will be received when successfully participant recording is started in meeting

###### Example

```javascript
{
    "webhookType": "participant-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopping

- A "Participant Recording Stopping" webhook is triggered when the participant recording end process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopped

- Participant Recording stopped webhook will be received when participant recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "participant-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-recording-failed

- A "Participant Recording Failed" webhook is generated when the participant recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "participant-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
    },
}
```

---

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Participant Recording API](/api-reference/realtime-communication/start-participant-recording)
- [Stop Participant Recording API](/api-reference/realtime-communication/stop-participant-recording)



---

VideoSDK provides participant track recording, creating separate audio or video files for participant.

New files are generated when a participant starts their audio or video again after turning it off (e.g., unmuting the microphone or restarting the camera). This ensures that each file represents a continuous segment of audio or video content.

Once track recording is complete, all audio files for a participant are consolidated into a single directory, as are the video files.


## Start Participant Track Recording

To start a participant track recording, you will have to call `/v2/recordings/participant/track/start` API with following body parameters.

- `roomId`: RoomId for which the participant track recording is to be started
- `participantId`: participantId of the participant to be recorder.
- `kind`: The kind of tracks you want to record.
  - You can pass following values: _`audio`_ | _`video`_ | _`screen_audio`_ | _`screen_video`_
- `fileFormat`: Currently only `webm` is supported as file format. We will add the support for other formats in future.
- `webhookUrl`: The webhook URL where you would like to get the status updates of the recording. To learn more about webhooks refer [here](#participant-track-recording-starting).
- `bucketDirPath`: If you are using your own storage, you can provide the directory path where you want to store the recording. To configure the storage please [refere this quide](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config).

The usual recording path would look like `${sessionId}/${participantId}/${kind}/${filename}`.

```js

const roomId = <YOUR ROOM ID>;
const participantId = <PARTICIPANT ID>;
const kind = <YOUR STREAM KIND> // kind of track: audio, video etc.
const fileFormat = <YOUR FILE FORMAT>; // (Optional) default: webm
const bucketDirPath = <YOUR CLOUD STORAGE BUCKET PATH>; // (Optional) test/abc
const webhookUrl = <YOUR WEBHOOK URL>; // (Optional)

async function main() {
    const options = {
    method: "POST",
    headers: {
      Authorization: "$YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      roomId: roomId,
      participantId: participantId,
      kind: kind,
      fileFormat: fileFormat,
      bucketDirPath: bucketDirPath,
      webhookUrl: webhookUrl
    }),
  };

  const url = `https://api.videosdk.live/v2/recordings/participant/track/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();
```

## Stop Participant Track Recording

To stop a participant track recording, you will have to call `/v2/recordings/participant/track/stop` API with following body parameters.

- `roomId`: RoomId for which the participant track recording is to be stopped
- `participantId`: participantId for which the recording is to be stopped.
- `kind`: The kind of track recording you want to stop for the given participant.
  - You can pass following values: _`audio`_ | _`video`_ | _`screen_audio`_ | _`screen_video`_

```js

const roomId = <YOUR ROOM ID>;
const participantId = <PARTICIPANT ID>;
const kind = <YOUR STREAM KIND>; // kind of track: audio, video etc.

async function main() {
    const options = {
    method: "POST",
    headers: {
      Authorization: "$YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      roomId: roomId,
      participantId: participantId,
      kind: kind
    }),
  };

  const url = `https://api.videosdk.live/v2/recordings/participant/track/stop`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();
```

## Webhook associated with Participant Track Recording

### participant-track-recording-starting

- A "Participant Track Recording Starting" webhook is triggered when the track recording process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-started

- Participant Track Recording started webhook will be received when successfully track recording is started in meeting

###### Example

```javascript
{
    "webhookType": "participant-track-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopping

- A "Participant Track Recording Stopping" webhook is triggered when the track recording end process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopped

- Participant Track Recording stopped webhook will be received when track recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-track-recording-failed

- A "Participant Track Recording Failed" webhook is generated when the track recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Track Recording API](/api-reference/realtime-communication/start-track-recording)
- [Stop Track Recording API](/api-reference/realtime-communication/stop-track-recording)



---

### Storage Configuration

While recording your meetings, you have the flexibility to store them either on VideoSDK's storage or configure your own storage solution such as **`AWS S3 Storage, Azure Blob or GCP Cloud Storage`**. To set up your own storage, you can navigate to the [API section](https://app.videosdk.live/api-keys) in the VideoSDK Dashboard.

- This feature allows you to configure storage provider for your meeting recordings.

- You can configure multiple storage provider with multiple API Keys.

- Currently, we support `AWS S3`, `Azure Blob` and `GCP Cloud Storage`. We will add support for other storage provider soon !!

## Prerequisites

- An active [VideoSDK Developer Account](https://app.videosdk.live)
- `Aws S3`, `Azure Blob Storage` or `GCP Cloud Storage` Credentials

## How to setup ?

### Step 1 : Select Api Key

![Dashboard](/img/tutorial/dashboard/api-key-dashboard.png)

- Go to [VideoSDK Dashboard](https://app.videosdk.live/api-keys).
- Select API Key for which, you want to set storage configuration.
- Then click on `Storage Config` Icon in Actions.

### Step 2 : Choose Cloud Storage Provider

![Dashboard](/img/tutorial/dashboard/storage-config.png)

- As you can see in the image, there are 3 Cloud Storage Provider (`Aws`, `Azure`, `GCP`).
- You can select a Cloud Storage Provider as per your requirements.

### Step 3 : Configure Bucket or Container

<h4> For Aws S3 Storage </h4>

![Aws S3](/img/tutorial/dashboard/s3.png)

- You will need AWS S3 Bucket. [Learn to create S3 Bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html).

- As you can see in the image, you will need enter `accessKeyId`, `secretAccessKey`, `region`, `bucket`, and `ACL` to setup for Aws S3 Storage.

- Click on `Save` button.

<hr />

<h4> For Azure Blob Storage: </h4>

![Azure Blob](/img/tutorial/dashboard/blob.png)

- You will need Azure Blob Container. [Learn to create Blob Container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal#create-a-container).

- As you can see in the image, you will need to enter `connectionString` and `containerName` to setup for Azure Blob.

- Click on `Save` button.

<hr />

<h4> For Google Cloud Storage: </h4>

<img src="/img/tutorial/dashboard/gcp.png" alt="GCP Cloud Storage" width="436" height="632"/>

1. You will need Google Cloud Storage Bucket. [Learn to create Google Cloud Storage Bucket](https://cloud.google.com/storage/docs/creating-buckets).

2. After creation, click on the <b> &#xFE19; </b>button in the upper right corner and select **`Project settings`**.

3. Under **`IAM and Admin`**, select **`Service Accounts`**. In the service account list, click on the <b> &#xFE19; </b> button for the account just added or created before, and select **`Manage keys`**.

4. Click **`ADD KEY > Create new key`**. Select **`JSON`** in the pop-up box and click **`CREATE`**. A json file is downloaded with the name format `projectId-xxxxxxxx.json`.

5. Open the downloaded json file, which looks like the following example:

```
{
  "type": "service_account",
  "project_id": "videosdk-12345",
  "private_key_id": "yourprivateidkeyyourprivateidkeyyourprivateidkey",
  "private_key": "-----BEGIN PRIVATE KEY-----\nThisisYourPrivateKeyThisisYourPrivateKeyThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\n-----END PRIVATE KEY-----\n",
  "client_email": "xxxx-xxxx@videosdk-12345.iam.gserviceaccount.com",
  "client_id": "123456789012345678901",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/videosdk%40videosdk-404307.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}
```

- As you can see in the image, you will need to enter `Project Id`, `Client Email`, `Bucket`, `Private Key` to setup for Google Cloud Storage Bucket. You can retrieve these details from the json file.

- Click on `Save` button.

### Step 4 : Test

- It's time to test !!
- [Create Room](https://docs.videosdk.live/api-reference/realtime-communication/create-room) with token generated with the API Key, you have configured for.
- Start meeting with the roomId created and Start Recording !!
- Then, you can see that recording will be available in your Bucket or Container.

:::note

- Only a single Recording Storage Config can be possible for a particular Api Key at a time.
- In order to add new Recording Configuration, first you need to delete current configuration.

:::


---

# Webhooks and Events - JavaScript

### Events associated with Recording

- **onRecordingStateChanged** - The `recording-state-changed` event is triggered whenever the state of meeting recording changes.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const Constants = VideoSDK.Constants;

meeting.on("recording-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.recordingEvents.RECORDING_STARTING) {
    console.log("Meeting recording is starting");
  } else if (status === Constants.recordingEvents.RECORDING_STARTED) {
    console.log("Meeting recording is started");
  } else if (status === Constants.recordingEvents.RECORDING_STOPPING) {
    console.log("Meeting recording is stopping");
  } else if (status === Constants.recordingEvents.RECORDING_STOPPED) {
    console.log("Meeting recording is stopped");
  } else {
    //
  }
});
```

:::important

You can access your recordings on our **[<u>Dashboard</u>](https://app.videosdk.live/meetings/recordings)**. Additionally, you can access your recordings using our **[<u>Recording API</u>](/api-reference/realtime-communication/fetch-recordings)**.

You can access your post transcriptions using our **[<u>Post Transcription API</u>](/api-reference/realtime-communication/fetch-post-transcriptions-summary)**

:::

## Webhook associated with Recording

### recording-starting

- A "Recording Starting" webhook is triggered when the recording process for a meeting is initiated.

###### Example

```javascript
{
    "webhookType": "recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-started

- Recording started webhook will be received when successfully recording is started in meeting

###### Example

```javascript
{
    "webhookType": "recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopping

- A "Recording Stopping" webhook is triggered when the recording end process for a meeting is initiated.

###### Example

```javascript
{
    "webhookType": "recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopped

- Recording stopped webhook will be received when recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
        "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",

    },
}
```

---

### recording-failed

- A "Recording Failed" webhook is generated when the recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```


---

# Interactive Livestream (HLS) - Javascript

Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

In an interactive live stream (HLS), viewers can participate in various activities, such as live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

<center>

![VideoSDK-HLS](/img/VideoSDK-HLS.png)

</center>

VideoSDK enables you to configure the interactive livestream layout in various ways, either by setting different prebuilt layouts in the configuration or by providing your own custom template for livestreaming according to your layout choice.

This guide provides an overview of how to implement starting and stopping Http Live Streaming (HLS).

:::important

To initiate automatic Interactive live streaming (HLS) at the beginning of a `session`, simply provide the `autoStartConfig` feature `hls` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.

:::

### `startHls()`

The `startHls()` method, accessible from the `meeting` object, is used to initiate interactive livestream of a meeting. This method accepts the following parameter:

- `config (optional)`: This parameter defines how the interactive livestream layout should look like.

- `transcription (optional)`: This parameter lets you start post transcription for the HLS.

  ```js
  const config = {
    // highlight-next-line
    // Layout Configuration
    layout: {
      type: "GRID", // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
      priority: "SPEAKER", // "PIN", Default : "SPEAKER"
      gridSize: 4, // MAX : 25
    },

    // highlight-next-line
    // Theme of livestream
    theme: "DARK", //  "LIGHT" | "DEFAULT"

    // highlight-next-line
    // `mode` is used to either interactive livestream video & audio both or only audio.
    mode: "video-and-audio", // "audio", Default : "video-and-audio"

    // highlight-next-line
    // Quality of livestream and is only applicable to `video-and-audio` type mode.
    quality: "high", /* Default : "med"
   "low" (SD HLS) | "med" (HD HLS) | "high" (FHD HLS) */

    //highlight-start
    // This mode refers to orientation of recording.
    // landscape : Livestream the meeting in horizontally
    // portrait : Livestream the meeting in vertically (Best for mobile view)
    //highlight-end
    orientation: "landscape", // "portrait",  Default : "landscape"
  };

  // highlight-next-line
  // Post Transcription Configuration
  const transcription = {
    enabled: true, // Enables post transcription
    summary: {
      enabled: true, // Enables summary generation
      // Guides summary generation
      prompt:
        "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    },
  };

  startHls(config, transcription);
  ```

### `stopHls()`

- The `stopHls()` method, accessible from the `meeting` object, is used to stop the interactive livestream of a meeting.

#### Example

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const startHlsBtn = document.getElementById("startHlsBtn");
startHlsBtn.addEventListener("click", () => {
  const config = {
    layout: {
      type: "GRID",
      priority: "SPEAKER",
      gridSize: 4,
    },
    theme: "DARK",
    mode: "video-and-audio",
    quality: "high",
    orientation: "landscape",
  };

  // Configuration for post transcription
  const transcription = {
    enabled: true,
    summary: {
      enabled: true,
      prompt:
        "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    },
  };

  // Start HLS
  meeting?.startHls(config, transcription);
});

const stopHlsBtn = document.getElementById("stopHlsBtn");
stopHlsBtn.addEventListener("click", () => {
  // Stop HLS
  meeting?.stopHls();
});
```

### Event associated with HLS

- **hls-state-changed** - The `hls-state-changed` event is triggered whenever the state of meeting HLS changes.

- You can get the `playbaclHlsUrl` and `livestreamUrl` of the HLS to play it on the Viewer side when the state changes to `Constants.hlsEvents.HLS_STARTED`

- when you receive `HLS_PLAYABLE` status you will receive 2 urls in response
  - `playbackHlsUrl` - Live HLS with playback support
  - `livestreamUrl` - Live HLS without playback support

:::note
`downstreamUrl` is now depecated. Use `playbackHlsUrl` or `livestreamUrl` in place of `downstreamUrl`
:::

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const Constants = VideoSDK.Constants;

meeting.on("hls-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.hlsEvents.HLS_STARTING) {
    console.log("Meeting Hls is starting");
  } else if (status === Constants.hlsEvents.HLS_STARTED) {
    // when hls is started you will receive playbaclHlsUrl and livestreamUrl.
    const { playbackHlsUrl } = data;

    console.log("Meeting Hls is started");
  } else if (status === Constants.hlsEvents.HLS_STOPPING) {
    console.log("Meeting Hls is stopping");
  } else if (status === Constants.hlsEvents.HLS_STOPPED) {
    console.log("Meeting Hls is stopped");
  } else {
    //
  }
});
```

:::important

You can access your post transcriptions using our **[<u>Post Transcription API</u>](/api-reference/realtime-communication/fetch-post-transcriptions-summary)**

:::

### Custom Template

With VideoSDK, you have the option to employ your own custom-designed layout template for meeting recordings. To use a custom template, [follow this guide](/javascript/guide/interactive-live-streaming/custom-template) to create and set up the template. Once the template is configured, you can initiate recording using the [REST API](/api-reference/realtime-communication/start-livestream), specifying the `templateURL` parameter.

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [startHls()](/javascript/api/sdk-reference/meeting-class/methods#starthls)
- [stopHls()](/javascript/api/sdk-reference/meeting-class/methods#stophls)
- [hls-state-changed](/javascript/api/sdk-reference/meeting-class/events#hls-state-changed)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

# Record Meeting - Javascript

VideoSDK enables you to record video and audio during meetings, and you can access the recorded files in the developer dashboard or opt to store them in your own cloud storage.

Additionally, VideoSDK offers flexibility in configuring recording layouts. You can achieve this by selecting various prebuilt layouts in the configuration or by providing your own custom template for recording, tailored to your layout preferences.

This guide provides an overview of implementing the start and stop functionality for meeting recording.

:::important

To initiate automatic recording at the beginning of a `session`, simply provide the `autoStartConfig` feature, `recording` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.

:::

### `startRecording()`

The `startRecording()` method, accessible from the `meeting` object, is used to initiate the recording of a meeting. This method accepts the following four parameters:

- `1. webhookUrl (optional)`: This is the webhook URL where you can listen to events related to the recording, such as the start and stop of recording. It triggers when the recording is completed and stored on the server. You can learn more about webhooks [here](https://en.wikipedia.org/wiki/Webhook)

- `2. awsDirPath (optional)`: This parameter specifies the path to your S3 bucket where you intend to store the recordings. To enable the storage of recordings in your S3 bucket with VideoSDK, follow this guide ([VideoSDK AWS S3 Integration](/docs/tutorials/user-dashboard/recording-storage-config))

- `3. config (optional)`: This parameter defines how the recording should be conducted

- `4. transcription (optional)`: This parameter lets you start post transcription for the recording.

  :::caution

  If you don't have a value for `webhookUrl` or `awsDirPath` and wish to utilize the `config` property, you should pass `null` in place of the missing values. Failing to do so may result in the configuration not being applied to the recording.
  :::

  ```js
  // URL for webhook
  const webhookUrl = "https://example.com";

  // directory path to store recording
  const awsDirPath = "path/to/file";

  const config = {
    // highlight-next-line
    // Layout Configuration
    layout: {
      type: "GRID", // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
      priority: "SPEAKER", // "PIN", Default : "SPEAKER"
      gridSize: 4, // MAX : 4
    },

    // highlight-next-line
    // Theme of recording
    theme: "DARK", //  "LIGHT" | "DEFAULT"

    // highlight-next-line
    // `mode` is used to either record video & audio both or only audio.
    mode: "video-and-audio", // "audio", Default : "video-and-audio"

    // highlight-next-line
    // Quality of recording and is only applicable to `video-and-audio` type mode.
    quality: "high", /* Default : "med"
   "low" (SD Recording) | "med" (HD Recording) | "high" (FHD Recording) */

    //highlight-start
    // This mode refers to orientation of recording.
    // landscape : Record the meeting in horizontally
    // portrait : Record the meeting in vertically (Best for mobile view)
    //highlight-end
    orientation: "landscape", // "portrait",  Default : "landscape"
  };

  // highlight-next-line
  // Post Transcription Configuration
  const transcription = {
    enabled: true, // Enables post transcription
    summary: {
      enabled: true, // Enables summary generation

      // Guides summary generation
      prompt:
        "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    },
  };
  ```

### `stopRecording()`

- The `stopRecording()` method, accessible from the `meeting` object, is used to stop the recording of a meeting.

#### Example

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const startRecordingBtn = document.getElementById("startRecordingBtn");
startRecordingBtn.addEventListener("click", () => {
  // Configuration for recording
  let config = {
    layout: {
      type: "GRID",
      priority: "SPEAKER",
      gridSize: 4,
    },
    theme: "DARK",
    mode: "video-and-audio",
    quality: "high",
    orientation: "landscape",
  };

  // Configuration for post transcription
  let transcription = {
    enabled: true,
    summary: {
      enabled: true,
      prompt:
        "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    },
  };

  // Start Recording
  meeting?.startRecording(
    "YOUR WEB HOOK URL",
    "AWS Directory Path",
    config,
    transcription
  );
});

const stopRecordingBtn = document.getElementById("stopRecordingBtn");
stopRecordingBtn.addEventListener("click", () => {
  // Stop Recording
  meeting?.stopRecording();
});
```

### Events associated with Recording

- **onRecordingStateChanged** - The `recording-state-changed` event is triggered whenever the state of meeting recording changes.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const Constants = VideoSDK.Constants;

meeting.on("recording-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.recordingEvents.RECORDING_STARTING) {
    console.log("Meeting recording is starting");
  } else if (status === Constants.recordingEvents.RECORDING_STARTED) {
    console.log("Meeting recording is started");
  } else if (status === Constants.recordingEvents.RECORDING_STOPPING) {
    console.log("Meeting recording is stopping");
  } else if (status === Constants.recordingEvents.RECORDING_STOPPED) {
    console.log("Meeting recording is stopped");
  } else {
    //
  }
});
```

:::important

You can access your recordings on our **[<u>Dashboard</u>](https://app.videosdk.live/meetings/recordings)**. Additionally, you can access your recordings using our **[<u>Recording API</u>](/api-reference/realtime-communication/fetch-recordings)**.

You can access your post transcriptions using our **[<u>Post Transcription API</u>](/api-reference/realtime-communication/fetch-post-transcriptions-summary)**

:::

### Storage Configuration

While recording your meetings, you have the flexibility to store them either on VideoSDK's storage or configure your own storage solution such as **`AWS S3 Storage, Azure Blob or GCP Cloud Storage`**. To set up your own storage, you can navigate to the [API section](https://app.videosdk.live/api-keys) in the VideoSDK Dashboard.

For detailed instructions on configuring storage or a step-by-step guide, you can refer to this [documentation](/docs/tutorials/user-dashboard/recording-storage-config) or watch the accompanying [video tutorial](https://www.loom.com/share/23a2617f824a4a5da004d14d1a541a9d).

### Custom Template

With VideoSDK, you have the option to employ your own custom-designed layout template for meeting recordings. To use a custom template, [follow this guide](/javascript/guide/interactive-live-streaming/custom-template) to create and set up the template. Once the template is configured, you can initiate recording using the [REST API](/api-reference/realtime-communication/start-recording), specifying the `templateURL` parameter.

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [startRecording()](/javascript/api/sdk-reference/meeting-class/methods#startrecording)
- [stopRecording()](/javascript/api/sdk-reference/meeting-class/methods#stoprecording)
- [recording-state-changed](/javascript/api/sdk-reference/meeting-class/events#recording-state-changed)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

# RTMP Livestream - Javascript

RTMP is a widely used protocol for live streaming video content from VideoSDK to platforms like YouTube, Twitch, Facebook, and others.

To initiate live streaming from VideoSDK to platforms supporting RTMP ingestion, you simply need to provide the platform-specific stream key and stream URL. This enables VideoSDK to connect to the platform's RTMP server and transmit the live video stream.

Furthermore, VideoSDK offers flexibility in configuring livestream layouts. You can achieve this by either selecting different prebuilt layouts in the configuration or by providing your custom template for livestreaming, catering to your specific layout preferences.

This guide will provide an overview of how to implement starting and stopping RTMP livestreaming with VideoSDK.

### `startLivestream()`

The `startLivestream()` method, accessible from the `meeting` object, is used to initiate the RTMP livestream of a meeting. This method accepts the following two parameters:

- `1. outputs`: This parameter takes an array of objects containing the RTMP `url` and `streamKey` specific to the platform where you want to initiate the livestream.

- `2. config (optional)`: This parameter defines the layout configuration for the livestream.

  ```js
  const config = {
    // highlight-next-line
    // Layout Configuration
    layout: {
      type: "GRID", // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
      priority: "SPEAKER", // "PIN", Default : "SPEAKER"
      gridSize: 4, // MAX : 4
    },

    // highlight-next-line
    // Theme of livestream layout
    theme: "DARK", //  "LIGHT" | "DEFAULT"
  };

  const outputs = [
    {
      url: "<RTMP_URL>",
      streamKey: "<RTMP_STREAM_KEY>",
    },
  ];

  startLivestream(outputs, config);
  ```

### `stopLivestream()`

The `stopLivestream()` method, accessible from the `meeting` object, is used to stop the RTMP livestream of a meeting.

#### Example

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const startLivestreamBtn = document.getElementById("startLivestreamBtn");
startLivestreamBtn.addEventListener("click", () => {
  // Start Livestream
  meeting?.startLivestream(
    [
      {
        url: "rtmp://a.rtmp.youtube.com/live2",
        streamKey: "key",
      },
    ],
    {
      layout: {
        type: "GRID",
        priority: "SPEAKER",
        gridSize: 4,
      },
      theme: "DARK",
    }
  );
});

const stopLivestreamBtn = document.getElementById("stopLivestreamBtn");
stopLivestreamBtn.addEventListener("click", () => {
  // Stop Livestream
  meeting?.stopLivestream();
});
```

### Event associated with Livestream

- **livestream-state-changed** - Whenever meeting livestream state changes, then `livestream-state-changed` event will trigger.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const Constants = VideoSDK.Constants;

meeting.on("livestream-state-changed", (data) => {
  const { status } = data;

  if (status === Constants.livestreamEvents.LIVESTREAM_STARTING) {
    console.log("Meeting livestream is starting");
  } else if (status === Constants.livestreamEvents.LIVESTREAM_STARTED) {
    console.log("Meeting livestream is started");
  } else if (status === Constants.livestreamEvents.LIVESTREAM_STOPPING) {
    console.log("Meeting livestream is stopping");
  } else if (status === Constants.livestreamEvents.LIVESTREAM_STOPPED) {
    console.log("Meeting livestream is stopped");
  } else {
    //
  }
});
```

### Custom Template

With VideoSDK, you have the option to employ your own custom-designed layout template for livestreaming a meeting. To use a custom template, [follow this guide](/javascript/guide/interactive-live-streaming/custom-template) to create and set up the template. Once the template is configured, you can initiate recording using the [REST API](/api-reference/realtime-communication/start-livestream), specifying the `templateURL` parameter.

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [startLivestream()](/javascript/api/sdk-reference/meeting-class/methods#startlivestream)
- [stopLivestream()](/javascript/api/sdk-reference/meeting-class/methods#stoplivestream)
- [livestream-state-changed](/javascript/api/sdk-reference/meeting-class/events#livestream-state-changed)


---

# Release Notes - JavaScript




---

# Display Audio and Video - Javascript

This guide elaborates on how to render a participant's audio and video on the screen.

## Rendering Participant

The steps involved in rendering the audio and video of a participant are as follows.

1. [Create a Container](#1-create-a-container)
2. [Rendering Video](#2-rendering-video)
3. [Rendering Audio](#3-rendering-audio)

### `1. Create a Container`

First, create a `div` container in your UI to hold all the video elements.

```html
<!DOCTYPE html>
<html>
  <body>
    ...

    
    <div id="videoContainer"></div>
  </body>
</html>
```

### `2. Rendering Video`

On the `stream-enabled` event for each participant, you will receive a `stream` object as a parameter. You can use this object to create video elements within a div container.

```js
const videoContainer = document.getElementById("videoContainer");

// local participant video
meeting.localParticipant.on("stream-enabled", (stream) => {
  createVideoElement(stream, meeting.localParticipant);
});

// remote participant video
participant.on("stream-enabled", (stream) => {
  if (stream.kind == "video") {
    createVideoElement(stream, participant);
  }
});

// creating video element
function createVideoElement(stream, participant) {
  const pId = participant.id;
  const name = participant.displayName;

  let videoFrame = document.createElement("div");
  videoFrame.setAttribute("id", `f-${pId}`);

  //create video
  let videoElement = document.createElement("video");
  videoElement.classList.add("video-frame");
  videoElement.setAttribute("id", `v-${pId}`);
  videoElement.setAttribute("playsinline", true);
  videoElement.setAttribute("width", "300");

  const mediaStream = new MediaStream();
  mediaStream.addTrack(stream.track);
  videoElement.srcObject = mediaStream;
  videoElement
    .play()
    .catch((error) => console.error("videoElem.current.play() failed", error));

  videoFrame.appendChild(videoElement);

  let displayName = document.createElement("div");
  displayName.innerHTML = `Name : ${name}`;

  videoFrame.appendChild(displayName);

  videoContainer.appendChild(videoElement);
}
```

<center>

![participant grid](/img/js-participant-video.png)

</center>

#### `Mirror Local Video View`

If you want to display the mirror view of the local participant, you can apply the transformation style to the participant's view.

```js
function createVideoElement(stream, participant) {
  // ...

  //create video
  let videoElement = document.createElement("video");
  videoElement.classList.add("video-frame");
  videoElement.setAttribute("id", `v-${pId}`);
  videoElement.setAttribute("playsinline", true);
  videoElement.setAttribute("width", "300");
  //highlight-start
  if (pId === meeting.localParticipant.id) {
    videoElement.style.transform = "scaleX(-1)";
    videoElement.style.WebkitTransform = "scaleX(-1)";
  }
  //highlight-end
  // ...
}
```

##### Sample of mirror view video

![mirror view](/img/mirror-view.jpg)

### `3. Rendering Audio`

On the `stream-enabled` event for each participant, you will receive a `stream` object as a parameter. You can use this object to create audio elements.

```js
const participants = meeting.participants;
const participant = participants.get("<participant-id>");

participant.on("stream-enabled", (stream) => {
  if (stream.kind == "audio") {
    createAudioElement(stream, participant);
  }
});

// creating audio element
function createAudioElement(stream, participant) {
  const pId = participant.id;

  let audioElement = document.createElement("audio");
  audioElement.setAttribute("autoPlay", "false");
  audioElement.setAttribute("playsInline", "true");
  audioElement.setAttribute("controls", "false");
  audioElement.setAttribute("id", `a-${pId}`);
  audioElement.style.display = "none";

  const mediaStream = new MediaStream();
  mediaStream.addTrack(stream.track);
  audioElement.srcObject = mediaStream;
  audioElement
    .play()
    .catch((error) => console.error("audioElem.play() failed", error));
}
```

:::caution
While rendering the audio, you should **not render the audio of the local participant** as it will create echo.
So to avoid that, you should not create an audio element for the local participant.
:::

## Autoplay Audio and Video

`autoplay` is a parameter passed to `<audio>` and `<video>` elements, indicating that their media should play automatically without requiring the user to click on the video or hit the play button.

When developing an audio-video calling app, ensure that the `autoplay` flag is set to `true`, allowing any loaded media to play even if the `play()` method was not explicitly called.

You can learn more about the `autoplay flag` in the [**official documentation**](https://developer.mozilla.org/en-US/docs/Web/Media/Autoplay_guide).

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [stream-enabled](/javascript/api/sdk-reference/participant-class/events#stream-enabled)


---

# Layout and Grid Management - Javascript

In this guide, we will take a look at how to efficiently manage the participants in different types of layout.

## Grid Layout

This guide focuses on how to efficiently manage the participants in different types of layout.

## Grid Layout

The most common way to display participants is within a grid. There are several factors to consider when showing participants in the grid, including the number of participants displayed on the screens, the number of participants in the background (in the meeting but not on the grid), and the quality being consumed for each participant in the grid.

### Quality of Participant's Video

When dealing with a large number of participants on the screen, it is advisable to consume their video streams at lower resolutions. To achieve this, we recommend using the `setQuality` method on the participants displayed in the grid, adjusting the values dynamically based on the number of participants visible on the screen.

The recommended video quality settings are as follows:

1. For fewer than 3 participants: `setQuality("high")`
2. For 4 to 6 participants: `setQuality("med")`
3. For more than 6 participants: `setQuality("low")`

![grid-quality](/img/grid-quality.png)

### Grid with Screen Share

When rendering a small grid alongside the screen share of the presenter, or when showing a simple sidebar video of the participants while the screenshare is on, it is recommended to set the quality to 'low' (`setQuality("low")`) for the participants present in the sidebar.

## Sidebar Layout

For a layout, where the speaker is displayed in the large view, and the rest of the participants are in small views in a sidebar, you should use `setQuality("high")` for the speaker participant, and `setQuality("low")` for the rest of the participants. 

![sidebar-quality](/img/sidebar-quality.png)

## Spotlight Layout

For a spotlight layout, where the speaker is the only one being displayed on the screen, you should use `setQuality("high")` for the speaker participant.

![spotlight-quality](/img/spotlight-quality.png)

## Grid with Pagination

When hosting large video calls with multiple speakers displaying their video feeds, it is recommended to implement a pagination-style setup. Display a limited number (6-9) of participants on the grid, allowing users to switch between pages to view additional participants.

**To optimize resources, consider pausing the streams of participants who are not currently visible on the grid. When they come into view, you can then resume their streams.**

![grid-pagination](/img/grid-pagination.png)

###### Example to pause and resume a participant's stream

```js
const participants = meeting.participants;
const participant = participants.get("<participant-id>");

const pauseStreamBtn = document.getElementById("pauseStreamBtn");
pauseStreamBtn.addEventListener("click", () => {
  participant.streams.forEach((stream, name) => {
    stream?.pause();
  });
});

const resumeStreamBtn = document.getElementById("resumeStreamBtn");
resumeStreamBtn.addEventListener("click", () => {
  participant.streams.forEach((stream, name) => {
    stream?.resume();
  });
});
```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [setQuality](/javascript/api/sdk-reference/participant-class/methods#setquality)
- [pause](/javascript/api/sdk-reference/stream-class/methods#pause)
- [resume](/javascript/api/sdk-reference/stream-class/methods#resume)


---

# Optimize Audio Track - Javascript

To optimize the listening experience, it's essential to fine-tune the audio tracks used during calls. 

For an enhanced fine-tuning experience, we've introduced the capability to provide a custom audio track for a participant's media before and during the meeting.

## Custom Audio Track

This feature allows you to incorporate custom layers like background noise removal, echo cancellation, etc. and send these modifications to other participants.

### `How to Create a Custom Audio Track ?`

- You can create a Custom Audio Track using `createMicrophoneAudioTrack()`

- This method enables the creation of a audio track with various encoding parameters and noise cancellation configuration.

#### Example

```javascript
let customTrack = await VideoSDK.createMicrophoneAudioTrack({
  // highlight-next-line
  // It will be the id of the mic from which the voice should be captured.
  microphoneId : 'mic-id' // OPTIONAL

  // highlight-next-line
  // This will accept the voice profile you want to capture.
  encoderConfig: "speech_standard", // `high_quality` | `music_standard`,  Default : `speech_standard`

  noiseConfig: {
  // highlight-start
  // It is used to improve the quality of audio by removing background noise
  // that can interfere with the clarity of speech.
  // highlight-end
    noiseSuppression: true,

  // highlight-next-line
  // It is used to remove unwanted echoes from voice.
    echoCancellation: true,

 // highlight-next-line
  // It is used to maintain a consistent level of loudness or amplitude in a voice.
    autoGainControl: true,
  },
});
```
Here are different configurations for customizing audio tracks based on specific use cases:

- `speech_standard` : This config is optimised for normal voice communication.

- `high_quality` : This config is used for obtaining RAW audio, allowing you to apply your `noiseConfig`.

- `music_standard` : This config is optimised for communication scenarios, where the sharing of musical elements, such as songs or instrumental sounds, is crucial.

### `How to Setup Custom Audio Track ?`

The custom track can be configured both before and after the meeting is initialized. Following are the methods that help in doing so:

1. [Setting up a Custom Track during the initialization of a meeting](#1-setting-up-a-custom-track-during-the-initialization-of-a-meeting)
2. [Setting up a Custom Track with methods](#2-setting-up-a-custom-track-with-methods)

##### 1. Setting up a Custom Track during the initialization of a meeting

If you are enabling the mic (`micEnabled: true`) in the `config` of `initMeeting` method and wish to use custom tracks from the start of the meeting, you can pass a custom track in the `config` as demonstrated below.

:::caution
Custom Track will not apply on `micEnabled: false` configuration.
:::

##### Example

```javascript
let customAudioTrack = await VideoSDK.createMicrophoneAudioTrack({
  encoderConfig: "high_quality",
  noiseConfig: {
    noiseSuppresion: true,
    echoCancellation: true,
    autoGainControl: true,
  },
});

// Meeting Init
meeting = window.VideoSDK.initMeeting({
  meetingId: meetingId, // required
  name: name, // required
  //highlight-next-line
  micEnabled: true, //If true, it will use the passed custom track to turn mic on
  webcamEnabled: true,
  //highlight-start
  //Pass the custom audio track here
  customMicrophoneAudioTrack: customAudioTrack,
  //highlight-end
});
```

#### 2. Setting up a Custom Track with methods

To switch tracks during the meeting, you need to pass the `MediaStream` in the **`unmuteMic()` or `toggleMic()`** method of the `meeting` object.

:::tip
Make sure to call the `muteMic()` meethod before you create a new track as it may lead to unexpected behavior.
:::

##### Example

```javascript
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const unmuteMicBtn = document.getElementById("unmuteMicBtn");
unmuteMicBtn.addEventListener("click", async () => {
  let customAudioTrack = await VideoSDK.createMicrophoneAudioTrack({
    encoderConfig: "high_quality",
    noiseConfig: {
      noiseSuppresion: true,
      echoCancellation: true,
      autoGainControl: true,
    },
  });

  meeting?.unmuteMic(customAudioTrack);
});
```


---

---
title: Optimize Video Tracks | VideoSDK Docs
hide_title: false
hide_table_of_contents: false
description: Optimize Video Tracks features quick integrate in Javascript, React JS, Android, IOS, React Native, Flutter with Video SDK to add live video & audio conferencing to your applications.
sidebar_label: Optimize Video Tracks
pagination_label: Optimize Video Tracks
keywords:
  - Camera on
  - Camera off
  - Webcam on
  - Webcam off
  - audio calling
  - video calling
  - real-time communication
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
--- 

# Optimize Video Tracks - Javascript

To optimize the viewing experience, it's essential to fine-tune the video tracks used during calls. 

For an enhanced fine-tuning experience, we've introduced the capability to provide a custom video track for a participant's media before and during the meeting.

1. [Custom Video Track](#custom-video-track)
2. [Custom Screen Share Track](#custom-screen-share-track)

## Custom Video Track

This feature allows you to incorporate custom video encoder configurations, choose optimization modes (focusing on **motion**, **text** or **detail** of the video), specify a modern video quality profile (bitrateMode), and control simulcast behavior (maxLayer), and apply background removal and video filters from external libraries (e.g., [videosdk-media-processor](https://www.npmjs.com/package/@videosdk.live/videosdk-media-processor-web)), then send these modifications to other participants.

### `How to Create a Custom Video Track ?`

- You can create a Custom Video Track using `createCameraVideoTrack()`.
- This method can be used to create video track by specifying parameters like video resolution, camera facing mode, and the quality controls (`bitrateMode` and `maxLayer`).
- You can choose video resolution from the below mentioned list of values for the encoder config:


| Encoder Config | Resolution | Frame Rate | Optimized (kbps) | Balanced (kbps) | High Quality (kbps) |
| -------------- | :--------: | :--------: | :----------: | :----------: | :----------: |
| h90p_w160p | 160x90 | 15 fps | 60  | 100 | 150|
| h180p_w320p | 320x180 | 15 fps | 100 | 150 | 250 |
| h216p_w384p | 384x216 | 15 | 120 | 200 | 350 |
| h360p_w640p | 640x360 | 20 | 200 | 400 | 600 |
| h540p_w960p | 960x540 | 25 | 350 | 550 | 800 |
| h720p_w1280p | 1280x720 | 30 | 1000 | 1500 | 2000 |
| h1080p_w1920p | 1920x1080 | 30 | 1600 | 2200 | 2700 |
| h1440p_w2560p | 2560x1440 | 30 | 5000 | 5500 | 6000 |
| h2160p_w3840p | 3840x2160 | 30 | 8000 | 8500 | 9000 |
| h120p_w160p | 160x120 | 15 | 60 | 100 | 150 |
| h180p_w240p | 240x180 | 15 | 100 | 150 | 250 |
| h240p_w320p | 320x240 | 15 | 120 | 200 | 350 |
| h360p_w480p | 480x360 | 20 | 200 | 400 | 600 |
| h480p_w640p | 640×480 | 25 | 300 | 500 | 700 |
| h540p_w720p | 720×540 | 30 | 350 | 550 | 800 |
| h720p_w960p | 960×720 | 30 | 900 | 1300 | 1600 |
| h1080p_w1440p | 1440×1080 | 30 | 1600 | 2200 | 2700 |
| h1440p_w1920p | 1920×1440 | 30 | 3500 | 4000 | 4500 |

:::note

Above mentioned encoder configurations are valid for both, landscape as well as portrait mode.

:::


#### Example

```javascript
let customTrack = await VideoSDK.createCameraVideoTrack({
  // highlight-next-line
  // It will be the id of the camera from which the video should be captured.
  cameraId:"camera-id", // OPTIONAL

  // highlight-next-line
  // We will discuss this parameter in next step.
  optimizationMode: "motion", // "text" | "detail",  Default : "motion"

  // highlight-next-line
  // This will accept the resolution (height x width) of video you want to capture.
  encoderConfig: "h540p_w960p", // "h360p_w640p" | "h720p_w960p" ... // Default : "h720p_w1280p"

  // highlight-next-line
  // For Mobile browser It will specify whether to use front or back camera for the video track.
  facingMode: "environment", // "front",  Default : "environment"

  // highlight-next-line
  // We will discuss this parameter in next step.
  multiStream:true, // false,  Default : true

  // highlight-next-line
  // Optional: This controls the video quality and bandwidth usage.
  bitrateMode: VideoSDK.Constants.BitrateMode.HIGH_QUALITY, // "BANDWIDTH_OPTIMIZED" | "BALANCED" , Default : BALANCED

  // highlight-next-line
  // Optional: This specifies the maximum number of simulcast layers (maxLayer) to publish.
  maxLayer: 2 // 3 , Default: 3
});
```

:::caution
The behavior of custom track configurations is influenced by the capabilities of the device. For example, if you set the encoder configuration to 1080p but the webcam only supports 720p, the encoder configuration will automatically adjust to the highest resolution that the device can handle, which in this case is 720p.
:::

##### What is `optimizationMode`?

- This parameter specifies the optimization mode for the video track being generated.

- `motion` : This type of track focuses more on motion video such as webcam video, movies or video games.

  - It will degrade `resolution` in order to maintain `frame rate`.

- `text` : This type of track focuses on significant sharp edges and areas of consistent color that can change frequently such as presentations or web pages with text content.

  - It will degrade `frame rate` in order to maintain `resolution`.

- `detail` : This type of track focuses more on the details of the video such as, presentations, painting or line art.

  - It will degrade `frame rate` in order to maintain `resolution`.

##### What is `multiStream`?

- This parameter specifies whether the stream should send multiple resolution layers or a single resolution layer.

The **`multiStream : true`** configuration indicates that VideoSDK, by default, sends multiple resolution video streams to the server. For example, if a user's device capability is 720p, VideoSDK sends streams in 720p, 360p, and 180p resolution. This enables VideoSDK to deliver the appropriate stream to each participant based on their network bandwidth.

<center>

![Multi Stream False](https://cdn.videosdk.live/website-resources/docs-resources/multistream_true_ios.png)


</center>

Setting **`multiStream : false`** restricts VideoSDK to send only one stream, helping to maintain quality by focusing on a single resolution.

<center>

![Multi Stream False](/img/multistream_false.png)

</center>

:::danger
The `setQuality` parameter will not have any effect if multiStream is set to `false`.
:::


##### What is `BitrateMode`?
`BitrateMode` is the key setting for video quality. It lets you decide whether to prioritize sharp details, save internet data, or find a good balance between the two.

You can choose from three distinct modes:
- `bandwidth_optimized`: Prioritizes lower bandwidth usage over video quality. Ideal for users with poor or unstable network conditions.
- `balanced`: The default setting. It provides a smart compromise between clear video and efficient bandwidth consumption, suitable for most use cases.
- `high_quality`: Prioritizes video quality over bandwidth usage. Use this when high-fidelity video is essential and viewers are expected to have strong network connections.

##### What is `maxLayer`?
`maxLayer` is an advanced parameter that gives you direct control over simulcast, which is the process of sending multiple versions (or "layers") of the same video stream at different resolutions and qualities simultaneously.

- `maxLayer : 3` **(Default)**: Publishes all available layers (e.g., high, medium, and low quality). This provides the maximum adaptability for viewers on diverse and unpredictable networks.
- `maxLayer : 2`: Intelligently publishes only the highest and lowest quality layers, skipping any in the middle. This is useful for providing a high-quality option and a low-bandwidth fallback without the overhead of a third stream.

  - If a device is capable of producing a `h720p_w960p` stream, setting `maxLayer : 2` will result in two streams being sent: the highest quality (`h720p_w960p`) and the lowest quality (e.g. `h180p_w240p`), ensuring a fallback for poor connections.

:::info
To use the `maxLayer` parameter, `multiStream` must be set to `true`. The `multiStream` flag enables simulcasting (sending multiple quality streams), while `maxLayer` specifies how many streams to send.
:::

:::note
- If the video width or height is 960 or higher, it will create 3 layers.
- If it’s 480 or higher and less than 960, it will create 2 layers.
- If it’s below 480, it will create only 1 layer.
  - For example, if you set maxLayer to 3 but your video is 320×180, it will only create 1 layer.
:::


### `How to Setup a Custom Video Track ?`

The custom track can be configured both before and after the meeting is initialized. Following are the methods that help in doing so:

1. [Setting up a Custom Track during the initialization of a meeting](#1-setting-up-a-custom-track-during-the-initialization-of-a-meeting)
2. [Setting up a Custom Track with methods](#2-setting-up-a-custom-track-with-methods)

##### 1. Setting up a Custom Track during the initialization of a meeting

If you are enabling the webcam (`webcamEnabled: true`) in the `config` of the `initMeeting` method and wish to use custom tracks from the start of the meeting, you can pass a custom track in the `config` as demonstrated below.

:::caution
Custom Track will not apply on `webcamEnabled: false` configuration.
:::

##### Example

```javascript
let customVideoTrack = await VideoSDK.createCameraVideoTrack({
  optimizationMode: "motion",
  encoderConfig: "h540p_w960p",
  facingMode: "environment",
  multiStream: true,
  bitrateMode: VideoSDK.Constants.BitrateMode.HIGH_QUALITY,
  maxLayer: 2
});

// Meeting Init
meeting = VideoSDK.initMeeting({
  meetingId: meetingId, // required
  name: name, // required
  //highlight-start
  //If true, it will use the passed custom track to turn webcam on
  webcamEnabled: true,
  //Pass the custom video track here
  customCameraVideoTrack: customVideoTrack,
  //highlight-end
});
```

#### 2. Setting up a Custom Track with methods

To switch tracks during the meeting, you need to pass the `MediaStream` in the `enableWebcam()` method of the `meeting` object.

:::tip
Make sure to call the `disableWebcam()` method before you create a new track as it may lead to unexpected behavior.
:::

##### Example

```javascript
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const enableWebcamBtn = document.getElementById("enableWebcamBtn");
enableWebcamBtn.addEventListener("click", async () => {
  let customVideoTrack = await VideoSDK.createCameraVideoTrack({
    optimizationMode: "motion",
    encoderConfig: "h540p_w960p",
    facingMode: "environment",
    multiStream: true,
    bitrateMode: VideoSDK.Constants.BitrateMode.HIGH_QUALITY,
    maxLayer: 2
  });

  // Enable Webcam in Meeting
  meeting?.enableWebcam(customVideoTrack);
});
```

:::info
Using custom video tracks is not just limited to the video tracks created using the `createCameraVideoTrack` method. You can use any `MediaStream` object as a replacement which can include a [custom canvas track created by you](https://developer.chrome.com/blog/capture-stream/).
:::

### `Which Configuration is suitable for me ?`

In this section, the focus is on understanding participant size and platform-wise `encoder(Resolution)` and `multiStream` configuration.

##### 1. For Desktop Browser

![web_browser](/img/web_browser.png)

##### 2. For Mobile Browser

![web_browser](/img/mobile_browser.png)

##### 3. For Desktop + Mobile Browser

![web_browser](/img/mobile+web.png)

## Custom Screen Share Track

This feature enables the customization of screenshare streams with enhanced optimization modes and predefined encoder configuration (resolution + FPS) for specific use cases, which can then be sent to other participants.

### `How to Create a Custom Screen Share Track ?`

- You can create a Video Track using the `createScreenShareVideoTrack()` method.
- This method enables the creation of a video track with different encoding parameters and optimization modes.

#### Example

```javascript
let customShareTrack = await VideoSDK.createScreenShareVideoTrack({
  optimizationMode: "motion", // "text" | "detail",  Default : "motion"

  // This will accept the  height & FPS of video you want to capture.
  encoderConfig: "h720p_15fps", //  `h360p_30fps` | `h1080p_30fps` // Default : `h720p_15fps`
});
```

You can learn about `optimizationMode` from here [What is optimizationMode ?](#what-is-optimizationmode)

### `How to Setup a Custom Screen Share Track ?`

In order to switch tracks during the meeting, you have to pass the `MediaStream` in the \*\*`enableScreenShare()` method of the `meeting` object.

:::note

Make sure to call `disableScreenShare()` before you create a new track as it may lead to unexpected behavior.

:::

##### Example

```javascript
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const enableScreenShareBtn = document.getElementById("enableScreenShareBtn");
enableScreenShareBtn.addEventListener("click", async () => {
  let customShareTrack = await VideoSDK.createScreenShareVideoTrack({
    optimizationMode: "motion",
    encoderConfig: "h720p_15fps",
  });

  meeting?.enableScreenShare(customShareTrack);
});
```


---

---
title: Picture-in-Picture Mode | Video SDK
hide_title: true
hide_table_of_contents: false
description: Picture-in-picture (PiP) is a feature that is commonly used in video conferencing software. It allows you to continue your video conference while also performing other tasks on your device.
sidebar_label: Picture-in-Picture Mode
pagination_label: Picture-in-Picture Mode
keywords:
  - audio calling
  - video calling
  - real-time communication
  - collaboration
image: img/videosdklive-thumbnail.jpg
sidebar_position: 1
slug: picture-in-picture
--- 

# Picture-in-Picture Mode - Javascript

Picture-in-picture (PiP) is a commonly used feature in video conferencing software, enabling users to simultaneously engage in a video conference and perform other tasks on their device. With PiP, you can keep the video conference window open, resize it to a smaller size, and continue working on other tasks while still seeing and hearing the other participants in the conference. This feature proves beneficial when you need to take notes, send an email, or look up information during the conference.

This guide explains the steps to implement the Picture-in-Picture feature using VideoSDK.

### PiP Video

All modern day browsers support popping a video stream out from the `HTMLVideoElement`. You can achieve this either directly from the controls shown on the video element or by using the Browser API method [`requestPictureInPicture()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement/requestPictureInPicture) on the video element.




<br/>

:::important
Chrome, Edge, and Safari support this browser Web API, however, Firefox has no programmatic way of triggering PiP.
:::

### Customize Video PiP with multiple video streams

**`Step 1:`** Create a button that toggles the Picture-in-Picture (PiP) mode during the meeting. This button should invoke the `togglePipMode()` method when clicked.

```js
const togglePipBtn = document.getElementById("togglePipBtn");

togglePipBtn.addEventListener("click", () => {
  togglePipMode();
});
```

**`Step 2:`** The first step is to check if the browser supports PiP mode; if not, display a message to the user.

```js
const togglePipMode = async () => {
  //Check if browser supports PiP mode else show a message to user
  if ("pictureInPictureEnabled" in document) {
    //
  } else {
    alert("PiP is not supported by your browser");\
    return
  }
};

```

**`Step 3:`** Now, if the browser supports PiP mode, create a `Canvas` element and a `Video` element. Generate a Stream from the Canvas and play it in the video element. Request PiP mode for the video element once the metadata has been loaded.

```js
const togglePipMode = async () => {
  //Check if browser supports PiP mode else show a message to user
  if ("pictureInPictureEnabled" in document) {
    //highlight-start
    //Creating a Canvas which will render our PiP Stream
    const source = document.createElement("canvas");
    const ctx = source.getContext("2d");

    //Create a Video tag which we will popout for PiP
    const pipVideo = document.createElement("video");
    pipWindowRef.current = pipVideo;
    pipVideo.autoplay = true;

    //Creating stream from canvas which we will play
    const stream = source.captureStream();
    pipVideo.srcObject = stream;

    //Do initial Canvas Paint
    drawCanvas();

    //When Video is ready we will start PiP mode
    pipVideo.onloadedmetadata = () => {
      pipVideo.requestPictureInPicture();
    };
    await pipVideo.play();
    //highlight-end
  } else {
    alert("PiP is not supported by your browser");
  }
};
```

**`Step 4:`** The next step is to paint the canvas with the Participant Grid, which will be visible in the PiP window.

```js
const getRowCount = (length) => {
  return length > 2 ? 2 : length > 0 ? 1 : 0;
};
const getColCount = (length) => {
  return length < 2 ? 1 : length < 5 ? 2 : 3;
};

const togglePipMode = async () => {
  //Check if browser supports PiP mode else show a message to user
  if ("pictureInPictureEnabled" in document) {
    //Stream playing here
    //...

    //highlight-start
    //When the PiP mode starts, we will start drawing canvas with PiP view
    pipVideo.addEventListener("enterpictureinpicture", (event) => {
      drawCanvas();
    });

    //When PiP mode exits, we will dispose the track we created earlier
    pipVideo.addEventListener("leavepictureinpicture", (event) => {
      pipWindowRef.current = null;
      pipVideo.srcObject.getTracks().forEach((track) => track.stop());
    });

    //This will draw all the video elements in to the Canvas
    function drawCanvas() {
      //Getting all the video elements in the document
      const videos = document.querySelectorAll("video");
      try {
        //Perform initial black paint on the canvas
        ctx.fillStyle = "black";
        ctx.fillRect(0, 0, source.width, source.height);

        //Drawing the participant videos on the canvas in the grid format
        const rows = getRowCount(videos.length);
        const columns = getColCount(videos.length);
        for (let i = 0; i < rows; i++) {
          for (let j = 0; j < columns; j++) {
            if (j + i * columns <= videos.length || videos.length == 1) {
              ctx.drawImage(
                videos[j + i * columns],
                j < 1 ? 0 : source.width / (columns / j),
                i < 1 ? 0 : source.height / (rows / i),
                source.width / columns,
                source.height / rows
              );
            }
          }
        }
      } catch (error) {}

      //If pip mode is on, keep drawing the canvas when ever new frame is requested
      if (document.pictureInPictureElement === pipVideo) {
        requestAnimationFrame(drawCanvas);
      }
    }
    //highlight-end
  } else {
    alert("PiP is not supported by your browser");
  }
};
```

:::note
Only the participants who have their video turned on, will be shown in the PiP mode.
:::

**`Step 5:`** Exit the PiP mode if it is alreay active.

```js
const togglePipMode = async () => {
  //highlight-start
  //Check if PiP Window is active or not
  //If active we will turn it off
  if (pipWindowRef.current) {
    await document.exitPictureInPicture();
    pipWindowRef.current = null;
    return;
  }
  //highlight-end

  //Check if browser supports PiP mode else show a message to user
  if ("pictureInPictureEnabled" in document) {
    //highlight-next-line
    // ...
  } else {
    alert("PiP is not supported by your browser");
  }
};
```

Here is the output of the PiP implementation.




---

# Understanding Analytics Dashboard - Javascript

Welcome to the world of actionable insights and empowered decision-making. VideoSDK's session analytics dashboard is your gateway to understanding, optimizing, and elevating every aspect of your sessions.

## Accessing Analytics Made Easy

Navigating through session data is a breeze with VideoSDK. Simply head to your session page at https://app.videosdk.live/meetings/sessions, where a treasure trove of session information awaits.

### How to Access Analytics?

Open Session Analytics effortlessly by following these steps:

1. **Click on Meeting-ID:**
    - Directly access analytics by clicking on the meeting-ID within the session table.
2. **Hover and Click View Analytics:**
    - Hover over a specific meeting row to reveal the **View Analytics** button in the Actions Column.
    - Click on **View Analytics** to open the Session Overview sidebar, unlocking a wealth of insights.

![Access Analytics](https://cdn.videosdk.live/website-resources/docs-resources/access_analytics.png)

---

There are three tabs available within the session analytics view:

## **1. Session Overview**

This tab provides an overview of the session, including its duration and participant details. You can explore individual participant statistics to understand their session performance better.

## **2. Errors**

In this tab, you can find information about any errors encountered during the session. It helps you identify and address issues like network problems or technical glitches promptly.

## **3. Session Stats**

Explore data and metrics sent and received by participants to measure performance of the session in this tab. It offers insights into data exchange among participants, including metrics on jitter, RTT, and packet loss, resolutions, and fps aiding in assessing communication efficiency.

Let's dive deeper into each of these tabs to gain a better understanding of session analytics.

# Session Overview

The session overview page is your compass in the sea of data. Here's what you'll uncover:

- **Meeting ID:** Unique identifier for the meeting in the format of `abcd-efgh-ijkl`.
- **Session ID:** Unique identifier for each session, uniquely identified by its `sessionId`.
- **Session Status:** Indicates if the session is ongoing or ended.
- **Session Initiating Time:** Time taken by the first participant to establish the connection.
- **Start and End Time:** Marks the start and end of the session.
- **Total Unique Participants Joined:** Total number of unique participants in the session.
- **Total Session Duration:** Overall duration of the session from start to end.
- **Total Participant Minutes:** A sum of all participant duration.
- **Recording, HLS, RTMP:** Additional services used in the session.

### Participant Table List

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for each participant.
- **Join Time:** Time taken by the participant to establish connection.
- **Duration:** Total time spent by this participant in the session.

### Efficient Session Management with Actions

Enhance your session management with streamlined actions:

- **Kick Out Participants:** Effortlessly remove/kickout participants from ongoing sessions.
- **Detailed Participant Analytics:**
- Hover over a specific participant row to reveal the `View Stats` button at the end of the row.
- Click on `View Stats` to open the Participant Overview sidebar.

![View Stats](https://cdn.videosdk.live/website-resources/docs-resources/view_stats.png)

## Explore Participant Insights

Discover valuable participant data that provides a clear view of engagement and experience:

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for better interaction.
- **Joined At:** Indicates the precise moment when participant connects to the session.
- **Left At:** Indicates the precise moment when participant left the session.
- **Total Duration:** Total duration of participant within that session.
- **Joining Time:** Time taken by the this participant to establish the connection.
- **Location:** Approx. geographic location from where the participant joined.
- **Platform:** Specifies whether participants are using a desktop or mobile device.
- **Device Info:** Offers details regarding the participant's device.
- **OS:** Provides information about the participant's OS.
- **Browser:** Provides specifics about the participant's browser
- **SDK Version:** Indicates the version of the SDK used by participants.

### Understanding Participant Call Health

We've developed call health to offer a rapid assessment of participant performance during calls. This feature highlights the performance of audio, video, and screen sharing audio-video separately. We've utilized color theory, with green indicating good performance, orange for moderate, and red for poor performance, to enhance clarity. For detailed insights, simply hover over the bars

![Participant Call Health](https://cdn.videosdk.live/website-resources/docs-resources/participant_call_health.png)

## Participant Session Stats

Dive into Participant Session Stats for valuable insights into your session experience! With just a click on `View Session Stats` at the bottom of the page, unlock a treasure trove of data crucial for understanding audio and video experiences.

Within this section, you can observe quality metrics for the selected participant, comparing them to others. Additionally, the `Sessions Stats` covers quality stats comparison for every participant. Keep reading to explore more about Session Stats.

**Visualizing Session Performance from Both Sides**

This section provides a two-sided view of your session's metrics.

- **Left Side: Sender Participant Graph** This section displays graphs representing the metrics sent by the sender participant.. Here, you can see how the various factors impacted the data you transmitted.
- **Right Side: Receiver Participant Graph** On the right side, you'll find a dropdown menu where you can select a specific participant. Choosing a receiver will display graphs showcasing the metrics **received by that participant**. This allows you to compare the sending experience (left side) with the receiving experience (right side) for different participants.

![VideoSDK Jitter Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_jitter_graph.png)

**See How Your Session Performed**

These metrics give you a clear picture of your session's quality. Understanding them helps you spot any issues and keep things running smoothly. Let's dive into what each metric means!

**Jitter:** Imagine your internet connection like a bumpy road. Jitter is how much those bumps cause your signal to bounce around. Less jitter means a smoother ride for your data (audio and video, threshold ≤ 30ms).

**RTT (Latency):** This is how long it takes for data to travel between you and the server you're connected to. Think of it like the time it takes for a message to get delivered – a lower RTT means a faster delivery (affects both audio and video, threshold ≤ 300ms).

**Bitrate:** This measures the amount of data flowing through your connection per second. Imagine it like the width of a water pipe – a higher bitrate allows for more data to flow, which can be good for high-quality audio/video or fast downloads.

**Packet Loss:** Think of data traveling in tiny packets. Packet loss is when some of those packets get dropped along the way. More packet loss means information might be missing, affecting things like audio/video quality or lag in games (threshold ≤ 5%).

**Resolution:** This refers to the sharpness and detail of an image or video. Think of it like the number of pixels on your screen – a higher resolution means a crisper picture (**Video Only**).

**FPS (Frames Per Second):** This measures how many images (frames) are displayed on your screen every second. Imagine it like a flipbook – a higher FPS creates a smoother and more fluid animation or video experience (**Video Only**).

![VideoSDK FPS Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_fps_graph.png)

![VideoSDK Resolution Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_resolution_graph.png)

---

# **Investigate Session Errors**

Get to the root of smoother sessions by addressing errors directly. Use the Errors tab to explore details of errors encountered during your session. Note: Session errors are visible with JS SDK v0.0.82 or higher, React SDK v0.1.85 or higher, and React Native v0.1.6 or newer versions.

- **Participant Name & ID:** Quickly identify the participant associated with each error for swift resolution.
- **Error Types:** Understand the different types of errors encountered, such as network issues or connection disruptions.
- **Detailed Descriptions:** Access clear explanations of errors to take actionable steps towards solution.

![VideoSDK Error Details](https://cdn.videosdk.live/website-resources/docs-resources/error_new.png)

# **Analyse Session Stats**

Similar to `Participant Session Stats`, this tab covers quality statistics sent by individual participants. You can select any participant to compare effectively with others.

Choose a sender participant from the dropdown menu on the left and select a recipient on the right to compare data over different time frames. This allows you to identify and explore issues within specific durations.

This tab covers the same metrics as covered in the `participant session stats`: Jitter, RTT (Latency), Bitrate, Packet-loss, Resolution (Video only), and FPS (Video only).

![VideoSDK Session Stats](https://cdn.videosdk.live/website-resources/docs-resources/session_stats.png)


---

# Understanding Call Quality - Javascript

When developing a video call app, customer satisfaction heavily depends on the app's video and audio quality and its fluctuation.

## Call Quality

From the user's perspective, good video quality is defined as smooth and clear video, along with crystal clear audio. Developers consider good video quality as high-resolution, high-frame-rate video with minimal latency and high-bitrate audio with minimal audio loss.

## Factors affecting Quality

When measuring video and audio quality, several variables come into play. The common factors affecting quality are as follows:

### `1. Network Bandwidth`

- Network bandwidth is the measure of a user's network capacity, indicating how much data can be received and sent.
- If the participant's bandwidth is low, they are likely to experience pixelated or frozen video, along with robotic voice or minor audio interruptions.
- Frequent changes in network providers can also lead to significant fluctuations in internet bandwidth, resulting in poor video quality.

### `2. Latency`

- Latency refers to the time it takes for data to transfer from one machine to another.
- If the meeting is hosted in `Ohio` region, and users are joining from `Singapore` region, this can result in a long delay for data to transfer between mackines. Therefore, it is advisable to choose a server based on your user base.
- With VideoSDK, you can specify the server during the creation of a Meeting/Room.

### `3. CPU Usage`

- CPU Usage is also a determining factor, as all the audio and video streams going out and coming in need to be encoded or decoded, requiring a significant amount of computation.
- The higher the resolution and frame rate of the videos, the greater the computation required, which can lead to a bottleneck in delivering good-quality video.
- If the CPU is heavily consumed, it can also result in choppy or robotic audio.

### `4. Camera and Mic Quality`

- The camera and microphone should capture high-quality streams to ensure that remote users don't receive a low-quality stream even if they have bad network bandwidth.

## Identifying various issues related to Quality.

In order to identify potential issues, VideoSDK collects various audio and video-related metrics that can help pinpoint quality concerns. Take a look at these metrics and understand what they indicate.

### `1. Resolution and Framerate`

- Resolution and frame rate serve as crucial metrics for video quality in a video call app. Resolution indicates the number of pixels in a video image, while frame rate denotes the number of frames displayed per second.

- While higher resolutions and frame rates can enhance video quality, they also demand more bandwidth and processing power. It's essential to optimize these metrics based on the devices and network conditions of your users.

- For instance, if the majority of your users are on mobile devices, opting for a lower resolution and frame rate may be more suitable to ensure smooth playback and minimize bandwidth usage.

- If your user base comprises both mobile and desktop devices, adopting higher resolution for desktops and mid-resolutions for mobile devices can contribute to improved performance and quality while conserving bandwidth on mobile devices.

### `2. Bitrate`

- Bitrate represents the number of bits per second transmitted or received during the transmission of audio or video streams. It is a crucial parameter for assessing the quality of audio or video streams and should be adjusted for each resolution to strike a balance between performance and bandwidth utilization.

- In scenarios with excellent network conditions, a higher bitrate can lead to significantly improved video quality. However, it's essential to be cautious when dealing with very high bitrates on mobile devices, as it may result in heating issues due to the substantial computational requirements for encoding and decoding videos.

##### Example

We used the same phone **(iPhone 14)**, for both participants, but there were differences in resolution and bitrate. The first participant had a resolution of **`1280x720`** with a bitrate of **`1442 kbps`**, while the second participant had a resolution of **`960x540`** with a bitrate of **`642 kbps`**. Surprisingly, both participants' videos appeared to be of equal quality despite variations in resolution and bitrate.

![resolution-and-bitrate](/img/resolution-and-bitrate.png)

### `3. Packet Loss`

- Packet loss is a metric that reveals the number of lost data packets during transmission from the sender to the receiver. It can happen due to network congestion, hardware or software issues, or network latency. Increased packet loss can lead to degraded video and audio quality, as the absence of packets may cause gaps or distortions in the media stream.


<div style={{textAlign: 'center'}}>



</div>

### `4. Jitter`

- The audio and video packets are sent out at random intervals over a specified time frame as they travel between the server and client. Jitter occurs when there is a variation in transmitting or receiving these data packets due to a faulty network connection.

- When data packets experience delays during transmission to the participant, usually because the network is busy, they may result in pixelated video during a video call or sound choppy, distorted, or robotic in a voice call upon arrival. This creates jitter, with packets arriving at random intervals.

### `5. Round Trip Time (Latency)`

- Round trip time refers to the duration it takes for data packets to be transmitted from the user's device to the server and back. If the servers are located far from the user's location, they may experience high latency (delay).

- With VideoSDK, this factor is addressed as we automatically choose the nearest available server for participants. However, if you are geofencing to a specific region, ensure that you choose the server nearest to your users.

<center>

![resolution-and-bitrate](/img/rtt.png)

</center>

## Checking Realtime Statistics

VideoSDK provides methods to check the realtime statistics of audio and video of all the participants.

### `getVideoStats()`

- The `getVideoStats()` method returns an object containing the different quality parameters for video stream, which can be accessed through the `useParticipant` hook.

- This object will contain values for the specific participant's video stream, including resolution, frame rate, bitrate, jitter, round trip time, and packet loss.

<div style={{textAlign: 'center'}}>



</div>

### `getAudioStats()`

- The `getAudioStats()` method returns an object containing the different quality parameters for audio stream, which can be accessed through the `useParticipant` hook.

- This object will contain values for the specific participant's audio stream, including bitrate, jitter, round trip time and packet loss.

### `getShareStats()`

- The `getShareStats()` method returns an object containing the different quality parameters for screen share stream, which can be accessed through the `useParticipant` hook.

- This objects will contain values for the specific participant's screen share stream, including resolution, frame rate, bitrate, jitter, round trip time, and packet loss.

### `getShareAudioStats()`

- The `getShareAudioStats()` method returns an object containing the different quality parameters for screen share audio stream, which can be accessed through the `useParticipant` hook.

- This object will contain values for the specific participant's screen share audio stream, including bitrate, jitter, round trip time and packet loss.

:::note
To show the popup dialog for the participant's realtime stats, you can [refer to this component](https://github.com/videosdk-live/videosdk-rtc-react-sdk-example/blob/main/src/utils/common.js#L142).
:::

## Quality analysis Graphs

For all sessions conducted using VideoSDK, you can access quality analysis graphs from the [VideoSDK Dashboard](https://app.videosdk.live/meetings/sessions). These graphs help you visualize real-time data and identify spikes in certain parameters during calls, aiding in understanding the reasons for quality issues.

![quality analysis](/img/quality-analysis.png)

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [getVideoStats()](/javascript/api/sdk-reference/participant-class/methods#getvideostats)
- [getAudioStats()](/javascript/api/sdk-reference/participant-class/methods#getaudiostats)
- [getShareStats()](/javascript/api/sdk-reference/participant-class/methods#getsharestats)


---

# Run a Sample Project




---

# Scalability Guide for Large Participant Meetings

## Overview

This guide explains how to optimize performance when hosting video meetings with 10+ participants by using two key features:

1. **Player Component**: Pauses off-screen video streams to reduce bandwidth usage
2. **Adaptive Subscriptions**: Intelligently prioritizes audio/video streams based on who's speaking

These features help solve common challenges in large meetings, such as excessive bandwidth consumption and poor quality for users with network constraints.

> **Note**: These features are independent and can be used separately. You can implement Adaptive Subscriptions with your existing player setup if desired, or use the Player Component without Adaptive Subscriptions.

## Common Challenges in Large Meetings

### 1. Excessive Bandwidth Consumption

**Problem**: All video streams remain active even when not visible on screen.

**Impact**:

- Higher data usage affecting users with limited bandwidth
- Decreased performance and call quality
- Unnecessary resource utilization

### 2. Ineffective Stream Prioritization

**Problem**: All streams receive equal treatment regardless of importance.

**Impact**:

- Users with limited bandwidth experience poor quality
- Audio quality suffers when competing with video for resources
- Important speakers may not be clearly heard or seen

## Solution Features

### Player Component

The Player Component intelligently manages video streams based on viewport visibility.

**Key Benefits**:

- Automatically detects which video streams are visible on screen
- Pauses streams for participants not currently in the viewport
- Significantly reduces bandwidth usage
- Adapts stream quality to container size when using `maxQuality: "auto"`

**How It Works**:  
When a participant scrolls or changes their view, the system automatically pauses streams that aren't visible and resumes them when they come into view.

_Visual Illustration:_

<div style={{textAlign: 'center'}}>

<img src="https://cdn.videosdk.live/website-resources/docs-resources/videosdk_player_viewport.png"  alt="Viewport illustration" height="400px" />

</div>

**Quality Adaptation Example**:  
If a participant's original video is 720p but your container size is 320x180, setting `maxQuality: "auto"` will make the player consume only a 320p stream instead of the full 720p, significantly reducing bandwidth usage.

### Adaptive Subscriptions

This feature optimizes bandwidth by prioritizing active speakers and managing stream quality.

**Key Benefits**:

- Identifies and prioritizes dominant speakers
- Intelligently manages bandwidth constraints
- Ensures clear audio even under network limitations
- Gives highest priority to pinned participants

**How It Works**:  
The system analyzes speaking patterns to detect active participants and adjusts stream priorities accordingly. For bandwidth-constrained users, it strategically pauses or lowers the quality of non-essential video streams. Pinned participants always receive the highest priority in stream allocation.

_Visual Illustration:_

<div style={{textAlign: 'center'}}>

<img src="https://cdn.videosdk.live/website-resources/docs-resources/adaptive_subscriptions_priority.png" alt="Viewport illustration" height="500px"/>
</div>

If a user experiences bandwidth constraints, Adaptive Subscriptions will pause the video streams in the following priority order:

1. Muted Participants
2. Least Dominant Speakers
3. Dominant Speakers

> If you want to achieve pin/unpin functionality, you can refer to [this documentation](https://docs.videosdk.live/javascript/api/sdk-reference/participant-class/methods#pin)

## Implementation Guide

### Prerequisites

- SDK Version: 0.1.6 or later

### Enabling Adaptive Subscriptionss(BETA)

You can toggle this feature using these methods:

```javascript
// Enable adaptive subscriptions
meeting.enableAdaptiveSubscriptions();

// Disable adaptive subscriptions
meeting.disableAdaptiveSubscriptions();
```

**Recommended Implementation**:

```javascript
// Enable on meeting join
meeting.on("meeting-joined", () => {
  meeting.enableAdaptiveSubscriptions();
});
```

### Stream Pause/Resume Events

When a video stream is paused or resumed, the system triggers events with specific reasons:

```javascript
// Listen for video stream pause events
participant.on("stream-paused", ({ kind, reason }) => {
  // kind: video
  console.log(reason); // Possible values: "muted", "leastDominance"
});

// Listen for video stream resume events
participant.on("stream-resumed", ({ kind, reason }) => {
  // kind: video
  console.log(reason); // Possible values: "adaptiveSubscriptionsDisabled", "networkStable"
});
```

**Pause Reasons**:

- `muted`: Participant has turned off their audio
- `leastDominance`: Participant hasn't spoken much in the meeting

**Resume Reasons**:

- `adaptiveSubscriptionsDisabled`: Feature was disabled
- `networkStable`: Network conditions have improved

> **Developer Tip**: When a stream is paused (e.g., due to network issues), always keep users in the loop by displaying a helpful UI indicator. For instance, render a message such as:
> "Paused: Waiting for stable connection..."

### Rendering Video and Audio

#### Video Renderings(BETA)

```javascript
meeting.on("participant-joined", (participant) => {
  // Render Video
  let videoElement = participant.renderVideo({
    type: "video", // Options: "video" or "share" for screen sharing
    maxQuality: "auto", // Options: "auto", "high", "med", "low"
    videoStyle: {}, // Custom styling for video element
    containerStyle: {
      // Custom styling for container
      width: "1280px",
      height: "720px",
    },
  });

  // Attach to DOM
  document.getElementById("video-container").appendChild(videoElement);
});
```

**Important Notes on Quality Settings**:

- When using `maxQuality: "auto"`, the player automatically selects the optimal stream quality based on container dimensions
- If `multiStream` is set to false, the `maxQuality: "auto"` setting will not work
- When using `maxQuality: "auto"`, you cannot use the `participant.setQuality()` method
- To manually control quality, use specific values: `maxQuality: "high"`, `maxQuality: "med"`, or `maxQuality: "low"`

#### Audio Renderings(BETA)

```javascript
let audioElement = participant.renderAudio({
  type: "audio", // Options: "audio" or "shareAudio" for screen share audio
});
document.body.appendChild(audioElement);
```

## Best Practices

- Enable adaptive subscriptions at the start of every meeting
- Design your UI to display indicators when a stream is paused
- Pin important participants to ensure they receive the highest streaming priority
- Consider implementing pagination for very large meetings to further reduce resource usage
- For maximum bandwidth efficiency:
  - Use container-appropriate sizes that match your layout needs
  - Enable multiStream for the auto-quality feature to work
  - Design your UI to show fewer high-quality streams rather than many low-quality ones


---

# End-to-End Encryption (E2EE) - Javascript

## Overview

End-to-end encryption (E2EE) ensures that your media content remains private and secure by encrypting it on the sender's device and decrypting it only on the receiver's device. This prevents intermediaries, including VideoSDK servers, from accessing or modifying the content.

E2EE is particularly important for applications in security-critical domains such as telehealth, finance, and legal services.

### How E2EE Works

- E2EE is applied at the room level, where a single shared key encrypts and decrypts all media tracks during a session.

- Participants without the key cannot access the media.

- The entire encryption process is handled client-side. VideoSDK does not access or store any encryption keys.

### Key Management & Distribution

You are **fully responsible** for generating, managing, and securely distributing encryption keys to all participants. VideoSDK **never stores, accesses, or transfers** your encryption keys.

- Common Key Distribution Approaches:

- Generate the key **on your server** when creating a meeting.

- Send the key securely along with the **meeting access token**.

- Use **HTTPS-secured API calls** to fetch the key on the client.

:::important

⚠️ Ensure that all participants have access to the correct encryption key before joining the room.

:::

The table below shows the minimum SDK versions that support E2EE. All subsequent versions also include E2EE support.

| React Native | iOS   | Flutter | React | Android     | JavaScript |
| ------------ | ----- | ------- | ----- | ----------- | ---------- |
| 0.2.1        | 2.2.2 | 2.1.0   | 0.3.5 | 0.5.0 | 0.2.6      |

### Enabling E2EE in VideoSDK Javascript

To enable E2EE in VideoSDK for Javascript, follow these steps:

```js
const keyProvider = new ExternalE2EEKeyProvider();
keyProvider.setSharedKey("<Secret_Key>");

// Setting key before initalizing meeting
// If you set key before initalize then e2ee will automatically enabled.
VideoSDK.setKeyProvider(keyProvider);

meeting = window.VideoSDK.initMeeting({
  meetingId: "pbow-6vec-vahn" || meetingId, // required
  micEnabled: true,
  webcamEnabled: true,
});
```

### Additional Configuration Options

You can customize the encryption behavior by passing parameters while creating the BaseKeyProvider instance:

| Parameter                         | Type   | Description                                                                                                 |
| --------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| `discardFrameWhenCryptorNotReady` | `bool` | If `true`, frames will be discarded when the cryptor is not ready, ensuring no unencrypted content is sent. |

### Event for E2EE State Changes

To monitor encryption state changes for each participant's media stream:

```js
participant.on("e2ee-state-change", (data) => {
  console.log("Media Kind ", data.kind);
  console.log("State changed to ", data.state);
});
```

The possible values for `state` are:

| State             | Description                               |
| ----------------- | ----------------------------------------- |
| EncryptionSuccess | Media encryption is successfully applied. |
| DecryptionSuccess | Incoming media is successfully decrypted. |
| EncryptionFailed  | Encryption encountered an error.          |
| DecryptionFailed  | Decryption encountered an error.          |
| InternalError     | Internal processing error occurred.       |
| MissingKey        | When key is missing.                      |
| InvalidKey        | Invalid key is passed.                    |

### To Check Whether E2EE enable not

You can check whether E2EE is enabled by using `e2eeEnabled` property of `Meeting` class.

```js
console.log("isE2EEEnabled ", meeting.isE2EEEnabled);
```

### Limitations

E2EE only applies to media. It does not apply to:

- Chat messages or metadata

- API calls and signaling data

These communications are still protected by TLS but are not encrypted end-to-end.

:::info
Recording and transcription features are not supported when End-to-End Encryption (E2EE) is enabled.
:::


---

<h1> {props.title} </h1>{" "}

### Why we are using JWT based Token ?

Token based authentication allows users to verify their identity by providing generated API key and secret.

We use JWT token for the authentication purpose because Token-based authentication is **widely used** in modern web applications and APIs because it offers several benefits over traditional authentication. For example, it can **reduce the risk of the credentials being misused**, and it allows for **more fine-grained control** over access to resources. Additionally, tokens can be easily revoked or expired, making it easier to manage access rights.

### How to generate Token ?

To manage secured communication, every participant that connects to the meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key` which you can get from [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

#### 1. Generating token from Dashboard

If you are looking to do **testing or for development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for getting token includes generating it from your backend server which will help in **keeping your credentials safe**.
:::

#### 2. Generating token in your backend

- Your server will generate access token using your API key and secret.
  - While generating a token, you can provide **expiration time, permissions and roles** which are discussed later in this section.
- Your client obtains token from your backend server.
- For token validation, client will pass this token to VideoSDK server.
- VideoSDK server will only allow entry in the meeting if the token is valid.

![img2.png](../../static/img/authentication-and-token.png)




Follow our official example repositories to setup token API [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)

### Payload while generating token

```js
{
 apikey: API_KEY, //MANDATORY
 permissions: [`allow_join`], //`ask_join` || `allow_mod` //MANDATORY
 version: 2, //OPTIONAL
 roomId: ROOM_ID, //OPTIONAL,
 participantId: PARTICIPANT_ID, //OPTIONAL
 roles: ['crawler', 'rtc'], //OPTIONAL
}
```

- **`apikey`(Mandatory)**: This must be the API Key generated from the VideoSDK Dashboard. You can get it from [here](https://app.videosdk.live/api-keys).

- **`permissions`(Mandatory)**: By providing the permissions, you can control what a participant can do in the meeting and whether he can join the meeting directly.

  Available permissions are:

  - **`allow_join`**: The participant is **allowed to join** the meeting directly.
  - **`ask_join`**: The participant is required to **ask for permission to join** the meeting. The participant having the permission `allow_join` can accept or reject a participant whenever someone wants to join.
  - **`allow_mod`**: The participant is **allowed to toggle** webcam & mic of other participants.

- **`version`(optional)**: For accessing the [v2 API](/api-reference/realtime-communication/intro), you need to provide `2` as the version value.

  - For passing `roomId`, `participantId` or `roles` parameters in payload, it is essential to set the version value to `2`.

- **`roomId`(optional)**: To provide customised access control, you can make the token applicable to a particular room by including the `roomId` in the payload.

- **`participantId`(optional)**: You can include the `participantId` in the payload to limit the token's access to a particular participant.

- **`roles`(optional)**:

  - **`crawler`**: This role is only for accessing [v2 API](/api-reference/realtime-communication/intro), you can not use this token for running the `Meeting`/`Room`.
  - **`rtc`**: This role is only allowed for running the `Meeting` / `Room`, with this role you can not use [server-side APIs](/api-reference/realtime-communication/intro).

Then, you have to sign this payload with your **`SECRET KEY`** and `jwt` options using the **`HS256 algorithm`**.

### Expiration time

You can set any expiration time to the token. But in the **production environment**, it is recommended to generate a token with **short expiration time** because by any chance if someone gets hold of the token, it won't be valid for a longer period of time.

### What happens if token is expired?

If your token is expired, the user won't be able to join the meeting and all the API calls will give error with message `Token is invalid or expired`.

:::note
Token is validated only once while joining the meeting, so if a person joins the meeting and the token gets expired after that, there won't be any issue in the current meeting.
:::

## How to check validity of token?

1. After generating the token, visit [jwt.io](https://jwt.io) and paste your token in the given area.
2. You will be able to see the payload you passed while generating the token and also be able to see the expiration time and token creation time.

![img1.png](../../static/img/validate-token.png)

## API Settings & Controls

The VideoSDK Dashboard provides a powerful [API Settings](https://app.videosdk.live/api-keys) section where you can configure various services and controls for your meetings. These settings allow you to customize the behavior of different features directly from the dashboard without requiring code changes.

## Audio/Video Configurations

:::note
Runtime configuration from the dashboard has higher precedence than static SDK configurations.
If a value is modified in the dashboard, it will override any previously defined SDK settings for that session.

Example:
Code: Video = HD → Dashboard: Video = Full HD → Applied: Full HD
:::

### Maximum Send Bitrate Per Participant

Control the maximum total upload bandwidth for all media streams from a single participant.

![Maximum Send Bitrate](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.00.11%E2%80%AFPM.png)

**Available Options:**
- **Auto**: Removes the upload bitrate limit (recommended for best quality)
- **SD (800kbps)**: Standard definition bitrate
- **HD (1500kbps)**: High definition bitrate
- **Full HD (3000kbps)**: Full high definition bitrate

:::tip
Setting this to **Auto** provides the best video quality as it removes upload bitrate constraints, allowing adaptive streaming based on network conditions.
:::

## Recording & Streaming Configuration

:::note
Recording and HLS follow a precedence-based configuration model:

API/SDK configuration → Highest priority
Dashboard configuration → Used only when no API values are defined

Any parameters explicitly set via the API will not be overridden by dashboard changes.
:::

### Recording Configuration

Configure recording settings for your meetings including layout, quality, and auto-start options.

![Recording Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.01.00%E2%80%AFPM.png)

**Recording Controls:**
- **Enabled**: Toggle to enable/disable recording functionality
- **Enabled Modes**: Choose between Video & Audio or Audio Only recording
- **Start Recording Automatically**: Auto-start recording when meeting begins
- **Layout Style**: Select Grid layout for recording composition
- **Maximum Tiles In Grid**: Set the number of participants visible in grid (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme for recordings
- **Video Orientation**: Choose between Landscape or Portrait mode
- **Recording Quality**: Select quality level (e.g., HD Medium)
- **Recording Mode**: Choose between Video & Audio or Audio Only

### HLS Streaming Configuration

Configure HTTP Live Streaming (HLS) settings for broadcasting your meetings.

![HLS Streaming Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.02.18%E2%80%AFPM.png)

**HLS Streaming Controls:**
- **Enabled**: Toggle to enable/disable HLS streaming
- **Enabled Modes**: Choose between Video & Audio or Audio Only streaming
- **Auto Start HLS**: Automatically start HLS when meeting begins
- **Record HLS Stream**: Enable recording of the HLS stream
- **Layout Style**: Select Grid layout for stream composition
- **Maximum Tiles In Grid**: Set the number of participants visible (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme
- **HLS Orientation**: Choose between Landscape or Portrait mode
- **HLS Quality**: Select streaming quality (e.g., HD Medium)
- **HLS Streaming Mode**: Choose between Video & Audio or Audio Only

### Additional Service Controls

Enable or disable additional services for your API key.

![Service Controls](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.08%E2%80%AFPM.png)

**Available Services:**
- **RTMP Output**: Enable RTMP streaming to external platforms
- **SIP Integration**: Enable SIP (Session Initiation Protocol) integration for telephony
- **Realtime Translation**: Enable real-time language translation in meetings

### Transcription & Summary

Configure transcription and domain whitelisting for your API key.

![Transcription Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.50%E2%80%AFPM.png)

**Transcription Controls:**
- **Enabled**: Toggle to enable/disable transcription and summary features
- **Whitelist Domain**: Add domain restrictions for API key usage
  - Enter domain names in the format `https://domain.name`
  - Click "Add Domain" to whitelist specific domains
  - Only whitelisted domains can use this API key
  - When no domains are whitelisted, the API key can be used from any domain


---

# Initialise Meeting - Javascript

To configure a VideoSDK meeting you require two things, first the `token` which will be used for **Authentication** purpose and a `meetingId` which will be used to specify where a participant will join. Examine each of the steps closely.

### Generating Token

You can generate a `token` in two ways:

1. **`Temporary Token`** : You can visit [Dashboard's API Key section](https://app.videosdk.live/api-keys) and generate a temporary token from there.

2. **`Server`** : You can setup **JWT** in backend and make an API call to get the token from your server.

To learn more about **Authentication** and token in detail you can follow [this guide](../authentication-and-token).

```js
// With Temporary Token
const getToken = async () => {
  // Update the token here from the VideoSDK dashboard
  // highlight-next-line
  let token = "YOUR_TOKEN";
};

// Server
const getToken = async () => {
  // highlight-start
  const response = await fetch(`http://localhost:3000/get-token`, {
    method: "GET",
    headers: {
      Accept: "application/json",
      "Content-Type": "application/json",
    },
  });
  const { token } = await response.json();
  // highlight-end
  return token;
};
```

### Generating Meeting Id

With the token ready, you can now get the `meetingId` from the [VideoSDK's rooms API](/api-reference/realtime-communication/create-room).

```js
const getMeetingId = async (token) => {
  try {
    //Use VideoSDK rooms API endpoint to create a meetingId
    //highlight-next-line
    const VIDEOSDK_API_ENDPOINT = `https://api.videosdk.live/v2/rooms`;
    const options = {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        // Pass the token in the headers
        // highlight-next-line
        Authorization: token,
      },
    };
    const meetingId = await fetch(VIDEOSDK_API_ENDPOINT, options)
      .then(async (result) => {
        const { roomId } = await result.json();
        return roomId;
      })
      .catch((error) => console.log("error", error));

    //Return the meetingId which we got from the response of the api
    //highlight-next-line
    return meetingId;
  } catch (e) {
    console.log(e);
  }
};
```

### Initialization of Meeting

You can initialize the meeting using the `initMeeting` method of the `VideoSDK` class. The `initMeeting` is responsible for initializing the meeting with the provided configuration, which includes the `meetingId`, `participantId` and many more.

:::tip
When conducting one-to-one meetings, it is recommended to set `multistream:false`.For more information on multistream, refer to the [multistream documentation](/javascript/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track#what-is-multistream).
:::

Take a deeper look at the available configuration options first.

```js
VideoSDK.config(token);

const meeting = VideoSDK.initMeeting({
  meetingId: "<Id-of-meeting>",
  name: "<Name-of-participant>",
  micEnabled: "<Flag-to-enable-mic>",
  webcamEnabled: "<Flag-to-enable-webcam>",
  participantId: "Id-of-participant", // optional, default: SDK will generate
  multistream: true,
});
```

- **`meetingId`** :

  - This is a unique identifier that allows participants to join a specific meeting or room.
  - It will be in the format of `xxx-yyy-zzz` and will be generated using the [VideoSDK's Room API](/api-reference/realtime-communication/create-room).

- **`name`**:

  - This represents the name of the participant in the meeting.
  - It will accept `String` type value.

- **`micEnabled`**:

  - This is a `boolean` flag, indicating whether a participant's microphone will be automatically enabled when they join a meeting.

- **`webcamEnabled`**:

  - This is a `boolean` flag, indicating whether a participant's webcam will be automatically enabled when they join a meeting.

- **`metaData`**:

  - If you want to provide additional details about a user joining a meeting, such as their profile image, you can pass that information in this parameter.
  - It has to be of `Object` type.
  - This is an `OPTIONAL` parameter.

- **`participantId`**:

  - This is a unique identifier for the participant's inside the meeting.

    - It can be used to specify the **unique identifier** which can be linked with **your own database** service.
    - It has to be of `String` type.
    - This is an `OPTIONAL` parameter. By default VideoSDK will generate unique id for each participant.

- **`multistream`**:

  - This is a `boolean` flag, indicating whether the stream should send multiple resolution layers or a single resolution layer.

- **`debugMode`**

  - This is a `boolean` flag that determines whether the user can view detailed error logs directly on the VideoSDK's dashboard.

    - This is an `OPTIONAL` parameter. By default, the user is enabled to view detailed error logs on the VideoSDK's dashboard.

:::caution
You must ensure that the `participantId` is not repeated in the same meeting or room. This will enable VideoSDK to eliminate any participant associated with that `participantId`.
:::

To know more about other properties, you can follow [our API Reference](/javascript/api/sdk-reference/initMeeting).

```js

let meeting;

const getToken = async () => {
  //highlight-next-line
  ...
};

const getMeetingId = async (token) => {
  //highlight-next-line
  ...
};

async function startMeeting() {
  const token = await getToken();
  const meetingId = await getMeetingId(token);

  // Configure authentication token
  VideoSDK.config(token);

  // Initialise meeting
  meeting = VideoSDK.initMeeting({
    meetingId: meetingId,
    name: "YOUR_NAME",
    micEnabled: true,
    webcamEnabled: true,
  });
}
```

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Meeting Class](/javascript/api/sdk-reference/meeting-class/introduction)


---

# Join Meeting - Javascript

## Overview

Before joining the meeting, it has to be initialized. If you have not initialized a meeting yet, you can [follow the guide here.](./initialise-meeting)

### `join()`

- To join a meeting you can call the `join()` method on the created `meeting` object.
- This method can be invoked after the meeting is initialized using the `initMeeting` method.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const joinBtn = document.getElementById("joinBtn");

joinBtn.addEventListener("click", () => {
  // Joining Meeting
  meeting?.join();
});
```

### Events associated with Join

Following events are received when a participant successfully joins a meeting.

- The [Local Participant](../concept-and-architecture#2-participant) will receive the [`meeting-joined`](/javascript/api/sdk-reference/meeting-class/events#meeting-joined) event, when the meeting is successfully joined.
- The [Remote Participant](../concept-and-architecture#2-participant) will receive the [`participant-joined`](/javascript/api/sdk-reference/meeting-class/events#participant-joined) event with the newly joined `Participant` object.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

meeting.on("meeting-joined", () => {
  console.log("Meeting Joined Successfully");
});

meeting.on("participant-joined", (participant) => {
  console.log("New Participant Joined: ", participant.id);
});
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [join()](/javascript/api/sdk-reference/meeting-class/methods#join)
- [meeting-joined event](/javascript/api/sdk-reference/meeting-class/events#meeting-joined)
- [participant-joined event](/javascript/api/sdk-reference/meeting-class/events#participant-joined)


---

# Leave or End Meeting - Javascript

A participant can choose to leave a meeting without removing all the other participants. This is typically done using the `Leave Meeting` functionality.

Alternatively, if the participant is the host or the last person remaining in the session, they can choose to `End Meeting` by removing all other participants, which will end the session for everyone.

### `leave()`

To leave the meeting without removing all the participants, you need to call the `leave()` method which is a part of the `meeting` object.

### `end()`

To end the meeting by removing all the participant you need to call the `end()` method which is a part of the `meeting` object.

:::note
These methods can be called only after the meeting is joined successfully.
:::

#### Example

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

const leaveBtn = document.getElementById("leaveBtn");

leaveBtn.addEventListener("click", () => {
  // Leave Meeting
  meeting?.leave();

  // Exit Meeting
  meeting?.end();
});
```

:::tip
You should call the `leave()` method on the unmount of your main meeting component so that meeting is left once the view is unmounted.
:::

### Events associated with the leave() method.

Following callbacks are received when a participant leaves the meeting.

- The [Local Participant](../concept-and-architecture#2-participant) will receive a [`meeting-left`](/javascript/api/sdk-reference/meeting-class/events#meeting-left) event.
- All [Remote Participants](../concept-and-architecture#2-participant) will receive a [`participant-left`](/javascript/api/sdk-reference/meeting-class/events#participant-left) event.

### Events associated with the end() method.

Following callbacks are received when a participant ends the meeting.

- All [remote participants](../concept-and-architecture#2-participant) and the [local participant](../concept-and-architecture#2-participant) will receive a callback on [`meeting-left`](/javascript/api/sdk-reference/meeting-class/events#meeting-left) event.

```js
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

meeting.on("meeting-left", () => {
  //Meeting Left
});

meeting.on("participant-left", (participant) => {
  //Participant Left the meeting
});
```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [leave()](/javascript/api/sdk-reference/meeting-class/methods#leave)
- [end()](/javascript/api/sdk-reference/meeting-class/methods#end)
- [meeting-left event](/javascript/api/sdk-reference/meeting-class/events#meeting-left)
- [participant-left event](/javascript/api/sdk-reference/meeting-class/events#participant-left)


---

# Meeting Connection State Events - Javascript

## Overview

The VideoSDK provides a feature to monitor the connection state of a meeting through the `meeting-state-changed` event. This event is triggered whenever the state of the meeting changes, allowing developers to handle different connection states appropriately.

### Event: `meeting-state-changed`

### Description

The `meeting-state-changed` event is fired when the connection state of the meeting changes. The event callback provides the current state of the meeting, which can be one of the following:

- **CONNECTING**
- **CONNECTED**
- **RECONNECTING**
- **DISCONNECTED**


### Meeting States and Their Triggers

1. **CONNECTING**

- This state indicates that the SDK has sent a request to the VideoSDK server to join a meeting using the provided meetingId.
- Typically, you might show a “Connecting…” screen to the end user during this phase.

2. **CONNECTED**

- Signifies that the WebSocket and, if applicable, the media channels have successfully connected.
- In SIGNALLING_ONLY and RECV_ONLY modes, this event triggers after the WebSocket connection is established since those modes do not rely on full media channels.

3. **RECONNECTING**

- Occurs if the network connection is lost or temporarily unstable. The SDK automatically attempts to rejoin the meeting.
- Useful for displaying a “Reconnecting…” status to the user, letting them know the system is attempting to recover the session.

4. **DISCONNECTED**

- Indicates that the WebSocket connection has closed and the meeting is effectively ended for this participant.
- This can happen if the user or the application explicitly leaves the meeting, or due to a critical error like a complete network drop.

### Subscription

The `meeting-state-changed` event can be subscribed to using the `meeting` object.

### Code Snippet

```javascript
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // Configuration options
});

// Subscribe to the meeting-state-changed event
meeting.on("meeting-state-changed", (data) => {
  const { state } = data;

  switch(state){
    case 'CONNECTING':
      console.log("Meeting is Connecting");
      break;
    case 'CONNECTED':
      console.log("Meeting is Connected");
      break;
    case 'DISCONNECTED':
      console.log("Meeting connection disconnected abruptly");
      break;
    case 'RECONNECTING':
      console.log("Meeting is Reconnecting");
      break;
    default:
      console.log("Unknown state:", state);
      break;
  }
});
```

### Notes

- Ensure that the `meeting` object is properly initialized before subscribing to the event.
- The `meeting-state-changed` event is crucial for monitoring the health of the meeting connection and providing feedback to the user.



---

# Precall Setup - Javascript

Picture this: before diving into the depths of a video call, imagine giving your setup a quick check-up, like a tech-savvy doctor ensuring all systems are a go. That's essentially what a precall experience does- it’s like your extensive debug session before the main code execution—a crucial step in ensuring your app's performance is top-notch.

## **Why is it necessary?**

Why invest time and effort into crafting a precall experience, you wonder? Well, picture this scenario: your users eagerly join a video call, only to encounter a myriad of technical difficulties—muted microphones, pixelated cameras, and laggy connections. Not exactly the smooth user experience you had in mind, right?

By integrating a robust precall process into your app, developers become the unsung heroes, preemptively addressing potential pitfalls and ensuring that users step into their video calls with confidence.

## **Step-by-Step Guide: Integrating Precall Feature**

### **Step 1: Check Permissions**

- Begin by ensuring that your application has the necessary permissions to access user devices such as cameras, microphones, and speakers.
- Utilize the `checkPermissions()` method of the `VideoSDK` class to verify if permissions are granted.

```js
const checkMediaPermission = async () => {
  //These methods return a Promise that resolve to a Map<string, boolean> object.
  const checkAudioPermission = await VideoSDK.checkPermissions("audio"); //For getting audio permission
  const checkVideoPermission = await VideoSDK.checkPermissions("video"); //For getting video permission
  const checkAudioVideoPermission = await VideoSDK.checkPermissions(
    "audio_video"
  ); //For getting both audio and video permissions
  // Output: Map object for both audio and video permission:
  /*
        Map(2)
        0 : {"audio" => true}
            key: "audio"
            value: true
        1 : {"video" => true}
            key: "video"
            value: true
    */
};
```

- When microphone and camera permissions are blocked, rendering device lists is not possible:




### **Step 2: Request Permissions (if necessary)**

- If permissions are not granted, use the `requestPermission()` method of the `VideoSDK` class to prompt users to grant access to their devices.

:::note

In case permissions are blocked by the user, the browser's permission request dialogue cannot be re-rendered programmatically. In such cases, consider providing guidance to users on manually adjusting their browser settings.

:::

```js
const requestAudioVideoPermission = async () => {
  try {
    //These methods return a Promise that resolve to a Map<string, boolean> object.
    const requestAudioPermission = await VideoSDK.requestPermission("audio"); //For Requesting Audio Permission
    const requestVideoPermission = await VideoSDK.requestPermission("video"); //For Requesting Video Permission
    const requestAudioVideoPermission = await VideoSDK.requestPermission(
      "audio_video"
    ); //For Requesting Audio and Video Permissions
  } catch (ex) {
    console.log("Error in requestPermission ", ex);
  }
};
```

- Requesting permissions if not already granted:

![Request Permissions](https://cdn.videosdk.live/website-resources/docs-resources/precall_requesting_permissions.png)

### **Step 3: Render Device List**

- Once you have the necessary permissions, Fetch and render list of available camera, microphone, and speaker devices using the `getCameras()`, `getMicrophones()`, and `getPlaybackDevices()` methods of the `VideoSDK` class respectively.
- Enable users to select their preferred devices from these lists.

```js
const getMediaDevices = async () => {
  try {
    //Method to get all available webcams.
    //It returns a Promise that is resolved with an array of CameraDeviceInfo objects describing the video input devices.
    let webcams = await VideoSDK.getCameras();
    //Method to get all available Microphones.
    //It returns a Promise that is resolved with an array of MicrophoneDeviceInfo objects describing the audio input devices.
    let mics = await VideoSDK.getMicrophones();
    //Method to get all available speakers.
    //It returns a Promise that is resolved with an array of PlaybackDeviceInfo objects describing the playback devices.
    let speakers = await VideoSDK.getPlaybackDevices();
  } catch (err) {
    console.log("Error in getting audio or video devices", err);
  }
};
```

- Displaying device lists once permissions are granted:



### **Step 4: Handle Device Changes**

- Implement the `device-changed` event of the `VideoSDK` class to dynamically re-render device lists whenever new devices are attached or removed from the system.
- Ensure that users can seamlessly interact with newly connected devices without disruptions.

```js
//Fetch camera, mic and speaker devices again using this function.
const deviceChangeEventListener = async (devices) => {
  //
  console.log("Device Changed", devices);
};

VideoSDK.on("device-changed", deviceChangeEventListener);
```

- Dynamically updating device lists when new devices are connected or disconnected:



### **Step 5: Create Media Tracks**

- Upon user selection of devices, create media tracks for the selected microphone and camera using the `createMicrophoneAudioTrack()` and `createCameraVideoTrack()` methods of the `VideoSDK` class.
- Ensure that these tracks originate from the user-selected devices for accurate testing.

```js
//For Getting Audio Tracks
const getMediaTracks = async () => {
  try {
    //Returns a MediaStream object, containing the Audio Stream from the selected Mic Device.
    const customAudioStream = await VideoSDK.createMicrophoneAudioTrack({
      // Here, selectedMicId should be the microphone id of the device selected by the user.
      microphoneId: selectedMicId,
    });
    //To retrive audio tracks that will be displayed to the user from the stream.
    const audioTracks = stream?.getAudioTracks();
    const audioTrack = audioTracks.length ? audioTracks[0] : null;
  } catch (error) {
    console.log("Error in getting Audio Track", error);
  }

  //For Getting Video Tracks
  try {
    //Returns a MediaStream object, containing the Video Stream from the selected Webcam Device.
    const customVideoStream = await VideoSDK.createCameraVideoTrack({
      // Here, selectedWebcamId should be the webcam id of the device selected by the user.
      cameraId: selectedWebcamId,
      encoderConfig: encoderConfig ? encoderConfig : "h540p_w960p",
      optimizationMode: "motion",
      multiStream: false,
    });
    //To retrive video tracks that will be displayed to the user from the stream.
    const videoTracks = stream?.getVideoTracks();
    const videoTrack = videoTracks.length ? videoTracks[0] : null;
  } catch (error) {
    console.log("Error in getting Video Track", error);
  }
};
```

- Rendering Media Tracks when necessary permissions are available:

![Media Tracks](https://cdn.videosdk.live/website-resources/docs-resources/precall_render_media_tracks.png)

### **Step 6: Testing Microphone**

- The process of testing microphone device provides valuable insights into microphone quality and ensures users can optimize their audio setup for clear communication.
- To facilitate this functionality, incorporate a recording feature that enables users to capture audio for a specified duration. After recording, users can playback the audio to evaluate microphone performance accurately.
- For implementing this functionality, you can refer to the official guide of [MediaRecorder](https://developer.mozilla.org/en-US/docs/Web/API/MediaRecorder) for comprehensive instructions and best practices.



### **Step 7: Testing Speakers**

- Testing the speaker device allows users to assess audio playback clarity and fidelity, enabling them to fine-tune settings for optimal sound quality in calls and meetings.
- To facilitate effective speaker testing, integrate sound playback functionality into your application.
- This functionality empowers users to play a predefined audio sample, providing a precise evaluation of their speaker output quality.

```js
const testSpeakers = () => {
  //Here, you have to path of your desired test sound.
  const test_sound_path = "test_sound_path";
  //Create an audio tag using a test sound of your choice.
  const audio = new Audio(test_sound_path);
  try {
    //Set the sinkId of the audio to the speaker's device Id, as selected by the user.
    audio.setSinkId(selectedSpeakerDeviceId).then(() => {
      audio.play();
    });
  } catch (error) {
    console.log(error);
  }
};
```



### **Step 8: Network Quality Assessment**

:::important

The `getNetworkStats()` method has been deprecated in javascript version 0.3.6

:::

- Utilize the `getNetworkStats()` method of the `VideoSDK` class to provide users with insights into their network upload and download speeds.
- Handle potential errors gracefully, such as offline status or poor connection, to maintain a smooth user experience.

```js
const getNetworkStatistics = async () => {
  try {
    //The timeOutDuration is a set time, after which the method stops fetching stats and throws a timeout error.
    const options = { timeoutDuration: 45000 };
    //This method returns a Promise that resolves with an object, containing network speed statistics or rejects with an error message.
    const networkStats = await VideoSDK.getNetworkStats(options);
    const downloadSpeed = networkStats["downloadSpeed"];
    const uploadSpeed = networkStats["uploadSpeed"];
  } catch (ex) {
    console.log("Error in networkStats: ", ex);
  }
};
```

- Displaying the Upload and Download speeds of the network:

![Network Stats](https://cdn.videosdk.live/website-resources/docs-resources/precall_network_stats.png)

- Error Handling when user is offline:

![Offline](https://cdn.videosdk.live/website-resources/docs-resources/precall_networ_stats_offline.png)

### **Step 9: Ensuring Correct Device Selection in the Meeting**

- Ensure that all relevant states, such as microphone and camera status (on/off), and selected devices, are passed into the meeting from the precall screen.
- This can be accomplished by passing these crucial states and media streams during the initialization of the meeting using the `initMeeting` method of the `VideoSDK` class.
- This ensures consistency and allows users to seamlessly transition from the precall setup to the actual meeting while retaining their chosen settings.

```js
const meeting = VideoSDK.initMeeting({
    ...
    //Status of Mircophone Device as selected by the user (On/Off).
    micEnabled: micEnable,
    //Status of Webcam Device as selected by the user (On/Off).
    webcamEnabled: webCamEnable,
    //customVideoStream has to be the Video Stream of the user's selected Webcam device as created in Step-5.
    customCameraVideoTrack: customVideoStream,
    //customAudioStream has to be the Audio Stream of the user's selected Microphone device as created in Step-5.
    customMicrophoneAudioTrack: customAudioStream,
});
```

By following these step-by-step instructions, you can seamlessly integrate a precall feature into your application, empowering users to optimize their audio and video setup for a superior communication experience.

:::note

You can explore the complete implementation of the Precall feature in the official JavaScript SDK example [available here.](https://github.com/videosdk-live/videosdk-rtc-javascript-sdk-example/tree/main)

:::

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [VideoSDK class](/javascript/api/sdk-reference/videosdk-class/introduction)
- [createMicrophoneAudioTrack()](/javascript/api/sdk-reference/custom-track/custom-audio-track#creating-a-custom-audio-track)
- [createCameraVideoTrack()](/javascript/api/sdk-reference/custom-track/custom-video-track#creating-a-custom-video-track)


---

# Waiting Lobby - Javascript

## Overview

With our Javascript SDK, you can implement a waiting lobby feature, which allows the host to control which participants can join the meeting by allowing or denying access. Here are the steps for implementing the waiting lobby.

## Generating Tokens in Your Backend

Your server should generate access tokens using your API key and secret. Two different tokens need to be generated with different permissions:

### HOST Token Payload

```js
{
  // ...
  apikey: API_KEY, // Your API key
  permissions: ['allow_join'], // Permission to directly join the meeting
  // ...
}
```

### GUEST Token Payload

```js
{
  // ...
  apikey: API_KEY, // Your API key
  permissions: ['ask_join'], // Permission to ask the host for permission to join the meeting
  // ...
}
```

Explanation of parameters:

- **`apikey` (Mandatory)**: Your API key generated from the VideoSDK Dashboard, which can be obtained [here](https://app.videosdk.live/api-keys).

- **`permissions` (Mandatory)**: Permissions that control participant activity. Available permissions include:

  - **`allow_join`**: Participants are allowed to join the meeting directly.
  - **`ask_join`**: Participants need to ask for permission to join the meeting. Participants with the `allow_join` permission can accept or reject others' join requests.
  - **`allow_mod`**: Participants are allowed to toggle webcam and mic of other participants.

Then, sign this payload with your `SECRET KEY` and use the `HS256 algorithm`. For more details on authentication and tokens, refer to [this guide](../authentication-and-token).

## Generating Meeting Id

With the tokens ready, you can obtain the `meetingId` from the VideoSDK's rooms API, which can be found [here](/api-reference/realtime-communication/create-room).

Refer to [this guide](/javascript/guide/video-and-audio-calling-api-sdk/setup-call/initialise-meeting#generating-meeting-id) for generating the meetingId.

## Initialization of Meeting

Initialize the meeting using the `initMeeting` method of the `VideoSDK` class. The `initMeeting` is responsible for setting up the meeting with the provided configuration, including the `meetingId`, `participantId`, and more.

For detailed configuration options, check [here](/javascript/guide/video-and-audio-calling-api-sdk/setup-call/initialise-meeting#initialization-of-meeting).

```js
// If a participant joins as a host, provide them with the "allow_join" permission token.
// Otherwise, provide the "ask_join" permission token.
VideoSDK.config(
  isHost ? "allow_join token will be here" : "ask_join token will be here"
);

const meeting = VideoSDK.initMeeting({
  meetingId: "

</div>

<br/>

## API Reference

Here are the API references for all the methods and events used in this guide:

- [MeetingClass](/javascript/api/sdk-reference/meeting-class/introduction)
- [join()](/javascript/api/sdk-reference/meeting-class/methods#join)
- [onentryrequested()](/javascript/api/sdk-reference/meeting-class/events#entry-requested)
- [onentryresponded()](/javascript/api/sdk-reference/meeting-class/events#entry-responded)

:::tip
You can find a complete [quick start example for the waiting lobby here](https://github.com/videosdk-live/quickstart/tree/main/js-waiting-lobby-rtc).
:::


---

### Generate Token

To manage secured communication, every participant that connects to a meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key`, which you can obtain from the [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

**For development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for obtaining a token involves generating it from your backend server which will help in **keeping your credentials safe**.
:::



---

SIP Connect allows you to connect any SIP-compatible device or softphone to a VideoSDK room. This guide explains how to configure SIP for your VideoSDK account and connect a SIP user to an existing meeting.

## Architecture

The following diagram illustrates how SIP Connect works. A SIP user connects to the VideoSDK SIP Gateway, which then bridges the call to the VideoSDK Room.

![VideoSDK Telephony Workflow](https://strapi.videosdk.live/uploads/SIP_CONNECT_c81702f580.png)

## Steps

In this guide, we are using Twilio as the SIP provider, but you can choose from other providers like Plivo, Exotel, Telnyx, Ozontel, etc. The configuration process is similar across most providers.

### 1. Create VideoSDK Meeting


:::note
Ensure you have a VideoSDK meeting setup. If you don't have one, follow the <a href={props.quickStartLink}>Quick Start Guide</a> to create a basic video calling app.
:::

You can connect a SIP user to any active VideoSDK meeting. If you already have a meeting ID, you can proceed to the next step.



### 2. Create Inbound Gateway


An **Inbound Gateway** is required to receive calls from a SIP provider (like Twilio, Vonage, Telnyx) and route them to VideoSDK.

**twilio:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/inbound-gateways).
2. Navigate to **Telephony > Inbound Gateways**.
3. Click **Add Inbound Gateway**.
4. Enter a name and the phone number you purchased from your SIP provider.
5. Select the Geo Region option and choose where inbound SIP traffic should be routed (currently supported: India, US).
6. Click **Create**.
7. Copy the **Inbound Gateway SIP URI**
- Default: `sip:orgId.sip.videosdk.live`
- Regional (to restrict calls to a specific region): `sip:orgId.<region>.sip.videosdk.live`
8. Configure this URI as the **Origination SIP URI** in your SIP provider's dashboard (e.g., Twilio, Vonage, Telnyx).

<div style={{textAlign: 'center'}}>
  
</div>

---

**vonage:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/inbound-gateways).
2. Navigate to **Telephony > Inbound Gateways**.
3. Click **Add Inbound Gateway**.
4. Enter a name and the phone number you purchased from Vonage.
5. Select the Geo Region option and choose where inbound SIP traffic should be routed (currently supported: India, US).
6. Click **Create**.
7. Copy the **Inbound Gateway SIP URI**
- Default: `sip:orgId.sip.videosdk.live`
- Regional (to restrict calls to a specific region): `sip:orgId.<region>.sip.videosdk.live`
8. In your **Vonage Console**, go to your SIP Trunk settings.
9. Under **Inbound Calls**, select your region.
10. In the **URI** section, paste the Inbound Gateway SIP URI you copied.
11. Link the phone number you purchased to this trunk.

<div style={{textAlign: 'center'}}>
  
</div>

---

**telnyx:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/inbound-gateways).
2. Navigate to **Telephony > Inbound Gateways**.
3. Click **Add Inbound Gateway**.
4. Enter a name and the phone number you purchased from Telnyx.
5. Select the Geo Region option and choose where inbound SIP traffic should be routed (currently supported: India, US).
6. Click **Create**.
7. Copy the **Inbound Gateway SIP URI**
- Default: `sip:orgId.sip.videosdk.live`
- Regional (to restrict calls to a specific region): `sip:orgId.<region>.sip.videosdk.live`
8. In your **Telnyx Console**, go to **Connections** and create a new SIP Connection.
9. Set the type as **FQDN**.
10. Under **FQDN**, add the VideoSDK Inbound Gateway SIP URI you copied.
11. Assign the phone number you purchased to this connection.

<div style={{textAlign: 'center'}}>
  
</div>

---

**api:**

You can create an inbound gateway programmatically using the API.

```bash title="cURL"
curl --request POST \
  --url https://api.videosdk.live/v2/sip/inbound-gateways \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
"name": "My Inbound Gateway",
"numbers": ["+1234567890"]
  }'
```

> **API Reference**: [Create Inbound Gateway](/api-reference/realtime-communication/sip/inbound-gateway/create-inbound-gateway)



### 3. Create Outbound Gateway


An **Outbound Gateway** is used if you want to dial out to a SIP user from a VideoSDK meeting.

**twilio:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/outbound-gateways).
2. Navigate to **Telephony > Outbound Gateways**.
3. Click **Add Outbound Gateway**.
4. Enter a name.
5. Enter the **Termination SIP URI** provided by your SIP provider.
6. Enter the **Username** and **Password** for your SIP provider.
7. Set the Geo Region to route outbound calls through a specific region (currently supported: India, US).
8. Click **Create**.

<div style={{textAlign: 'center'}}>
  
</div>

---

**vonage:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/outbound-gateways).
2. Navigate to **Telephony > Outbound Gateways**.
3. Click **Add Outbound Gateway**.
4. Enter a name.
5. Enter the **Domain** you set up in your Vonage SIP Trunk settings.
6. Enter the **Username** and **Password** you configured in Vonage under **Outbound Calls**.
7. Set the Geo Region to route outbound calls through a specific region (currently supported: India, US).
8. Click **Create**.
9. **Note:** For outbound gateway numbers, do not use the `+` sign—just use the country code and number.

<div style={{textAlign: 'center'}}>
  
</div>

---

**telnyx:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/outbound-gateways).
2. Navigate to **Telephony > Outbound Gateways**.
3. Click **Add Outbound Gateway**.
4. Enter a name.
5. Enter the **SIP Domain** you configured in your Telnyx SIP Connection.
6. Enter the **Username** and **Password** you set up in Telnyx under **Outbound Authentication**.
7. Set the Geo Region to route outbound calls through a specific region (currently supported: India, US).
8. Click **Create**.

<div style={{textAlign: 'center'}}>
  
</div>

---

**api:**

To route outbound calls through a specific region, set the `geoRegion` property in the API request. By default, the SIP server region is automatically selected based on the location nearest to the dialed number (currently supported: India, US).

```bash title="cURL"
curl --request POST \
  --url https://api.videosdk.live/v2/sip/outbound-gateways \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
"name": "My Outbound Gateway",
"numbers": ["+1234567890"],
"address": "sip.provider.com",
"geoRegion" : "us002",
"auth": {
  "username": "sip_username",
  "password": "sip_password"
}
  }'
```

> **API Reference**: [Create Outbound Gateway](/api-reference/realtime-communication/sip/outbound-gateway/create-outbound-gateway)



### 4. Create Routing Rules


Routing rules determine how calls are handled.

#### Inbound Routing
For inbound calls, you need to route the call to a specific meeting room.

1. Go to **Telephony > Routing Rules**.
2. Click **Add Routing Rule**.
3. Select your **Inbound Gateway**.
4. Select the **Phone Number**.
5. Under **Dispatch**, select **Room**.
6. Choose **Dynamic** (creates a new room) or **Static** (connects to a specific room ID).
7. Click **Create**.

#### Outbound Routing
For outbound calls, the routing rule selects which Outbound Gateway to use based on the dialed number.

1. Go to **Telephony > Routing Rules**.
2. Click **Add Routing Rule**.
3. Select your **Outbound Gateway**.
4. Enter the **Phone Number** pattern (e.g., `+1*`).
5. Click **Create**.

<div style={{textAlign: 'center'}}>
  
</div>



## Connect SIP User

### Inbound Call
Now that everything is configured, a SIP user can join the meeting by simply dialing the phone number configured in the Inbound Gateway.
1. The call reaches your SIP provider.
2. The provider forwards it to VideoSDK.
3. VideoSDK checks the Routing Rule.
4. The user is connected to the VideoSDK Room.

### Outbound Call
To dial a SIP user from the meeting, you can use the `dispatch` API or the SDK method if available.

```bash title="cURL"
curl --request POST \
  --url https://api.videosdk.live/v2/sip/call \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "gatewayId": "outbound-gateway-id",
    "sipCallTo": "+1234567890",
    "destinationRoomId": "room-id"
  }'
```

> **API Reference**: [Make Outbound Call](/api-reference/realtime-communication/sip/calls/call-trigger)

## Webhooks

You can configure webhooks to receive real-time updates about SIP calls.

### Available Webhook Events
Below is the list of all supported webhook events:

| Event Name | Description |
| :--- | :--- |
| `call-started` | Triggered when a new outbound or inbound call is initiated. |
| `call-answered` | Triggered when the call is answered by the recipient. |
| `call-hangup` | Triggered when the call is completed or hung up by either party. |
| `call-transferred` | Call transferred to another destination. |
| `call-missed` | Triggered when the call is not answered or missed by the recipient. |
| `call-update` | Triggered when there is an update in the call status. |
| `call-ringing` | Triggered when the call is ringing at the destination endpoint. |
| `call-transfer-initiated` | Call transfer has been initiated. |
| `call-transfer-accepted` | Call transfer has been accepted by the target. |
| `call-transferring` | Call is being transferred to another destination. |
| `call-transfer-ringing` | Call is ringing at the transfer target. |
| `call-transfer-failed` | Call transfer failed. |

You can configure these in the **Telephony > Webhooks** section of the dashboard.

## Configuring Webhooks

You can set up webhooks using:

- **Dashboard:** Navigate to the SIP section and add a webhook by specifying your target URL and selecting the events you want to subscribe to.
- **API:** Use the `POST /v2/sip/webhooks` endpoint to register a webhook.



## API Reference

- [Create Webhook API](/api-reference/realtime-communication/sip/webhook/create-webhook)
- [Fetch all Webhook API](/api-reference/realtime-communication/sip/webhook/fetch-all-webhooks)
- [Fetch a Webhook API](/api-reference/realtime-communication/sip/webhook/fetch-webhook)
- [Update Webhook API](/api-reference/realtime-communication/sip/webhook/update-webhook)
- [Delete Webhook API](/api-reference/realtime-communication/sip/webhook/delete-webhook)



---

# Explore video & audio calling

This guide will get you running with the VideoSDK video & audio calling in minutes.

## Overview

At it's core, VideoSDK RTC is a distributed SFU. It eanbles highly scalable video & audio meetings unlike vanilla webRTC.

VideoSDK enables opportunity to integrate video & audio calling to Web, Android, IOS applications. it provides Programmable SDKs and REST APIs to build up scalable video conferencing applications.

## Terminology

#### **Meeting**

A Meeting represents real-time audio, video, and/or screen-share session, and is the basic building block for media sharing among participants.

#### **Participants**

Participants are the client applications that are connected to a Meeting and shares video & audio media with one another.

#### **Local Participant**

Local Participant producing audio or video stream from the local client's media sources

#### **Streams**

Streams are indiviual video & audio streams produced by the participants in the meeting

#### **Active Speaker**

Active Speaker represents the participant who is currently producing highest decibels audio stream (in other words speaking)

#### **Active Presenter**

Active Presenter is the participant who is currently sharing his/her screen as a video stream

#### **Main participant**

Main Participant represents the client who shall be displayed on the main screen indicating that he/she is either presenting or speaking

## Architecture

This diagram demonstrates end-to-end flow to implement video & audio calling, record calls and go-live on social media.



---

# Supported Browsers

:::note
The following browser versions represent the minimum required versions to ensure full support for the listed features.
:::





---

# Post Transcription & Summary - Javascript

Welcome to the developer guide for implementing a post-transcription feature using the JS SDK. This guide will walk you through the necessary steps to enable post-transcription functionality in your application, allowing users to access transcriptions of recorded meetings.

Moreover, VideoSDK offers flexibility in configuring post-time transcription, allowing you to set up webhooks for this purpose.

## Integrating Post Transcription Feature

![alt text](/img/transcription/post-transcription.png)

In the image above, the recording begins with transcription and summary features turned on. This triggers a webhook call for the start of recording. When the recording stops, another webhook is activated. After the recording, our transcriber starts transcribing, which in turn activates a webhook. Once the transcription is finished, it's sent to the summarizer for summary generation, and then another webhook is triggered.

### **Step 1: Configure Post Transcription & Summary**

- In this step, we set up the configuration for post transcription and summary generation. We define the webhook URL where the webhooks will be received.

```js
// Webhook URL where, webhooks are received
const webhookUrl = "https://www.example.com";

// highlight-next-line
// Post Transcription Configuration
const transcription = {
  enabled: true, // Enables post transcription
  summary: {
    enabled: true, // Enables summary generation

    // Guides summary generation
    prompt:
      "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
  },
};
```

### **Step 2: Start Recording with Transcription Configuration**

- Once the configuration is set, we initiate the recording process for the meeting, incorporating the transcription configuration we defined earlier.

```js
// Start Recording
meeting.startRecording(webhookUrl, null, null, transcription);
```

### **Step 3: Stop Recording**

- When the meeting concludes or recording is no longer needed, we stop the recording process.

```js
// Stop Recording
meeting.stopRecording();
```

### **Step 4: Fetch Post Transcriptions**

- After the meeting recording is stopped, post transcription and summary data can be obtained using the [Post Transcription API](/api-reference/realtime-communication/fetch-post-transcriptions-summary).

- The API provides information such as the status of transcription, file paths for transcription data in various formats (JSON, SRT, TXT, TSV, VTT), and a summarized text file.

- The transcription document is structured as follows:

```json
{
  "id": "40b0a4ed-9842-40c9-a288-e4b1bf98a90a",
  "status": "completed",
  "roomId": "abc-xyzw-lmno",
  "sessionId": "621497578bea0d0404c35c4c",
  "recordingId": "65d303d6d2c373dfd71b38a2",
  "filePath": "https://cdn.videosdk.live/encoded/videos/dummy.mp4",
  "transcriptionFilePaths": {
    "json": "https://cdn.videosdk.live/transcriptions/dummy/dummy.json",
    "srt": "https://cdn.videosdk.live/transcriptions/dummy/dummy.srt",
    "txt": "https://cdn.videosdk.live/transcriptions/dummy/dummy.txt",
    "tsv": "https://cdn.videosdk.live/transcriptions/dummy/dummy.tsv",
    "vtt": "https://cdn.videosdk.live/transcriptions/dummy/dummy.vtt"
  },
  "summarizedFilePaths": {
    "txt": "https://cdn.videosdk.live/transcriptions/dummy/dummy-summary.txt"
  },
  "userStorage": null,
  "start": "2024-02-27T16:00:36.828Z",
  "end": "2024-02-27T16:01:46.939Z"
}
```

### Example

- The following JavaScript code snippet allows you to start and stop recording meetings with just a click. When you click the "Start Recording" button, it begins recording the meeting and enables post-transcription, which generates a summary of the meeting's content. Clicking the "Stop Recording" button ends the recording.

```js
// Meeting object
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

// Get start button element
const startRecordingBtn = document.getElementById("startRecordingBtn");

// Get stop button element
const stopRecordingBtn = document.getElementById("stopRecordingBtn");

// Listen for click event
startRecordingBtn.addEventListener("click", () => {
  // Webhook URL where, webhooks are received
  const webhookUrl = "https://example.com";

  // Configuration for post transcription
  const transcription = {
    enabled: true, // Enables post transcription
    summary: {
      enabled: true, // Enables summary generation

      // Guides summary generation
      prompt:
        "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary",
    },
  };

  // Start recording with post transcription
  meeting?.startRecording(webhookUrl, null, null, transcription);
});

// Listen for click event
stopRecordingBtn.addEventListener("click", () => {
  // Stop  recording
  meeting?.stopRecording();
});
```

:::important

Please be aware that there may be a delay in processing the transcription data after the recording has been stopped. This delay could vary depending on factors such as server load and the duration of the meeting.

:::

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [startRecording()](/javascript/api/sdk-reference/meeting-class/methods#startrecording)
- [stopRecording()](/javascript/api/sdk-reference/meeting-class/methods#stoprecording)
- [fetchPostTranscriptions](/api-reference/realtime-communication/fetch-post-transcriptions-summary)


---

# Realtime Transcription - Javascript

Realtime transcription allows you to transcribe audio content into text in real-time during a session. This guide will walk you through using the `startTranscription()` and `stopTranscription()` functions to manage realtime transcription in your application.

Moreover, VideoSDK offers flexibility in configuring real-time transcription, allowing you to set up webhooks for this purpose.

## Integrating Realtime Transcription Feature

![alt text](/img/transcription/realtime-transcription.png)

The above image represents,

1. **Start Transcription:** The SDK Client initiates real-time transcription using the `startTranscription` method.

2. **Resource Acquisition:** VideoSDK server requests necessary resources from transcription service.

   - If the request is denied, the server sends a `transcription-failed` event to the SDK Client.
   - If the request is successful, the server sends a `transcription-started` event to the client, indicating that transcription has begun.

3. **Transcription Data:** As transcription progresses, the client receives `transcription-text` event with data such as the text itself, participant ID, and timestamp.

4. **Stop Transcription:** When the client decides to stop transcription, it informs the VideoSDK server to release resources.
   - The server then sends a `transcription-stopped` event to confirm that transcription has ended and resources are released.

### **Step 1: Configure Realtime Transcription**

- In this step, we set up the configuration for realtime transcription. We define the webhook URL where the webhooks will be received.

```js
// highlight-next-line
// Realtime Transcription Configuration
const config = {
  webhookUrl = "https://www.example.com",
  summary: {
    enabled: true,
    prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
  }
};
```

### **Step 2: Listen for the transcription events**

- Here, we configure the callback methods for transcription events.

```js

const Constants = VideoSDK.Constants;

// Listen for transcription state changed event
meeting.on("transcription-state-changed", (data) => {
  let { status, id } = data;

  if (status === Constants.transcriptionEvents.TRANSCRIPTION_STARTING) {
    console.log(`Realtime Transcription with ${id} is starting`);
  } else if (status === Constants.transcriptionEvents.TRANSCRIPTION_STARTED) {
    console.log(`Realtime Transcription with ${id} is started`);
  } else if (status === Constants.transcriptionEvents.TRANSCRIPTION_STOPPING) {
    console.log(`Realtime Transcription with ${id} is stopping`);
  } else if (status === Constants.transcriptionEvents.TRANSCRIPTION_STOPPED) {
    console.log(`Realtime Transcription with ${id} is stopped`);
  }
});

// Listen for transcription text event
meeting.on("transcription-text", (data) => {
  let { participantId, participantName, text, timestamp, type } = data;
  console.log(`${participantName}: ${text} ${timestamp}`);
});
```

### **Step 3: Start realtime transcription**

- Initiate the realtime transcription using the `startTranscription()` method.

```js
// Starts realtime transcription
meeting.startTranscription(config);
```

### **Step 4: Stop realtime transcription**

- Terminate the realtime transcription using the `stopTranscription() `method.

```js
// Stops realtime transcription
meeting.stopTranscription();
```

:::important

You can access a summary of your realtime transcription using the **[<u>Fetch Realtime Transcription API</u>](/api-reference/realtime-communication/fetch-a-realtime-transcription)**.

:::

### Example

- The following JavaScript code snippet allows you to start and stop realtime transcription with just a click. When you click the "Start Realtime Transcription" button, it begins realtime transcription. Clicking the "Stop Realtime Transcription" button ends the realtime transcription.

```js
// Meeting object
let meeting;

// Initialize Meeting
meeting = VideoSDK.initMeeting({
  // ...
});

// Get start button element
const startRealtimeTranscriptionBtn = document.getElementById(
  "startRealtimeTranscriptionBtn"
);

// Get stop button element
const stopRealtimeTranscriptionBtn = document.getElementById(
  "stopRealtimeTranscriptionBtn"
);

// Listen for transcription state changed event
meeting?.on("transcription-state-changed", (data) => {
  const { status, id } = data;

  // Check for starting event
  if (status === Constants.transcriptionEvents.TRANSCRIPTION_STARTING) {
    console.log("Realtime Transcription is starting", id);
  }
  // Check for started event
  else if (status === Constants.transcriptionEvents.TRANSCRIPTION_STARTED) {
    console.log("Realtime Transcription is started", id);
  }
  // Check for stopping event
  else if (status === Constants.transcriptionEvents.TRANSCRIPTION_STOPPING) {
    console.log("Realtime Transcription is stopping", id);
  }
  // Check for stopped event
  else if (status === Constants.transcriptionEvents.TRANSCRIPTION_STOPPED) {
    console.log("Realtime Transcription is stopped", id);
  }
});

// Listen for transcription text event
meeting?.on("transcription-text", (data) => {
  // Destructuring data
  let { participantId, participantName, text, timestamp, type } = data;
  console.log(`${participantName}: ${text} ${timestamp}`);
});

// Listen for click event
startRealtimeTranscriptionBtn.addEventListener("click", () => {
  // Configuration for realtime transcription
  let config = {
    webhookUrl: "https://example.com",
  };

  // Start realtime transcription
  meeting?.startTranscription(config);
});

// Listen for click event
stopRealtimeTranscriptionBtn.addEventListener("click", () => {
  // Stop  realtime transcription
  meeting?.stopTranscription();
});
```

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [startTranscription()](/javascript/api/sdk-reference/meeting-class/methods#starttranscription)
- [stopTranscription()](/javascript/api/sdk-reference/meeting-class/methods#stoptranscription)
- [transcription-state-changed](/javascript/api/sdk-reference/meeting-class/events#transcription-state-changed)
- [transcription-text](/javascript/api/sdk-reference/meeting-class/events#transcription-text)


---

## Introduction

You can create audio-video rooms and invite participants without even writing a line of code. You can also set role-wise permissions and change the names of these roles. This guide explains it’s steps.


<div style={{textAlign: 'center'}}>



</div>

## Prerequisites

- If you are new to video sdk then create account by referring [https://app.videosdk.live/signup](https://app.videosdk.live/signup) link

## Step 1 : Go to Quickstart

1. Go to [Quickstart panel](https://app.videosdk.live/quick-start) of Video SDK's website
2. Select No code SDK and click on continue.

   ![img1.png](../../../static/img/no-code-img1.png)

## Step 2 : Create Template

1. Add a Template name and select your nearest region specified in the region and click on continue.

   - Naming conventions for template name
     - no space is allowed
     - only - , \_ characters are allowed in addition with [a-z,A-Z,0-9]

   ![img2.png](../../../static/img/no-code-img2.png)

## Step 3 : Create Roles and Set Permissions

1. Let’s say you have created a template named as `Template`
2. By default 2 roles are provided and few permissions are also set, you can make changes in the permissions and even change the name of these 2 roles.
3. Moreover, you can create new roles and set permissions for that particular role.

**By clicking on **+** icon one can add as many roles as they want**

![img3.png](../../../static/img/no-code-img3.png)

**You can edit default specified role name by clicking on an icon shown below**

![img4.png](../../../static/img/no-code-img4.png)

**you can edit default role’s permissions by clicking on an icon mentioned below**

![img5.png](../../../static/img/no-code-img5.png)

:::note
Role name should be unique for each template
:::

- By clicking on toggle button for each permission you can set those permissions either true or false.
- After setting all configurations click on the close icon which will auto save all the permissions.

![img6.png](../../../static/img/no-code-img6.png)

## Step 4 : Launch Template

Click on `launch template` to launch your template

![img7.png](../../../static/img/no-code-img7.png)

After clicking on `Launch Template` you will be redirected to a page which will contain the list of the templates created by you using `Video SDK’s no code sdk`

![img8.png](../../../static/img/no-code-img8.png)

From the list you can delete role for the specific template as shown in an image below

![img9.png](../../../static/img/no-code-img9.png)

:::note
By Default, all templates are activated. You can toggle the button to deactivate a template.
:::

![img10.png](../../../static/img/no-code-img10.png)

You can make changes in the role-wise permissions and also add new roles from the table.

![img11.png](../../../static/img/no-code-img11.png)

## How to start a meeting ?

**Step 1** : From the template list, click on Get meeting link to get role wise URL for a specific template. You can get links only if that template is in active status.

:::note
Each time you click on “Get meeting link”, will generate new meeting room and give it’s links. Hence, you need to save/send meeting links of each role, before closing this pop-up.
:::

![img13.png](../../../static/img/no-code-img12.png)

**Step 2** : Copy the link, open a new tab and paste it there.

![img12.png](../../../static/img/no-code-img13.png)

**Voila!** You have started a meeting in 5 minutes. You can copy the guest meeting link and send it to others.

![img14.png](../../../static/img/no-code-img14.png)

:::note
each time you make changes to permissions of a role , you’ll have to copy meeting link by clicking on get meeting link for that specific role of a template or have to refresh ongoing meeting tab in order to start a meeting with new permissions for a specific role.
:::


---

<div class="sdk-api-ref-only-h4">

```js
meeting.init({
  name: "John Doe",
  apiKey: "YOUR API KEY", // generated from app.videosdk.live
  meetingId: "milkyway", // enter your meeting id

  // @discontinued
  // region: "sg001",
  // The region parameter has been discontinued; instead, the Video SDK's smart service will pick the best optimal servers for a conference, closest to your end-users' location. If you still need to hold your conferences in a specific region, i.e. Geo Fencing. https://videosdk.live/contacts

  containerId: null,
  redirectOnLeave: "https://www.videosdk.live/",

  micEnabled: true,
  webcamEnabled: true,
  participantCanToggleSelfWebcam: true,
  participantCanToggleSelfMic: true,
  participantCanLeave: true, // if false, leave button won't be visible

  chatEnabled: true,
  screenShareEnabled: true,
  pollEnabled: true,
  whiteboardEnabled: true,
  raiseHandEnabled: true,
  mode: "CONFERENCE", // VIEWER || CONFERENCE

  recording: {
    autoStart: true, // auto start recording on participant joined
    enabled: true,
    webhookUrl: "https://www.videosdk.live/callback",
    awsDirPath: `/meeting-recordings/${meetingId}/`, // automatically save recording in this s3 path
  },

  livestream: {
    autoStart: true,
    enabled: true,
  },

  hls: {
    enabled: true,
    autoStart: false,
  },

  layout: {
    type: "SPOTLIGHT", // "SPOTLIGHT" | "SIDEBAR" | "GRID"
    priority: "PIN", // "SPEAKER" | "PIN",
    // gridSize: 3,
  },

  branding: {
    enabled: true,
    logoURL:
      "https://static.zujonow.com/videosdk.live/videosdk_logo_circle_big.png",
    name: "Prebuilt",
    poweredBy: false,
  },

  permissions: {
    pin: true,
    askToJoin: false, // Ask joined participants for entry in meeting
    toggleParticipantMic: true, // Can toggle other participant's mic
    toggleParticipantWebcam: true, // Can toggle other participant's webcam
    toggleParticipantScreenshare: true, // Can toggle other participant's screen share
    toggleParticipantMode: true, // Can toggle other participant's mode
    canCreatePoll: true, // Can create a poll
    toggleHls: true, // Can toggle Start HLS button
    drawOnWhiteboard: true, // Can draw on whiteboard
    toggleWhiteboard: true, // Can toggle whiteboard
    toggleVirtualBackground: true, // Can toggle virtual background
    toggleRecording: true, // Can toggle meeting recording
    toggleLivestream: true, //can toggle live stream
    removeParticipant: true, // Can remove participant
    endMeeting: true, // Can end meeting
    changeLayout: true, //can change layout
  },

  joinScreen: {
    visible: true, // Show the join screen ?
    title: "Daily scrum", // Meeting title
    meetingUrl: window.location.href, // Meeting joining url
  },

  leftScreen: {
    // visible when redirect on leave not provieded
    actionButton: {
      // optional action button
      label: "Video SDK Live", // action button label
      href: "https://videosdk.live/", // action button href
    },
  },

  notificationSoundEnabled: true,

  debug: true, // pop up error during invalid config or netwrok error

  maxResolution: "sd", // "hd" or "sd"
});
```

</div>


---

# Branding Parameters - Prebuilt

<div class="sdk-api-ref-only-h4">

## branding

- type: `object`

### enabled

- type: `Boolean`

- If `true`, then branding will be visible on topbar of the meeting layout.

### logoURL

- type: `String`

- `url` of your brand logo, to be shown on the topbar of the meeting screen layout.

### name

- type: `String`

- It represents your brand name, that will be shown on the topbar of the meeting screen layout.

### poweredBy

- type: `Boolean`

- If it is `true`, powered by [videosdk.live](https://www.videosdk.live) will be shown below the branch name else it will be hidden.

```js
meeting.init({
  //other params
  branding: {
    enabled: true,
    logoURL: "https://your-brand.logo",
    name: "Prebuilt",
    poweredBy: true,
  },
  //other params
});
```

</div>


---

# Customize Audio/Video Parameters - Prebuilt

<div class="sdk-api-ref-only-h4">

## Custom Video Config

### videoConfig

- type: `object`

### resolution

- type: `String`

- `videoConfig.resolution` represents the resolution of your video which can be `h90p_w160p` , `h180p_w320p` , `h216p_w384p` , `h360p_w640p` , `h540p_w960p` , `h720p_w1280p` , `h1080p_w1920p` , `h1440p_w2560p` , `h2160p_w3840p` , `h120p_w160p` , `h180p_w240p` , `h240p_w320p` , `h360p_w480p` , `h480p_w640p` , `h540p_w720p` , `h720p_w960p` , `h1080p_w1440p` or `h1440p_w1920p`.

### optimizationMode

- type: `String`

- `videoConfig.optimizationMode` represents the specific mode of your video which can be `motion` , `text` or `detail`.

### multiStream

- type: `Boolean`

- If it is `true`, multiple resolution layers are send in single video stream. If it is `false`, then only single resolution layer is send in video stream.

```js
meeting.init({
  // other params
  videoConfig: {
    resolution: "h720p_w1280p",
    optimizationMode: "motion",
    multiStream: true,
  },
  // other params
});
```

## Custom Audio Config

### audioConfig

- type: `object`

### quality

- type: `String`

- `audioConfig.quality` represents the quality of your audio which can be `speech_low_quality` , `speech_standard` , `music_standard` , `standard_stereo` , `high_quality` or `high_quality_stereo`.

```js
meeting.init({
  // other params
  audioConfig: {
    quality: "high_quality",
  },
  // other params
});
```

## Custom Screen Share Config

### screenShareConfig

- type: `object`

### resolution

- type: `String`

- `screenShareConfig.resolution` represents the resolution of your screen shared video which can be `h360p_30fps`, `h720p_5fps`, `h720p_15fps`, `h1080p_15fps`, `h1080p_30fps`.

### optimizationMode

- type: `String`

- `screenShareConfig.optimizationMode` represents the specific mode of your screen shared video which can be `motion` , `text` or `detail`.

```js
meeting.init({
  // other params
  screenShareConfig: {
    resolution: "h720p_5fps",
    optimizationMode: "text",
  },
  // other params
});
```

</div>


---

# HLS Feature Parameter - Prebuilt

<div class="sdk-api-ref-only-h4">

## hls

- type: `object`

### enabled

- type: `Boolean`

- `hls.enabled` enables participant for hls.

### autostart

- type: `Boolean`

- `hls.autostart` autostart hls if set to `true` when meeting gets started.

### playerControlsVisible

- type: `Boolean`

- `hls.playerControlsVisible` : If it is `true` then participant can view controls for the interactive meeting player.

### theme

- type: `String`

- `hls.theme` represents the hls theme which can be `DARK` , `LIGHT` or `DEFAULT`.

### toggleParticipantMode

- type: `Boolean`

- `toggleParticipantMode` represents whether participant can toggle other participant's mode or not.

### toggleHLS

- type: `Boolean`

- `toggleHLS` if set to `true` you can toggle `Start HLS` Button.

### mode

- type: `String`

- `mode` represents the mode of participant which can be `VIEWER` | `CONFERENCE`

:::note

`hls.playerControlsVisible` parameter will only work if the mode is set to `viewer`, for `conference` mode there will not be any interactive meeting player hence `hls.playerControlsVisible` will be ignored if mode is set to `conference`.

:::

```js
meeting.init({
  //other params
  hls: {
    enabled: true,
    autoStart: false,
    theme: "DARK" // DARK | LIGHT | DEFAULT
    playerControlsVisible: true,
  },
  permissions: {
    //  ...other permissions
    toggleParticipantMode: true,
    toggleHls: true,
  },
  mode: "CONFERENCE", // VIEWER || CONFERENCE
  //other params
});
```

</div>


---

# Layout Feature Parameter - Prebuilt

<div class="sdk-api-ref-only-h4">

## layout

- type: `object`

### type

- type: `String`

- `layout.type` represents the type of layout which can be `SPOTLIGHT` | `SIDEBAR` | `GRID`

### priority

- type: `String`

- `layout.priority` represents the priority of layout type which can be `SPEAKER` | `PIN`

### gridSize

- type: `Number`

- `layout.gridSize` represents the maximum participants to be shown on the meeting screen. Max value should be **`25`**

```js
meeting.init({
  //other params
  layout: {
    type: "SPOTLIGHT", // "SPOTLIGHT" | "SIDEBAR" | "GRID"
    priority: "SPEAKER", // "SPEAKER" | "PIN",
    gridSize: 3,
  },
  //other params
});
```

</div>


---

# LeftScreen Parameters - Prebuilt

<div class="sdk-api-ref-only-h4">

## leftScreen

- type: `object`

### actionButton

- type: `object`

- with the help of `leftScreen.actionButton` host of the meeting can customize button on left screen page

- `{href,label}`

  - href : URL of a customized action button

  - label : label of type `String` of a customized action button

### rejoinButtonEnabled

- type: `Boolean`

- If set to true one can see rejoin button on left screen page.

```js
meeting.init({
  //other params
  leftScreen: {
    actionButton: {
      label: "Video SDK",
      href: "https://www.videosdk.live",
    },
    rejoinButtonEnabled: true,
  },
  //other params
});
```

</div>


---

# LiveStream Parameters - Prebuilt

<div class="sdk-api-ref-only-h4">

## livestream

- type: `object`

### enabled

- type: `Boolean`

- `livestream.enabled` enables participant for live streaming.

### autostart

- type: `Boolean`

- `livestream.autostart` autostart live streaming if set to `true` when meeting gets started.

### theme

- type: `String`

- `livestream.theme` represents the theme of live streaming which can be `DARK` , `LIGHT` or `DEFAULT`.

### outputs

- type: `json object array`

- \{streamKey,url}

  - type: `{ url: String, streamKey: String }[]`

  - here you have to mention your streamKey and url of live streaming platform.

```js
meeting.init({
  //other params
  livestream: {
    enabled: true,
    autoStart: true,
    theme: "DARK" // DARK | LIGHT | DEFAULT
    outputs: [
      {
        url: "rtmp://x.rtmp.youtube.com/live2",
        streamKey: "dmkp-2x3k-ksxk-6rrg-f73b",
      },
    ],
  },
  //other params
});
```

</div>


---

# Permissions Parameters - Prebuilt

<div class="sdk-api-ref-only-h4">

## permissions

- type: `object`

### pin

- type: `Boolean`

- `pin` represents whether participant can be `pin` other self or participants or not.

### askToJoin

- type: `Boolean`

- `askToJoin` represents whether participant can request to join in the meeting or not.
- If it is `false`, then participant will directly join the meeting

### toggleParticipantWebcam

- type: `Boolean`

- `toggleParticipantWebcam` represents whether participant can toggle other participant's webcam or not.

### toggleParticipantMic

- type: `Boolean`

- `toggleParticipantMic` represents whether participant can toggle other participant's mic or not.

### toggleParticipantMode

- type: `Boolean`

- `toggleParticipantMode` represents whether participant can toggle other participant's mode or not.

### toggleParticipantScreenshare

- type: `Boolean`

- `toggleParticipantScreenshare` represents whether participant can toggle other participant's screen share or not.

### canToggleParticipantTab

- type: `Boolean`

- `canToggleParticipantTab` represents whether participant can toggle `participant tab` panel or not.

### removeParticipant

- type: `Boolean`

- `removeParticipant` represents whether participant can remove other participant or not.

### canCreatePoll

- type: `Boolean`

- `canCreatePoll` represents whether participant can create a poll or not.

### endMeeting

- type: `Boolean`

- `endMeeting` represents whether participant can end meeting or not.
- If it is `true`, then participant can end the meeting and all joined participants will be removed from the meeting.

### drawOnWhiteboard

- type: `Boolean`

- `drawOnWhiteboard` represents whether participant have permission to draw on white board or not.

### toggleWhiteboard

- type: `Boolean`

- `toggleWhiteboard` enables participant to toggle white board if set to `true`.

### toggleVirtualBackground

- type: `Boolean`

- `toggleVirtualBackground` enables participant to see virtual background option if set to `true`.

### toggleRecording

- type: `Boolean`

- `toggleRecording` enables participant to toggle recording if set to `true`

### toggleLivestream

- type: `Boolean`

- `toggleLivestream` enables participant to toggle live streaming if set to `true`

### changeLayout

- type: `Boolean`

- `changeLayout` enables participant to change the layout of a meeting when set to `true`

```js
meeting.init({
  //other params
  permissions: {
    pin: true,
    askToJoin: false,
    toggleParticipantWebcam: true,
    toggleParticipantMic: true,
    toggleParticipantMode: true,
    canCreatePoll: true,
    canToggleParticipantTab: true,
    toggleParticipantScreenshare: true,
    removeParticipant: true,
    endMeeting: true,
    drawOnWhiteboard: true,
    toggleWhiteboard: true,
    toggleVirtualBackground: true,
    toggleRecording: true,
    toggleLivestream: true,
    changeLayout: true,
  },
  //other params
});
```

</div>


---

# Recording Parameters - Prebuilt

<div class="sdk-api-ref-only-h4">

## recording

- type: `object`

### enabled

- type: `Boolean`

- `recording.enabled` enables participant to record the meeting.

### webhookUrl

- type: `String`

- `recording.webhookUrl`, represents web hook url called when the recording of the meeting is created.

### awsDirPath

- type: `String`

- `recording.awsDirPath` represents the path where recording will get stored.

### autostart

- type: `Boolean`

- `recording.autostart` autostarts recording if set to `true` when meeting gets started.

### theme

- type: `String`

- `recording.theme` represents the theme of recording which can be `DARK` , `LIGHT` or `DEFAULT`.

```js
meeting.init({
  recording: {
    enabled: true,
    webhookUrl: "https://www.videosdk.live/callback",
    awsDirPath: `/meeting-recordings/${meetingId}/`,
    autoStart: false,
    theme: "DARK" // DARK | LIGHT | DEFAULT
});
```

</div>


---

# WaitingScreen Parameters - Prebuilt

<div class="sdk-api-ref-only-h4">

## waitingScreen

- type: `object`

### imageURL

- type: `String`

- `url` of your lottie or image, to be shown on the waiting screen.

### text

- type: `String`

- It represents your customize message, that will be shown on the waiting screen.

```js
meeting.init({
  //other params
  waitingScreen: {
    imageUrl: "<imageUrl || lottieUrl>",
    text: "Connecting to the meeting...",
  },
  //other params
});
```

</div>


---

# Basic Features - Prebuilt

<div class="sdk-api-ref-only-h4">

## apiKey

- type: `String`

- ApiKey of Video SDK generated from [app.videosdk.live/api-keys](https://app.videosdk.live/api-keys)

---

## meetingId

- type: `String`

- Enter any arbitrary meetingId _or_ an id generated with the reference of [Create-Room](/api-reference/realtime-communication/create-room)

---

## name

- type: `String`

- Name of participant who will join the meeting.

---

## region

- @discontinued

- The region parameter has been discontinued; instead, the Video SDK's smart service will pick the best optimal servers for a conference, closest to your end-users' location. If you still need to hold your conferences in a specific region, i.e. Geo Fencing. [Contact Us](https://videosdk.live/contact)

---

## containerId

- type: `String`

- In the `containerId` you need to specify an `id of your dom element` which will help you rendering your meeting in that particular portion which could be your entire page or any element of a page.

- If nothing provided, then the meeting will be rendered in full screen.

```js
meeting.init({
  //othe params
  containerId: "meeting-container-id",
  //other params
});
```

```html
<html>
  <body>
    <div id="meeting-container-id"></div>
  </body>
</html>
```

---

## redirectOnLeave

- type: `String`

- `redirectOnLeave` will redirect that participant to the specified url, when a participant leave the meeting.

---

## micEnabled

- type: `Boolean`

- If set to true `micEnabled` represents the initial state of **mic** when a participant join the meeting.

---

## webcamEnabled

- type: `Boolean`

- If set to true `webcamEnabled` represents the initial state of **webcam** when a participant join the meeting.

---

## participantCanToggleSelfWebcam

- type: `Boolean`

- When `true`, participant will be able to enable or disable self webcam.

---

## participantCanToggleSelfMic

- type: `Boolean`

- When `true`, participant will be able to enable or disable self mic.

---

## participantCanLeave

- type: `Boolean`

- If `true`, then leave button will be visible on topbar of meeting layout.

---

## chatEnabled

- type: `Boolean`

- If `true`, then participant will be able to chat during the meeting.

---

## screenShareEnabled

- type: `Boolean`

- If `true`, then participant will be able to share their screen in the meeting.

---

## whiteboardEnabled

- type: `Boolean`

- If `true`, then participant will be able to see the white board status.

---

## raiseHandEnabled

- type: `Boolean`

- if true then participant will be able to raise his/her hand in the meeting

---

## joinScreen

- type: `object`

### visible

- type: `Boolean`

- `joinScreen.visible`. If set to `true`, then joinScreen will be visible to enter the meeting.

### title

- type: `String`

- `joinScreen.title`. Represents the title of the meeting.

### meetingUrl

- type: `String`

- `joinScreen.meetingUrl`. Represents meeting joining url.

```js
meeting.init({
  //other params
  joinScreen: {
    visible: false, // Show the join screen ?
    title: "Recording Scaling Testing", // Meeting title
    meetingUrl: window.location.href, // Meeting joining url
  },
  //other params
});
```

---

## participantTabPanelEnabled

- type: `Boolean`

- Setting `participantTabPanelEnabled` to `true` will show an participant tab panel in the meeting.

---

## maxResolution

- type: `String`

- `maxResolution`, sets the max webcam resolution which can either be `hd` | `sd`

---

## debug

- type: `Boolean`

- Setting `debug` to `true` will show an error which may cause during the meeting.

---

## participantId

- type: `String`

- If participant wants to explicitly specify their **`id`** , then it can be managed using `participantId`.

---

## joinWithoutUserInteraction

- type: `Boolean`

- Participant can directly join the meeting if `joinWithoutUserInteraction` set to `true`.

---

## maintainVideoAspectRatio

- type: `Boolean`

- Participant videos will maintain the aspect ratio if `true`, so if the video stream is portrait it will be shown as portrait.

- Default: `true`

---

## moreOptionsEnabled

- type: `Boolean`

- Setting `moreOptionsEnabled` to `true` or `false` will show or hide More Option tab panel in the meeting.

- Default: `true`

---

## participantNotificationAlertsEnabled

- type: `Boolean`

- Setting `participantNotificationAlertsEnabled` to `true` will show notification when participant join or left the meeting.

- Default: `false`

---

</div>


---

# Setup - Prebuilt

## Using prebuilt sdk

Our prebuilt sdk enables opportunity to integrate real time communication with your application with just 10 minutes.

### Setting up prebuilt sdk using `<script>`

The easiest way to get started is by just adding our prebuilt script in your website.

```js
<script src="https://sdk.videosdk.live/rtc-js-prebuilt/0.3.43/rtc-js-prebuilt.js"></script>
```

### Setting up prebuilt sdk using NPM package manager

Another way is by installing `@videosdk.live/rtc-js-prebuilt` in your app.



**npm:**

```js
npm install @videosdk.live/rtc-js-prebuilt
```

---

**yarn:**

```js
yarn add @videosdk.live/rtc-js-prebuilt
```


---

# VideoSDKMeeting Class - Prebuilt

The entry point into real-time communication prebuilt SDK.

## The VideoSDKMeeting Class

The `VideoSDKMeeting Class` includes properties, methods and events to control user interface and experience of prebuilt.

## Methods

### init()

- `VideoSDKMeeting` class is used to initialize meeting for prebuilt SDK. One can pass parameters as per their meeting requirement to the `init()` method.

```js title="Javascript"
const meeting = new VideoSDKMeeting();

meeting.init({
  //parameters
});
```

- Have a look to [`parameters`](./parameters/basic-parameters)




---

# Authentication and Tokens




---

# Go Live On HLS - Prebuilt

HLS allows participant to broadcast live streaming to other participants.
This guide will provide an overview of how participant can start and stop broadcasting meeting.

### HLS attributes

- `mode`: It should be any of `VIEWER` or `CONFERENCE`, by default is set to `CONFERENCE`
- `toggleHLS` : When set to `true` it will enable you to click on `Start HLS` button.
- `hls.enabled` : When set to `true` , you can see `Start HLS` button.
- `hls.autoStart`: If it is `true` then HLS will start automatically when the meeting starts, default value is false (You can't start HLS during the meeting).
- `hls.theme`: It will HLS the meeting based on theme you are passing. it can be a either DARK , LIGHT or DEFAULT.
- `hls.playerControlsVisible` : If it is `true` then participant can view controls for the interactive meeting player.
- `toggleParticipantMode`: When set to `true`, you can toggle other participant mode from an ongoing meeting by clicking on `Add as a Cohost` Icon button.

:::note

`hls.playerControlsVisible` parameter will only work if the mode is set to `viewer`, for `conference` mode there will not be any interactive meeting player hence `hls.playerControlsVisible` will be ignored if mode is set to `conference`.

:::

## Better Understanding of Modes

### 1. CONFERENCE Mode

This mode is default mode if you do not give any mode, it will look similar as a normal meeting. when you pass `hls.enabled` true you can see `Start HLS` button. if you want to toggle the button then in `permission` config pass other parameter `toggleHLS` true so you can toggle button.

![Go live on Videosdk](/img/prebuilt/prebuilt-join-as-cohost.png)

In `CONFERENCE` mode you can toggle other participant mode also. like you can add other participant as a co-host. for that you need to pass parameter `toggleParticipantMode` true in `permission` config.

You can click on more button to see add as co-host icon.

![Go live on Videosdk](/img/prebuilt/More.png)

![Go live on Videosdk](/img/prebuilt/Add-as-a-cohost.png)

When you click on `Add as a Co-host` button other participant recive popup. whethere participant can accept or deny. if you accept than only participant add as a cohost.

![Go live on Videosdk](/img/prebuilt/prebuilt-mode-popup.png)

```js title="conference.html"
const config = {
  // ...
  hls: {
    enabled: true,
    autoStart: false,
    theme: "DARK", // DARK || LIGHT || DEFAULT
  },
  permissions: {
    //  ...other permissions
    toggleParticipantMode: true,
    toggleHls: true,
  },
  mode: "CONFERENCE", // VIEWER || CONFERENCE
  // ...
};
```

### 2. VIEWER Mode

You can join meeting as a viewer. in this mode when you join the meeting you can see the waiting screen.

![Go live on Videosdk](/img/prebuilt/prebuilt-join-as-viewer.png)

when host start HLS you can get hls stream in your player and you can see that stream. as a viewer you can do raise hand, chat and leave the meeting.

![Go live on Videosdk](/img/prebuilt/prebuilt-join-as-viewer-view.png)

```js title="viewer.html"
const config = {
  // ...
  hls: {
    playerControlsVisible: true,
  },
  mode: "VIEWER", // VIEWER || CONFERENCE
  // ...
};
```


---

# Authentication and Token

VideoSDK uses access tokens for authentication. Using our dashboard ([app.videosdk.live](https://app.videosdk.live/)), anyone can generate access tokens tokens with an API key and secret pair.

- Your backend server will generate access tokens using API Key and secret.
- Your client obtains token from your backend server.
- Your client will pass the token to VideoSDK server.
- VideoSDK client sdk will conncts to the VideoSDK server with available token.
- VideoSDK server will validate the token and accpets your incoming connection.

Here is the simple sequence diagram represents the authentication.


## Generate API Key and Secret

Visit, [app.videosdk.live](https://app.videosdk.live/) to gererate API Key and secret.

![Generate API Key from Dashboard](/img/tutorial/generate-api-key.jpg)

## Generate Access Token

For security, every participant that connects to meeting needs a access token. By substituting `apikey` and `permissions` in it.



**node:**

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

// Need to generate from app.videosdk.live
const API_KEY = "API_KEY_GENERATED";
const SECRET_KEY = "API_SECRET_KEY_GENERATED";

jwt.sign(
  {
apikey: API_KEY,
permissions: ["allow_join"], // Permission to join the meeting
  },
  SECRET_KEY,
  {
algorithm: "HS256",
expiresIn: "24h",
jwtid: uuid4(),
  },
  function (err, token) {
console.log(token);
  }
);
```

---

**python:**

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

api_key = 'api_key_generated'
secret_key = 'secret_key_generated'


def generateToken():
expires = 24 * 3600
now = datetime.datetime.utcnow()
exp = now + datetime.timedelta(seconds=expires)
return jwt.encode(payload={
      'apikey': api_key,
      permissions: ["allow_join"]
    }, key=secret_key).decode('utf-8')

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

---

**java:**

```js
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("apikey", "<api_key_generated>");
payload.put("permissions", ["allow_join"]);
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, "<secret_key_generated>".getBytes()).compact();
  }
```

---

**ruby:**

```js
require 'jwt'
require 'securerandom'

$api_key = "api_key_generated"
$secret_key = "secret_key_generated"

def generateToken()
payload = {
  apikey: $api_key,
  permissions: ["allow_join"]
}
token = JWT.encode(payload, $secret_key, 'HS256')
return token
end

puts generateToken
```

---

**php:**

```js
<?php

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

$api_key = "api_key_generated";
$secret_key = "secret_key_generated"

$payload = [
'apikey' => api_key,
'permissions': ["allow_join"],
];

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

Available permissions are:

- **allow_join**: The participant will be permitted entry without request.
- **ask_join**: The participant will not be permitted entry without request.
- **allow_mod**: Allow participant to enable/disable other participant's mic/webcam.


---

# Client Setup - Prebuilt

Prebuilt SDK enables opportunity to integrate real-time communication SDK witout writing explicit code. It just requires 10 minutes to integrate.

It supports all the modern frameworks such as plain JavaScript, React JS, Vue and Angular.

:::note

Also check out this [example code](https://github.com/videosdk-live/videosdk-rtc-js-prebuilt-embedded-example) on github or [download](https://github.com/videosdk-live/videosdk-rtc-js-prebuilt-embedded-example/archive/refs/tags/v0.1.1.zip) the full source code and unzip on your computer to get started quickly.

:::

## Setup Meeting using npm package manager

### Step 1: Install Package

**npm:**

```js
npm install @videosdk.live/rtc-js-prebuilt
```

---

**yarn:**

```js
yarn add @videosdk.live/rtc-js-prebuilt
```

### Step 2: Initialize Meeting

Copy API key generated from [Signup & Create API Key](/docs/guide/prebuilt-video-and-audio-calling/signup-and-create-api) , paste it in to `apiKey` attribute.

**react:**

```js
import React, { useEffect } from "react";

export default function App() {
  useEffect(() => {
const config = {
  name: "John Doe",
  apiKey: "<API KEY>", // generated in step 1
  meetingId: "milkyway", // enter your meeting id

  containerId: null,

  /**
   FEATURE ATTRIBUTES
  */
};

const meeting = new VideoSDKMeeting();
meeting.init(config);
  }, []);

  return <div></div>;
}
```

---

**angular:**

```js



@Component({
  selector: "app-root",
  templateUrl: "./app.component.html",
})
export class AppComponent implements OnInit {
  async ngOnInit() {
const config = {
  name: "John Doe",
  apiKey: "<API KEY>", // generated in step 1
  meetingId: "milkyway", // enter your meeting id

  containerId: null,

  /**
   FEATURE ATTRIBUTES
  */
};

const meeting = new VideoSDKMeeting();
meeting.init(config);
  }
}
```

---

**vue:**

```js
<script>

export default {
  name: "App",
  mounted: async function() {
const config = {
  name: "John Doe",
  apiKey: "<API KEY>", // generated in step 1
  meetingId: "milkyway", // enter your meeting id

  containerId: null,

  /**
   FEATURE ATTRIBUTES
  */
};
const meeting = new VideoSDKMeeting();
meeting.init(config);
  },
};
</script>

```
Now, you can run it in your Web Browser.

## Setup Meeting using `script` tag

### Step 1: Add script and setup the meeting

Create an `index.html` file and add the following `<script>` tag at the end of your code's `<body>` tag. Initialize `VideoSDKMeeting` after the script gets loaded. Replace the `apiKey` with the one generated in Previous Step [Signup & Create API Key](/docs/guide/prebuilt-video-and-audio-calling/signup-and-create-api).

```html title="index.html"
<script>
  var script = document.createElement("script");
  script.type = "text/javascript";

  script.addEventListener("load", function (event) {
    const meeting = new VideoSDKMeeting();

    const config = {
      name: "John Doe",
      apiKey: "<API KEY>", // generated in step 1
      meetingId: "milkyway", // enter your meeting id

      containerId: null,

      /**
       FEATURE ATTRIBUTES
      */
    };

    meeting.init(config);
  });

  script.src =
    "https://sdk.videosdk.live/rtc-js-prebuilt/0.2.6/rtc-js-prebuilt.js";
  document.getElementsByTagName("head")[0].appendChild(script);
</script>
```

### Step 2: Run the application

Install any http server if you don't already have one and run the server to join meeting from browser.

**node:**

```bash
$ npm install -g live-server
$ live-server --port=8000
```

and open [http://localhost:8000](http://localhost:8000) in your web browser

---

**python:**

```bash
$ python3 -m http.server
```

and open [http://localhost:8000](http://localhost:8000) in your web browser

---

**php:**

```bash
$ php -S localhost:8000
```

and open [http://localhost:8000](http://localhost:8000) in your web browser

---

**wamp:**

```
Move the html file to C:\wamp\www and start the WAMP server
```

and open [http://localhost/index.html](http://localhost/index.html) in your web browser

---

**xampp:**

```
Move the html file to C:\xampp\htdocs and start the XAMPP server
```

and open [http://localhost/index.html](http://localhost/index.html) in your web browser

![Prebuilt SDK Example to add video call widget in your web application](/img/prebuilt/prebuilt-grid.png)

:::tip

Stuck anywhere? Check out this [example code](https://github.com/videosdk-live/videosdk-rtc-js-prebuilt-embedded-example) on github or [download](https://github.com/videosdk-live/videosdk-rtc-js-prebuilt-embedded-example/archive/refs/tags/v0.1.1.zip) the full source code and unzip on your computer.

:::


---

# Dynamic Meeting Link - Prebuilt

If you don't want to have the same meeting id every time, you can generate a random id each time and use it. Let's see how it's done.

### Step 1. Create `createMeeting.html` and add `createMeeting()` function

Add a `<script>` which will contain `createMeeting()` which will create and redirect to a new meeting. And add this method to `onClick` of `<button>`

Your `<body>` should look something like this.

```js title="createMeeting.html"
<body>
  <script>
    // Function to create meeting ID
    function createMeeting() {
          let meetingId =  'xxxxyxxx'.replace(/[xy]/g, function(c) {
              var r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8);
              return v.toString(16);
          });
          console.log("http://"+ window.location.host + "?meetingId="+ meetingId)
          document.getElementById("copyInput").value = "https://"+ window.location.host + "/meeting.html?meetingId="+ meetingId;
    }

    // Function to copy the link
    function copyFunction() {
      /* Get the text field */
      var copyText = document.getElementById("copyInput");

      /* Select the text field */
      copyText.select();
      copyText.setSelectionRange(0, 99999); /* For mobile devices */

      /* Copy the text inside the text field */
      navigator.clipboard.writeText(copyText.value);
    }
  </script>
  <div>
    <button onclick="createMeeting()">Create Meeting</button>
    <br/>
    <input type="text" id="copyInput">
    <button onclick="myFunction()">Copy Link</button>
  </div>
</body>
```

### Step 2. Update your `meeting.html` to take the `meetingId` from the URL.

In this way, you will be able to access meetingId from the URL and each unique URL will work as different room

```js title="meeting.html"
//...
<script>

   script.addEventListener("load", function (event) {
      //Get URL query parameters
      const url = new URLSearchParams(window.location.search);

      //...

      const config = {
        // ...
        meetingId: url.get("meetingId"), // Get meeting id from params.
        // ...
      };

      const meeting = new VideoSDKMeeting();
      meeting.init(config);
    });

</script>

//...
```

## Step 3. Run and test

**node:**

```bash
$ npm install -g live-server
$ live-server --port=8000
```

and open [http://localhost:8000/createMeeting.html](http://localhost:8000/createMeeting.html) to create meeting URL

---

**python:**

```bash
$ python3 -m http.server
```

and open [http://localhost:8000/createMeeting.html](http://localhost:8000/createMeeting.html) to create meeting URL

---

**php:**

```bash
$ php -S localhost:8000
```

and open [http://localhost:8000/createMeeting.html](http://localhost:8000/createMeeting.html) to create meeting URL

---

**wamp:**

```
Move the HTML file to C:\wamp\www and start the WAMP server
```

and open [http://localhost/createMeeting.html](http://localhost:8000/createMeeting.html) to create meeting URL

---

**xampp:**

```
Move the HTML file to C:\xampp\htdocs and start the XAMPP server
```

and open [http://localhost:8000/createMeeting.html](http://localhost:8000/createMeeting.html) to create meeting URL


---

# Camera Controls - Prebuilt

Webcam control permissions allow the host to enable/disable their webcam along with other participants webcams as well as set default settings when the meeting starts.

### How it works ?

- While `participantCanToggleSelfWebcam` value is set to `true`, you can enable/disable your own webcam as display in below image.

- While `participantCanToggleSelfWebcam` value is set to `false`, the below webcam button will not appear.

![Go live with VideoSDK](/img/prebuilt/prebuilt-webcam.png)

### Camera Attributes

- `webcamEnabled`: Default webcam setting for meeting joinee, true enables webcam & false disable webcam.
- `participantCanToggleSelfWebcam`: Allow participant to enable/disable their own webcam.

```js title="index.html"
const config = {
  // ...
  webcamEnabled: true,
  participantCanToggleSelfWebcam: true,
  // ...
};
```

## Set webcam resolution

If you want to restrict the `webcam` stream quality of any participant that is being uploaded to server, you can use `maxResolution`.

### How it works ?

- `maxResolution` can be set to `sd` or `hd`. If it is `sd` then the upload resolution will be `360p` else if it is set to `hd` then it will be `720p`. By default it is set to `sd`.

### Max resolution Attributes

```js title="index.html"
const config = {
  // ...
  maxResolution: "sd", // "sd" or "hd"
  // ...
};
```


---

# Change Layout - Prebuilt

This feature allows participants to change layout in the meeting.

- `changeLayout` : If Set to true then participants can change their layout from an ongoing meeting by clicking on config button as shown in the following figure.

![prebuilt-grid](/img/prebuilt/configuration.png)

- `layout.type`: It should be a any of `GRID` or `SPOTLIGHT` or `SIDEBAR`, by default it is set to `GRID`.
- `layout.priority`: if set to `speaker` then speaker will get high priority even though someone else is pinned.Otherwise pin participate will get higher priority for layout.
- `layout.gridSize` : if `layout.type` set to `GRID` then participant can also set gridSize for the meeting screen . For example if gridSize set to 3 then only 3 participants will be appear on the meeting screen.

## Better understanding of Layouts

### 1. GRID Layout

This layout is default layout if no participants are pinned, it will look same as a normal meeting grid layout, when any participant is pinned that participant will be moved on top of the main screen grid above all non pinned participants

![prebuilt-grid](/img/prebuilt/prebuilt-grid.png)

While screenshare as well the main view will contain only screenshare media but the side panel view of participant grid will maintain same order of pinned and unpinned participants.

![prebuilt-grid-share](/img/prebuilt/prebuilt-grid-share.png)

### 2. SIDEBAR Layout

This layout will have one main screen view and other sidebar grid layout. Only pinned participant will be visible in this layout, all unpinned participants will not be visible in this layout. If more than one participant is pinned then the first participant who was pinned will appear in main screen layout and all other remaining pinned particiapants will be visible in sidebar.

![prebuilt-sidebar](/img/prebuilt/prebuilt-sidebar.png)

If any pinned participant started screenshare then the screenshare media will be visible in main screen layout and all other pinned participants webcam view will be visible in sidebar

![prebuilt-sidebar-share](/img/prebuilt/prebuilt-sidebar-share.png)

### 3. SPOTLIGHT Layout

This layout will only contain main screen layout, multiple pinned participants will be visible in main screen view. Same as `SIDEBAR` layout only pinned participants will be visible in main screen.

![prebuilt-spotlight](/img/prebuilt/prebuilt-spotlight.png)

If any pinned participant started screenshare then only screenshare view will be visible in main screen, no webcam view will be visible when any pinned participant started screenshare.

![prebuilt-spotlight-share](/img/prebuilt/prebuilt-spotlight-share.png)

### Layout attributes

```js title="index.html"
const config = {
  // ...
  permissions: {
    //other permissions
    changeLayout: true,
  },
  layout: {
    type: "SIDEBAR", // "SPOTLIGHT" | "SIDEBAR" | "GRID"
    priority: "PIN", // "SPEAKER" | "PIN",
    gridSize: 3,
  },
  // ...
};
```


---

# Customize Audio/Video - Prebuilt

We now have the option to customize the audio, video and screen sharing. This feature is used to pass resolution, optimization mode for associated audio, video, and screen sharing configuration.

Three different configurations will be covered in this guide.

1. [Custom Video Config](/prebuilt/guide/prebuilt-video-and-audio-calling/features/customize-audio-video#custom-video-config)
2. [Custom Audio Config](/prebuilt/guide/prebuilt-video-and-audio-calling/features/customize-audio-video#custom-audio-config)
3. [Custom Screen Share Config](/prebuilt/guide/prebuilt-video-and-audio-calling/features/customize-audio-video#custom-screen-share-config)

## Custom Video Config

This feature can be used to add custom video resolution, optimization mode (whether you want to focus on **motion**, **text** or **detail** of the video).

![Custom Video Resolution](/img/prebuilt/in-meeting-quality-stats.png)

### Custom Video Attributes

- `videoConfig.resolution`- You can set `resolution` value to `h360p_w640p`, `h540p_w960p`, `h720p_w1280p`, or `h1080p_w1920p`, by default the resolution is set to `h360p_w640p`. If you want to know more values of resolution then checkout this [Prebuilt SDK Referenece](/prebuilt/api/sdk-reference/parameters/advance-parameters/customize-audio-video#resolution).

- `videoConfig.optimizationMode` - You can focus on optimization by providing specific mode of the video (i.e. text, motion, etc.) to the `optimizationMode`, by default is set to `motion`.
- `videoConfig.multiStream` - If it is true, multiple resolution layers are send in single video stream. If it is false, then only single resolution layer is send in video stream, by default is set to true.

:::info

- For meetings with fewer than or equal to four participants, setting `multiStream:false` is regarded as best practice.
- This parameter is only available from v0.3.29.

:::

```js title="index.html"
const config = {
  // ...
  videoConfig: {
    resolution: "h720p_w1280p", //h360p_w640p, h540p_w960p, h1080p_w1920p
    optimizationMode: "motion", // text , detail
    multiStream: true,
  },
  // ...
};
```

### How it works ?

- The network icon of the user video tile, as seen below, will display the video resolution configuration that you have specified.


<div style={{textAlign: 'center'}}>



</div>

## Custom Audio Config

This feature can be used to set the quality of audio and send it to other participants.

### Custom Audio Attributes

- `audioConfig.quality`- You can set `quality` value to `speech_low_quality` , `speech_standard` or `high_quality` , by default quality is set to `speech_standard`.
  If you want to know more values of quality then checkout this [Prebuilt SDK Referenece](/prebuilt/api/sdk-reference/parameters/advance-parameters/customize-audio-video#quality).

```js title="index.html"
const config = {
  // ...
  audioConfig: {
    quality: "speech_standard", //speech_low_quality , high_quality
  },
  // ...
};
```

## Custom Screen Share Config

This feature can be used to add custom screen sharing resolution, optimization mode (whether you want to focus on **motion**, **text** or **detail** of the video) and send it to other participants.

### Custom Screen Share Attributes

- `screenShareConfig.resolution`- You can set `resolution` value to `h360p_30fps` , `h720p_5fps` or `h1080p_15fps` of screen shared video , by default resolution is set to `h720p_15fps`. If you want to know more values of resolution then checkout this [Prebuilt SDK Referenece](/prebuilt/api/sdk-reference/parameters/advance-parameters/customize-audio-video#resolution-1).

- `screenShareConfig.optimizationMode` - You can focus on optimization by providing specific mode of the video (i.e. text, motion, etc.) to the `optimizationMode`, by default is set to `motion`.

```js title="index.html"
const config = {
  // ...
  screenShareConfig: {
    resolution: "h720p_15fps", // h360p_30fps , h720p_5fps, h1080p_15fps
    optimizationMode: "text", // motion , detail
  },
  // ...
};
```


---

# Branding Logo - Prebuilt

This feature allows you to embed your branding to top of the meeting .

### How it works ?

- While `branding.enabled` value is set to `true`, you will see branding as shown in below image.

- While `branding.enabled` value is set to `false`, the branding will not appear.

![Go live with VideoSDK](/img/prebuilt/prebuilt-branding.png)

### Branding Attributes

- `branding.enabled`: If it is true, then branding will be visible on top bar of the meeting. If it is false, then branding won't be available on top bar of the meeting.
- `branding.logoURL`: Provide public URL of your logo. Keep the resolution of logo `400px * 400px`.
- `branding.name`: Provide your brand title.
- `branding.poweredBy`: If it is true, then `Powered by videosdk.live` text will appear in bottom of the branding. If it is false, then text will not appear in bottom of the branding

:::note

If you set `branding.enabled` true, then you should have to provide `branding.logoURL` and `branding.name`.

:::

```js title="index.html"
const config = {
  // ...
  branding: {
    enabled: true,
    logoURL:
      "https://static.videosdk.live/videosdk.live/videosdk_logo_circle_big.png",
    name: "Prebuilt",
    poweredBy: false,
  },
  // ...
};
```


---

# Customize Permissions - Prebuilt

This feature allows you to control meeting join, webcam and mic permissions for participants.

### Permissions Attributes

- `askToJoin`: If it is true, then participant will require to take permission before joining the meeting. If it is false, then participant will directly join meeting without any permission.

- `toggleParticipantMic`: If it is true, then participant can disable mic of other participants, but it will ask for permission when enabling mic. If it is false, then participant can not toggle mic of other participants.

- `toggleParticipantWebcam`: If it is true, then participant can disable webcam of other participants, but it will ask for permission when enabling webcam. If it is false, then participant can not toggle webcam of other participants.

- `toggleParticipantScreenshare`: If it is true, then participant can disable screen share of other participants, but it will ask for permission when enabling screen share. If it is false, then participant can not toggle screen share of other participants.

:::note

- While using `askToJoin` attribute, configuration for meeting initiator (You) and other participants will be different.
  If you are meeting initiator then you must set `askToJoin` false, otherwise you won't be able to join the meeting.
- If `askToJoin` set to true, any given permissions for `toggleParticipantMic` , `toggleParticipantWebcam` and `toggleParticipantScreenshare` will be ignored.

:::

```js title="index.html"
const config = {
  // ...
  permissions: {
    askToJoin: false,
    toggleParticipantWebcam: false,
    toggleParticipantMic: false,
    toggleParticipantScreenshare: false,
  },
  // ...
};
```

- Permission (Join / Mic / Webcam) pop up will appear as describe in below image.

![Go live with VideoSDK](/img/prebuilt/prebuilt-permission.png)


---

# Debug Mode - Prebuilt

This feature allows SDK to raise error pop up for providing invalid parameter during SDK integration.

## How it works ?

- While `debug` value set to `true`, and you have provided invalid parameter in config object, you can get a pop-up related to that error.

- **For example**, you have provided invalid API key in config object, now it will raise error pop up as below image.

![error-pop-up-1](/img/prebuilt/error-pop-up-1.png)

- While `debug` value set to `false`, and you have provided invalid parameter in config object, you can get a pop-up, but it will not specify an exact error.

- **For example**, your account discontinued for some reason, now it will not raise error related to account discontinue, but it will display as below image.

![error-pop-up-2](/img/prebuilt/error-pop-up-2.png)

By default, `debug` value is `false`.

### Debug Mode attributes

```js title="index.html"
const config = {
  // ... other configuration
  debug: true, // false
  // ...
};
```


---

# End Meeting - Prebuilt

This feature allows any participant to end meeting.

## How it works ?

- When `endMeeting` value is set to `true`, you will be able to see options as displayed in image below. Ending the meeting makes all participants leave the meeting.

![End meeting button](/img/prebuilt/prebuilt-end-meeting.png)

### End Meeting attributes

```js title="index.html"
const config = {
  // ... other configuration
  permissions: {
    // ... other permissions
    endMeeting: true,
  },
  // ...
};
```


---

# Go Live On HLS - Prebuilt

HLS allows participant to broadcast live streaming to other participants.
This guide will provide an overview of how participant can start and stop broadcasting meeting.

### HLS attributes

- `mode`: It should be any of `VIEWER` or `CONFERENCE`, by default is set to `CONFERENCE`
- `toggleHLS` : When set to `true` it will enable you to click on `Start HLS` button.
- `hls.enabled` : When set to `true` , you can see `Start HLS` button.
- `hls.autoStart`: If it is `true` then HLS will start automatically when the meeting starts, default value is false (You can't start HLS during the meeting).
- `hls.theme`: It will HLS the meeting based on theme you are passing. it can be a either DARK , LIGHT or DEFAULT.
- `hls.playerControlsVisible` : If it is `true` then participant can view controls for the interactive meeting player.
- `toggleParticipantMode`: When set to `true`, you can toggle other participant mode from an ongoing meeting by clicking on `Add as a Cohost` Icon button.

:::note

`hls.playerControlsVisible` parameter will only work if the mode is set to `viewer`, for `conference` mode there will not be any interactive meeting player hence `hls.playerControlsVisible` will be ignored if mode is set to `conference`.

:::

## Better Understanding of Modes

### 1. CONFERENCE Mode

This mode is default mode if you do not give any mode, it will look similar as a normal meeting. when you pass `hls.enabled` true you can see `Start HLS` button. if you want to toggle the button then in `permission` config pass other parameter `toggleHLS` true so you can toggle button.

![Go live on Videosdk](/img/prebuilt/prebuilt-join-as-cohost.png)

In `CONFERENCE` mode you can toggle other participant mode also. like you can add other participant as a co-host. for that you need to pass parameter `toggleParticipantMode` true in `permission` config.

You can click on more button to see add as co-host icon.

![Go live on Videosdk](/img/prebuilt/More.png)

![Go live on Videosdk](/img/prebuilt/Add-as-a-cohost.png)

When you click on `Add as a Co-host` button other participant recive popup. whethere participant can accept or deny. if you accept than only participant add as a cohost.

![Go live on Videosdk](/img/prebuilt/prebuilt-mode-popup.png)

```js title="conference.html"
const config = {
  // ...
  hls: {
    enabled: true,
    autoStart: false,
    theme: "DARK", // DARK || LIGHT || DEFAULT
  },
  permissions: {
    //  ...other permissions
    toggleParticipantMode: true,
    toggleHls: true,
  },
  mode: "CONFERENCE", // VIEWER || CONFERENCE
  // ...
};
```

### 2. VIEWER Mode

You can join meeting as a viewer. in this mode when you join the meeting you can see the waiting screen.

![Go live on Videosdk](/img/prebuilt/prebuilt-join-as-viewer.png)

when host start HLS you can get hls stream in your player and you can see that stream. as a viewer you can do raise hand, chat and leave the meeting.

![Go live on Videosdk](/img/prebuilt/prebuilt-join-as-viewer-view.png)

```js title="viewer.html"
const config = {
  // ...
  hls: {
    playerControlsVisible: true,
  },
  mode: "VIEWER", // VIEWER || CONFERENCE
  // ...
};
```


---

# Go Live On Social Media - Prebuilt

Livestreaming allows participant to broadcast meeting on various social media platforms such as Facebook or Youtube.
This guide will provide an overview of how participant can start and stop broadcasting meeting.

![Go-Live](/img/prebuilt/go-live.png)

## Live streaming flow

1. Click on `More Options` Button you can find `Add Live Streams` selection option.

![Go-Live](/img/prebuilt/more-options.png)

2. Add your streaming platforms there.
3. Now one can live their streams on different platforms by hitting `Go Live` button.

### Live streaming attributes

- `toggleLivestream` : When set to true it will enable you to add your streaming platform details when you click on `Add Live Streams` button.
- `liveStream.enabled` : When set to true , one can go live otherwise one has no permission to go live even if live streaming platforms has been added.
- `liveStream.autoStart`: If it is true then live streaming will start automatically when the meeting starts, default value is false (You can't start live streaming during the meeting).
- `liveStream.theme`: You can provide theme when you live streaming the meeting . it can be a either DARK , LIGHT or DEFAULT.

:::note

keep **liveStream.enabled** and **toggleLivestream** **true** in order to see `Add Live Stream` button

:::

```js title="index.html"
const config = {
  // ...

  permissions: {
    //other permissions
    toggleLivestream: true,
  },
  livestream: {
    autoStart: true,
    enabled: true,
    theme: "DARK", // DARK || LIGHT || DEFAULT
  },
  // ...
};
```


---

# Join Screen - Prebuilt

After the successful installation of VideoSDK prebuilt, the next step is to integrate VideoSDK prebuilt features with your webApp.

To Communicate with other participant's audio or video call, you will need to join the meeting.

This guide will provide an overview of how to setup join feature in VideoSDK prebuilt.

## How it works ?

- While JoinScreen `visible` value is set to `true`, the below screen will display before the meeting start.

![Go live with VideoSDK](/img/prebuilt/prebuilt-join-screen.png)

- While JoinScreen `visible` value is set to `false`, the below screen will display before the meeting start and you have to click any where to start the meeting.

![Go live with VideoSDK](/img/prebuilt/prebuilt-click-anywhere.png)

### Join Screen Attributes

To configure join screen feature, you need to add join screen object in meeting config.

`joinScreen` object has following attributes:

- `visible`: If you want to show join screen before the start of the meeting set it `true `otherwise `false`.

- `title`: Meeting title.
- `meetingUrl`: Meeting join url, where your meeting will be hosted.

```js title="index.html"
const config = {
  // ...
  joinScreen: {
    visible: true,
    title: "Daily scrum",
    meetingUrl: "customURL.com",
  },
  // ...
};
```


---

# Left Screen - Prebuilt

- Left screen will be shown when participant left the meeting if `redirectOnLeave` parameter is not provided while initializing the meeting.

## How it works ?

- While Leftscreen `redirectOnLeave` value is set to `null`, the below screen will display when any participant left the meeting.

![Meeting Left screen prebuilt](/img/prebuilt/prebuilt-left-screen.png)

### Left Screen Attributes

To configure left screen feature, you need to add lefts screen object in meeting config.

`leftScreen` object has following attributes:

- `actionButton` objecet has following attributes

  - `label`: Action button label

  - `href`: Action button href

- `rejoinButtonEnabled`: If it is set to true then rejoin button will be appeared on the screen else it will be nonapparent.

```js title="index.html"
const config = {
  // ...
  leftScreen: {
    actionButton: {
      label: "Video SDK",
      href: "https://videosdk.live/",
    },
    rejoinButtonEnabled: true,
  },

  // ...
};
```


---

# Live Poll - Prebuilt

Using this feature a host can create polls and guest participant can submit their opnions on that poll. This guide will provide an overview of how participant can create poll.

## Poll attributes

- `canCreatePoll` : When set to `true`, you can create a poll in the meeting.

### How it works ?

- On Click of `More Options` Button you can find `Polls` selection option.

![Go live with VideoSDK](/img/prebuilt/Polls.png)

- When you pass `canCreatePoll` parameter `true` you can create poll.

![Go live with VideoSDK](/img/prebuilt/create-poll.png)

- Guest Participant can submit their opnions on the poll and can also see the result of their previous submitted polls as shown in image.

![Go live with VideoSDK](/img/prebuilt/poll-list.png)

```js title="index.html"
const config = {
  // ...
  permissions: {
    //  ...other permissions
    canCreatePoll: true,
  },
  // ...
};
```


---

# Mic Controls - Prebuilt

Different mic control permissions allows participant to enable/disable their own mic and other participant's mic too & also can set default participant's mic settings, when meeting start.

## How it works ?

- While `participantCanToggleSelfMic` value is set to `true`, you can enable/disable your own mic as display in below image.

- While `participantCanToggleSelfMic` value is set to `false`, the below mic button will not appear.

![Go live with VideoSDK](/img/prebuilt/prebuilt-mic.png)

### Mic Attributes

- `micEnabled`: Default mic setting for meeting joinee, true enables mic & false disable mic.
- `participantCanToggleSelfMic`: Allow participant to enable/disable their own mic.

```js title="index.html"
const config = {
  // ...
  micEnabled: true,
  participantCanToggleSelfMic: true,
  // ...
};
```


---

# AI Noise Removal (BETA) - Prebuilt

With AI Noise Removal, you can filter out your background noise and make your virtual communication as smooth as face-to-face communication.

## How to Turn On AI Noise Removal?

You can find `AI Noise Removal` option inside `Microphone options` Modal.

By selecting `AI Noise Removal`, other user can hear your voice with minimum background noise.

![Noise Removal on Videosdk](/img/prebuilt/ai-noise-removal.jpg)

:::note

AI Noise Removal feature is supported from `0.3.21` version.

:::


---

# Pin Participants - Prebuilt

This feature allows participants to pin self or other participants in the meeting.

- `permissions.pin`: If it is true then that participant can pin or unpin other participants in the meeting, by default it is set to `false`.

## Pin attributes

```js title="index.html"
const config = {
  // ...
  permissions: {
    pin: true,
  },
};
```


---

# Real-Time Transcription

Real-time transcription allows participants to transcribe audio into text during a meeting session. This feature enhances accessibility and enables better meeting documentation.

## How It Works

When participants speak during a meeting, their speech is transcribed into text in real-time and displayed on the screen as captions. This ensures better accessibility and engagement for all participants.

![Transcription Button UI Example](/img/transcription/realtime-transcription.png)

## Configuration Parameters

| **Parameter**                       | **Type** | **Default** | **Description**                                                                 |
|-------------------------------------|----------|-------------|---------------------------------------------------------------------------------|
| `realtimeTranscription.enabled`     | Boolean  | `false`     | Enables or disables real-time transcription during the meeting.                 |
| `realtimeTranscription.visible`     | Boolean  | `false`     | Controls the visibility of the transcription button in the UI.                  |
| `permissions.toggleRealtimeTranscription` | Boolean | `false`     | Allows participants to start or stop real-time transcription during the meeting.|

## Example Configuration

```js title="index.html"
// Transcription Configuration
const config = {
  realtimeTranscription: {
    enabled: true, // Enables real-time transcription
    visible: true, // Shows transcription button in UI
  },
  permissions: {
    toggleRealtimeTranscription: true, // Allows participants to toggle transcription
  },
};
```
:::note
To enable transcription in specific languages, use the **[Start a Realtime Transcription - API](https://docs.videosdk.live/api-reference/realtime-communication/start-realtime-transcription)** with the body parameter `language`

:::

---

# Record Meeting - Prebuilt

Record meeting allows participants to record video & audio during the meeting. The recording files are available in customer dashboard.
Any participant can start/stop recording any time during the meeting.

## How it works ?

- While `recording.enabled` value is set to `true`, you will show recording button as display in below image.

- While `recording.enabled` value is set to `false`, the below recording button will not appear.

![Go live with VideoSDK](/img/prebuilt/prebuilt-recording.png)

### Recording Attributes

- `recording.enabled`: If it is true, then recording button will be visible on top bar of the meeting. If it is false, then recording button won't be available on top bar of the meeting.
- `toggleRecording`: If it is true, then other participant can start/stop recording during the meeting. If it is false, then participant can not start/stop recording during the meeting.
- `recording.webhookUrl`: It's your [webhook url](https://en.wikipedia.org/wiki/Webhook), where we notify once meeting recording is complete.
- `recording.theme`: It will record the meeting based on theme indicated. it can be a either DARK , LIGHT or DEFAULT.
- `recording.autoStart`: It will auto start recording when participant joined
- `recording.awsDirPath`: It indicates where the recording will get stored.
- `recording.layout.type` : It will record the meeting based on layout type indicated.
- `recording.layout.priority` : It will prioritise the view of either pin participant or speaker participant for recording.
- `recording.layout.gridsize` : It will indicates number of participants shown on the screen.

```js title="index.html"
const config = {
  // ...
  recording: {
    enabled: true,
    webhookUrl: "https://www.videosdk.live/callback",
    // awsDirPath: `/meeting-recordings/${meetingId}/`, // Pass it only after configuring your S3 Bucket credentials on Video SDK dashboard
    autoStart: false,
    theme: "DARK", // DARK || LIGHT || DEFAULT

    layout: {
      type: "SIDEBAR", // "SPOTLIGHT" | "SIDEBAR" | "GRID"
      priority: "PIN", // "SPEAKER" | "PIN",
      gridSize: 3,
    },
  },

  permissions: {
    toggleRecording: true,
    //...
  },

  //...
};
```


---

# Redirect on Leave - Prebuilt

Whenever participant wishes to end their communication in the meeting, they can simply leave the meeting.

## Leave Meeting Attributes

- **participantCanLeave**: If it is true, then end meeting button will be visible on top right bar of the meeting. If it is false, then end meeting button won't be available on top right bar of the meeting.
- **redirectOnLeave**: It's URL where you want to redirect participant after leave the meeting,**OPTIONAL**.

```js title="index.html"
const config = {
  // ...
  participantCanLeave: true,
  redirectOnLeave: "https://www.videosdk.live/",
  // ...
};
```


---

# Remove Participant - Prebuilt

This feature will allow any participant to remove other participant in the meeting.

## How it works ?

- When `removeParticipant` value is set to `true`, you will be able to see remove participant icon in participants panel. By clicking you will be able to remove the participant from meeting.

![Remove participant button](/img/prebuilt/Remove-participant.png)

### Remove Participant attributes

```js title="index.html"
const config = {
  // ... other configuration
  permissions: {
    // ... other permissions
    removeParticipant: true,
  },
  // ...
};
```


---

# Share Your Screen - Prebuilt

Screen sharing allows any participant who wants to share either the complete screen, a specific window or, a browser tab during the meeting.

## How it works ?

- While `screenShareEnabled` value is set to `true`, you will show screen share button as display in below image.

- While `screenShareEnabled` value is set to `false`, the below screen share button will not appear.

![Go live with VideoSDK](/img/prebuilt/prebuilt-screen-share.png)

### Screen Share Attributes

- `screenShareEnabled`: If it is true, then screen share button will be visible on top bar of the meeting. If it is false, then screen share button won't be available on top bar of the meeting.

```js title="index.html"
const config = {
  // ...
  screenShareEnabled: true,
  // ...
};
```

### Screen Share with Audio

To do screen share with audio, select the **Share tab audio** option when sharing the chrome tab as shown below.

<center>

![Screen Share with Audio](/img/screenshare-with-audio.png)

</center>

:::note

Screen Share with Audio feature is only supported while **sharing chrome tab on Google Chrome** browser only.

:::


---

# Send Messages - Prebuilt

This feature allows participants who wants to notify other participants via chat messages or Raise hand in the meeting.

## Chat

If a participant wants to inform or notify something in current meeting,
they can use this feature to communicate with other participants in the meeting.

- `chatEnabled`: If it is true, then chat button will be visible on top bar of the meeting. If it is false, then chat button won't be available on top bar of the meeting.

  ![Go live with VideoSDK](/img/prebuilt/prebuilt-chat.png)

### Raise hand

It allows participant to raise their hand virtually to indicate that participant has some doubts or comment during the meeting.

- `raiseHandEnabled`: If it is true, then raise hand button will be visible on top bar of the meeting. If it is false, then raise hand button won't be available on top bar of the meeting

  ![Go live with VideoSDK](/img/prebuilt/prebuilt-raise-hand.png)

```js title="index.html"
const config = {
  // ...
  chatEnabled: true,
  raiseHandEnabled: true,
  // ...
};
```


---

# Theme - Prebuilt

Using this feature you can change your prebuilt SDK theme to either `DARK` or `LIGHT`.

## Theme attributes

- `theme` : You can set `theme` attribute to either `DARK` , `LIGHT` or `DEFAULT`, by default theme is set to `DEFAULT`.

### How it works ?

- When you set the value of `theme` parameter to `DARK` your prebuilt theme switches to a dark theme.

![Go live with VideoSDK](/img/prebuilt/dark-theme.jpg)

- When you set the value of `theme` parameter to `LIGHT` your prebuilt theme switches to a light theme.

![Go live with VideoSDK](/img/prebuilt/light-theme.jpg)

```js title="index.html"
const config = {
  // ...
  theme: "DARK", // DARK || LIGHT || DEFAULT
  // ...
};
```


---

# Understanding Analytics Dashboard - Prebuilt

Welcome to the world of actionable insights and empowered decision-making. VideoSDK's session analytics dashboard is your gateway to understanding, optimizing, and elevating every aspect of your sessions.

## Accessing Analytics Made Easy

Navigating through session data is a breeze with VideoSDK. Simply head to your session page at https://app.videosdk.live/meetings/sessions, where a treasure trove of session information awaits.

### How to Access Analytics?

Open Session Analytics effortlessly by following these steps:

1. **Click on Meeting-ID:**
    - Directly access analytics by clicking on the meeting-ID within the session table.
2. **Hover and Click View Analytics:**
    - Hover over a specific meeting row to reveal the **View Analytics** button in the Actions Column.
    - Click on **View Analytics** to open the Session Overview sidebar, unlocking a wealth of insights.

![Access Analytics](https://cdn.videosdk.live/website-resources/docs-resources/access_analytics.png)

---

There are three tabs available within the session analytics view:

## **1. Session Overview**

This tab provides an overview of the session, including its duration and participant details. You can explore individual participant statistics to understand their session performance better.

## **2. Errors**

In this tab, you can find information about any errors encountered during the session. It helps you identify and address issues like network problems or technical glitches promptly.

:::note

Session errors are visible with JS SDK v0.0.82 or higher, React SDK v0.1.85 or higher, and React Native v0.1.6 or newer versions.

:::

## **3. Session Stats**

Explore data and metrics sent and received by participants to measure performance of the session in this tab. It offers insights into data exchange among participants, including metrics on jitter, RTT, and packet loss, resolutions, and fps aiding in assessing communication efficiency.

Let's dive deeper into each of these tabs to gain a better understanding of session analytics.

# Session Overview

The session overview page is your compass in the sea of data. Here's what you'll uncover:

- **Meeting ID:** Unique identifier for the meeting in the format of `abcd-efgh-ijkl`.
- **Session ID:** Unique identifier for each session, uniquely identified by its `sessionId`.
- **Session Status:** Indicates if the session is ongoing or ended.
- **Session Initiating Time:** Time taken by the first participant to establish the connection.
- **Start and End Time:** Marks the start and end of the session.
- **Total Unique Participants Joined:** Total number of unique participants in the session.
- **Total Session Duration:** Overall duration of the session from start to end.
- **Total Participant Minutes:** A sum of all participant duration.
- **Recording, HLS, RTMP:** Additional services used in the session.

### Participant Table List

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for each participant.
- **Join Time:** Time taken by the participant to establish connection.
- **Duration:** Total time spent by this participant in the session.

### Efficient Session Management with Actions

Enhance your session management with streamlined actions:

- **Kick Out Participants:** Effortlessly remove/kickout participants from ongoing sessions.
- **Detailed Participant Analytics:**
- Hover over a specific participant row to reveal the `View Stats` button at the end of the row.
- Click on `View Stats` to open the Participant Overview sidebar.
    
![View Stats](https://cdn.videosdk.live/website-resources/docs-resources/view_stats.png)

## Explore Participant Insights

Discover valuable participant data that provides a clear view of engagement and experience:

- **Participant ID:** Unique identifier for each participant.
- **Participant Name:** Personalized identification for better interaction.
- **Joined At:** Indicates the precise moment when participant connects to the session.
- **Left At:** Indicates the precise moment when participant left the session.
- **Total Duration:** Total duration of participant within that session.
- **Joining Time:** Time taken by the this participant to establish the connection.
- **Location:** Approx. geographic location from where the participant joined.
- **Platform:** Specifies whether participants are using a desktop or mobile device.
- **Device Info:** Offers details regarding the participant's device.
- **OS:** Provides information about the participant's OS.
- **Browser:** Provides specifics about the participant's browser
- **SDK Version:** Indicates the version of the SDK used by participants.

### Understanding Participant Call Health

We've developed call health to offer a rapid assessment of participant performance during calls. This feature highlights the performance of audio, video, and screen sharing audio-video separately. We've utilized color theory, with green indicating good performance, orange for moderate, and red for poor performance, to enhance clarity. For detailed insights, simply hover over the bars

![Participant Call Health](https://cdn.videosdk.live/website-resources/docs-resources/participant_call_health.png)

## Participant Session Stats

Dive into Participant Session Stats for valuable insights into your session experience! With just a click on `View Session Stats` at the bottom of the page, unlock a treasure trove of data crucial for understanding audio and video experiences.

Within this section, you can observe quality metrics for the selected participant, comparing them to others. Additionally, the `Sessions Stats` covers quality stats comparison for every participant. Keep reading to explore more about Session Stats.

**Visualizing Session Performance from Both Sides**

This section provides a two-sided view of your session's metrics.

- **Left Side: Sender Participant Graph** This section displays graphs representing the metrics sent by the sender participant.. Here, you can see how the various factors impacted the data you transmitted.
- **Right Side: Receiver Participant Graph** On the right side, you'll find a dropdown menu where you can select a specific participant. Choosing a receiver will display graphs showcasing the metrics **received by that participant**. This allows you to compare the sending experience (left side) with the receiving experience (right side) for different participants.

![VideoSDK Jitter Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_jitter_graph.png)

**See How Your Session Performed**

These metrics give you a clear picture of your session's quality. Understanding them helps you spot any issues and keep things running smoothly. Let's dive into what each metric means!

**Jitter:** Imagine your internet connection like a bumpy road. Jitter is how much those bumps cause your signal to bounce around. Less jitter means a smoother ride for your data (audio and video, threshold ≤ 30ms).

**RTT (Latency):** This is how long it takes for data to travel between you and the server you're connected to. Think of it like the time it takes for a message to get delivered – a lower RTT means a faster delivery (affects both audio and video, threshold ≤ 300ms).

**Bitrate:** This measures the amount of data flowing through your connection per second. Imagine it like the width of a water pipe – a higher bitrate allows for more data to flow, which can be good for high-quality audio/video or fast downloads.

**Packet Loss:** Think of data traveling in tiny packets. Packet loss is when some of those packets get dropped along the way. More packet loss means information might be missing, affecting things like audio/video quality or lag in games (threshold ≤ 5%).

**Resolution:** This refers to the sharpness and detail of an image or video. Think of it like the number of pixels on your screen – a higher resolution means a crisper picture (**Video Only**).

**FPS (Frames Per Second):** This measures how many images (frames) are displayed on your screen every second. Imagine it like a flipbook – a higher FPS creates a smoother and more fluid animation or video experience (**Video Only**).

![VideoSDK FPS Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_fps_graph.png)

![VideoSDK Resolution Graph](https://cdn.videosdk.live/website-resources/docs-resources/video_resolution_graph.png)

---

# **Analyse Session Stats**

Similar to `Participant Session Stats`, this tab covers quality statistics sent by individual participants. You can select any participant to compare effectively with others.

Choose a sender participant from the dropdown menu on the left and select a recipient on the right to compare data over different time frames. This allows you to identify and explore issues within specific durations.

This tab covers the same metrics as covered in the `participant session stats`: Jitter, RTT (Latency), Bitrate, Packet-loss, Resolution (Video only), and FPS (Video only).

![VideoSDK Session Stats](https://cdn.videosdk.live/website-resources/docs-resources/session_stats.png)


---

:::important

Virtual background feature is supported from `0.3.21` version.

:::

# Virtual Background- Prebuilt

You can personalise the background of your video call by blurring it or by replacing it with a static image.

### How it works ?

- When `toggleVirtualBackground` value is set to `true`, you will be able to see `Virtual Background` option inside `More Options` Tab Panel as displayed in image below. By default it is set to `true`.

![Virtual Background on Videosdk](/img/prebuilt/virtual-background-option.jpg)

:::note

- Currently, This feature is only available on Google Chrome, Safari, Firefox and Brave browser.


:::

## Apply Virtual Background

### 1. Blur Effect

By selecting blur effect, background of your video will be blurred.

![Virtual Background on Videosdk](/img/prebuilt/blur.jpg)

### 2. Custom Image Background

You can set static image as your video background by choosing any of the images provided in the list.

![Virtual Background on Videosdk](/img/prebuilt/background.jpg)

### 3. Remove Virtual Background Effect

By clicking on &#128683; , you can remove the blur effect or any custom image if applied.

![Virtual Background on Videosdk](/img/prebuilt/no-filter.jpg)

:::note

It will take 4-5 seconds to reflects the changes. Virtual background experience will be better untill 3-4 participants are using it.

:::

## Virtual Background attributes

```js title="index.html"
const config = {
  // ...
  permissions: {
    // ...
    toggleVirtualBackground: true,
  },
  // ...
};
```


---

# Waiting Screen - Prebuilt

After the successfull integrating VideoSDK prebuilt features with your webApp, after joining the meeting you can see waiting screen.

This guide will provide an overview of how to do customize waiting screen feature in VideoSDK prebuilt.

### How it works ?

- You have to pass public URL of your image or lottie in `imageUrl` param that you want to display on your waiting screen.

- Then pass your customize message in `text` param that you want to display on your waiting screen.

:::note

It is not compulsory to pass both paramaters. If you want to display just an image or a text you can pass parameters accordingly.

If you do not pass any of the parameters it will display the default waiting screen.

:::

![Go live with VideoSDK](/img/prebuilt/waiting-screen.png)

### Waiting Screen Attributes

To configure waiting screen feature, you need to add waiting screen object in meeting config.

`waitingScreen` object has following attributes:

- `imageUrl`: Provide public URL of your image or lottie.

- `text`: Provide your message.

```js title="index.html"
const config = {
  // ...
  waitingScreen: {
    imageUrl: "<imageUrl || lottieUrl>",
    text: "Connecting to the meeting...",
  },
  // ...
};
```


---

# Whiteboard - Prebuilt

This feature allows participants to explain their thoughts to other participants by drawing on an interactive whiteboard.

### How it works ?

- When `whiteboardEnabled` value is set to `true`, you will be able to see whiteboard option inside `More Options` Tab Panel as displayed in image below. By Clicking that you can start Whiteboard.

![whiteboard button](/img/prebuilt/Whiteboard.png)

- When `drawOnWhiteboard`: value is set to `true`, you will be able to draw on whiteboard, by default it is set to `true`.

- When `toggleWhiteboard`: value is set to `true`, you will be able to start or stop whiteboard, if it is false whiteboard button will be displayed but you can not start or stop whiteboard. By default it is set to `true`.

![whiteboard demo](/img/prebuilt/prebuilt-whiteboard-open.png)

### Whiteboard attributes

```js title="index.html"
const config = {
  // ...
  whiteboardEnabled: true,
  permissions: {
    // ...
    drawOnWhiteboard: true,
    toggleWhiteboard: true,
  },
  // ...
};
```


---

# Whitelist Domain For Better Security - Prebuilt

You can secure your prebuilt by using **Domain Whitelisting** feature in dashboard.

**Domain Whitelisting** is a method of ensuring that no one but your organization is using your prebuilt. It’s one way of securing prebuilt, so others don’t attempt to piggy back on your account.

## How to Whitelist domain ?

### Step : 1 API Listing

First of all, you need to generate API key from [Dashboard](https://app.videosdk.live/dashboard), for generating API key you need to follow [Signup and Create API Key](/docs/guide/prebuilt-video-and-audio-calling/signup-and-create-api).

After genearting API, you will see your [API List](https://app.videosdk.live/settings/api-keys) as describe below.

In **Action** column, click on globe icon.

![Go live with VideoSDK](/img/api-keys.png)

### Step : 2 Add Domain

After clicking earth icon, sidebar popup will appear which prompt you to add domain name.

After adding domain name in textinput, just click on **ADD** button, which placed on right side of the textinput.

For example, if you add _**testing**_ as your domain name, now it will restrict other domain (except _**testing.com**_) to access prebuilt.

You can also add more than one domain under the same API key.

![Go live with VideoSDK](/img/add-domain.png)

:::note

1. If you don't provide any domains under whitelisting, then you can acess prebuilt with any domain name.
2. If you have already added some domains, and you want to use **localhost** as development purpose, then for developing you should have to add **localhost** as domain name under whitelisting.
3. For subdomain cases, suppose you have **abc.xyz.com**, for this case you can't list your domain name as **xyz**. You should have to add it as **abc.xyz** in whitelisting.

:::

### Step : 3 Delete Domain

You can also delete the listed domain by pressing cross icon as described below.

![Go live with VideoSDK](/img/delete-domain.png)


---

# Prebuilt SDK Overview

Video SDK enables easy to use one-to-one and group call support with voice only and voice + video call modes.

:::important

A maximum of 50 participants can be added in one room.
And a maximum of 15 videos can be turned ON in a single room.
If your application necessitates a higher quota, please [**Contact Us**](https://www.videosdk.live/contact)

:::

## Features

| Functions            | Description                                                                         |
| -------------------- | ----------------------------------------------------------------------------------- |
| Audio and Video Call | Send and receive local and remote videos and audio from multiple participants       |
| Screen Sharing       | Enables the user to share the screen to other users in the room.                    |
| Rich Chat            | Enables the user to send messages .                                                 |
| RTMP Streaming       | Enables going live to RTMP compatible streaming services such as YouTube or Twitch. |
| Cloud Recording      | Record and store composed cloud recordings to your favorite storage provider.       |
| Dynamic Layout       | Chage layout of meeting, recording and live streaming on-fly.                       |
| HLS Streaming        | HLS Streaming allows for scaling to millions of viewers in near real time.          |

## Known issues

| Version | Impact                                                |
| ------- | ----------------------------------------------------- |
| 1.x.x   | Blackout videos in newer version of safari and chrome |

# Getting Started with Prebuilt Video & Audio Calling

Prebuilt SDK is an easy-to-use video meeting SDK. Embed video meetings into an application or website with the API allowing your team to build faster and ship more often.

# Steps


<div class="container guide-steps-block">
  <div class="row ">
    <div class="col col--6">
      
    </div>
    <div class="col col--6" >
      
    </div>
  </div>
  <div class="row " >
    <div class="col col--6">
      
    </div>
    <div class="col col--6">
      
    </div>
  </div>

  <div class="row " >
    <div class="col col--6">
      
    </div>
    <div class="col col--6">
      
    </div>
  </div>
</div>




---

Prebuilt SDK enables the opportunity to integrate real-time video & audio communication SDK without writing explicit code. It just requires 10 minutes to integrate.

### Prerequisites

:::important

One should have a VideoSDK account to generate a token.
Visit VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate token

:::

## Permissions

In order to embed VideoSDK in Android, add these permissions to the manifest:

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

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

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

### Embeding Prebuilt in Android

You will need to use the [WebView](https://developer.android.com/reference/android/webkit/WebView) class.

1. We will start by creating a web view and setup some javascript settings on it.

```js
public class MainActivity extends AppCompatActivity {

    private WebView myWebView;

    @SuppressLint("SetJavaScriptEnabled")
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        myWebView = new WebView(this);
        setContentView(myWebView);

        WebSettings webSettings = myWebView.getSettings();
        webSettings.setJavaScriptEnabled(true);

    }
}
```

2. We need to setup a `WebChromeClient` for the webview which will handle the permissions of audio and video of the user.

```js
public class MainActivity extends AppCompatActivity {

  @SuppressLint("SetJavaScriptEnabled")
  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    //.... WebView Setup here

    //.... WebChromeClient Setup
    myWebView.setWebViewClient(new WebViewClient());
    myWebView.setWebChromeClient(new WebChromeClient() {
      @Override
      public void onPermissionRequest(final PermissionRequest request) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
            request.grant(request.getResources());
        }
      }
    });

  }
}
```

3. Next step is to load the URL of the prebuilt. Make sure you replace the `token` and `meetingId` with respective variables.

```js
public class MainActivity extends AppCompatActivity {

  //Declare following variables
  private String token  = "REPLACE_YOUR_TOKEN_HERE";

  private String prebuiltVersion = "0.3.43";

  private String meetingId = "MEETING_ID";

  private String name = "John Doe";
  private String micEnabled = "true";
  private String webcamEnabled = "true";

  @Override
  protected void onResume() {
    super.onResume();
    if (myWebView.getUrl() == null) {
      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M && isPendingPermissions()) {
        // This explicitly requests the camera and audio permissions.
        // It's fine for a demo app but should probably be called earlier in the flow,
        // on a user interaction instead of onResume.
        requestCameraAndAudioPermissions();
      } else {
        loadPrebuilt();
      }
    }
  }

  private void loadPrebuilt() {
    Uri.Builder builder = new Uri.Builder();

    builder.scheme("https")
            .authority("embed.videosdk.live")
            .appendPath("rtc-js-prebuilt")
            .appendPath(prebuiltVersion)
            .appendQueryParameter("name", name) // Name Parameter
            .appendQueryParameter("micEnabled", micEnabled) // initial Mic Status Parameter
            .appendQueryParameter("webcamEnabled", webcamEnabled) // initial webcam status paramter
            .appendQueryParameter("meetingId", meetingId)
            .appendQueryParameter("redirectOnLeave", "https://videosdk.live")
            .appendQueryParameter("token", token);

    String url = builder.build().toString();
    myWebView.loadUrl(url);
  }
}
```

4. Handle the runtime permissions.

```js
public class MainActivity extends AppCompatActivity {

  private int PERMISSION_REQUEST_CODE = 1234;
  private String[] requiredDangerousPermissions = {
      Manifest.permission.CAMERA,
      Manifest.permission.MODIFY_AUDIO_SETTINGS,
      Manifest.permission.RECORD_AUDIO
  };

  @Override
  public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {

    if (requestCode == PERMISSION_REQUEST_CODE) {
      if (grantResultsContainsDenials(grantResults)) {
        // Show some permissions required dialog.
      } else {
        // All necessary permissions granted, continue loading.
        loadPrebuilt();
      }
    } else {
      super.onRequestPermissionsResult(requestCode, permissions, grantResults);
    }
  }

  @RequiresApi(api = Build.VERSION_CODES.M)
  private void requestCameraAndAudioPermissions() {
    requestPermissions(getPendingPermissions(), PERMISSION_REQUEST_CODE);
  }

  @RequiresApi(api = Build.VERSION_CODES.M)
  private String[] getPendingPermissions() {
    String[] permissions = {};
    ArrayList<String> pendingPermissions = new ArrayList<String>();
    for (String permission : requiredDangerousPermissions) {
      if (checkSelfPermission(permission) == PackageManager.PERMISSION_DENIED) {
        pendingPermissions.add(permission);
      }
    }
    return pendingPermissions.toArray(permissions);
  }

  private boolean isPendingPermissions() {
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.M) {
      return false;
    } else return getPendingPermissions().length > 0;
  }

  private boolean grantResultsContainsDenials(int[] grantResults){
    for (int result : grantResults) {
      if (result == PackageManager.PERMISSION_DENIED) {
        return true;
      }
    }
    return false;
  }
}
```

5. Run the app.

:::note

You can checkout the sample project for **[prebuilt implementation of android in webview ](https://github.com/videosdk-live/videosdk-rtc-prebuilt-examples/tree/main/android-webview)** here.

:::


---

Prebuilt SDK enables the opportunity to integrate real-time video & audio communication SDK without writing explicit code. It just requires 10 minutes to integrate.

### Prerequisites

:::important

One should have a VideoSDK account to generate a token.
Visit VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate token

:::

### Permissions

In order to embed VideoSDK in iOS, add these permissions to the `Info.plist`:

```js
<key>NSCameraUsageDescription</key>
<string>Allow camera access to start video.</string>

<key>NSMicrophoneUsageDescription</key>
<string>Allow microphone access to start audio.</string>
```

## Embeding Prebuilt in iOS

You will need to use the [SFSafariViewController](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller) class.

1. We will setup the `SFSafariViewController` to load the VideoSDK Prebuilt when the view appears.

```js
import SafariServices

class ViewController: UIViewController, SFSafariViewControllerDelegate {

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        var meetingUrl = URLComponents() // We will update the URL in next step
        let safariVC = SFSafariViewController(url: meetingUrl.url!)
        safariVC.delegate = self
        present(safariVC, animated: true)
    }
}
```

2. Next step is to update the URL for the prebuilt. Make sure you replace the token and meetingId with respective variables.

```js
import SafariServices

class ViewController: UIViewController, SFSafariViewControllerDelegate {

    public var prebuiltVersion = "0.3.43" // VideoSDK Prebuilt Version
    public var token = "YOUR_TOKEN_HERE" //Replace your token here
    public var meetingId = "YOUR_MEETINGID" //Replace your meeting id

    public var name = "John Doe"
    public var webcamEnabled = "true"
    public var micEnabled = "true"

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        var meetingUrl = URLComponents()

        //Setup the Prebuilt URL
        meetingUrl.scheme = "https"
        meetingUrl.host = "embed.videosdk.live"
        meetingUrl.path = "/rtc-js-prebuilt/"+prebuiltVersion
        meetingUrl.queryItems = [
            URLQueryItem(name: "name", value: name),
            URLQueryItem(name: "micEnabled", value: micEnabled),
            URLQueryItem(name: "webcamEnabled", value: webcamEnabled),
            URLQueryItem(name: "meetingId", value: meetingId),
            URLQueryItem(name: "token", value: token),
        ]
        let safariVC = SFSafariViewController(url: meetingUrl.url!)
        safariVC.delegate = self
        present(safariVC, animated: true)
    }
}
```

3. Run the app.

:::note

You can checkout the sample project for **[prebuilt implementation of iOS in webview here](https://github.com/videosdk-live/videosdk-rtc-prebuilt-examples/tree/main/Prebuilt%20Webview%20iOS)**.

:::


---

# Quickstart with Javascript

Prebuilt SDK enables the opportunity to integrate real-time video & audio communication SDK without writing explicit code. It just requires 10 minutes to integrate.

It supports all modern frameworks such as plain JavaScript, React JS, Vue, and Angular.

## Prerequisites

:::important

One should have a VideoSDK account to generate a token.
Visit VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate token

:::

## Embeding Prebuilt in JS

1. Create an `index.html` file and add the following `<script>` tag at the end of your code's `<body>` tag. Initialize `VideoSDKMeeting` after the script gets loaded.

```html title="index.html"
<script>
  var script = document.createElement("script");
  script.type = "text/javascript";

  script.addEventListener("load", function (event) {
    const config = {
      name: "Demo User",
      meetingId: "milkyway",
      apiKey: "
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Videosdk.live RTC</title>
  </head>
  <body>
    <button onclick="">Create Meeting</button>
  </body>
</html>
```

2. Add a `<script>` which will contain `createMeeting()` which will create and redirect to a new meeting. And add this method to `onClick` of `<button>`

Your `<body>` should look something like this.

```js title="createMeeting.html
<body>
  <script>
    function createMeeting() {
      let meetingId =  'xxxxyxxx'.replace(/[xy]/g, function(c) {
          var r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8);
          return v.toString(16);
      });
      window.location.href = "http://"+window.location.host+"?meetingId="+meetingId;
    }
  </script>
  <button onclick="">Create Meeting</button>
</body>
```

3. Now update your `index.html` to take the `meetingId` from the URL.

```js title="index.html"
//...
<script>

   script.addEventListener("load", function (event) {
      //Get URL query parameters
      const url = new URLSearchParams(window.location.search);

      //...

      const config = {
        // ...
        meetingId: url.get("meetingId"), // Get meeting id from params.
        // ...
      };

      const meeting = new VideoSDKMeeting();
      meeting.init(config);
    });

</script>

//...
```

4. Now go to `host/createMeeting.html` and press the button to create a new meeting with a random meeting id.


---

# Release Notes - Prebuilt

This page will keep you update all the releases of Prebuilt SDK.

## 0.3.43

**Release Date** : 25th December 2024

**Change log** :

- Improved whiteboard for cross platform

## 0.3.42

**Release Date** : 29th August 2024

**Change log** : 

1. `participantNotificationAlertsEnabled` param added for show notification when participant join or left the meeting.

     **Docs** : [`participantNotificationAlertsEnabled`](/prebuilt/api/sdk-reference/parameters/basic-parameters#participantnotificationalertsenabled) 

2. Poll results now show after launching a poll when the `SHOW RESULTS` button is clicked in the Poll List Tabpanel.     

## 0.3.38

**Release Date** : 27th Mar 2024

**Change log** : 

- Error logs added :


| Constant                                     | Code | Message                                                                                                                                                                                                                          |
| -------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ERROR_CAMERA_ACCESS_DENIED_OR_DISMISSED      | 3017 | Oops! It seems like camera access was denied or dismissed. To proceed, kindly grant access through your browser settings.                                                                                                        |
| ERROR_MICROPHONE_ACCESS_DENIED_OR_DISMISSED  | 3018 | Oops! It seems like microphone access was denied or dismissed. To proceed, kindly grant access through your browser settings.                                                                                                    |
| ERROR_CAMERA_PERMISSION_DENIED_BY_OS         | 3019 | Camera permission denied by OS system settings. Please check the system settings and grant permission for this browser.                                                                                                          |
| ERROR_MICROPHONE_PERMISSION_DENIED_BY_OS     | 3020 | Microphone permission denied by OS system settings. Please check the system settings and grant permission for this browser.                                                                                                      |
| ERROR_CAMERA_NOT_FOUND                       | 3021 | Please ensure your camera is connected and turned on, and that the camera driver is installed and up-to-date.                                                                                                                    |
| ERROR_MICROPHONE_NOT_FOUND                   | 3022 | Please ensure your microphone is connected and turned on.                                                                                                                                                                        |
| ERROR_CAMERA_IN_USE                          | 3023 | The camera is being used by another application. Please close any programs utilizing the camera, such as video conferencing tools, screen recording software, or other browsers. Restart your browser and attempt again.         |
| ERROR_MICROPHONE_IN_USE                      | 3024 | The microphone is being used by another application. Please close any programs utilizing the microphone, such as video conferencing tools, screen recording software, or other browsers. Restart your browser and attempt again. |
| ERROR_CAMERA_PERMISSION_OR_AUTOPLAY_ISSUE    | 3025 | It seems like there's an issue with camera permission or video autoplay, you can check out this link for details: [http://tinyurl.com/autoplay-issue](http://tinyurl.com/autoplay-issue)                                         |
| ERROR_VIDEO_SOURCE_INITIATION_FAILED         | 3026 | Unable to initiate video source. Please verify browser settings for video permissions.                                                                                                                                           |
| ERROR_WEBCAM_TRACK_ENDED                     | 3027 | Webcam track has ended or the webcam is disconnected. Please ensure your webcam is properly connected and try restarting it.                                                                                                     |
| ERROR_MICROPHONE_TRACK_ENDED                 | 3028 | Microphone track has ended or the microphone is disconnected. Please check your microphone connection and try again.                                                                                                             |
| ERROR_INVALID_CUSTOM_VIDEO_TRACK             | 3029 | The provided custom video track is invalid; reverting to the default video track. Please ensure that the video track meets the required specifications.                                                                          |
| ERROR_INVALID_CUSTOM_AUDIO_TRACK             | 3030 | The provided custom audio track is invalid; reverting to the default audio track. Please ensure that the audio track meets the required specifications.                                                                          |
| ERROR_CUSTOM_VIDEO_TRACK_ENDED               | 3031 | The provided custom video track is in an ended state. Please verify the video track's status, and try again.                                                                                                                     |
| ERROR_CUSTOM_AUDIO_TRACK_ENDED               | 3032 | The provided custom audio track is in an ended state. Please verify the audio track's status, and try again.                                                                                                                     |
| ERROR_CAMERA_ACCESS_UNAVAILABLE              | 3033 | Camera access unavailable: Please ensure your device is compatible and that you're on a secure website (https://).                                                                                                               |
| ERROR_MICROPHONE_ACCESS_UNAVAILABLE          | 3034 | Microphone access unavailable: Please ensure your device is compatible and that you're on a secure website (https://).                                                                                                           |
| ERROR_ACTION_PERFORMED_BEFORE_MEETING_JOINED | 3035 | Oops! Something went wrong. The room was in a connecting state, and during that time, an action encountered an issue. Please try again after joining a meeting.                                                                  |
| MAX_SPEAKER_LIMIT_REACHED_ON_ORGANIZATION | 4026 | You have reached max speaker limit on organization. To increase contact at support@videosdk.live      |
| MAX_VIEWER_LIMIT_REACHED_ON_ORGANIZATION | 4027 | You have reached max viewer limit on organization. To increase contact at support@videosdk.live      |
| MAX_RECORDING_LIMIT_REACHED_ON_ORGANIZATION | 4028 | You have reached max limit of recording on organization. To increase contact at support@videosdk.live      |
| MAX_HLS_LIMIT_REACHED_ON_ORGANIZATION | 4029 | You have reached max limit of hls on organization. To increase contact at support@videosdk.live      |
| MAX_LIVESTREAM_LIMIT_REACHED_ON_ORGANIZATION | 4030 | You have reached max limit of livestream on organization. To increase contact at support@videosdk.live      |


**Bug Fix** :

1. Fixed host with permission not able to enable mic, webcam or screen share of remote participants.

2. Fixed edge case where multiple participants attempting screen sharing in a meeting could result in misleading of stream showcase.

## 0.3.37

**Release Date** : 31st Oct 2023

**Change log** :

1. HLS Player Improvements

## v0.3.36

**Release Date** : 31st Oct 2023

**Change log** :

1. `moreOptionsEnabled` param added for show/hide More Option Tabpanel.

     **Docs** : [`moreOptionsEnabled`](/prebuilt/api/sdk-reference/parameters/basic-parameters#moreoptionsenabled) 

## v0.3.31

**Release Date** : 5th July 2023

**Change log** :

1. Internal improvements


## v0.3.30

**Release Date** : 15th May 2023

**Change log** :

1. `toggleVirtualBackground` parameter added in `permissions` object.

   **Docs** : [`toggleVirtualBackground`](/prebuilt/api/sdk-reference/parameters/advance-parameters/permissions#togglevirtualbackground)

2. Microphone dropdown now includes a speaker list.

## v0.3.29

**Release Date** : 27th February 2023

**Change log** :

1. `multistream` parameter added in `videoConfig` object.

   **Docs** : [Audio/Video Config](/prebuilt/api/sdk-reference/parameters/advance-parameters/customize-audio-video#multistream)

## v0.3.25

**Release Date** : 20th February 2023

**Change log** :

1. Mirror your camera view from `Change Webcam` menu in topbar.

2. Change incoming video resolution to SD or HD. You can find this options in `Configuration` panel.

3. Support of custom configuartion in custom track of video, audio and screenShare.

   **Docs** : [Audio/Video Config](/prebuilt/guide/prebuilt-video-and-audio-calling/features/customize-audio-video)

4. Get the notification when you switch the networks or become disconnected from the meeting.

## v0.3.23

**Release Date** : 17th November 2022

**Change log** :

1. If `maintainLandscapeVideoAspectRatio` is set to true , then it will maintain aspect ratio of webcam streams for all participants inside all meeting layouts.

2. By passing the `networkBarEnabled` true, you can see a network icon on the top right corner of the video feed where you can inspect data like latency, jitter, packet loss, bitrate etc.

---

## v0.3.22

**Release Date** : 16th November 2022

**Change log** :

1. In `VIEWER` mode, the participant joining limit has been increased to 100.

---

## v0.3.21

**Release Date** : 3rd October 2022

**Change log** :

1. `Virtual Background (BETA)` and `AI Noise Removal (BETA)` added.

   **Docs** : [Virtual Background](/prebuilt/guide/prebuilt-video-and-audio-calling/features/virtual-background)

   **Docs** : [AI Noise Removal](/prebuilt/guide/prebuilt-video-and-audio-calling/features/noise-removal)

---

## v0.3.20

**Release Date** : 23rd September 2022

**Change log** :

1. `Activities` Tab has been renamed to `More Options`.
2. Whiteboard and Add Live Stream has been moved into `More Options`.
3. In Participant Tab, Media permission icon list has been redesigned.

---

## v0.3.19

**Release Date** : 12th September 2022

**Change log** :

1. Added option to configure themes for Recordings, Livestreaming and HLS

   **Docs** : [Change Recording Theme](/prebuilt/api/sdk-reference/parameters/advance-parameters/recording)

   **Docs** : [Change LiveStreaming Theme](/prebuilt/api/sdk-reference/parameters/advance-parameters/live-stream)

   **Docs** : [Change HLS Theme](/prebuilt/api/sdk-reference/parameters/advance-parameters/hls)

---

## v0.3.18

**Release Date** : 9th September 2022

**Change log** :

1. `DARK` and `LIGHT` theme added.

   **Docs** : [Change Theme](/prebuilt/guide/prebuilt-video-and-audio-calling/features/theme)

2. Activity icon can be hidden by setting `pollEnabled : false` .

---

## v0.3.17

**Release Date** : 24th August 2022

**Change log** :

1. Waiting screen customization added

   **Docs** : [Waiting screen](/prebuilt/guide/prebuilt-video-and-audio-calling/features/waiting-screen)

2. Provided permission for participant icon button visibility.

   **Docs** : [Enabled Participant Tab Panel](/prebuilt/api/sdk-reference/parameters/basic-parameters#participanttabpanelenabled)

3. Provided permission to toggle participant tab panel.

   **Docs** : [Toggle Participant Tab Panel](/prebuilt/api/sdk-reference/parameters/advance-parameters/permissions#cantoggleparticipanttab)

**Bug Fix** :

In Chat timestamp issue resolved.

---

## v0.3.15

**Release Date** : 6th August 2022

**Change log** :

1. While Screen sharing, participant can share audio of their chrome tab.

   **Docs** : [Screen Share with Audio](/prebuilt/guide/prebuilt-video-and-audio-calling/features/screenshare#screen-share-with-audio)

---

## v0.3.14

**Release Date** : 6th August 2022

**Change log** :

1. Few edge cases have been covered in the poll.

---

## v0.3.13

**Release Date** : 31st July 2022

**Change log** :

1. [Live Poll (BETA)](/prebuilt/guide/prebuilt-video-and-audio-calling/features/live-poll) Release.

2. Any participant can create a poll by passing `canCreatePoll` true.

3. Maintain webcam streams aspect ratio config added `maintainVideoAspectRatio` true.

4. Participant network status bar provided in Participant grid view.

## v0.3.11

**Release Date** : 28th July 2022

**Change log** :

1. In HLS, for visible player controls you can pass `playerControlsVisible` true. so that participant can view control of player.

---

## v0.3.10

**Release Date** : 15th July 2022

**Change log** :

1. HLS can be enabled by any participant with permission `hls.enabled`.

2. Participate can toggle other participant's mode by passing `toggleParticipantMode` true.

3. HLS can be toggle by any participant with passing `toggleHls`.

4. HLS mode added with this parameter `mode`. It can be `VIEWER` or `CONFERENCE`.

---

## v0.3.8

**Release Date** : 8th July 2022

**Change log** :

1. Participant can now toggle other participant screenShare if they are having permission `participantCanToogleOtherScreenShare`.

**Bug Fix** :

2. Join screen is now responsive if `title` or `meetingUrl` is not provided.

---

## v0.3.7

**Release Date** : 5th July 2022

**Change log** :

1. Add google echoCancellation params during creation of audio stream.

2. Loader Animation added between join screen.

**Bug Fix** :

1. Remove googDsp dependency warn.

---

## v0.3.6

**Release Date** : 7th June 2022

**Change log** : None

**Bug Fix** :

1. Fullscreen model issue resolved.

2. Resolve UDP port blocking and video blackout issue.

---

## v0.3.4

**Release Date** : 14th May 2022

**Change log** : None

**Bug Fix** :

1. Throw error when device or browser does not support audio or video communication.

2. Resolved error `No peers found for the Data consumer` while start recording/ livestream/HLS.

---

## v0.3.2 & v0.3.3

**Release Date** : 4th May 2022

**Change log** :

1. Region support added for new meetings.

**Bug Fix** :

2. Mozila browser (Mac OS) Video Control button not working.

---

## v0.3.1

**Release Date** : 19th March 2022

**Change log** :

1. Change layout dynamically to all participants.

2. Changing layout will reflect to recorders.

3. Livestream configurations options added.

4. `Go Live` button added, so that participant can start live stream while running meeting.

---

## v0.3.0

**Release Date** : 22nd March 2022

**Change log** : None

**Fix** :

1. Topbar icons container component code refactoring.


---

# Setup - Prebuilt


To begin working with the VideoSDK, you need to setup a server that can authenticate & validate your API key and secret which we generated in the previous step. Follow this [Signup & Create API Key](signup-and-create-api) if you haven't generated API key and secret.

For server setup, you'll need the following API's:

1. `GET` **get-token** : By providing API key and secret, this API will return accesstoken. We'll discuss in depth how to achieve it.

2. `POST` **create-meeting** : By providing generated access token, this API will return dash(-) separated meetingId, for example **abc-pqr-xyz**.

3. `POST` **validate-meeting/:meetingId** : By providing generated meetingId as a path parameter, this API will only validate the provided meetingId and return a `200 status`response. This API is for verification purpose only **[OPTIONAL]**.

:::note
You can integrate this API's in client side also.
:::

### Why we use token based Authentication ?

Token based authentication allow users to verify their identity by providing generated API key and secrets.

- Your server will generate access token using your API key and secret
- Your client obtains token from your backend server.
- For token validation, client will pass this token to VideoSDK.
- VideoSDK server will only allow entry in meeting if the token is valid.

Here is the simple sequence diagram represents the authentication.


### Code Sample

For Node server environment, refer this [GUIDE](https://github.com/videosdk-live/videosdk-rtc-nodejs-sdk-example/blob/main/README.md), download the code sample [videosdk-rtc-nodejs-sdk-example](https://github.com/videosdk-live/videosdk-rtc-nodejs-sdk-example) and for other server environment
you can continue with below topic.

### Generate Access Token and integrate other API's

For security, every participant that connects to meeting needs a access token. By substituting `apikey` and `permissions` in it.



**node:**

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

// Need to generate from app.videosdk.live
const API_KEY = "API_KEY_GENERATED";
const SECRET_KEY = "API_SECRET_KEY_GENERATED";

jwt.sign(
  {
apikey: API_KEY,
permissions: ["allow_join"], // Permission to join the meeting
  },
  SECRET_KEY,
  {
algorithm: "HS256",
expiresIn: "24h",
jwtid: uuid4(),
  },
  function (err, token) {
console.log(token);
  }
);
```

---

**python:**

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

api_key = 'api_key_generated'
secret_key = 'secret_key_generated'


def generateToken():
expires = 24 * 3600
now = datetime.datetime.utcnow()
exp = now + datetime.timedelta(seconds=expires)
return jwt.encode(payload={
      'apikey': api_key,
      permissions: ["allow_join"]
    }, key=secret_key).decode('utf-8')

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

---

**java:**

```js
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("apikey", "<api_key_generated>");
payload.put("permissions", ["allow_join"]);
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, "<secret_key_generated>".getBytes()).compact();
  }
```

---

**ruby:**

```js
require 'jwt'
require 'securerandom'

$api_key = "api_key_generated"
$secret_key = "secret_key_generated"

def generateToken()
payload = {
  apikey: $api_key,
  permissions: ["allow_join"]
}
token = JWT.encode(payload, $secret_key, 'HS256')
return token
end

puts generateToken
```

---

**php:**

```js
<?php

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

$api_key = "api_key_generated";
$secret_key = "secret_key_generated"

$payload = [
'apikey' => api_key,
'permissions': ["allow_join"],
];

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

Available permissions are:

- **allow_join**: The participant will be permitted entry without request.
- **ask_join**: The participant will not be permitted entry without request.
- **allow_mod**: Allow participant to enable/disable other participant's mic/webcam.

For other APIs you can follow [Create Meeting & Validate Meeting.](/api-reference/realtime-communication/create-room)


---

This guide will help you to generate API key and secret from dashboard.

## 1. Generate API Key

Go to Dashboard, navigate to [<ins>**Settings > API Keys**</ins>](https://app.videosdk.live/settings/api-keys) and click on **ADD NEW** button.

![Video SDK Home Dashboard](/img/tutorial/add_new_api.png)

## 2. Enter Project Name

After clicking **ADD NEW** button, enter your project name in **Add a project name for new API key** pop-up window and click on **Create new API key** button.
For example, we provide project name **HelloWorld**.

![Video SDK Home Dashboard](/img/tutorial/project_name.png)

## 3. Copy API Key and Secret

After submitting your project name, the API Key and Secret will be displayed in API key's table with your project name.

![Video SDK Home Dashboard](/img/tutorial/api_key_table.png)


---

# Explore video & audio calling

This guide will get you running with the VideoSDK video & audio calling in minutes.

## Overview

At it's core, VideoSDK RTC is a distributed SFU. It eanbles highly scalable video & audio meetings unlike vanilla webRTC.

VideoSDK enables opportunity to integrate video & audio calling to Web, Android, IOS applications. it provides Programmable SDKs and REST APIs to build up scalable video conferencing applications.

## Terminology

#### **Meeting**

A Meeting represents real-time audio, video, and/or screen-share session, and is the basic building block for media sharing among participants.

#### **Participants**

Participants are the client applications that are connected to a Meeting and shares video & audio media with one another.

#### **Local Participant**

Local Participant producing audio or video stream from the local client's media sources

#### **Streams**

Streams are indiviual video & audio streams produced by the participants in the meeting

#### **Active Speaker**

Active Speaker represents the participant who is currently producing highest decibels audio stream (in other words speaking)

#### **Active Presenter**

Active Presenter is the participant who is currently sharing his/her screen as a video stream

#### **Main participant**

Main Participant represents the client who shall be displayed on the main screen indicating that he/she is either presenting or speaking

## Architecture

This diagram demonstrates end-to-end flow to implement video & audio calling, record calls and go-live on social media.



---

# Supported Browsers

:::note
The following browser versions represent the minimum required versions to ensure full support for the listed features.
:::





---

Prebuilt SDK enables opportunity to integrate real-time communication SDK without writing explicit code. It just requires 10 minutes to integrate.

It supports all the modern frameworks such as plain JavaScript, React JS, Vue and Angular.



### Step 1: Install Package

**npm:**

```js
npm install @videosdk.live/rtc-js-prebuilt
```

---

**yarn:**

```js
yarn add @videosdk.live/rtc-js-prebuilt
```

### Step 2: Initialize Meeting

Copy API key generated from [Signup & Create API Key](/docs/guide/prebuilt-video-and-audio-calling/signup-and-create-api) , paste it in to `apiKey` attribute.

**react:**

```js
import React, { useEffect } from "react";

export default function App() {
  useEffect(() => {
const config = {
  name: "Demo User",
  meetingId: "milkyway",
  apiKey: "<API KEY>",

  containerId: null,

  micEnabled: true,
  webcamEnabled: true,
  participantCanToggleSelfWebcam: true,
  participantCanToggleSelfMic: true,

  chatEnabled: true,
  screenShareEnabled: true,

  /*

 Other Feature Properties
  
  */
};

const meeting = new VideoSDKMeeting();
meeting.init(config);
  }, []);

  return <div></div>;
}
```

:::tip

Stuck anywhere? Check out this react [example code](https://github.com/videosdk-live/videosdk-rtc-react-prebuilt-example) on github or [download](https://github.com/videosdk-live/videosdk-rtc-react-prebuilt-example/archive/refs/heads/main.zip) the full source code and unzip on your computer.

:::

---

**angular:**

```js



@Component({
  selector: "app-root",
  templateUrl: "./app.component.html",
})
export class AppComponent implements OnInit {
  async ngOnInit() {
const config = {
  name: "Demo User",
  meetingId: "milkyway",
  apiKey: "<API KEY>",

  containerId: null,

  micEnabled: true,
  webcamEnabled: true,
  participantCanToggleSelfWebcam: true,
  participantCanToggleSelfMic: true,

  chatEnabled: true,
  screenShareEnabled: true,

  /*

 Other Feature Properties
  
  */
};

const meeting = new VideoSDKMeeting();
meeting.init(config);
  }
}
```

:::tip

Stuck anywhere? Check out this angular [example code](https://github.com/videosdk-live/videosdk-rtc-angular-prebuilt-example) on github or [download](https://github.com/videosdk-live/videosdk-rtc-angular-prebuilt-example/archive/refs/heads/main.zip) the full source code and unzip on your computer.

:::

---

**vue:**

```js
<script>

export default {
  name: "App",
  data() {
return {
  name: "Flavio",
};
  },
  mounted: async function() {

  const config = {
  name: "Demo User",
  meetingId: "milkyway",
  apiKey: "<API KEY>",

  containerId: null,

  micEnabled: true,
  webcamEnabled: true,
  participantCanToggleSelfWebcam: true,
  participantCanToggleSelfMic: true,

  chatEnabled: true,
  screenShareEnabled: true,

  /*

 Other Feature Properties

  */
};

const meeting = new VideoSDKMeeting();
meeting.init(config);
  },
};
</script>

```

:::tip
Stuck anywhere? Check out this vue [example code](https://github.com/videosdk-live/videosdk-rtc-vue-prebuilt-example) on github or [download](https://github.com/videosdk-live/videosdk-rtc-vue-prebuilt-example/archive/refs/heads/main.zip) the full source code and unzip on your computer.

:::

### Step 3: Run the application

Now, final step is to run the application and verify prebuilt in browesr.

```bash
$ npm start
```

![Prebuilt SDK Example to add video call widget in your web application](/img/prebuilt/prebuilt-grid.png)


---

Prebuilt SDK enables an opportunity to integrate real-time communication SDK without writing explicit code. It just requires 10 minutes to integrate.

## Step 1: Add script and set up the meeting

Create an `index.html` file and add the following `<script>` tag at the end of your code's `<body>` tag. Initialize `VideoSDKMeeting` after the script gets loaded. Replace the `apiKey` with the one generated in the Previous Step [Signup & Create API Key](/docs/guide/prebuilt-video-and-audio-calling/signup-and-create-api).

```html title="index.html"
<script>
  var script = document.createElement("script");
  script.type = "text/javascript";

  script.addEventListener("load", function (event) {
    const config = {
      name: "Demo User",
      meetingId: "milkyway",
      apiKey: "<API KEY>",

      containerId: null,

      micEnabled: true,
      webcamEnabled: true,
      participantCanToggleSelfWebcam: true,
      participantCanToggleSelfMic: true,

      chatEnabled: true,
      screenShareEnabled: true,

      /*

     Other Feature Properties
      
      */
    };

    const meeting = new VideoSDKMeeting();
    meeting.init(config);
  });

  script.src =
    "https://sdk.videosdk.live/rtc-js-prebuilt/0.3.43/rtc-js-prebuilt.js";
  document.getElementsByTagName("head")[0].appendChild(script);
</script>
```

### Step 2: Run the application

Install any http server if you don't already have one and run the server to join the meeting from the browser.

**node:**

```bash
$ npm install -g live-server
$ live-server --port=8000
```

and open [http://localhost:8000](http://localhost:8000) in your web browser

---

**python:**

```bash
$ python3 -m http.server
```

and open [http://localhost:8000](http://localhost:8000) in your web browser

---

**php:**

```bash
$ php -S localhost:8000
```

and open [http://localhost:8000](http://localhost:8000) in your web browser

---

**wamp:**

```
Move the HTML file to C:\wamp\www and start the WAMP server
```

and open [http://localhost/index.html](http://localhost/index.html) in your web browser

---

**xampp:**

```
Move the HTML file to C:\xampp\htdocs and start the XAMPP server
```

and open [http://localhost/index.html](http://localhost/index.html) in your web browser

![Prebuilt SDK Example to add video call widget in your web application](/img/prebuilt/prebuilt-grid.png)

:::tip

Stuck anywhere? Check out this [example code](https://github.com/videosdk-live/videosdk-rtc-js-prebuilt-embedded-example) on GitHub or [download](https://github.com/videosdk-live/videosdk-rtc-js-prebuilt-embedded-example/archive/refs/tags/v0.1.1.zip) the full source code and unzip it on your computer.

:::


---

# Meeting Class Event Handler - Python

<div class="sdk-api-ref">

## Overview

`MeetingEventHandler` is a base class for event handlers. Event handlers are used to handle events from the meeting, such as when a participant joins or leaves the meeting, when the active speaker changes, or other various meeting-related events.

Refer to the [Example](#example) section and modify `MyMeetingEventHandler` based on your requirements.

## Events

The base class `MeetingEventHandler` has the following events associated with it:

### on_meeting_joined

- Event emitted when a participant (local participant) joins the meeting. This indicates that the meeting has been successfully joined.
- **Parameters:**
  - `data`: `None`

### on_meeting_left

- Event emitted when a participant leaves the meeting.
- **Parameters:**
  - `data`: `None`

### on_participant_joined

- Event emitted when a new participant joins the meeting.
- **Parameters:**
  - `participant`: [Paritcipant](../participant/introduction).

### on_participant_left

- Event emitted when a participant leaves the meeting.
- **Parameters:**
  - `participant`: [Paritcipant](../participant/introduction).

### on_speaker_changed

- Event emitted when the active speaker changes in the meeting.
- **Parameters:**
  - `data`: `participantId` of the new active speaker.

### on_recording_state_changed

- Event emitted when the recording state of the meeting changes.
- **Parameters:**
  - `data`: Information about the new recording state.

### on_recording_started

- Event emitted when the recording of the meeting starts.
- **Parameters:**
  - `data`: Information about the recording start.

### on_recording_stopped

- Event emitted when the recording of the meeting stops.
- **Parameters:**
  - `data`: Information about the recording stop.

### on_mic_requested

- Event emitted when a microphone is requested.
- **Parameters:**
  - `data`: Information about the microphone request.

### on_webcam_requested

- Event emitted when a webcam is requested.
- **Parameters:**
  - `data`: Information about the webcam request.

### on_meeting_state_change

- Event emitted when the state of the meeting changes.
- **Parameters:**
  - `data`: Information about the new meeting state.

### on_transcription_state_changed

- Event emitted when the transcription state of the meeting changes.
- **Parameters:**
  - `data`: Information about the new transcription state.

### on_transcription_text

- Event emitted when new transcription text is available.
- **Parameters:**
  - `data`: The transcription text.

### on_error

- Event emitted when any type of error occurred.
- **Parameters:**
  - `data`: `str`

## Example

```python
from videosdk import MeetingEventHandler

class MyMeetingEventHandler(MeetingEventHandler):
    def __init__(self):
        super().__init__()

    def on_participant_joined(self, data):
        # Custom logic when a participant joins
        print("Participant joined")
        pass

    def on_participant_left(self, data):
        # Custom logic when a participant leaves
        print("Participant left")
        pass

    # Additional event callbacks as needed

# Pass MyMeetingEventHandler instance to the meeting
meeting.add_event_listener(MyMeetingEventHandler())
```

---

</div>


---

# Meeting Class - Python

<div class="sdk-api-ref">

## Introduction

The `Meeting` class includes properties, methods and events for managing a meeting, participants video, audio and share streams and messaging.

## Meeting Properties

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [id](./properties#id)

</div>
<div class="col col--4 margin-bottom--sm" >

- [active_speaker_id](./properties#active_speaker_id)

</div>

<div class="col col--4 margin-bottom--sm" >

- [local_participant](./properties#local_participant)

</div>
<div class="col col--4 margin-bottom--sm" >

- [participants](./properties#participants)

</div>

<div class="col col--4 margin-bottom--sm">

- [recording_state](./properties#recording_state)

</div>

<div class="col col--4 margin-bottom--sm">

- [transcription_state](./properties#transcription_state)

</div>

<div class="col col--4 margin-bottom--sm">

- [pubsub](./properties#pubsub)

</div>
</div>

## Meeting Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [join](./methods#join)

</div>

<div class="col col--4 margin-bottom--sm" >

- [async_join](./methods#async_join)

</div>
<div class="col col--4 margin-bottom--sm" >

- [leave](./methods#leave)

</div>
<div class="col col--4 margin-bottom--sm" >

- [end](./methods#end)

</div>
<div class="col col--4 margin-bottom--sm" >

- [enable_webcam](./methods#enable_webcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disable_webcam](./methods#disable_webcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [enable_mic](./methods#enable_mic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disable_mic](./methods#disable_mic)

</div>

<div class="col col--4 margin-bottom--sm" >

- [start_recording](./methods#start_recording)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stop_recording](./methods#stop_recording)

</div>
<div class="col col--4 margin-bottom--sm" >

- [start_transcription](./methods#start_transcription)

</div>
<div class="col col--4 margin-bottom--sm" >

- [stop_transcription](./methods#stop_transcription)

</div>
<div class="col col--4 margin-bottom--sm" >

- [fetch_base64](./methods#fetch_base64)

</div>
<div class="col col--4 margin-bottom--sm" >

- [upload_base64](./methods#upload_base64)

</div>

<div class="col col--4 margin-bottom--sm" >

- [add_event_listener](./methods#add_event_listener)

</div>

<div class="col col--4 margin-bottom--sm" >

- [remove_event_listener](./methods#remove_event_listener)

</div>
<div class="col col--4 margin-bottom--sm" >

- [remove_all_listeners](./methods#remove_all_listeners)

</div>
</div>

## Meeting Events

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [on_meeting_joined](./events#on_meeting_joined)

</div>
<div class="col col--4 margin-bottom--sm" >

- [on_meeting_left](./events#on_meeting_left)

</div>
<div class="col col--4 margin-bottom--sm" >

- [on_participant_joined](./events#on_participant_joined)

</div>
<div class="col col--4 margin-bottom--sm" >

- [on_participant_left](./events#on_participant_left)

</div>
<div class="col col--4 margin-bottom--sm" >

- [on_speaker_changed](./events#on_speaker_changed)

</div>

<div class="col col--4 margin-bottom--sm" >

- [on_webcam_requested](./events#on_webcam_requested)

</div>
<div class="col col--4 margin-bottom--sm" >

- [on_mic_requested](./events#on_mic_requested)

</div>
<div class="col col--4 margin-bottom--sm" >

- [on_recording_state_changed](./events#on_recording_state_changed)

</div>
<div class="col col--4 margin-bottom--sm" >

- [on_recording_started](./events#on_recording_started)

</div>
<div class="col col--4 margin-bottom--sm" >

- [on_recording_stopped](./events#on_recording_stopped)

</div>

<div class="col col--4 margin-bottom--sm" >

- [transcription_state_changed](./events#transcription_state_changed)

</div>
<div class="col col--4 margin-bottom--sm" >

- [on_transcription_text](./events#on_transcription_text)

</div>

<div class="col col--4 margin-bottom--sm" >

- [on_meeting_state_change](./events#on_meeting_state_change)

</div>

<div class="col col--4 margin-bottom--sm" >

- [on_error](./events#on_error)

</div>

</div>

</div>


---

# Meeting Class Methods - Python

<div class="sdk-api-ref-only-h4">

### join

- It is used to join a meeting.
- After meeting initialization by [`init_meeting()`](../videosdk/init_meeting.md) it returns a new instance of [Meeting](./introduction.md). However, by default, it will not automatically join the meeting. Hence, to join the meeting you should call `join()`.

#### Events associated with `join()`:

- Local Participant will receive a [`on_meeting_joined`](./events#on_meeting_joined) event when successfully joined.
- Remote Participant will receive a [`on_participant_joined`](./events#on_participant_joined) event with the newly joined [`Participant`](../participant/introduction.md) object from the event callback.

---

### async_join

- It is used to join a asynchronously meeting.
- After meeting initialization by [`init_meeting()`](../videosdk/init_meeting.md) it returns a new instance of [Meeting](./introduction.md). However, by default, it will not automatically join the meeting. Hence, to join the meeting you should call `async_join()`.

#### Events associated with `async_join()`:

- Local Participant will receive a [`on_meeting_joined`](./events#on_meeting_joined) event when successfully joined.
- Remote Participant will receive a [`on_participant_joined`](./events#on_participant_joined) event with the newly joined [`Participant`](../participant/introduction.md) object from the event callback.

---

### leave

- It is used to leave the current meeting.

#### Events associated with `leave()`:

- Local participant will receive a [`on_meeting_left`](./events#on_meeting_left) event.
- All remote participants will receive a [`on_participant_left`](./events#on_participant_left) event with `participantId`.

#### Returns

- _`void`_

---

### end

- It is used to end the current running session.
- By calling `end()`, all joined [participants](../participant/introduction.md) including [local_participant](../participant/introduction.md) of that session will leave the meeting.

#### Events associated with `end()`:

- All [participants](../participant/introduction.md) and [local_participant](../participant/introduction.md), will be emitted [`on_meeting_left`](./events#on_meeting_left) event.

#### Returns

- _`void`_

---

### enable_webcam

- It is used to enable self camera.
- [`on_stream_enabled`](../participant/events#on_stream_enabled) event will be emitted with [`stream`](../stream/introduction.md) object from the event callback, inside that [participant](../participant/introduction.md) object.

#### Returns

- _`void`_

---

### disable_webcam

- It is used to disable self camera.
- [`on_stream_disabled`](../participant/events#on_stream_disabled) event will be emitted with [`stream`](../stream/introduction.md) object from the event callback, inside that [participant](../participant/introduction.md) object.

#### Returns

- _`void`_

---

### enable_mic

- It is used to enable self microphone.
- [`on_stream_enabled`](../participant/events#stream-enabled) event will be emitted with [`stream`](../stream/introduction.md) object from the event callback, inside that [participant](../participant/introduction.md) object.

#### Returns

- _`void`_

---

### disable_mic

- It is used to disable self microphone.
- [`on_stream_disabled`](../participant/events#on_stream_disabled) event will be emitted with [`stream`](../stream/introduction.md) object from the event callback, inside that [participant](../participant/introduction.md) object.

#### Returns

- _`void`_

---

### start_recording

- It is used to start meeting recording.
- All [participants](../participant/introduction.md) and [local_participant](../participant/introduction.md), will receive [`on_recording_started`](./events#on_recording_started) and [`on_recording_state_changed`](./events#on_recording_state_changed) event.

- `webhook_url` will be triggered when the recording is completed and stored in the server. Read more about webhooks [here](https://en.wikipedia.org/wiki/Webhook).

- `dir_path` will be the path for your S3 bucket to which you want to store recordings. To allow us to store the recording in your Cloud (S3 bucket, GCP or Azure), you will need to fill out on Dashboard by providing the required values. [VideoSDK Cloud Integration](https://app.videosdk.live/api-keys)

- `config: mode` is used to either record video-and-audio both or only audio. And by default it will be video-and-audio.

- `config: quality` is only applicable to video-and-audio.

- `transcription: enabled` indicates whether post transcription is enabled.

- `transcription: summary: enabled` Indicates whether post transcription summary generation is enabled. Only applicable when post transcription is enabled.

- `transcription: summary: prompt` provides guidelines or instructions for generating a custom summary based on the post transcription content.

- to learn more about transcription config [PostTranscriptionConfig](../../types#posttranscriptionconfig)

#### Parameters

- **webhookUrl**: str
- **dir_path**: str
- **config**:
  - **layout**:
    - **type**: _"GRID"_ | _"SPOTLIGHT"_ | _"SIDEBAR"_
    - **priority**: _"SPEAKER"_ | _"PIN"_
    - **gridSize**: Number _`max 4`_
  - **theme**: _"DARK"_ | _"LIGHT"_ | _"DEFAULT"_
  - **mode**: _"video-and-audio"_ | _"audio"_
  - **quality**: _"low"_ | _"med"_ | _"high"_
  - **orientation**: _"landscape"_ | _"portrait"_
- **transcription**:
  - **enabled**: bool
  - **summary**:
    - **enabled**: bool
    - **prompt**: str

#### Returns

- _`void`_

#### Example

```python
from videosdk import RecordingConfig, PostTranscriptionConfig, SummaryConfig

recording_config = RecordingConfig(
  webhook_url = "https://example.com",
  transcription = PostTranscriptionConfig(
    enabled = True,
    summary = SummaryConfig(
      enabled = True,
      prompt = "Write Good Summary On This Recording"
    )
  )
)

# highlight-next-line
meeting.start_recording(recording_config)
```

---

### stop_recording

- It is used to stop meeting recording.
- All [participants](../participant/introduction.md) and [local_participant](../participant/introduction.md), will receive [`on_recording_stopped`](./events#on_recording_stopped) event.

#### Returns

- _`void`_

---

### start_transcription

- It is used to start realtime transcription.
- All [participants](../participant/introduction.md) and [local_participant](../participant/introduction.md), will receive [`TRANSCRIPTION_STARTING`](../../classes/meeting/events#on_transcription_state_changed) event state and [`transcription-text`](../../classes/meeting/events#on_transcription_text) event.

- `config: webhookUrl` will be triggered when the state of realtime transcription is changed. Read more about webhooks [here](https://en.wikipedia.org/wiki/Webhook).

- `config: summary: enabled` Indicates whether realtime transcription summary generation is enabled. Summary will be available after realtime transcription stopped.

- `config: summary: prompt` provides guidelines or instructions for generating a custom summary based on the realtime transcription content.

- to learn more about realtime transcription config [TranscriptionConfig](../../types#transcriptionconfig)

#### Parameters

- **config**:
  - **webhook_url**: str
  - **summary**:
    - **enabled**: bool
    - **prompt**: str

#### Returns

- _`void`_

#### Example

```python
from videosdk import TranscriptionConfig, SummaryConfig
config = TranscriptionConfig(
  webhook_url="https://example.com",
  summary=SummaryConfig{
    enabled=True,
    prompt="Write Good Summary"
  }
)

# highlight-next-line
meeting.start_transcription(config)
```

---

### stop_transcription

- It is used to stop realtime transcription.
- All [participants](../participant/introduction.md) and [local_participant](../participant/introduction.md), will receive [`TRANSCRIPTION_STOPPING`](../../classes/meeting/events#on_transcription_state_changed) event state.

#### Returns

- _`void`_

#### Example

```python
meeting.stop_transcription()
```

---

### add_custom_audio_track

- It is used to add custom audio track in the meeting.
- It can be used to play audio from any source such as file, network etc...

#### Parameters

- **track**: `MediaStreamTrack`

#### Returns

- _`void`_

#### Example

```python
from videosdk import CustomAudioTrack

custom_audio_track = CustomAudioTrack()

meeting.add_custom_audio_track(custom_audio_track)
```

---

### add_custom_video_track

- It is used to add custom video track in the meeting.
- It can be used to play video from any source such as file, network etc...

#### Parameters

- **track**: `MediaStreamTrack`

#### Returns

- _`void`_

#### Example

```python
from videosdk import CustomVideoTrack

custom_video_track = CustomVideoTrack()

meeting.add_custom_video_track(custom_video_track)
```

---

### fetch_base64

- It is used to fetch a base64-encoded file from VideoSDK temporary storage.
- It can be used to retrieve files in a base64 format from a specified URL using an authorization token.
- Available since: `0.0.3`

#### Parameters

- **url**: `str`
  - The URL of the file to be fetched.
- **token**: `str`
  - The authorization token required to access the file.

#### Returns

- **base64_data**: `str`
  - The base64-encoded representation of the fetched file.

---

### upload_base64

- It is used to upload base64-encoded data to VideoSDK temporary storage.
- It can be used to store files in a base64 format in a specified meeting.
- Available since: `0.0.3`

#### Parameters

- **base64_data**: `str`
  - The base64-encoded data to be uploaded.
- **token**: `str`
  - The authorization token required to upload the file.
- **file_name**: `str`
  - The name of the file to be uploaded.

#### Returns

- **url**: `str`
  - The URL of the uploaded file in the VideoSDK temporary storage.

---

### add_event_listener

- It is used to add event listener in the meeting.

#### Parameters

- **event_listener**: [MeetingEventHandler](./events.md#overview)

#### Returns

- _`void`_

#### Example

```python
from videosdk import MeetingEventHandler

class MyMeetingEventHandler(MeetingEventHandler):
  pass

meeting_event_handler = MyMeetingEventHandler()
# highlight-next-line
meeting.add_event_listener(meeting_event_handler)
```

---

### remove_event_listener

- It is used to remove event listener from the meeting.

#### Parameters

- **event_listener**: [MeetingEventHandler](./events.md#overview)

#### Returns

- _`void`_

#### Example

```python
from videosdk import MeetingEventHandler

class MyMeetingEventHandler(MeetingEventHandler):
  pass

meeting_event_handler = MyMeetingEventHandler()
# highlight-next-line
meeting.remove_event_listener(meeting_event_handler)
```

---

### remove_all_listeners

- It is used to remove all event listener in the meeting.

#### Returns

- _`void`_

#### Example

```python
meeting.remove_all_listeners()
```

</div>


---

# Meeting Class Properties - Python

<div class="sdk-api-ref-only-h4">

### id

- type: `str`

- Unique id of the meeting where the participant has joined.

---

### active_speaker_id

- type: `str`

- It will be the `id` of the participant who is actively speaking in the meeting. If no participant is speaking, at that time value of `active_speaker_id` will be `None`.

---

### recording_state

- type : `str`
- `recording_state` will be the current state of the meeting recording.

---

### transcription_state

- type : `str`
- `transcription_state` will be the current state of the meeting transcription.

---

### local_participant

- type: [Participant](../participant/introduction.md)

- It will be the instance of [Participant](../participant/introduction.md) class for the local participant(You) who joined the meeting.

---

### participants

- type: `dict` of [Participant](../participant/introduction.md)

- `dict[str, Participant]`

  - dict{'<'}`participantId`, [Participant](../participant/introduction.md)>

- It will contain all joined participants in the meeting except the [`local_participant`](../participant/introduction.md).

- This will be the `dict` what will container all participants attached with the key as id of that participant.

```python
participantId = "abc"
participant = meeting.participants.get(participantId)
```

---

### pubSub

- It is used to enable Publisher-Subscriber feature in [`meeting`](introduction) class.

Learn more about `PubSub`, [here](./pubsub)

</div>


---

# PubSub - Python

- `PubSub` one of the property of a [Meeting Class](../meeting/introduction.md) is used for messaging purpose for an ongoing meeting

<div class="sdk-api-ref-only-h4">

## Methods

### publish()

- `publish()` is used to publish messages on a specified topic in the meeting.

- While publishing message, if you provide `persist` as `true`, then it will persist the message throughout the meeting and newly joined partcipant will get all old messages of a meeting, otherwise not.

#### Parameters

- [PubSubPublishConfig](../../types#pubsubpublishconfig)

#### Returns

- `void`

#### Example

```python
from videosdk import PubSubPublishConfig
pubsub_config = PubSubPublishConfig(
    topic="CHAT",
    message=description
)
#highlight-next-line
meeting.pubsub.publish(pubsub_config)
```

---

### subscribe()

- `subscribe()` is used to subscribe a particular topic to get all the messages of that particular topic in the meeting. While `publish()` subscribe callback will be invoked.

#### Parameters

- [PubSubSubscribeConfig](../../types.md#pubsubsubscribeconfig)

#### Returns

- This will return old messages for this topic, if you passed `persist` to `true` while [publish](#publish)

- List{'<'}[message](#pubsub-message-data)>

#### Example

```python
from videosdk import PubSubSubscribeConfig

def on_pubsub_message(pubsub_message):
  pass

pubsub_config = PubSubSubscribeConfig(
    topic="CHAT",
    cb=on_pubsub_message
)

old_messages = await self.meeting.pubsub.subscribe(pubsub_config)

```

---

### unsubscribe()

- `unsubscribe()` is used to unsubscribe a particular topic on which you have subscribed priviously.

#### Parameters

- topic :
  - type : `str`

#### Returns

- `void`

#### Example

```python
  meeting.pubsub.unsubscribe("CHAT")
```

---

## Pubsub message data

### message

- type : `str`

- Message that has been published on the specific topic.

### senderId

- type : `str`

- id of a sender who has published this message.

### senderName

- type : `str`

- Name of a sender who has published this message.

### timestamp

- type : `Date`

- Timestamp of when a message has been published.

### topic

- type : `str`

- Name of the topic.

### payload

- type : `dict`

- The additional data that you have send with message.

</div>


---

# Participant Class Event Handler - Python

<div class="sdk-api-ref">

## Overview

`ParticipantEventHandler` is a base class for event handlers. Event handlers are used to handle events from the meeting, such as when a participant joins or leaves the meeting, when the active speaker changes, or other various meeting-related events.

Refer to the [Example](#example) section and modify `MyParticipantEventHandler` based on your requirements.

## Events

The base class `ParticipantEventHandler` has the following events associated with it:

### on_stream_enabled

- `on_stream_enabled` is a callback which gets triggered whenever a participant's video, audio or screen share stream is enabled.

- **Parameters:**
  - `data`: [Stream](../stream/introduction.md)

### on_stream_disabled

- `on_stream_disabled` is a callback which gets triggered whenever a participant's video, audio or screen share stream is disabled.

- **Parameters:**
  - `data`: [Stream](../stream/introduction.md)

### on_media_status_changed

- `on_media_status_changed` is a callback which gets triggered whenever a participant's video, audio is disabled or enabled.

- **Parameters:**
  - `data`: Information about the media status update.
    - `kind`: stream kind
    - `newStatus`: new status

---

### on_video_quality_changed

- `on_video_quality_changed` is a callback which gets triggered whenever a participant's video quality changes.

- **Parameters:**
  - `data`: Information about the video quality changes.
    - `currentQuality`: `HIGH` | `MEDIUM` | `LOW`
    - `prevQuality`: `HIGH` | `MEDIUM` | `LOW`

## Example

```python
from videosdk import ParticipantEventHandler

class MyParticipantEventHandler(ParticipantEventHandler):
    def __init__(self):
        super().__init__()

    def on_stream_enabled(self, data):
        # Custom logic when a participant joins
        print("Participant Stream Enabled")
        pass

    def on_stream_disabled(self, data):
        # Custom logic when a participant leaves
        print("Participant Stream Disabled")
        pass

    # Additional event callbacks as needed

# Pass MyParticipantEventHandler instance to the participant
participant.add_event_listener(MyParticipantEventHandler())
```

</div>


---

# Participant Class - Python

<div class="sdk-api-ref">

## Introduction

The `Participant` class includes properties, methods and events related to all the participants joined in a particular meeting.

## Participant Properties

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [id](./properties#id)

</div>
<div class="col col--4 margin-bottom--sm" >

- [display_name](./properties#display_name)

</div>

<div class="col col--4 margin-bottom--sm" >

- [local](./properties#local)

</div>

<div class="col col--4 margin-bottom--sm">

- [meta_data](./properties#meta_data)

</div>

<div class="col col--4 margin-bottom--sm">

- [listeners](./properties#listeners)

</div>

<div class="col col--4 margin-bottom--sm">

- [mic_on](./properties#mic_on)

</div>
<div class="col col--4 margin-bottom--sm">

- [webcam_on](./properties#webcam_on)

</div>

<div class="col col--4 margin-bottom--sm">

- [streams](./properties#streams)

</div>
</div>

## Participant Methods

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [enable_webcam](./methods#enable_webcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disable_webcam](./methods#disable_webcam)

</div>
<div class="col col--4 margin-bottom--sm" >

- [enable_mic](./methods#enable_mic)

</div>
<div class="col col--4 margin-bottom--sm" >

- [disable_mic](./methods#disable_mic)

</div>

<div class="col col--4 margin-bottom--sm" >

- [capture_image](./methods#capture_image)

</div>
<div class="col col--4 margin-bottom--sm" >

- [async_capture_image](./methods#async_capture_image)

</div>

<div class="col col--4 margin-bottom--sm" >

- [add_event_listener](./methods#add_event_listener)

</div>

<div class="col col--4 margin-bottom--sm" >

- [remove_event_listener](./methods#remove_event_listener)

</div>
<div class="col col--4 margin-bottom--sm" >

- [remove_all_listeners](./methods#remove_all_listeners)

</div>
<div class="col col--4 margin-bottom--sm" >

- [remove](./methods#remove)

</div>
</div>

## Participant Events

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [on_stream_enabled](./events#on_stream_enabled)

</div>
<div class="col col--4 margin-bottom--sm" >

- [on_stream_disabled](./events#on_stream_disabled)

</div>
<div class="col col--4 margin-bottom--sm" >

- [on_media_status_changed](./events#on_media_status_changed)

</div>
<div class="col col--4 margin-bottom--sm" >

- [on_video_quality_changed](./events#on_video_quality_changed)

</div>

</div>

</div>


---

# Participant Class Methods - Python

<div class="sdk-api-ref-only-h4">

### enable_webcam

- `enable_webcam()` is used to enable participant's camera.

#### Events associated with `enable_webcam()` :

- First the participant will get a callback on [`on_webcam_requested`](../meeting/events#on_webcam_requested) and once the participant accepts the request, webcam will be enabled.

- Every Participant will receive a `on_stream_enabled` event with `stream` object.

#### Returns

- `void`

---

### disable_webcam

- `disable_webcam()` is used to disable participant camera.

#### Events associated with `disable_webcam()` :

- Every Participant will receive a `on_stream_disabled` event with `stream` object.

#### Returns

- `void`

---

### enable_mic

- `enable_mic()` is used to enable participant microphone.

#### Events associated with `enable_mic()` :

- First the participant will get a callback on [`on_mic_requested`](../meeting/events#on_mic_requested) and once the participant accepts the request, mic will be enabled.

- Every Participant will receive a `on_stream_enabled` event with `stream` object.

#### Returns

- `void`

---

### disable_mic

- `disable_mic()` is used to disable participant microphone.

#### Events associated with `disable_mic()`:

- Every Participant will receive a `on_stream_disabled` event with `stream` object.

#### Returns

- `void`

---

### remove

- It is used to remove a participant from the meeting

---

### capture_image

- It is used to capture image of the participant's current videoStream.

- It will return image in a form of [PIL Image](https://pillow.readthedocs.io/en/stable/reference/Image.html#image-module).

#### Parameters

- **filepath**: The path to the file in `str`
- **desr_height**: number
- **desr_weight**: number

### async_capture_image

- It is used to capture image of the participant's current videoStream asynchronously.

- it returns the image as a base64 encoded `str`.

#### Parameters

- **filepath**: The path to the file in `str`
- **desr_height**: number
- **desr_weight**: number

#### Returns

- **PIL Image**: In version `0.0.2`, it returns an image in the form of a [PIL Image](https://pillow.readthedocs.io/en/stable/reference/Image.html#image-module).
- **base64**: In version `0.0.3` and later, it returns the image as a base64 encoded `str`.

#### Example

```python
# For version 0.0.2
from PIL import Image

image = await participant.async_capture_image(filepath="path/to/file", desr_height=720, desr_weight=1280)
image.show()

# For version 0.0.3
base64_image = await participant.async_capture_image(filepath="path/to/file", desr_height=720, desr_weight=1280)
print(base64_image)
```

---

### add_event_listener

- It is used to add event listener for the participant.

#### Parameters

- [ParticipantEventHandler](./events.md#overview)

#### Returns

- _`void`_

#### Example

```python
from videosdk import ParticipantEventHandler

class MyParticipantEventHandler(ParticipantEventHandler):
  pass

participant_event_handler = MyParticipantEventHandler()
# highlight-next-line
participant.add_event_listener(participant_event_handler)
```

---

### remove_event_listener

- It is used to remove event listener for the participant.

#### Parameters

- [Participant](./events.md#overview)

#### Returns

- _`void`_

#### Example

```python
from videosdk import ParticipantEventHandler

class MyParticipantEventHandler(ParticipantEventHandler):
  pass

participant_event_handler = MyParticipantEventHandler()
# highlight-next-line
participant.remove_event_listener(participant_event_handler)
```

---

### remove_all_listeners

- It is used to remove all event listener from the participant.

#### Returns

- _`void`_

#### Example

```python
participant.remove_all_listeners()
```

</div>


---

# Participant Class Properties - Python

<div class="sdk-api-ref-only-h4">

### id

- type: `str`

- Unique id of the participant who has joined the meeting.

---

### display_name

- type: `str`

- It will be the `display_name` of the participant.

---

### local

- type: `bool`

- It will represents whether the participant is [`LocalParticipant`](../meeting/properties#local_participant)(You) or not. If it is true, then participant is [`LocalParticipant`](../meeting/properties#local_participant) otherwise RemoteParticipant.

---

### mic_on

- type: `bool`

- It will represents whether the participant is [`LocalParticipant`](../meeting/properties#local_participant)(You) or not. If it is true, then participant is [`LocalParticipant`](../meeting/properties#local_participant) otherwise RemoteParticipant.

---

### webcam_on

- type: `bool`

- It will represents whether the participant is [`LocalParticipant`](../meeting/properties#local_participant)(You) or not. If it is true, then participant is [`LocalParticipant`](../meeting/properties#local_participant) otherwise RemoteParticipant.

---

### streams

- type: `dict[str, Stream]`

  - dict{'<'}`streamId`, [Stream](../stream/introduction.md)>

- It will represents the stream for that particular participant who has joined the meeting. Streams could be `audio` , `video` or `share`.

---

### meta_data

- type: `dict`

- It will represents the additional information, that you have passed in `init_meeting()`.

---

### listeners

- type: List{'<'}[ParticipantEventListener](./events.md#overview)>

- It will represents Event Handlers Attached to given Participant.

</div>


---

# Stream Class - Python

<div class="sdk-api-ref">

## Introduction

Stream class is responsible for handling audio, video and screen sharing streams. Stream class defines instance of audio, video and shared screen stream of participants in form of [MediaStreamTrack](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack).

## Stream Properties

<div class="row">

<div class="col col--4 margin-bottom--sm" >

- [id](./properties#id)

</div>
<div class="col col--4 margin-bottom--sm" >

- [kind](./properties#kind)

</div>

<div class="col col--4 margin-bottom--sm" >

- [track](./properties#track)

</div>

<div class="col col--4 margin-bottom--sm">

- [codecs](./properties#codecs)

</div>

</div>
</div>


---

# Participant Class Properties - Python

<div class="sdk-api-ref-only-h4">

### id

- type: `str`

- Represents the id for that stream .

---

### kind

- type: `str`

- `kind` represents the type of stream which could be `audio` | `video` or `share` .

---

### codecs

- type: `str`

- `codec` stand for encoding and decoding which is useful for shrinking the stream size.

---

### track

- type: `MediaStreamTrack`

- It represents a single media track within a stream.

</div>


---

# Track - Python

<div class="sdk-api-ref">

## Introduction

The `Track` classes in the Video SDK provide a way to handle media streams, specifically video and audio tracks. The `CustomVideoTrack` and `CustomAudioTrack` classes are dummy implementations that generate green video frames and silent audio frames, respectively. These can be subclassed to create more useful implementations tailored to specific use cases.

## Track Properties

### CustomVideoTrack

- **kind**: str
  - Type of media, in this case, "video".
- **\_start**: float
  - Timestamp indicating when the track started.
- **\_timestamp**: int
  - The current timestamp of the track.

### CustomAudioTrack

- **kind**: str
  - Type of media, in this case, "audio".
- **\_start**: float
  - Timestamp indicating when the track started.
- **\_timestamp**: int
  - The current timestamp of the track.

## Track Methods

### CustomVideoTrack Methods

#### `async recv() -> Frame`

Receives the next `VideoFrame`, which is a green frame with a resolution of 640x480 pixels at 30fps.

- **Returns**:
  - `Frame`: The next video frame.

### CustomAudioTrack Methods

#### `async recv() -> Frame`

Receives the next `AudioFrame`, which is a silent audio frame.

- **Returns**:
  - `Frame`: The next audio frame.

### Example Usage

Here's an example of how you might subclass `CustomVideoTrack` to create a custom video track:

```python
class MyCustomVideoTrack(CustomVideoTrack):
    async def recv(self) -> Frame:
        # Your custom implementation here
        pass
```

And similarly, for the audio track:

```python
class MyCustomAudioTrack(CustomAudioTrack):
    async def recv(self) -> Frame:
        # Your custom implementation here
        pass
```

## Conclusion

The `Track` classes in the Video SDK are designed to provide a flexible and extensible way to handle media streams in your applications. By subclassing `CustomVideoTrack` and `CustomAudioTrack`, you can create custom implementations tailored to your specific needs.

</div>

## Implementation Guide

- [Custom Audio Track](/python/guide/video-and-audio-calling/stream-ingestion/custom-audio-track)
- [Custom Video Track](/python/guide/video-and-audio-calling/stream-ingestion/custom-video-track)


---

# VideoSDK Class - Python

<div class="sdk-api-ref">

## Introduction

The `VideoSDK` class purpose is to facilitate the initialization and setup of a meeting session within a SDK.

## init_meeting

The `init_meeting` method is a static method defined within the `VideoSDK` class

The method serves as an entry point to create and configure a meeting session using various parameters passed via keyword arguments (kwargs). These parameters allow customization of the meeting setup to tailor it according to specific requirements.

### Parameters

- [MeetingConfig](../../types.md#meetingconfig)

### Returns

- [Meeting](../meeting/introduction.md)

## Example

```python
from videosdk import VideoSDK, MeetingConfig
    meeting_config = MeetingConfig(
        meeting_id=MEETING_ID,
        name=NAME,
        mic_enabled=True,
        webcam_enabled=True,
        token=VIDEOSDK_TOKEN,
    )
    # highlight-next-line
    meeting = VideoSDK.init_meeting(**meeting_config)
```

</div>


---

# MeetingConfig - Python

MeetingConfig `dataclass` simplifies configuration of meeting.

:::note
`dataclass` is decorater for user-defined classes, it was originally described in [pep-0557](https://peps.python.org/pep-0557/)
:::

## Meeting Config

```python title="Meeting Config"
  from videosdk import MeetingConfig
  meeting_config = MeetingConfig(
    meeting_id=MEETING_ID,
    name=NAME,
    mic_enabled=True,
    webcam_enabled=True,
    token=VIDEOSDK_TOKEN
  )

```

## MeetingConfig Parameters

---

### meeting_id

- Unique Id of the meeting where that participant will be joining.

  - type : `str`
  - `REQUIRED`

Please refer this [documentation](/api-reference/realtime-communication/create-room) to create a room.

---

### name

- Name of the participant who will be joining the meeting, this name will be displayed to other participants in the same meeting.

  - type : `str`
  - `REQUIRED`

---

### mic_enabled

- Whether `mic` of the participant will be on while joining the meeting. If it is set to `false`, then mic of that participant will be `disabled` by default, but can be `enabled` or `disabled` later.

  - type: `bool`
  - `REQUIRED`

---

### webcam_enabled

- Whether `webcam` of the participant will be on while joining the meeting. If it is set to `false`, then webcam of that participant will be `disabled` by default, but can be `enabled` or `disabled` later.

  - type: `bool`
  - `REQUIRED`

---

### token

- The auth token generated from your server.

  - type: `str`
  - `REQUIRED`

Please refer this [documentation](/api-reference/realtime-communication/intro) to generate a token.

---

### participant_id

- You can specify your custom participantId here.

  - type: `str`
  - `OPTIONAL`

---

### custom_camera_video_track

- Set the initial custom video track using different encoding parameters, camera facing mode, and optimization mode.

  - type: `MediaStreamTrack`
  - `OPTIONAL`

---

### custom_microphone_audio_track

- Set the initial custom audio track using different encoding parameters and optimization mode.

  - type: `MediaStreamTrack`
  - `OPTIONAL`

---

### mode

- `OPTIONAL`

- There are 2 types of modes:

  - `CONFERENCE`: Both audio and video streams will be produced and consumed in this mode.
  - `VIEWER`: Audio and video streams will not be produced or consumed in this mode.

  - defaultValue : `CONFERENCE`

---

### meta_data

- If you want to provide additional details about a user joining a meeting, such as their profile image, you can pass that information in this parameter.

  - type: `Dict`
  - `OPTIONAL`

---

### preferred_protocol

- `OPTIONAL`

- There are 3 types of protocol:

  - `UDP_OVER_TCP`: Initially the server attempts to establish a connection using UDP, if that fails it automatically switches to TCP protocol.
  - `UDP_ONLY`: Force UDP protocol
  - `TCP_ONLY`: Force TCP protocol
  - defaultValue : `UDP_OVER_TCP`

---

### signaling_base_url

- Proxy URL to origin signaling and media.

  - type: `str`
  - `OPTIONAL`

---


---

# Setup - Python

The `videosdk` library provides functionalities to manage video conferencing through the Video SDK platform. Here's a guide to get started with the `videosdk` library in Python.

## Installation

First, you need to install the `videosdk` package. You can do this using `pip`.

```sh
pip install videosdk
```

## Importing the Library

Import the necessary modules from the `videosdk` library:

```python
from videosdk import MeetingConfig, VideoSDK
```

## Sample Code

Here's a sample script to initialize and manage a meeting using the Video SDK:

```python
from videosdk import MeetingConfig, VideoSDK
import asyncio
loop = asyncio.get_event_loop()

def main():
    # Create meeting configuration
    meeting_config = MeetingConfig(
        meeting_id=MEETING_ID,
        name=NAME,
        mic_enabled=True,
        webcam_enabled=True,
        token=VIDEOSDK_TOKEN
    )

    # Initialize meeting
    meeting = VideoSDK.init_meeting(**meeting_config)

    meeting.join()

if __name__ == '__main__':
    main()
    loop.run_forever()
```


---

<h1> {props.title} </h1>{" "}

When integrating VideoSDK, you will come across with multiple terms like meeting, room, session and many more.

Let's discuss each term in detail so while integrating VideoSDK you don't get confused.

### Meeting / Room

- A Meeting or Room is a VideoSDK object which represents a real-time audio, video, and/or screen-share session, and is the basic building block for media sharing among participants which is returned by the VideoSDK once a successful connection is established.
- Meeting or Room can be uniquely identified by `meetingId` or `roomId`.

:::note
Meeting and Room are both the same. Similarly `meetingId` and `roomId` are same.
:::

### Session

- A Session is the instance of an ongoing meeting/room which has one or more participants in it. A single room or meeting can have multiple sessions.
- Each session can be uniquely identified by `sessionId`.
- All the sessions are associated with `meetingId`/`roomId` and can be listed using it.

### Participant

- Participant is a VideoSDK object which represents each user/client in the meeting or room and can share audio/video media with other.
- There can be multiple participants in a meeting/room and each participant can be uniquely identified by `participantId`.

### MediaStream

- MediaStream is the collection of audio and video tracks which holds the segments of audio/video media that are send and received by all the participants in the meeting.

### RTMP Live Stream

- RTMP live streaming is used to live stream your video conferencing apps to platforms like YouTube, Twitch, Facebook, etc. by providing the platform specific `streamKey` and `streamUrl`.

### Interactive Live streaming (HLS)

- Interactive live streaming is used to live stream your video conferencing apps within your own platform to allow a larger number of viewers who can not be accomodated in a real-time conference.



---

# Types - Python | VideoSDK

## MeetingConfig

| Parameter                       | Description                                                                                                                                                 | Type               | Required | Default Value  |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | -------- | -------------- |
| `meeting_id`                    | Unique Id of the meeting where that participant will be joining.                                                                                            | `str`              | Yes      | -              |
| `name`                          | Name of the participant who will be joining the meeting, this name will be displayed to other participants in the same meeting.                             | `str`              | Yes      | -              |
| `mic_enabled`                   | Whether `mic` of the participant will be on while joining the meeting. If set to `false`, mic will be `disabled` by default but can be changed later.       | `bool`             | Yes      | -              |
| `webcam_enabled`                | Whether `webcam` of the participant will be on while joining the meeting. If set to `false`, webcam will be `disabled` by default but can be changed later. | `bool`             | Yes      | -              |
| `token`                         | The auth token generated from your server.                                                                                                                  | `str`              | Yes      | -              |
| `participant_id`                | Custom participant ID.                                                                                                                                      | `str`              | No       | -              |
| `custom_camera_video_track`     | Set the initial custom video track using different encoding parameters, camera facing mode, and optimization mode.                                          | `MediaStreamTrack` | No       | -              |
| `custom_microphone_audio_track` | Set the initial custom audio track using different encoding parameters and optimization mode.                                                               | `MediaStreamTrack` | No       | -              |
| `mode`                          | Mode of the meeting. `CONFERENCE` produces and consumes audio/video streams. `VIEWER` does not.                                                             | `str`              | No       | `CONFERENCE`   |
| `meta_data`                     | Additional details about a user joining a meeting, such as their profile image.                                                                             | `Dict`             | No       | -              |
| `preferred_protocol`            | Preferred protocol: `UDP_OVER_TCP` attempts UDP first, then TCP; `UDP_ONLY` forces UDP; `TCP_ONLY` forces TCP.                                              | `str`              | No       | `UDP_OVER_TCP` |
| `signaling_base_url`            | Proxy URL to origin signaling and media.                                                                                                                    | `str`              | No       | -              |

You can use this table to quickly reference the parameters and their details for configuring a meeting using `MeetingConfig`.

#### Example

```python title="Meeting Config"
  from videosdk import MeetingConfig
  meeting_config = MeetingConfig(
    meeting_id=MEETING_ID,
    name=NAME,
    mic_enabled=True,
    webcam_enabled=True,
    token=VIDEOSDK_TOKEN
  )
  meeting = VideoSDK.init_meeting(**meeting_config)

```

## PubSubPublishConfig

| Parameter | Description                                                 | Type   | Required | Default Value |
| --------- | ----------------------------------------------------------- | ------ | -------- | ------------- |
| `topic`   | The topic under which the message will be published.        | `str`  | Yes      | -             |
| `message` | The message to be published under the specified topic.      | `str`  | Yes      | -             |
| `options` | Options for publish.                                        | `dict` | No       | -             |
| `payload` | Additional data or details to be included with the message. | `dict` | No       | -             |

### `options`

| Parameter | Description                                                                                         | Type   | Required | Default Value |
| --------- | --------------------------------------------------------------------------------------------------- | ------ | -------- | ------------- |
| `persist` | Whether the message should be persisted or not. If `true`, the message will be stored persistently. | `bool` | No       | `false`       |

Sure, here are the definitions in the form of Markdown tables:

## PubSubSubscribeConfig

| Parameter | Description                                              | Type       | Required | Default Value |
| --------- | -------------------------------------------------------- | ---------- | -------- | ------------- |
| `topic`   | The topic to subscribe to.                               | `str`      | Yes      | -             |
| `cb`      | The callback function to handle messages for this topic. | `Callable` | Yes      | -             |

## SummaryConfig

| Parameter | Description                                         | Type            | Required | Default Value |
| --------- | --------------------------------------------------- | --------------- | -------- | ------------- |
| `enabled` | Whether summary is enabled or not.                  | `bool`          | No       | `False`       |
| `prompt`  | An optional string prompt to customize the summary. | `Optional[str]` | No       | `None`        |

## TranscriptionConfig

| Parameter     | Description                                            | Type                      | Required | Default Value |
| ------------- | ------------------------------------------------------ | ------------------------- | -------- | ------------- |
| `webhook_url` | The URL for the webhook to send transcription updates. | `Optional[str]`           | No       | `None`        |
| `summary`     | Configuration for generating a summary.                | `Optional[SummaryConfig]` | No       | `None`        |

## PostTranscriptionConfig

| Parameter | Description                                       | Type                      | Required | Default Value |
| --------- | ------------------------------------------------- | ------------------------- | -------- | ------------- |
| `enabled` | Whether post-transcription processing is enabled. | `Optional[bool]`          | No       | `False`       |
| `summary` | Configuration for generating a summary.           | `Optional[SummaryConfig]` | No       | `None`        |

## RecordingConfig

| Parameter       | Description                                         | Type                                | Required | Default Value |
| --------------- | --------------------------------------------------- | ----------------------------------- | -------- | ------------- |
| `dir_path`      | The directory path where recordings will be stored. | `Optional[str]`                     | No       | `None`        |
| `transcription` | Configuration for post-transcription processing.    | `Optional[PostTranscriptionConfig]` | No       | `None`        |
| `config`        | Additional configuration options for recording.     | `Optional[Dict[str, Any]]`          | No       | `None`        |
| `webhook_url`   | The URL for the webhook to send recording updates.  | `Optional[str]`                     | No       | `None`        |


---

# Real-time AI Agent - Overview

In traditional online meetings, participants join, talk, listen, and collaborate. But what if one of those participants wasn’t human, yet could think, respond, and handle repetitive tasks? With VideoSDK, you can integrate AI agents into meetings, they can automate workflows, assist participants, and enhance collaboration in the virtual world.

![Realtime AI Agent Workflow](https://assets.videosdk.live/images/realtime_ai_agent_.png)

Building an AI agent that listens, thinks, and speaks feels like giving life to a virtual presence. Each of these capabilities adds a layer of intelligence, turning the AI from a passive observer to an active participant in the meeting. Here's how these three pillars of interaction come together:

| **Capability** | **Tools You Could Use**                                                                | **Description**                                                                                                                                    |
| -------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **STT**        | Deepgram, Google Speech-to-Text, AssemblyAI, Whisper, Sensory's TrulyHandsfree         | Tools that convert spoken language into text, enabling applications to process and understand human speech.                                        |
| **LLM**        | OpenAI's GPT Models, Google Bard, Claude by Anthropic, Meta's Llama 4, Amazon's Alexa+ | Advanced language models and AI assistants capable of understanding context, generating human-like text, and engaging in meaningful conversations. |
| **TTS**        | Eleven Labs, Amazon Polly, Microsoft Azure Speech Service, WaveNet, Sanas, Uniphore    | Solutions that transform text into natural-sounding speech, allowing applications to communicate with users audibly.                               |

## Workflow - Add an AI Agent to a Meeting

At VideoSDK, we are always keen on finding new ways to connect people virtually. Whether it’s a game, an online meeting, or any scenario that demands a human presence in a virtual setting, we strive to push the boundaries. So, why not take it a step further and introduce a truly human-like participant—an AI copilot meticulously crafted for its role?

### 1. Setup Environment & Dependencies

Install our Python SDK using pip, Python's package installer. Ensure you have a Python environment configured on your machine before installation.
[VideoSDK on PyPI](https://pypi.org/project/videosdk/)

```python
pip install videosdk
```

### 2. Connect to an Existing Meeting

The `MeetingConfig` class helps configure initial agent settings before joining a meeting. Since AI Agents don't have physical microphones, you can create a custom microphone audio track.

```python
from videosdk import MeetingConfig

# Initial settings for AI Agent
meeting_config = MeetingConfig(
    name=name,
    meeting_id=meeting_id,
    token=authToken,
    mic_enabled=True,
    webcam_enabled=False,
    custom_microphone_audio_track=self.audio_track
)
```

Next, create an instance connected to an active session. This session can be running on any platform (e.g., iOS, Web, Android).

```python
agent = VideoSDK.init_meeting(**meeting_config)
```

Finally, call the `join()` method on the meeting instance to connect the AI Agent to the existing meeting.

```python
agent.join()
```

### 3. Handle Meeting Events

Implement meeting event callbacks by extending VideoSDK's `MeetingEventHandler` class.

```python
from videosdk import Participant, MeetingEventHandler
from participant_events import MyParticipantEventHandler

class MyMeetingEventHandler(MeetingEventHandler):
    def __init__(self):
        super().__init__()

    def on_meeting_joined(self, data):
        print("Meeting joined:", data)

    def on_meeting_left(self, data):
        print("Meeting left:", data)

    def on_participant_joined(self, participant: Participant):
        print("Participant joined:", participant)
        participant.add_event_listener(
            MyParticipantEventHandler(participant_id=participant.id)
        )

    def on_participant_left(self, participant: Participant):
        print("Participant left:", participant)
```

Implement remote participant event listeners using similar patterns.

```python
from videosdk import ParticipantEventHandler, Stream

class MyParticipantEventHandler(ParticipantEventHandler):
    def __init__(self, participant_id: str):
        super().__init__()
        self.participant_id = participant_id

    def on_stream_enabled(self, stream: Stream):
        print("Participant stream enabled:", self.participant_id, stream.kind)

    def on_stream_disabled(self, stream: Stream):
        print("Participant stream disabled:", self.participant_id, stream.kind)
```

### 4. Working Example

The code below includes a working example where an AI agent joins an existing meeting using a FastAPI application. This application listens to client requests, accesses meeting credentials such as `meeting_id` and `token`, and joins an existing meeting.
![AI Agent FastAPI example](https://assets.videosdk.live/images/Untitled.png)

```python
from videosdk import MeetingConfig, VideoSDK

class AIAgent:
    def __init__(self, meeting_id: str, authToken: str, name: str):
        # MeetingConfig
        self.meeting_config = MeetingConfig(
            name=name,
            meeting_id=meeting_id,
            token=authToken,
            mic_enabled=False,
            webcam_enabled=False
        )
        # Create instance of existing session
        self.agent = VideoSDK.init_meeting(**self.meeting_config)

    async def join(self):
        await self.agent.async_join()
```

Next, we create a basic server where the client sends a request to join an AI Agent to an existing session.

```python
from fastapi.middleware.cors import CORSMiddleware
from fastapi import FastAPI
from pydantic import BaseModel
from videosdk.agents import AIAgent

port = 8000
app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

ai_agent = None

class MeetingReqConfig(BaseModel):
    meeting_id: str
    token: str

@app.get("/test")
async def test():
    return {"message": "CORS is working!"}

# Join AI agent
@app.post("/join-player")
async def join_player(req: MeetingReqConfig):
    global ai_agent
    ai_agent = AIAgent(req.meeting_id, req.token, "AI")
    await ai_agent.join()
    return {"message": "AI agent joined"}

# Running the server on port: 8000
if __name__ == "__main__":
    import uvicorn
    uvicorn.run("main:app", host="127.0.0.1", port=8000)
```

## Use Cases

Imagine a meeting where an intelligent participant listens, reflects, and responds with a human touch—making your digital interactions feel natural and engaging. Our projects exemplify how AI agents can be seamlessly integrated into your virtual workspace, enhancing communication and collaboration with lifelike interaction.

<div align="center">

**Explore Our AI Agent Projects**

| **Project**                                                                                        | **Description**                                                                                                                                 |
| -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| [AI Voice Agent with Deepgram STT](./ai-voice-agent-videosdk-deepgram-stt)                         | A real-time meeting assistant that harnesses advanced speech-to-text and voice synthesis technologies to deliver dynamic, natural interactions. |
| [AI Game Agent with ElevenLabs STT](./ai-game-agent-videosdk-elevenlabs-tts)                       | An engaging game agent that combines voice interaction with real-time communication, bringing a human-like presence to your gaming experiences. |
| [AI Translator Agent with OpenAI Realtime API](./ai-translator-agent-videosdk-openai-realtime-api) | A sophisticated translation tool that facilitates seamless multilingual communication, breaking down language barriers during online meetings.  |

</div>


---

# AI Game Agent - Integrating VideoSDK, ElevenLabs, and Deepgram



This project integrates VideoSDK, ElevenLabs, and Deepgram APIs to create an AI-powered game agent. Below are the setup instructions.

### Start with the project




---

# AI Translator Agent using VideoSDK and OpenAI Realtime API

This project integrates VideoSDK, OpenAI Realtime APIs to create an AI Translator Agent. Below are the setup instructions.

### Start with the project




---

# AI Voice Agent - Real-Time Meeting Assistant with Deepgram



This project is an AI Voice Agent that uses VideoSDK for video conferencing, Deepgram for speech-to-text (STT), and OpenAI for language model (LLM) capabilities. The AI Copilot can join meetings, transcribe speech, and respond intelligently.

### Start with the project



### Generate a Room ID

Generate a room ID on the client side and add it to the Python configuration. This can be done by running the client application and using the generated room ID in the `.env` file for the Python setup.


---

# Build Docker Image - Python Worker

This guide will walk you through the process of dockerizing a Python worker that uses the VideoSDK Python SDK. Dockerizing your worker allows you to package it along with all its dependencies, ensuring consistency across different environments.

## Prerequisites

- Docker installed on your system.
- Valid VideoSDK [Account](https://app.videosdk.live/)

### Step 1: Create Your Python Worker Script:

Below is a minimalistic example of a Python worker using VideoSDK:

```python
import asyncio
import os
from videosdk import (
    MeetingConfig,
    VideoSDK,
    Participant,
    Stream,
    MeetingEventHandler,
    ParticipantEventHandler,
    Meeting,
)

from dotenv import load_dotenv

load_dotenv()
VIDEOSDK_TOKEN = os.getenv("VIDEOSDK_TOKEN")
MEETING_ID = os.getenv("MEETING_ID")
NAME = os.getenv("NAME")

loop = asyncio.get_event_loop()

meeting: Meeting = None


class MyMeetingEventHandler(MeetingEventHandler):
    def __init__(self):
        super().__init__()

    def on_meeting_left(self, data):
        print("meeting left")

    def on_participant_joined(self, participant: Participant):
        print("participant joined")
        participant.add_event_listener(ParticipantEventHandler(participant=participant))

    def on_participant_left(self, participant: Participant):
        print("participant left")


class ParticipantEventHandler(ParticipantEventHandler):
    def __init__(self, participant: Participant):
        super().__init__()
        self.participant = participant

    def on_stream_enabled(self, stream: Stream):
        print("stream enabled", stream.kind)

    def on_stream_disabled(self, stream: Stream):
        print("stream disabled", stream.kind)


def main():
    global meeting

    meeting_config = MeetingConfig(
        meeting_id=MEETING_ID,
        name=NAME,
        mic_enabled=False,
        webcam_enabled=False,
        token=VIDEOSDK_TOKEN,
    )
    meeting = VideoSDK.init_meeting(**meeting_config)

    print("adding event listener...")
    meeting.add_event_listener(MyMeetingEventHandler())

    print("joining into meeting...")
    meeting.join()


if __name__ == "__main__":
    main()
    loop.run_forever()
```

### Step 2: Create requirements.txt

If your Python script relies on other dependencies, you should specify them in a requirements.txt file. Here’s an example:

```txt
videosdk==0.0.5
python-dotenv==1.0.1
asyncio==3.4.3
```

### Step 3: Configure Environment Variables

To securely pass your Auth Token and other sensitive information to the Docker container, you should use environment variables. Here, you will create a .env file to store your environment variables locally.

```env
VIDEOSDK_TOKEN="YOUR_VIDEOSDK_TOKEN"
MEETING_ID="YOUR_MEETING_ID"
NAME="YOUR_NAME"
```

### Step 4: Write a Dockerfile

A Dockerfile is a script that contains a series of commands used to create a Docker image. Here’s an example Dockerfile for your Python worker:

```dockerfile
FROM python:3.11-slim

RUN apt-get update && apt-get install -y python3-dev

WORKDIR /app

COPY requirements.txt .

RUN python -m pip install -r requirements.txt

COPY . .

ENTRYPOINT ["python", "-u" , "main.py"]
```

### Step 5: Build the Docker Image

In the same directory as your Dockerfile and Python script, run the following command to build your Docker image:

```bash
docker build -t videosdk-python-worker .
```

This command creates a Docker image named videosdk-python-worker.

### Step 6: Run the Docker Container

Once the image is built, you can run it using the following command:

```bash
docker run --env ENV_VARS="$(cat ./.env)" videosdk-python-worker
```

### Step 7: Push to a Container Registry (Optional)

If you want to deploy your Dockerized python worker on a platform like AWS, GCP, or Azure, you might want to push the image to a container registry like Docker Hub.

Log in to Docker Hub:

```bash
docker login
```

Tag your image:

```bash
docker tag videosdk-python-worker your_dockerhub_username/videosdk-python-worker
```

Replace `your_dockerhub_username` with your dockerhub username.

Push your image to Docker Hub:

```bash
docker push your_dockerhub_username/videosdk-python-worker
```

:::tip

Stuck anywhere? Check out this [example code](https://github.com/videosdk-live/videosdk-rtc-python-sdk-example/tree/main/python-worker) on GitHub

:::

### Conclusion

You've successfully dockerized your Python worker using the VideoSDK Python SDK, including configuring environment variables for security. This Dockerized version can be deployed in any environment that supports Docker, ensuring consistency and scalability.


---

Our Python SDK provides the necessary tools to integrate Video and Audio calls into your server. It simplifies the process, enabling you to create customizable real-time video & audio calling applications efficiently.

### Installing Python SDK

You can install our Python SDK using pip, the package installer for Python. Make sure you have a Python environment set up on your machine before proceeding with the installation.

```sh
pip install videosdk
```

### Upgrading Python SDK

You can upgrade our Python SDK using pip.

```sh
pip install -U videosdk
```


---

# Release Notes - Python

This page will provide you with updates on all releases of the Python SDK.

## v0.0.2

**Release Date** : 25th June 2024

**Change log** :

1. Foundation (BETA): implementation of python sdk for realtime/post transcription, cloud recordings, support of ai/ml pipeline on mediastream.

2. Participant: capture_image method implmenetation on participant

3. bux fixes

## v0.0.1

**Release Date** : 25th June 2024

**Change log** :

1. Foundation (BETA): implementation of python sdk for audio-video call.


---

# Supported Device OS and Architecture

:::note
The following device OS versions represent the minimum required versions to ensure full support for the listed features.
:::

## Ubuntu Linux Supported Versions

- Ubuntu 18.04 LTS and above

## macOS Supported Versions

- macOS 10.14 Mojave and above

## Windows Supported Versions

- Windows 10 and above

If you have any questions or need further assistance, feel free to reach out to our support team.


---

<h1> {props.title} </h1>{" "}

### Why we are using JWT based Token ?

Token based authentication allows users to verify their identity by providing generated API key and secret.

We use JWT token for the authentication purpose because Token-based authentication is **widely used** in modern web applications and APIs because it offers several benefits over traditional authentication. For example, it can **reduce the risk of the credentials being misused**, and it allows for **more fine-grained control** over access to resources. Additionally, tokens can be easily revoked or expired, making it easier to manage access rights.

### How to generate Token ?

To manage secured communication, every participant that connects to the meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key` which you can get from [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

#### 1. Generating token from Dashboard

If you are looking to do **testing or for development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for getting token includes generating it from your backend server which will help in **keeping your credentials safe**.
:::

#### 2. Generating token in your backend

- Your server will generate access token using your API key and secret.
  - While generating a token, you can provide **expiration time, permissions and roles** which are discussed later in this section.
- Your client obtains token from your backend server.
- For token validation, client will pass this token to VideoSDK server.
- VideoSDK server will only allow entry in the meeting if the token is valid.

![img2.png](../../static/img/authentication-and-token.png)




Follow our official example repositories to setup token API [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)

### Payload while generating token

```js
{
 apikey: API_KEY, //MANDATORY
 permissions: [`allow_join`], //`ask_join` || `allow_mod` //MANDATORY
 version: 2, //OPTIONAL
 roomId: ROOM_ID, //OPTIONAL,
 participantId: PARTICIPANT_ID, //OPTIONAL
 roles: ['crawler', 'rtc'], //OPTIONAL
}
```

- **`apikey`(Mandatory)**: This must be the API Key generated from the VideoSDK Dashboard. You can get it from [here](https://app.videosdk.live/api-keys).

- **`permissions`(Mandatory)**: By providing the permissions, you can control what a participant can do in the meeting and whether he can join the meeting directly.

  Available permissions are:

  - **`allow_join`**: The participant is **allowed to join** the meeting directly.
  - **`ask_join`**: The participant is required to **ask for permission to join** the meeting. The participant having the permission `allow_join` can accept or reject a participant whenever someone wants to join.
  - **`allow_mod`**: The participant is **allowed to toggle** webcam & mic of other participants.

- **`version`(optional)**: For accessing the [v2 API](/api-reference/realtime-communication/intro), you need to provide `2` as the version value.

  - For passing `roomId`, `participantId` or `roles` parameters in payload, it is essential to set the version value to `2`.

- **`roomId`(optional)**: To provide customised access control, you can make the token applicable to a particular room by including the `roomId` in the payload.

- **`participantId`(optional)**: You can include the `participantId` in the payload to limit the token's access to a particular participant.

- **`roles`(optional)**:

  - **`crawler`**: This role is only for accessing [v2 API](/api-reference/realtime-communication/intro), you can not use this token for running the `Meeting`/`Room`.
  - **`rtc`**: This role is only allowed for running the `Meeting` / `Room`, with this role you can not use [server-side APIs](/api-reference/realtime-communication/intro).

Then, you have to sign this payload with your **`SECRET KEY`** and `jwt` options using the **`HS256 algorithm`**.

### Expiration time

You can set any expiration time to the token. But in the **production environment**, it is recommended to generate a token with **short expiration time** because by any chance if someone gets hold of the token, it won't be valid for a longer period of time.

### What happens if token is expired?

If your token is expired, the user won't be able to join the meeting and all the API calls will give error with message `Token is invalid or expired`.

:::note
Token is validated only once while joining the meeting, so if a person joins the meeting and the token gets expired after that, there won't be any issue in the current meeting.
:::

## How to check validity of token?

1. After generating the token, visit [jwt.io](https://jwt.io) and paste your token in the given area.
2. You will be able to see the payload you passed while generating the token and also be able to see the expiration time and token creation time.

![img1.png](../../static/img/validate-token.png)

## API Settings & Controls

The VideoSDK Dashboard provides a powerful [API Settings](https://app.videosdk.live/api-keys) section where you can configure various services and controls for your meetings. These settings allow you to customize the behavior of different features directly from the dashboard without requiring code changes.

## Audio/Video Configurations

:::note
Runtime configuration from the dashboard has higher precedence than static SDK configurations.
If a value is modified in the dashboard, it will override any previously defined SDK settings for that session.

Example:
Code: Video = HD → Dashboard: Video = Full HD → Applied: Full HD
:::

### Maximum Send Bitrate Per Participant

Control the maximum total upload bandwidth for all media streams from a single participant.

![Maximum Send Bitrate](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.00.11%E2%80%AFPM.png)

**Available Options:**
- **Auto**: Removes the upload bitrate limit (recommended for best quality)
- **SD (800kbps)**: Standard definition bitrate
- **HD (1500kbps)**: High definition bitrate
- **Full HD (3000kbps)**: Full high definition bitrate

:::tip
Setting this to **Auto** provides the best video quality as it removes upload bitrate constraints, allowing adaptive streaming based on network conditions.
:::

## Recording & Streaming Configuration

:::note
Recording and HLS follow a precedence-based configuration model:

API/SDK configuration → Highest priority
Dashboard configuration → Used only when no API values are defined

Any parameters explicitly set via the API will not be overridden by dashboard changes.
:::

### Recording Configuration

Configure recording settings for your meetings including layout, quality, and auto-start options.

![Recording Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.01.00%E2%80%AFPM.png)

**Recording Controls:**
- **Enabled**: Toggle to enable/disable recording functionality
- **Enabled Modes**: Choose between Video & Audio or Audio Only recording
- **Start Recording Automatically**: Auto-start recording when meeting begins
- **Layout Style**: Select Grid layout for recording composition
- **Maximum Tiles In Grid**: Set the number of participants visible in grid (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme for recordings
- **Video Orientation**: Choose between Landscape or Portrait mode
- **Recording Quality**: Select quality level (e.g., HD Medium)
- **Recording Mode**: Choose between Video & Audio or Audio Only

### HLS Streaming Configuration

Configure HTTP Live Streaming (HLS) settings for broadcasting your meetings.

![HLS Streaming Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.02.18%E2%80%AFPM.png)

**HLS Streaming Controls:**
- **Enabled**: Toggle to enable/disable HLS streaming
- **Enabled Modes**: Choose between Video & Audio or Audio Only streaming
- **Auto Start HLS**: Automatically start HLS when meeting begins
- **Record HLS Stream**: Enable recording of the HLS stream
- **Layout Style**: Select Grid layout for stream composition
- **Maximum Tiles In Grid**: Set the number of participants visible (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme
- **HLS Orientation**: Choose between Landscape or Portrait mode
- **HLS Quality**: Select streaming quality (e.g., HD Medium)
- **HLS Streaming Mode**: Choose between Video & Audio or Audio Only

### Additional Service Controls

Enable or disable additional services for your API key.

![Service Controls](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.08%E2%80%AFPM.png)

**Available Services:**
- **RTMP Output**: Enable RTMP streaming to external platforms
- **SIP Integration**: Enable SIP (Session Initiation Protocol) integration for telephony
- **Realtime Translation**: Enable real-time language translation in meetings

### Transcription & Summary

Configure transcription and domain whitelisting for your API key.

![Transcription Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.50%E2%80%AFPM.png)

**Transcription Controls:**
- **Enabled**: Toggle to enable/disable transcription and summary features
- **Whitelist Domain**: Add domain restrictions for API key usage
  - Enter domain names in the format `https://domain.name`
  - Click "Add Domain" to whitelist specific domains
  - Only whitelisted domains can use this API key
  - When no domains are whitelisted, the API key can be used from any domain


---

# Concept and Architecture - Python

Before diving into the concept, it's essential to understand the VideoSDK. VideoSDK is a software development kit that offers tools and APIs for creating apps that are based on video and audio. It typically includes features such as video and audio calls, chat, cloud recording, simulcasting (RTMP), interactive live streaming (HLS), and many more across a wide range of platforms and devices.

The **Python SDK** streamlines server-side integration of `VideoSDK`, unlocking its **Full feature set**. Developers can seamlessly incorporate **AI agents**, **ML pipelines** and more into VideoSDK using this powerful SDK.

## Concepts

<div style={{textAlign: 'center'}}>

<img src="/img/room-concept.png" alt="room_concept_img" />

</div>

### `1. Meeting / Room`

- Meeting or Room object in the VideoSDK provides a virtual place for participants to interact and engage in real-time voice, video, and screen-sharing sessions. The object is in charge of handling media streams and participant communication.

- Meeting or Room can be uniquely identified by `meetingId` or `roomId`.

### `2. Participant`

- Participant is a VideoSDK object that represents each user/client in the meeting or room and allows them to share audio/video assets.

- `2.1 Local Participant` :
  The local participant is the one that runs on the user's device. The local participant has control over their own media streams, including the ability to start and stop audio and video.

  - The local participant in a meeting/room can also connect with other participants by transmitting and receiving audio and video streams, exchanging chat messages, and more.

- `2.2 Remote Participant` :
  The remote participant receives audio and video streams from both the local participant and other remote participants. Additionally, they have the ability to exchange audio, video, and chat messages with the local participant.

- Each participant in VideoSDK can be uniquely identified by `participantId`.

### `3. MediaStream & Track`

- A mediastream is a collection of audio & video tracks that can be transmitted between participants in real-time.

- A track is a continuous flow of audio or video data and can be thought of as a stream of media frames.

- A mediastream can contain multiple tracks. One video track for the video feed from the camera and one audio track for the audio feed from the microphone. These tracks can be transmitted between participants in VideoSDK Meeting / Room.

### `4. Events / Notifications`

- Events / Notifications can be used to inform users about various activities happening in a Meeting / Room, including participant join/leave and new messages. They can also be used to alert users about any SDK-level errors that occur during a call.

### `5. Session`

- A Session is the instance of an ongoing meeting/room which has one or more participants in it. A single room or meeting can have multiple sessions.
- Each session can be uniquely identified by `sessionId`.

![img.png](../../../../static/img/meeting-session.jpg)

---

<div style={{textAlign: 'center'}}>

<img src="/img/recording-hls-rtmp.png" alt="sesssion_img" />

</div>

### `6. Cloud Recording`

- Cloud recording in VideoSDK refers to the process of recording audio or video content and storing it on a remote server or VideoSDK server.

### `7. Simulcasting (RTMP)`

- RTMP is a popular protocol for live streaming video content from the VideoSDK to platforms such as YouTube, Twitch, Facebook, and others.
- By providing the platform-specific `stream key` and `stream URL`, the VideoSDK can connect to the platform's RTMP server and transmit the live video stream.

### `8. Http Live Streaming (HLS)`

- Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

- In an interactive live stream (HLS), viewers can participate in various activities, such as live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

### `9. Transcription`

- Transcription is the process of converting spoken language into written text. Transcription plays a crucial role in various fields such as journalism, legal proceedings, medical documentation, and content creation for accessibility purposes.

- `9.1 Post Transcription` :
  Post-transcription, also known as offline transcription, occurs after the spoken content has been recorded. The recording is then transcribed into text.

  This method is commonly used for creating written records of meetings, interviews, podcasts, and other recorded events.

- `9.2 Realtime Transcription` :
  Real-time transcription, also known as live transcription or simultaneous transcription, is the process of converting spoken language into text as the speech is occurring.

  This is often used in live broadcasts, webinars, conferences, and for providing live captions for individuals with hearing impairments.

## Architecture

This diagram illustrates the comprehensive flow for implementing video and audio calls, recording calls, and broadcasting live on social media platforms.

<div style={{textAlign: 'center'}}>

<img src="/img/video-sdk-archietecture.svg" alt="architecture_image" />

</div>


---

Real-time AI translation bridges language barriers in video calls by automatically processing spoken audio, translating it, and speaking the translation in another language. In this project, we leverage VideoSDK for real-time audio/video conferencing and [OpenAI’s Realtime API](https://platform.openai.com/docs/guides/realtime) for integrated speech-to-text (STT), translation, and text-to-speech (TTS).

The **AI voice agent** joins a meeting as a "translator," capturing participants’ audio streams, sending them to OpenAI’s streaming endpoint, and injecting the synthesized translated speech back into the meeting. This full-stack system combines a React frontend, a FastAPI backend, and a Python-based AI agent to facilitate seamless multilingual communication.

### Get the Code on GitHub



<div style={{
  display: 'inline-block', // Equivalent to HTML display: inline-block;
  width: '100%',
  maxWidth: '1200px',     // Equivalent to HTML max-width: 1200px;
  backgroundColor: '#191919', // Equivalent to HTML background-color: #1e1e1e; (camelCase)
  color: '#ffffff',
  padding: '20px',
  // Correct border syntax: width style color as a single string
  border: '1px solid #333', // Added a 1px solid border with color #333 (brighter than #191919)
  borderRadius: '10px',   // Equivalent to HTML border-radius: 10px; (camelCase)
  overflow: 'hidden',
  boxSizing: 'border-box' // Equivalent to HTML box-sizing: border-box; (camelCase)
}}>
  <div style={{
    display: 'inline-block',
    verticalAlign: 'top', // Changed back to 'top' as it's more reliable for vertical alignment of inline-block elements than 'center'
    width: 'calc(65% - 16px)', // calc() value remains a string - using 16px based on user's margin
    marginRight: '16px',  // Equivalent to HTML margin-right: 20px; (camelCase)
    boxSizing: 'border-box',
    fontStyle: 'italic',    // Equivalent to HTML font-style: italic; (camelCase)
    fontSize: '1.1em',      // Equivalent to HTML font-size: 1.1em; (camelCase)
    lineHeight: '1.5',       // Equivalent to HTML line-height: 1.5; (camelCase)
    color:'gray'
  }}>
    This project integrates VideoSDK and OpenAI Realtime APIs to create a powerful AI Translator Agent. Below are the detailed setup instructions to help you get started quickly. Be sure to <a href="https://github.com/videosdk-community/videosdk-openai-realtime-translator" target="_blank">check out the GitHub</a> repository for a fully functional working example
  </div>
  <div style={{
    display: 'inline-block',
    verticalAlign: 'top',
    width: '35%', // Adjust this if needed based on the text width and margin
    boxSizing: 'border-box'
  }}>
    <a href="https://github.com/videosdk-community/videosdk-openai-realtime-translator" target="_blank" style={{ // Style object for the anchor tag
      display: 'block',
      textDecoration: 'none' // Equivalent to HTML text-decoration: none; (camelCase)
    }}>
      <img
        src="https://assets.videosdk.live/images/isis.png"
        alt="Architecture Diagram"
        style={{ // Style object for the image tag
          maxWidth: '100%', // Equivalent to HTML max-width: 100%; (camelCase)
          height: 'auto',
          display: 'block',
          borderRadius: '10px' // Equivalent to HTML border-radius: 10px; (camelCase)
        }}
      />
    </a>
  </div>
</div>



### Step-by-Step Video Guide

<div style={{
  display: 'block',
  width: '100%',
  maxWidth: '1200px',
  backgroundColor: '#191919', // Equivalent to HTML background-color: #1e1e1e; (camelCase)
  color: '#ffffff',
  padding: '20px',
  border: '1px solid #333',
  borderRadius: '10px',
  overflow: 'hidden',
  boxSizing: 'border-box',
  margin: '20px auto'
}}>

  <p style={{
    margin: '0',
    fontStyle: 'italic',
    fontSize: '1.1em',
    lineHeight: '1.5',
    marginBottom: '20px',
    color: 'gray'
  }}>
    This webinar dives into building real-time conversational AI agents using VideoSDK for robust audio/video infrastructure and [OpenAI's Realtime API](https://platform.openai.com/docs/guides/realtime), with a focus on speech-to-speech functionality. We explore the architecture of an AI Translator Agent, covering how the client, Python backend, audio processing, and OpenAI integration work together. Discover the potential of AI in real-time communication and find the complete code example on our GitHub repository. New users can also get <a href="https://app.videosdk.live" target="_blank">10,000 free minutes</a> every month on VideoSDK to start building their own agents.
  </p>

  <div>
    Watch the video: [YouTube video player](https://www.youtube.com/watch?v=t7fenFczUog)
  </div>
</div>

## System Architecture

Below is the architecture diagram illustrating this flow:

![Architecture Diagram](https://assets.videosdk.live/images/isis.png)

As highlighted in the diagram above, the AI Translation Agent is a distributed system comprising three core components working in synergy:

1.  **React Frontend:** The user interface built with React and VideoSDK's React SDK, enabling users to create/join meetings and interact visually.
2.  **FastAPI Backend:** A Python server acting as an intermediary to launch the AI Agent process upon user request from the frontend.
3.  **Python AI Agent:** The intelligent core, using the VideoSDK Python SDK to participate in the meeting and the OpenAI Realtime API for integrated speech processing and translation.

The flow begins with users interacting with the **React Frontend** to manage their meeting session. When a user decides to add the translation capability, the frontend signals the **FastAPI Backend**. The backend's role is simple but crucial: it spins up the separate **Python AI Agent** process. This agent then uses its own VideoSDK client (via the Python SDK) to join the same meeting as a participant. Once inside, it listens to the audio streams of other participants, processes them, sends them to OpenAI for transcription and translation, receives the translated speech back, and injects that audio stream into the meeting for everyone to hear.

## Clone This Project

Follow the steps below to get started with the <b>AI Translation Agent</b> project.



## Technical Deep Dive

### Key Components and Code Walkthrough

Let's break down the code in each major part of the application to understand how this real-time translation happens.

#### 1. React Frontend

The frontend is responsible for the user experience – letting them join a meeting, setting their name and language, and visualizing the participants. It also handles the UI logic for inviting the AI agent and managing microphone state.

- **`client/src/App.tsx`**: This is the main entry point for the client application.
  - It manages the meeting state (`meetingId`), user name (`userName`), and selected language (`selectedLanguage`).
  - It uses the `MeetingProvider` from `@videosdk.live/react-sdk` to set up the meeting context, passing the `meetingId`, user `name`, and importantly, their `preferredLanguage` in the `metaData`. This metadata is later accessed by the AI Agent.
  - It handles the UI for creating or joining a meeting and gathering user information.

```typescript title="client/src/App.tsx (within App component)"

```

- The `MeetingView` component (also in `App.tsx`) displays the participants. It iterates through the `participants` map provided by `useMeeting`, identifying the AI participant based on display name and rendering `ParticipantCard` for each.

- **`client/src/components/ParticipantCard.tsx`**: This component renders individual participant tiles (or a large view for the AI).
  - It uses the `useParticipant` hook to get participant-specific data like `displayName`, `micStream`, `webcamStream`, `isActiveSpeaker`, and `isLocal`.
  - It includes logic for a "Hold to Speak" (spacebar push-to-talk) button for local human participants. This is a common pattern to control when audio is sent, crucial for managing potential feedback in calls with agents.

```typescript title="client/src/components/ParticipantCard.tsx (Push-to-Talk useEffect)"
React.useEffect(() => {
  if (!isLocal || isAI) return;
  // ... add keydown/keyup listeners for spacebar ...
  const handleKeyDown = (e: KeyboardEvent) => {
    if (e.code === "Space" && !isSpeaking) {
      e.preventDefault();
      setIsSpeaking(true);
      unmuteMic(); // Unmute mic when spacebar is held
    }
  };
  const handleKeyUp = (e: KeyboardEvent) => {
    if (e.code === "Space") {
      e.preventDefault();
      setIsSpeaking(false);
      muteMic(); // Mute mic when spacebar is released
    }
  };
  // ... add and remove event listeners ...
}, [isLocal, isAI, isSpeaking, unmuteMic, muteMic]);
```

- It has a key `useEffect` hook that detects when the AI participant becomes the `isActiveSpeaker`. When this happens _and_ the current participant is the local human user, it includes logic to automatically mute the local microphone. This is a critical step to prevent the human's microphone from picking up the AI's translated speech and creating a feedback loop or confusing the AI's STT.

```typescript title="client/src/components/ParticipantCard.tsx (Auto-Mute useEffect)"
React.useEffect(() => {
  if (isLocal && !isAI && isActiveSpeaker) {
    // If THIS card is the local human AND they are active speaker...
    const aiParticipants = document.querySelectorAll(
      '[data-ai-participant="true"]' // Find AI participants
    );
    aiParticipants.forEach((ai) => {
      // Check if ANY AI participant is marked as currently speaking by the UI
      if (ai.getAttribute("data-is-speaking") === "true") {
        muteMic(); // If an AI is speaking, mute the local human mic
        setIsSpeaking(false);
      }
    });
  }
}, [isLocal, isAI, isActiveSpeaker, muteMic]); // Depend on mic state changes
```

- Displays video (`<video ref={videoRef}>`) or an avatar (`` or ``) and the participant's name.

- **`client/src/components/MeetingControls.tsx`**: Contains basic meeting controls.
  - The "Invite AI Translator" button triggers a `fetch` request to the backend's `/join-player` endpoint, sending the current `meetingId` and `token`.

```typescript title=client/src/components/MeetingControls.tsx (inviteAI function)
const inviteAI = async () => {
  try {
    const response = await fetch("http://localhost:8000/join-player", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ meeting_id: meetingId, token }),
    });
    if (!response.ok) throw new Error("Failed to invite AI");
    toast.success("AI Translator joined successfully");
    setAiJoined(true); // Update state to reflect AI joined
  } catch (error) {
    toast.error("Failed to invite AI Translator");
    console.error("Error inviting AI:", error);
  }
};
```

#### 2. FastAPI Backend

The backend is minimal, serving primarily to launch the AI agent process when requested by the frontend.

- **`main.py`**:
  - Sets up a basic FastAPI app with CORS enabled.
  - Defines the `/join-player` endpoint that accepts the meeting ID and token.
  - It uses FastAPI's `BackgroundTasks` to run the `server_operations` function. This is important because the `ai_agent.join()` call is a long-running asynchronous process that would otherwise block the HTTP request.

```python title="main.py"
  @app.post("/join-player")
  async def join_player(req: MeetingReqConfig, bg_tasks: BackgroundTasks):
      # Add the server_operations async function to background tasks
      bg_tasks.add_task(server_operations, req)
      return {"message": "AI agent joined"}

  async def server_operations(req: MeetingReqConfig):
      global ai_agent
      # Initialize and join the AI agent in the background
      ai_agent = AIAgent(req.meeting_id, req.token, "AI")
      try:
          await ai_agent.join()
          # Keep the background task running to keep the agent active
          while True:
              await asyncio.sleep(1)
      except Exception as ex:
          print(f"[ERROR]: either joining or running bg tasks: {ex}")
      finally:
          # Ensure the agent leaves the meeting cleanly if the task stops
          if ai_agent:
              ai_agent.leave()

  # ... uvicorn main execution block ...
```

#### 3. Python AI Agent

This is where the AI Agent lives and interacts with both VideoSDK and OpenAI.

- **`ai_agent.py`**:
  - Initializes the `VideoSDK` meeting client using `VideoSDK.init_meeting`. Notice the `custom_microphone_audio_track` is set to an instance of `CustomAudioStreamTrack`. This is how the agent will output its translated speech into the meeting.

```python title="agent/ai_agent.py (within AIAgent.__init__)"
  self.audio_track = CustomAudioStreamTrack(
      loop=self.loop, handle_interruption=True
  )
  self.meeting_config = MeetingConfig(
      # ... other config ...
      mic_enabled=True, # Agent needs mic enabled to speak
      webcam_enabled=False,
      custom_microphone_audio_track=self.audio_track, # Inject custom audio here
  )
  self.agent = VideoSDK.init_meeting(**self.meeting_config)
  # Add event listeners for meeting and participant events
  self.agent.add_event_listener(MeetingHandler(...))
```

- The `on_participant_joined` callback (part of `MeetingHandler`) is triggered when a user joins. It extracts the `preferredLanguage` from the participant's `meta_data` that was sent from the frontend.
- When two human participants have joined (besides the AI), the agent can dynamically update the OpenAI session instructions using `self.intelligence.update_session_instructions`. This tells OpenAI the languages to translate _between_ based on the detected languages of the human participants.

```python title="agent/ai_agent.py (within on_participant_joined)"
  peer_name = participant.display_name
  native_lang = participant.meta_data["preferredLanguage"] # Get language from frontend metadata
  self.participants_data[participant.id] = {
      "name": peer_name,
      "lang": native_lang,
  }
  print("Participant joined:", peer_name)
  print("Native language :", native_lang)

  # When we have 2 human participants, set the translator instructions
  if len(self.participants_data) == 2:
      participant_ids = list(self.participants_data.keys())
      p1 = self.participants_data[participant_ids[0]]
      p2 = self.participants_data[participant_ids[1]]

      translator_instructions = f"""
          You are a real-time translator bridging a conversation between:
          - {p1['name']} (speaks {p1['lang']})
          - {p2['name']} (speaks {p2['lang']})

          You have to listen and speak those exactly word in different language
          eg. when {p1['lang']} is spoken then say that exact in language {p2['lang']}
          similar when {p2['lang']} is spoken then say that exact in language {p1['lang']}
          Keep in account who speaks what and use
          NOTE -
          Your job is to translate, from one language to another, don't engage in any conversation
      """
      # Asynchronously update the OpenAI session
      asyncio.create_task(
          self.intelligence.update_session_instructions(translator_instructions)
      )
  # ... stream handling logic ...
```

- For each participant, a `ParticipantHandler` is attached. When a participant's audio stream is enabled (`on_stream_enabled`), the agent starts an asynchronous task (`add_audio_listener`) to process that stream.
- The `add_audio_listener` method reads audio frames (`stream.track.recv()`), processes the raw audio data (converting from VideoSDK's internal format to a NumPy array, resampling from 48kHz to 16kHz, and converting to 16-bit PCM bytes), and then sends these processed bytes to the `OpenAIIntelligence` instance.

```python title="agent/ai_agent.py (within add_audio_listener)"
  while True:
      try:
          # await asyncio.sleep(0.01) # Small sleep to prevent tight loop
          if not self.intelligence.ws:
              continue # Wait for OpenAI WS to be ready

          frame = await stream.track.recv() # Receive audio frame from VideoSDK
          audio_data = frame.to_ndarray()[0]
          audio_data_float = ( # Convert to float32
              audio_data.astype(np.float32) / np.iinfo(np.int16).max
          )
          audio_mono = librosa.to_mono(audio_data_float.T) # Ensure mono
          audio_resampled = librosa.resample( # Resample to 16kHz
              audio_mono, orig_sr=48000, target_sr=16000
          )
          pcm_frame = ( # Convert back to 16-bit PCM bytes
              (audio_resampled * np.iinfo(np.int16).max)
              .astype(np.int16)
              .tobytes()
          )

          # Send processed audio to OpenAI Intelligence module
          await self.intelligence.send_audio_data(pcm_frame)

      except Exception as e:
          print("Audio processing error:", e)
          break # Exit loop on error
```

#### 4. OpenAI Integration

This module handles the communication with the OpenAI Realtime API over a WebSocket.

- **`openai_intelligence.py`**:
  - The `OpenAIIntelligence` class establishes and manages the WebSocket connection to the OpenAI Realtime API endpoint (`wss://api.openai.com/v1/realtime`).
  - The `connect` method sets up the WebSocket and initiates the `receive_message_handler` task.
  - The `send_audio_data` method takes the 16kHz PCM audio bytes received from the `AIAgent`, Base64 encodes them, and sends them as an `input_audio_buffer.append` message over the WebSocket.

```python title="intelligence/openai/openai_intelligence.py (send_audio_data)"
  async def send_audio_data(self, audio_data: bytes):
      """audio_data is assumed to be pcm16 24kHz mono little-endian"""
      # Base64 encode the raw audio bytes
      base64_audio_data = base64.b64encode(audio_data).decode("utf-8")
      # Create and send the append message
      message = InputAudioBufferAppend(audio=base64_audio_data)
      await self.send_request(message) # send_request just sends the JSON string over WS
```

- The `receive_message_handler` asynchronously processes incoming messages from OpenAI. It parses the JSON messages and handles different event types.
- A critical event it handles is `EventType.RESPONSE_AUDIO_DELTA`, which contains Base64 encoded chunks of the synthesized translated speech. When this event is received, the audio data is decoded and passed to the AI agent's custom audio track using `self.on_audio_response`.

```python title="intelligence/openai/openai_intelligence.py (within receive_message_handler)"
  async for response in self.ws:
      try:
          if response.type == aiohttp.WSMsgType.TEXT:
              message = json.loads(response.data)
              match message["type"]:
                  case EventType.RESPONSE_AUDIO_DELTA:
                      # Decode the received Base64 audio chunk
                      audio_chunk = base64.b64decode(message["delta"])
                      # Pass the audio chunk to the custom audio track buffer
                      self.on_audio_response(audio_chunk)
                  case EventType.ITEM_INPUT_AUDIO_TRANSCRIPTION_COMPLETED:
                      # Log the transcription of the input audio
                      print(f"Client Transcription: {message['transcript']}")
                  # ... handle other events like SESSION_CREATED, ERROR, etc. ...
      except Exception as e:
          traceback.print_exc()
          print("Error in receiving message:", e)
```

- The `update_session_instructions` method, called by the AI agent, updates the system prompt for the OpenAI session, informing it of the languages to translate between.

```python title="intelligence/openai/openai_intelligence.py (update_session_instructions)"
  async def update_session_instructions(self, new_instructions: str):
      """Dynamically update the system instructions for the OpenAI session."""
      if self.ws is None:
          self.pending_instructions = new_instructions # Queue if not connected yet
          return
      # Update the session parameters object and send the update message
      self.session_update_params.instructions = new_instructions
      await self.update_session(self.session_update_params)

  async def update_session(self, session: SessionUpdateParams):
      # Send the session.update message over the WebSocket
      await self.send_request(
          SessionUpdate(
              event_id=generate_event_id(),
              session=session,
          )
      )
```

#### 5. Custom Audio Stream Track

This class acts as a virtual microphone for the AI Agent, allowing it to inject audio received from OpenAI back into the VideoSDK meeting.

- **`agent/audio_stream_track.py`**:
  - Inherits from `videosdk.CustomAudioTrack`, requiring implementation of the `recv` method.
  - It maintains a `frame_buffer` which stores `av.AudioFrame` objects.
  - The `add_new_bytes` method is called by `OpenAIIntelligence` when it receives translated audio chunks. This method takes the raw audio bytes, converts them into `av.AudioFrame` objects, and adds them to the `frame_buffer`.

```python title="agent/audio_stream_track.py (add_new_bytes and _process_audio)"
  async def add_new_bytes(self, audio_data_stream: Iterator[bytes]):
      # This method receives audio bytes from the intelligence module
      # It puts the stream into a queue to be processed in a separate thread
      await self._process_audio_task_queue.put(audio_data_stream)

  async def _process_audio(self):
      # This runs in a separate thread to process incoming audio bytes
      while True:
          try:
              audio_data_stream = asyncio.run_coroutine_threadsafe(
                  self._process_audio_task_queue.get(), self.loop # Get stream from queue
              ).result()
              for audio_data in audio_data_stream:
                  # Convert raw bytes to AudioFrame and append to buffer
                  self.audio_data_buffer += audio_data
                  while len(self.audio_data_buffer) > self.chunk_size:
                      chunk = self.audio_data_buffer[: self.chunk_size]
                      self.audio_data_buffer = self.audio_data_buffer[self.chunk_size :]
                      audio_frame = self.buildAudioFrames(chunk) # Converts bytes to AudioFrame
                      self.frame_buffer.append(audio_frame) # Add frame to buffer
          except Exception as e:
               print("Error while process audio", e)
```

- The `recv` method is the core of the `CustomAudioTrack`. VideoSDK's Python SDK calls this method whenever it needs the next audio frame from this custom track to send to the meeting.
- `recv` checks the `frame_buffer`. If there are frames (translated audio from OpenAI), it pops one and returns it. If the buffer is empty, it returns a silence frame to maintain the audio stream integrity.

```python
  # agent/audio_stream_track.py (recv method)
  async def recv(self) -> AudioFrame:
      try:
          # ... timestamp logic ...

          if len(self.frame_buffer) > 0:
              # If there's buffered audio from OpenAI TTS, return the next frame
              frame = self.frame_buffer.pop(0)
          else:
              # If buffer is empty, return a silence frame
              frame = AudioFrame(format="s16", layout="mono", samples=self.samples)
              for p in frame.planes:
                  p.update(bytes(p.buffer_size)) # Fill with silence

          # Set presentation timestamp (pts) for the frame
          frame.pts = pts
          frame.time_base = time_base
          frame.sample_rate = self.sample_rate
          return frame
      except Exception as e:
          traceback.print_exc()
          print("error while creating tts->rtc frame", e)
          # Return None or raise MediaStreamError if the stream is done/failed
          raise MediaStreamError

```

## The Real-Time Translation Flow

Let's trace the path of audio through the system when a participant speaks:

1.  **Audio Capture and Transmission:** A human participant speaks. Their client application (React Frontend) captures the audio and sends it via VideoSDK's real-time infrastructure.
2.  **Agent Receives Audio:** The Python AI Agent, connected to the meeting, receives the participant's audio stream through the VideoSDK Python SDK.
3.  **Audio Processing & Forwarding:** The Agent processes the raw audio (resampling, formatting) and sends it continuously over a WebSocket connection to the OpenAI Realtime API.
4.  **OpenAI STT, Translation, and TTS:** OpenAI receives the audio stream, performs Speech-to-Text (STT) to transcribe it, translates the transcription based on the participant languages defined in the instructions, and then performs Text-to-Speech (TTS) to synthesize the translated audio.
5.  **OpenAI Streams Translated Audio Back:** OpenAI streams the synthesized, translated audio back to the Agent over the same WebSocket connection in real-time chunks.
6.  **Agent Receives & Buffers Translation:** The Agent receives these audio chunks and buffers them within its `CustomAudioStreamTrack`.
7.  **Agent Injects Audio into Meeting:** The VideoSDK Python SDK continuously requests audio frames from the Agent's `CustomAudioStreamTrack`. The Agent provides the buffered translated audio frames.
8.  **VideoSDK Broadcasts Translation:** VideoSDK broadcasts the audio received from the Agent's custom track to all other participants in the meeting.
9.  **Participants Hear Translation & UI Updates:** Other participants' clients receive and play the translated audio. The frontend UI includes logic to detect the AI speaking and can automatically mute the local participant's microphone to help prevent echoes.

This streamlined flow demonstrates how audio seamlessly moves from one speaker, through the AI agent and OpenAI, and back into the meeting for others to hear in their language.

## Conclusion

This project effectively demonstrates how to build sophisticated real-time AI agents that participate directly in video conferencing using VideoSDK and the OpenAI Realtime API. By treating the AI as a peer participant with a custom audio input, we can seamlessly integrate external AI processing into the live conversation.

The use of VideoSDK provides the robust real-time audio and video infrastructure, while the OpenAI Realtime API handles the complex integrated speech-to-text, translation, and text-to-speech tasks with low latency. The Python agent orchestrates this process, intelligently managing audio streams and dynamically instructing the AI based on the meeting context (like participant languages).

This architecture is not limited to translation. The same pattern could be applied to build agents for transcription, summarization, real-time sentiment analysis, information retrieval, or any task that involves processing meeting audio and providing real-time output back to participants.

We encourage you to clone the project from GitHub, follow the setup steps detailed above, and experiment with this powerful combination of real-time communication and cutting-edge AI. Unlock new possibilities for interactive and intelligent online meetings!


---

# Quick Start for Conference in Python

VideoSDK empowers you to seamlessly integrate the video calling feature into your Python application within minutes.

In this quickstart, you'll explore the group calling feature of VideoSDK. Follow the step-by-step guide to integrate it within your application.

## Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

- VideoSDK Developer Account (Not having one? Follow **[VideoSDK Dashboard](https://app.videosdk.live/)**)
- Basic understanding of Python
- Python installed on your device.
- **[Python VideoSDK](https://pypi.org/project/videosdk/)**
- Python asyncio (optional)

:::important

You need a VideoSDK account to generate a token.
Visit the VideoSDK **[dashboard](https://app.videosdk.live/api-keys)** to generate a token.

:::

## Getting Started with the Code!

Follow the steps to create the environment necessary to add video calls to your app. You can also find the code sample for [quickstart here](https://github.com/videosdk-live/quickstart/tree/main/python-rtc).

### Create a New Python Project

Create a new Python project using the below command.

```bash
mkdir videosdk-python && cd videosdk-python
```

### Install VideoSDK

Install the VideoSDK using the pip command below.

```bash
pip install videosdk
```

### Project Structure

Your project structure should look like this:

```plaintext
videosdk-python
├── main.py
├── meeting_events.py
├── participant_events.py
├── api.py
```

### Step 1: Create an API Call


Before moving on, create an API request to generate a unique meetingId. You will need an authentication token, which you can create either through the [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples) or directly from the [VideoSDK Dashboard](https://app.videosdk.live/api-keys) for developers.

```python title="api.py"
import requests

# This is the Auth token, you will use it to generate a meeting and connect to it
token = "

</div>

You have completed the implementation of audio-video call using VideoSDK in Python. To explore more features like transform participant video, vision ai go through upcoming detailed guide.

:::tip
You can check out the complete [quick start example here](https://github.com/videosdk-live/quickstart/tree/main/python-rtc).
:::


---

<h1> {props.title} </h1>{" "}

Building applications with real-time voice, video, and interaction are just plain hard. It is complex and it takes a lot of time to build.

Video SDK provides developers with simple-to-use, highly customisable, and widely compatible APIs to embed real-time video, voice, and interaction functionalities into their applications without the need to develop the technology or the underlying infrastructure for real-time engagement themselves.


## Steps


<div class="container guide-steps-block">
  <div class="row ">
    <div class="col col--6">
      
    </div>
   <div class="col col--6" >
      
    </div>
  </div>
    <div class="row ">
    <div class="col col--6">
      
    </div>
  </div>
</div>

## Architecture

This diagram demonstrates end-to-end flow to implement video & audio calling, record calls and go-live on social media.

![Video-sdk-architecture!](/img/video-sdk-archietecture.svg)


---

# Run Audio & Video Call Project - Python

VideoSDK provides an open-source sample project [videosdk-rtc-python-sdk-example](https://github.com/videosdk-live/quickstart/tree/main/python-rtc) on Github. This document introduces how to run the project.

## Prerequisites

- python version 3.11 or later
- Valid VideoSDK [Account](https://app.videosdk.live/)


### Generate Token

To manage secured communication, every participant that connects to a meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key`, which you can obtain from the [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

**For development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for obtaining a token involves generating it from your backend server which will help in **keeping your credentials safe**.
:::


## Run the Sample Project

### Step 1: Clone the sample project


Clone the repository to your local environment.

```bash
git clone https://github.com/videosdk-live/videosdk-rtc-python-sdk-example.git
cd videosdk-rtc-python-sdk-example
cd python-rtc
```


### Step 2: Copy the .env.example file to .env file


Open your favorite code editor and copy `.env.example` to `.env` file.

```bash
cp .env.example .env
```


### Step 3: Modify .env file


Modify the file by pasting the previously generated temporary token here.

```python title=".env"
VIDEOSDK_TOKEN="

</div>


---

<h1> {props.title} </h1>{" "}

### Why we are using JWT based Token ?

Token based authentication allows users to verify their identity by providing generated API key and secret.

We use JWT token for the authentication purpose because Token-based authentication is **widely used** in modern web applications and APIs because it offers several benefits over traditional authentication. For example, it can **reduce the risk of the credentials being misused**, and it allows for **more fine-grained control** over access to resources. Additionally, tokens can be easily revoked or expired, making it easier to manage access rights.

### How to generate Token ?

To manage secured communication, every participant that connects to the meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key` which you can get from [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

#### 1. Generating token from Dashboard

If you are looking to do **testing or for development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for getting token includes generating it from your backend server which will help in **keeping your credentials safe**.
:::

#### 2. Generating token in your backend

- Your server will generate access token using your API key and secret.
  - While generating a token, you can provide **expiration time, permissions and roles** which are discussed later in this section.
- Your client obtains token from your backend server.
- For token validation, client will pass this token to VideoSDK server.
- VideoSDK server will only allow entry in the meeting if the token is valid.

![img2.png](../../static/img/authentication-and-token.png)




Follow our official example repositories to setup token API [videosdk-rtc-api-server-examples](https://github.com/videosdk-live/videosdk-rtc-api-server-examples)

### Payload while generating token

```js
{
 apikey: API_KEY, //MANDATORY
 permissions: [`allow_join`], //`ask_join` || `allow_mod` //MANDATORY
 version: 2, //OPTIONAL
 roomId: ROOM_ID, //OPTIONAL,
 participantId: PARTICIPANT_ID, //OPTIONAL
 roles: ['crawler', 'rtc'], //OPTIONAL
}
```

- **`apikey`(Mandatory)**: This must be the API Key generated from the VideoSDK Dashboard. You can get it from [here](https://app.videosdk.live/api-keys).

- **`permissions`(Mandatory)**: By providing the permissions, you can control what a participant can do in the meeting and whether he can join the meeting directly.

  Available permissions are:

  - **`allow_join`**: The participant is **allowed to join** the meeting directly.
  - **`ask_join`**: The participant is required to **ask for permission to join** the meeting. The participant having the permission `allow_join` can accept or reject a participant whenever someone wants to join.
  - **`allow_mod`**: The participant is **allowed to toggle** webcam & mic of other participants.

- **`version`(optional)**: For accessing the [v2 API](/api-reference/realtime-communication/intro), you need to provide `2` as the version value.

  - For passing `roomId`, `participantId` or `roles` parameters in payload, it is essential to set the version value to `2`.

- **`roomId`(optional)**: To provide customised access control, you can make the token applicable to a particular room by including the `roomId` in the payload.

- **`participantId`(optional)**: You can include the `participantId` in the payload to limit the token's access to a particular participant.

- **`roles`(optional)**:

  - **`crawler`**: This role is only for accessing [v2 API](/api-reference/realtime-communication/intro), you can not use this token for running the `Meeting`/`Room`.
  - **`rtc`**: This role is only allowed for running the `Meeting` / `Room`, with this role you can not use [server-side APIs](/api-reference/realtime-communication/intro).

Then, you have to sign this payload with your **`SECRET KEY`** and `jwt` options using the **`HS256 algorithm`**.

### Expiration time

You can set any expiration time to the token. But in the **production environment**, it is recommended to generate a token with **short expiration time** because by any chance if someone gets hold of the token, it won't be valid for a longer period of time.

### What happens if token is expired?

If your token is expired, the user won't be able to join the meeting and all the API calls will give error with message `Token is invalid or expired`.

:::note
Token is validated only once while joining the meeting, so if a person joins the meeting and the token gets expired after that, there won't be any issue in the current meeting.
:::

## How to check validity of token?

1. After generating the token, visit [jwt.io](https://jwt.io) and paste your token in the given area.
2. You will be able to see the payload you passed while generating the token and also be able to see the expiration time and token creation time.

![img1.png](../../static/img/validate-token.png)

## API Settings & Controls

The VideoSDK Dashboard provides a powerful [API Settings](https://app.videosdk.live/api-keys) section where you can configure various services and controls for your meetings. These settings allow you to customize the behavior of different features directly from the dashboard without requiring code changes.

## Audio/Video Configurations

:::note
Runtime configuration from the dashboard has higher precedence than static SDK configurations.
If a value is modified in the dashboard, it will override any previously defined SDK settings for that session.

Example:
Code: Video = HD → Dashboard: Video = Full HD → Applied: Full HD
:::

### Maximum Send Bitrate Per Participant

Control the maximum total upload bandwidth for all media streams from a single participant.

![Maximum Send Bitrate](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.00.11%E2%80%AFPM.png)

**Available Options:**
- **Auto**: Removes the upload bitrate limit (recommended for best quality)
- **SD (800kbps)**: Standard definition bitrate
- **HD (1500kbps)**: High definition bitrate
- **Full HD (3000kbps)**: Full high definition bitrate

:::tip
Setting this to **Auto** provides the best video quality as it removes upload bitrate constraints, allowing adaptive streaming based on network conditions.
:::

## Recording & Streaming Configuration

:::note
Recording and HLS follow a precedence-based configuration model:

API/SDK configuration → Highest priority
Dashboard configuration → Used only when no API values are defined

Any parameters explicitly set via the API will not be overridden by dashboard changes.
:::

### Recording Configuration

Configure recording settings for your meetings including layout, quality, and auto-start options.

![Recording Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.01.00%E2%80%AFPM.png)

**Recording Controls:**
- **Enabled**: Toggle to enable/disable recording functionality
- **Enabled Modes**: Choose between Video & Audio or Audio Only recording
- **Start Recording Automatically**: Auto-start recording when meeting begins
- **Layout Style**: Select Grid layout for recording composition
- **Maximum Tiles In Grid**: Set the number of participants visible in grid (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme for recordings
- **Video Orientation**: Choose between Landscape or Portrait mode
- **Recording Quality**: Select quality level (e.g., HD Medium)
- **Recording Mode**: Choose between Video & Audio or Audio Only

### HLS Streaming Configuration

Configure HTTP Live Streaming (HLS) settings for broadcasting your meetings.

![HLS Streaming Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.02.18%E2%80%AFPM.png)

**HLS Streaming Controls:**
- **Enabled**: Toggle to enable/disable HLS streaming
- **Enabled Modes**: Choose between Video & Audio or Audio Only streaming
- **Auto Start HLS**: Automatically start HLS when meeting begins
- **Record HLS Stream**: Enable recording of the HLS stream
- **Layout Style**: Select Grid layout for stream composition
- **Maximum Tiles In Grid**: Set the number of participants visible (1-25)
- **Who to Prioritize**: Choose Active Speaker or Pinned Participant
- **Theme**: Select System Default, Light, or Dark theme
- **HLS Orientation**: Choose between Landscape or Portrait mode
- **HLS Quality**: Select streaming quality (e.g., HD Medium)
- **HLS Streaming Mode**: Choose between Video & Audio or Audio Only

### Additional Service Controls

Enable or disable additional services for your API key.

![Service Controls](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.08%E2%80%AFPM.png)

**Available Services:**
- **RTMP Output**: Enable RTMP streaming to external platforms
- **SIP Integration**: Enable SIP (Session Initiation Protocol) integration for telephony
- **Realtime Translation**: Enable real-time language translation in meetings

### Transcription & Summary

Configure transcription and domain whitelisting for your API key.

![Transcription Settings](https://assets.videosdk.live/images/Screenshot%202026-01-09%20at%2012.03.50%E2%80%AFPM.png)

**Transcription Controls:**
- **Enabled**: Toggle to enable/disable transcription and summary features
- **Whitelist Domain**: Add domain restrictions for API key usage
  - Enter domain names in the format `https://domain.name`
  - Click "Add Domain" to whitelist specific domains
  - Only whitelisted domains can use this API key
  - When no domains are whitelisted, the API key can be used from any domain


---

### Generate Token

To manage secured communication, every participant that connects to a meeting needs an access token. You can easily generate this token by using your `apiKey` and `secret-key`, which you can obtain from the [VideoSDK Dashboard](https://app.videosdk.live/api-keys).

**For development purpose**, you can generate a temporary token from [VideoSDK Dashboard's API section](https://app.videosdk.live/api-keys).




<br />

:::tip
The best practice for obtaining a token involves generating it from your backend server which will help in **keeping your credentials safe**.
:::



---

# Overview of SIP with VideoSDK - Python





SIP (Session Initiation Protocol) is extensively employed for setting up and controlling IP-based calls. It facilitates the initiation and termination of user sessions over IP networks, enabling SIP-based systems to connect and exchange voice communications over the internet.

With VideoSDK's SIP Connect feature, you can enable your users to join VideoSDK meetings via VOIP using third-party service providers. This allows for establishing a bridge between participants using our client SDKs and those joining via SIP, enhancing the accessibility and connectivity of your video meetings.

![SIP Architecture](https://cdn.videosdk.live/website-resources/docs-resources/sip-architechture.png)

### Getting SIP Credentials

To use SIP Connect, you will first need to generate the credentials for the SIP. Go to the [VideoSDK dashboard](https://app.videosdk.live) and under the [API Keys](https://app.videosdk.live/api-keys) sections, first enable the SIP for the desired API key after which you will be presented with the SIP `username` and `password` you can use to establish connection with our SIP servers.

![SIP Credentials](https://cdn.videosdk.live/website-resources/docs-resources/sip-get-credentials.gif)

### How to use SIP to join a particular meeting?

Once you have the credentials, you can use any of the softphones like Linphone, Zoiper etc. or use a third party service provider like twilio to connect with a VideoSDK meeting by initiating a SIP call to `sip:<meeting-id>@sip.videosdk.live`

For example if you want to connect to `abcd-abcd-abcd` meeting then the SIP address will look like `sip:abcd-abcd-abcd@sip.videosdk.live`

### Example of Twilio PSTN

To utilize third-party PSTN (Public Switched Telephone Network) providers like Twilio for making calls via SIP (Session Initiation Protocol), follow these steps:

1. Log in to your Twilio account and navigate to the Phone Numbers section.
2. Purchase a phone number and access its configuration settings.
3. Set up a Webhook handler that will initiate a call to the VideoSDK SIP endpoint whenever an incoming call is received on the selected phone number.

![SIP Configuration for Twilio](https://cdn.videosdk.live/website-resources/docs-resources/sip-twilio-config.png)

##### Example for creating Webhook using Express

```js
const express = require("express");
const VoiceResponse = require("twilio").twiml.VoiceResponse;
const urlencoded = require("body-parser").urlencoded;

const app = express();

// Parse incoming POST params with Express middleware
app.use(urlencoded({ extended: false }));

// Webhook route which will be called by twilio when a call is received
app.post("/incoming-call-handler", (request, response) => {
  console.log({ request });
  // Use the Twilio Node.js SDK to build an XML response
  const twiml = new VoiceResponse();

  const dial = twiml.dial();
  dial.sip(
    {
      username: "<User name generated for dashboard>",
      password: "<Password generated from dashboard>",
    },
    "sip:<meetingId>@sip.videosdk.live"
  );

  // Render the response as XML in reply to the webhook request
  response.type("text/xml");
  response.send(twiml.toString());
});

//Start the express app on port 8000
app.listen(8000, () => {
  console.log(`Server listening on port ${8000}.`);
});
```



---

# Build a SIP Integration: VideoSDK & Twilio for Inbound Outbound Calls! Step-by-Step


Imagine joining an online meeting using just your phone—no apps, no browsers, no internet. This powerful option allows participants to connect via traditional telephony, by creating a bridge between phone systems and modern video conferencing platforms. In this post, we’ll explore how to build a SIP integration using VideoSDK and Twilio for both inbound and outbound VoIP calls.



We’ll break down the flow of calls, set up the project, and show you how to bring this functionality to life using Next.js.

## What Is a SIP Integration?

SIP, or Session Initiation Protocol, enables voice and video communications over internet-based networks. With SIP integrations, traditional phone systems can connect to online platforms .

By integrating SIP with VideoSDK’s SIP address and Twilio, you can handle both inbound and outbound calls while linking them to video meetings. This integration is particularly helpful for situations where participants lack internet access, allowing them to simply dial in to join a meeting or receive phone calls initiated by meeting participants.

## Understanding Inbound and Outbound Call Flows

### Inbound Calls

![Inboud Call Flow](https://assets.videosdk.live/images/inbound.png)

Inbound calls are initiated by a user or customer dialing a phone number, such as a Twilio-provisioned number. Here’s how the process works:

1. **User Dialing**: A participant dials the Twilio number tied to the SIP integration.
2. **Call Routing**: Twilio receives the call and notifies your server with call details.
3. **Server Processing**: Your server processes the request and sends an invite SIP request to the VideoSDK SIP address.
4. **Connection Established**: Once validated, the caller is connected to the specific video meeting through VideoSDK.

For example, if a customer wants to join a video conference using their phone, they can call a designated number. Following this process, the integration connects them to the meeting.

### Outbound Calls

![Outbound Call Flow](https://assets.videosdk.live/images/outbound.png)

Outbound calls begin with a participant or agent in an online meeting initiating a call to a customer’s phone. The process involves the following steps:

1. **Call Request Initiated**: A participant requests your server to call a specific phone number.
2. **Server Action**: The server notifies Twilio to establish the call.
3. **User Accepts Call**: When the user accepts, the connection is forwarded to the video meeting through VideoSDK.

This two-way communication ensures smooth interaction between online participants and phone users.

## Step-by-Step Guide to Setting Up the Project

### Prepare the Project Files

1. Create a workspace for the SIP integration project (or open your existing project if you already have one).

```bash
mkdir videosdk-sip-integration && cd videosdk-sip-integration
```

1. Navigate to project directory

```javascript
cd videosdk-sip-integration
```

1. Install dependencies that are required for you application to work

```javascript
npm install
```

### Configure the Environment

1. **Set Up the `.env` File**: Copy the `.env.example` file in the repository and rename it to `.env`.
2. **Add VideoSDK Details**: Obtain the SIP username, password, and authentication token from the [VideoSDK dashboard](https://app.videosdk.live/).
   - Generate an authentication token under “API Keys.”
   - Get your SIP username and password from the “SIP Config” section.
   - Add these details to the `.env` file.
3. **Configure Twilio**: Sign in to your [Twilio console](https://console.twilio.com/).
   - Copy your Twilio phone number, Account SID, and Auth Token.
   - Paste these values into the `.env` file.

```javascript
TWILIO_ACCOUNT_SID=your-twilio-account-sid
TWILIO_AUTH_TOKEN=your-twilio-auth-token
VIDEOSDK_SIP_USERNAME=your-videosdk-sip-username
VIDEOSDK_SIP_PASSWORD=your-videosdk-sip-password
NEXT_PUBLIC_TWILIO_PHONE_NUMBER=your-twilio-phone-number
NEXT_APP_URL=http://localhost:3000 # Replace with your production URL
```

Your `.env` file should now contain all necessary credentials.

### Running the Application

Once the configurations are complete, start the project using the following command:

```bash
npm run dev
```

![demo home page](https://assets.videosdk.live/images/demo.png)

The application will run locally on port 3000.



## Setting Up Call Routing

### Inbound Call Setup

**Define the API URL**: In Twilio’s Active Numbers section, specify your API endpoint (e.g., `/api/webhook/inbound`). Twilio will send incoming call details to this URL.

If hosting locally, tools like `ngrok` or `pinggy` can expose your server to the internet for testing purposes. Replace the localhost URL with the public domain generated by these tools in the Twilio configuration.

![Twilio Dashboard](https://assets.videosdk.live/images/twilio-dashboard.png)

**Handle Calls with VideoSDK**: Once Twilio routes the call, your code forwards the meeting ID to VideoSDK’s SIP address. This connects the caller to the online meeting.

```javascript

// Environment variables
const accountSid = process.env.TWILIO_ACCOUNT_SID || "";
const authToken = process.env.TWILIO_AUTH_TOKEN || "";
const videosdkSipUsername = process.env.VIDEOSDK_SIP_USERNAME || "";
const videosdkSipPassword = process.env.VIDEOSDK_SIP_PASSWORD || "";

const client = twilio(accountSid, authToken);

export async function POST(request: Request): Promise<Response> {
  try {
    const url = new URL(request.url);
    const meetingId = url.searchParams.get("meetingId");

    const twiml = new twilio.twiml.VoiceResponse();
    twiml.say("Welcome to the Video sdk conference. Connecting you now.");
    twiml.dial().sip(
      {
        username: videosdkSipUsername,
        password: videosdkSipPassword,
      },
      `sip:${meetingId}@sip.videosdk.live`
    );

    return new Response(twiml.toString(), {
      headers: {
        "Content-Type": "text/xml",
      },
    });
  } catch (error) {
    console.error("Error processing Twilio webhook:", error);

    // Return TwiML error response
    const twiml = new twilio.twiml.VoiceResponse();
    twiml.say("Sorry, there was an error connecting your call.");

    return new Response(twiml.toString(), {
      headers: {
        "Content-Type": "text/xml",
      },
    });
  }
}
```

### Outbound Call Setup

For outbound calls, the meeting participant in the web app interacts with an API endpoint that sends a request to Twilio. Twilio establishes the call with the provided number, connecting the phone user back to the meeting through VideoSDK.

```javascript

// Environment variables
const accountSid = process.env.TWILIO_ACCOUNT_SID || "";
const authToken = process.env.TWILIO_AUTH_TOKEN || "";
const twilioPhoneNumber = process.env.NEXT_PUBLIC_TWILIO_PHONE_NUMBER || "";

const client = twilio(accountSid, authToken);

export const dynamic = "force-dynamic";

export async function POST(request: Request): Promise<Response> {
  try {
    const { phoneNumber, meetingId } = await request.json();

    if (!phoneNumber) {
      throw new Error("phone number is required!");
    }

    // Make the outbound call
    const call = await client.calls.create({
      to: phoneNumber,
      from: twilioPhoneNumber,
      url: `${process.env.NEXT_APP_URL}/api/webhook/inbound?meetingId=${meetingId}`,
      method: "POST",
    });

    return new Response(JSON.stringify({ success: true, callSid: call.sid }), {
      headers: {
        "Content-Type": "application/json",
      },
    });
  } catch (error) {
    console.error("Error making outbound call:", error);

    return new Response(
      JSON.stringify({
        success: false,
        error: "Failed to initiate call",
      }),
      {
        status: 500,
        headers: {
          "Content-Type": "application/json",
        },
      }
    );
  }
}
```

**Create an Outbound API**: Write an API function to trigger calls using Twilio’s client instancee.g., `/api/webhook/outbound`)

**Trigger Outbound Calls**: Use this API in your application to handle requests for dialing specific numbers.

When the call is accepted, the system routes it to the VideoSDK SIP address, establishing a connection to the meeting.

## Testing the Integration

To test the setup:

1. Make a call to the Twilio number for inbound calls.
   - Ensure the meeting ID and SIP configurations are correctly passed.
2. Initiate an outbound call from a meeting participant to a phone number.
   - Validate that the phone user is successfully connected to the meeting.

Both inbound and outbound calls should work smoothly, demonstrating the bridged connection between telephony and video conferencing.

## Conclusion

Integrating SIP functionality into your project using VideoSDK and Twilio unlocks new possibilities for communication. By enabling inbound and outbound VoIP calls, you can connect traditional phone systems with modern video conferencing platforms.

This guide covered the basics of setting up the integration, routing calls, and ensuring smooth connectivity. If you encounter any issues or need further help, join the VideoSDK Discord community.

Simplify your users’ communication experience—embrace the power of SIP integration.



---

# Face Detection - Python

This guide will help you understand how to implement real-time face detection on video frames using the VideoSDK. We will leverage the Mediapipe library to detect faces and draw bounding boxes around them.

## Prerequisites

1. Install necessary libraries:
   ```bash
   pip install videosdk python-dotenv opencv-python av mediapipe
   ```
2. Create a `.env` file and add your VideoSDK token, meeting ID, and name:
   ```env
   VIDEOSDK_TOKEN=your_token
   MEETING_ID=your_meeting_id
   NAME=your_name
   ```

## Code Breakdown

### Imports and Constants

We start by importing necessary libraries and loading environment variables in `face_detection.py` file:

```python
import asyncio
import os
from videosdk import MeetingConfig, VideoSDK, Participant, Stream, MeetingEventHandler, ParticipantEventHandler, CustomVideoTrack, Meeting
import mediapipe as mp
import cv2
from av import VideoFrame

from dotenv import load_dotenv
load_dotenv()
VIDEOSDK_TOKEN = os.getenv("VIDEOSDK_TOKEN")
MEETING_ID = os.getenv("MEETING_ID")
NAME = os.getenv("NAME")
loop = asyncio.get_event_loop()

# Initialize Mediapipe face detection
mp_face_detection = mp.solutions.face_detection
mp_drawing = mp.solutions.drawing_utils

meeting: Meeting = None
```

### Face Detection Processor

This processor performs face detection on each video frame, draws the outline and return the frame:

```python
class FaceDetectionProcessor():
    def __init__(self) -> None:
        print("Processor initialized")

    def process(self, frame: VideoFrame) -> VideoFrame:
        # Convert frame to image
        img = frame.to_ndarray(format="bgr24")

        # Convert the image to RGB
        img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)

        # Perform face detection
        with mp_face_detection.FaceDetection(
            min_detection_confidence=0.2
        ) as face_detection:
            results = face_detection.process(img_rgb)

            # Draw face detections on the image
            if results.detections:
                for detection in results.detections:
                    mp_drawing.draw_detection(img, detection)

        # rebuild a VideoFrame, preserving timing information
        new_frame = VideoFrame.from_ndarray(img, format="bgr24")
        new_frame.pts = frame.pts
        new_frame.time_base = frame.time_base
        return new_frame
```

### CustomVideoTrack

Define a custom video track that will run the above processor when new frame received.

```python
class ProcessedVideoTrack(CustomVideoTrack):
    """
    A video stream track that transforms frames from an another track.
    """

    kind = "video"

    def __init__(self, track):
        super().__init__()  # don't forget this!
        self.track = track
        # highlight-next-line
        self.processor = FaceDetectionProcessor()

    async def recv(self):
        frame = await self.track.recv()
        # highlight-next-line
        new_frame = self.processor.process(frame)
        return new_frame
```

### Process on stream available

This function applies the `ProcessedVideoTrack` to a available video track:

```python
def process_video(track: CustomVideoTrack):
    global meeting
    meeting.add_custom_video_track(
        track=ProcessedVideoTrack(track=track)
    )
```

### Event Handlers

Define event handlers to handle meeting and participant events:

```python
class MyMeetingEventHandler(MeetingEventHandler):
    def __init__(self):
        super().__init__()

    def on_meeting_left(self, data):
        print("on_meeting_left")

    # highlight-start
    def on_participant_joined(self, participant: Participant):
        participant.add_event_listener(
            MyParticipantEventHandler(participant_id=participant.id)
        )
    # highlight-end

    def on_participant_left(self, participant: Participant):
        print("on_participant_left")

class MyParticipantEventHandler(ParticipantEventHandler):
    def __init__(self, participant_id: str):
        super().__init__()
        self.participant_id = participant_id

    # highlight-start
    def on_stream_enabled(self, stream: Stream):
        print("on_stream_enabled: " + stream.kind)
        if stream.kind == "video":
            process_video(track=stream.track)
    # highlight-end

    def on_stream_disabled(self, stream: Stream):
        print("on_stream_disabled")
```

### Main Function

Initialize the meeting and start the event loop:

```python
def main():
    global meeting
    # Example usage:
    meeting_config = MeetingConfig(
        meeting_id=MEETING_ID,
        name=NAME,
        mic_enabled=False,
        webcam_enabled=False,
        token=VIDEOSDK_TOKEN,
    )
    meeting = VideoSDK.init_meeting(**meeting_config)

    print("adding event listener...")
    meeting.add_event_listener(MyMeetingEventHandler())

    print("joining into meeting...")
    meeting.join()

if __name__ == "__main__":
    main()
    loop.run_forever()
```


## Running the Code

To run the code, simply execute the script:

```bash
python face_detection.py
```

This script will join the meeting specified by `MEETING_ID` with the provided `VIDEOSDK_TOKEN` and `NAME`, and perform real-time face detection on video frames using Mediapipe.

Feel free to modify the face detection logic inside the `FaceDetectionProcessor` class to adjust the detection parameters or apply additional processing.

## Output

<img src="https://cdn.videosdk.live/website-resources/docs-resources/realtime_face_detection.png" width="100%" />

:::tip

Stuck anywhere? Check out this [example code](https://github.com/videosdk-live/videosdk-rtc-python-sdk-example/tree/main/face-detection) on GitHub.

:::

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [CustomTrack](/python/api/sdk-reference/classes/stream/track)
- [Stream](/python/api/sdk-reference/classes/stream/introduction)


---

# Face Landmarks - Python

This guide will help you implement real-time face landmark detection on video frames using the VideoSDK. We will leverage the Mediapipe library to detect facial landmarks and draw them on the video frames.

## Prerequisites

1. Install necessary libraries:
   ```bash
   pip install videosdk python-dotenv opencv-python av mediapipe
   ```
2. Create a `.env` file and add your VideoSDK token, meeting ID, and name:
   ```env
   VIDEOSDK_TOKEN=your_token
   MEETING_ID=your_meeting_id
   NAME=your_name
   ```

## Code Breakdown

### Imports and Constants

We start by importing necessary libraries and loading environment variables in `face_landmarks.py` file:

```python
import asyncio
import os
from videosdk import MeetingConfig, VideoSDK, Participant, Stream, MeetingEventHandler, ParticipantEventHandler, CustomVideoTrack, Meeting
import mediapipe as mp
import cv2
from av import VideoFrame

from dotenv import load_dotenv
load_dotenv()
VIDEOSDK_TOKEN = os.getenv("VIDEOSDK_TOKEN")
MEETING_ID = os.getenv("MEETING_ID")
NAME = os.getenv("NAME")
loop = asyncio.get_event_loop()

# Initialize Mediapipe face landmarks
mp_face_mesh = mp.solutions.face_mesh
mp_drawing = mp.solutions.drawing_utils

meeting: Meeting = None
```

### Face Landmarks Processor

This processor performs face landmark detection on each video frame and draws the landmarks and return the frame:

```python
class FaceLandMarkProcessor():
  def __init__(self) -> None:
    print("Processor initialized")
    self.face_mesh = mp_face_mesh.FaceMesh(
        static_image_mode=False,
        max_num_faces=1,
        min_detection_confidence=0.5,
        min_tracking_confidence=0.5,
    )

  def process(self, frame: VideoFrame) -> VideoFrame:
    # Convert frame to image
    img = frame.to_ndarray(format="bgr24")

    # Convert the image to RGB
    img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)

    # Perform face landmark detection
    results = self.face_mesh.process(img_rgb)

    # Draw face landmarks on the image
    if results.multi_face_landmarks:
        for face_landmarks in results.multi_face_landmarks:
            mp_drawing.draw_landmarks(
                image=img,
                landmark_list=face_landmarks,
                connections=mp_face_mesh.FACEMESH_TESSELATION,
                landmark_drawing_spec=None,
                connection_drawing_spec=mp_drawing.DrawingSpec(
                    color=(0, 255, 0), thickness=1, circle_radius=1
                ),
            )

    # rebuild a VideoFrame, preserving timing information
    new_frame = VideoFrame.from_ndarray(img, format="bgr24")
    new_frame.pts = frame.pts
    new_frame.time_base = frame.time_base
    return new_frame
```

### CustomVideoTrack

Define a custom video track that will run the above processor when new frame received.

```python
class ProcessedVideoTrack(CustomVideoTrack):
    """
    A video stream track that transforms frames from an another track.
    """

    kind = "video"

    def __init__(self, track):
        super().__init__()  # don't forget this!
        self.track = track
        # highlight-next-line
        self.processor = FaceLandMarkProcessor()

    async def recv(self):
        frame = await self.track.recv()
        # highlight-next-line
        new_frame = self.processor.process(frame)
        return new_frame
```

### Process on stream available

This function applies the `ProcessedVideoTrack` to a available video track:

```python
def process_video(track: CustomVideoTrack):
    global meeting
    meeting.add_custom_video_track(
        track=ProcessedVideoTrack(track=track)
    )
```

### Event Handlers

Define event handlers to handle meeting and participant events:

```python
class MyMeetingEventHandler(MeetingEventHandler):
    def __init__(self):
        super().__init__()

    def on_meeting_left(self, data):
        print("on_meeting_left")

    # highlight-start
    def on_participant_joined(self, participant: Participant):
        participant.add_event_listener(
            MyParticipantEventHandler(participant_id=participant.id)
        )
    # highlight-end

    def on_participant_left(self, participant: Participant):
        print("on_participant_left")

class MyParticipantEventHandler(ParticipantEventHandler):
    def __init__(self, participant_id: str):
        super().__init__()
        self.participant_id = participant_id

    # highlight-start
    def on_stream_enabled(self, stream: Stream):
        print("on_stream_enabled: " + stream.kind)
        if stream.kind == "video":
            process_video(track=stream.track)
    # highlight-end

    def on_stream_disabled(self, stream: Stream):
        print("on_stream_disabled")
```

### Main Function

Initialize the meeting and start the event loop:

```python
def main():
    global meeting
    # Example usage:
    meeting_config = MeetingConfig(
        meeting_id=MEETING_ID,
        name=NAME,
        mic_enabled=False,
        webcam_enabled=False,
        token=VIDEOSDK_TOKEN,
    )
    meeting = VideoSDK.init_meeting(**meeting_config)

    print("adding event listener...")
    meeting.add_event_listener(MyMeetingEventHandler())

    print("joining into meeting...")
    meeting.join()

if __name__ == "__main__":
    main()
    loop.run_forever()
```


## Running the Code

To run the code, simply execute the script:

```bash
python face_landmarks.py
```

This script will join the meeting specified by `MEETING_ID` with the provided `VIDEOSDK_TOKEN` and `NAME`, and perform real-time face landmark detection on video frames using Mediapipe.

Feel free to modify the face landmark detection logic inside the `FaceLandMarkProcessor` class to adjust the detection parameters or apply additional processing.

## Output


<div style={{textAlign: 'center'}}>



</div>

:::tip
Stuck anywhere? Check out this [example code](https://github.com/videosdk-live/videosdk-rtc-python-sdk-example/tree/main/face-detection-and-landmarks) on GitHub.
:::

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [CustomTrack](/python/api/sdk-reference/classes/stream/track)
- [Stream](/python/api/sdk-reference/classes/stream/introduction)


---

# Transform Video - Python

This guide will help you understand how to transform video frames in real-time using the VideoSDK. In this example, we'll transform video frames into a cartoon-like appearance.

## Prerequisites

1. Install necessary libraries:
   ```bash
   pip install videosdk python-dotenv opencv-python av
   ```
2. Create a `.env` file and add your VideoSDK token, meeting ID, and name:
   ```env
   VIDEOSDK_TOKEN=your_token
   MEETING_ID=your_meeting_id
   NAME=your_name
   ```

## Code Breakdown

### Imports and Constants

We start by importing necessary libraries and loading environment variables in `transform_video.py` file:

```python
import asyncio
import os
from videosdk import MeetingConfig, VideoSDK, Participant, Stream, MeetingEventHandler, ParticipantEventHandler, CustomVideoTrack, Meeting
import mediapipe as mp
import cv2
from av import VideoFrame

from dotenv import load_dotenv
load_dotenv()
VIDEOSDK_TOKEN = os.getenv("VIDEOSDK_TOKEN")
MEETING_ID = os.getenv("MEETING_ID")
NAME = os.getenv("NAME")
loop = asyncio.get_event_loop()

meeting: Meeting = None
```

### Transform Video Processor

This processor performs frame detection on each video frame and draws the cartoon-like anime and return the frame:

```python
class TransformVideoProcessor():
    def __init__(self) -> None:
        print("Processor initialized")

    def process(self, frame: VideoFrame) -> VideoFrame:
        img = frame.to_ndarray(format="bgr24")

        # prepare color
        img_color = cv2.pyrDown(cv2.pyrDown(img))
        for _ in range(6):
            img_color = cv2.bilateralFilter(img_color, 9, 9, 7)
        img_color = cv2.pyrUp(cv2.pyrUp(img_color))

        # prepare edges
        img_edges = cv2.cvtColor(img, cv2.COLOR_RGB2GRAY)
        img_edges = cv2.adaptiveThreshold(
            cv2.medianBlur(img_edges, 7),
            255,
            cv2.ADAPTIVE_THRESH_MEAN_C,
            cv2.THRESH_BINARY,
            9,
            2,
        )
        img_edges = cv2.cvtColor(img_edges, cv2.COLOR_GRAY2RGB)

        # combine color and edges
        img = cv2.bitwise_and(img_color, img_edges)

        # rebuild a VideoFrame, preserving timing information
        new_frame = VideoFrame.from_ndarray(img, format="bgr24")
        new_frame.pts = frame.pts
        new_frame.time_base = frame.time_base

        return new_frame
```

### CustomVideoTrack

Define a custom video track that will run the above processor when new frame received.

```python
class ProcessedVideoTrack(CustomVideoTrack):
    """
    A video stream track that transforms frames from an another track.
    """

    kind = "video"

    def __init__(self, track):
        super().__init__()  # don't forget this!
        self.track = track
        # highlight-next-line
        self.processor = TransformVideoProcessor()

    async def recv(self):
        frame = await self.track.recv()
        # highlight-next-line
        new_frame = self.processor.process(frame)
        return new_frame
```

### Process on stream available

This function applies the `ProcessedVideoTrack` to a available video track:

```python
def process_video(track: CustomVideoTrack):
    global meeting
    meeting.add_custom_video_track(
        track=ProcessedVideoTrack(track=track)
    )
```

### Event Handlers

Define event handlers to handle meeting and participant events:

```python
class MyMeetingEventHandler(MeetingEventHandler):
    def __init__(self):
        super().__init__()

    def on_meeting_left(self, data):
        print("on_meeting_left")

    # highlight-start
    def on_participant_joined(self, participant: Participant):
        participant.add_event_listener(
            MyParticipantEventHandler(participant_id=participant.id)
        )
    # highlight-end

    def on_participant_left(self, participant: Participant):
        print("on_participant_left")

class MyParticipantEventHandler(ParticipantEventHandler):
    def __init__(self, participant_id: str):
        super().__init__()
        self.participant_id = participant_id

    # highlight-start
    def on_stream_enabled(self, stream: Stream):
        print("on_stream_enabled: " + stream.kind)
        if stream.kind == "video":
            process_video(track=stream.track)
    # highlight-end

    def on_stream_disabled(self, stream: Stream):
        print("on_stream_disabled")
```

### Main Function

Initialize the meeting and start the event loop:

```python
def main():
    global meeting
    # Example usage:
    meeting_config = MeetingConfig(
        meeting_id=MEETING_ID,
        name=NAME,
        mic_enabled=False,
        webcam_enabled=False,
        token=VIDEOSDK_TOKEN,
    )
    meeting = VideoSDK.init_meeting(**meeting_config)

    print("adding event listener...")
    meeting.add_event_listener(MyMeetingEventHandler())

    print("joining into meeting...")
    meeting.join()

if __name__ == "__main__":
    main()
    loop.run_forever()
```


## Running the Code

To run the code, simply execute the script:

```bash
python transform_video.py
```

This script will join the meeting specified by `MEETING_ID` with the provided `VIDEOSDK_TOKEN` and `NAME`, and transform video frames in real-time using the cartoon filter.

Feel free to modify the transformation logic inside the `process` method of the `VideoTransformTrack` class to apply different kinds of video transformations.

## Output

<img src="https://cdn.videosdk.live/website-resources/docs-resources/python_transform_video.png" width="100%" />

:::tip

Check out this [example code](https://github.com/videosdk-live/videosdk-rtc-python-sdk-example/tree/main/transform-video) on GitHub, to Explore More Transformation like `cartoon`, `edges`, `blur`, `face-blur`, `rotate`

:::

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [CustomTrack](/python/api/sdk-reference/classes/stream/track)
- [Stream](/python/api/sdk-reference/classes/stream/introduction)


---

# Vision AI - Python

This guide will help you understand how to capture video frames in real-time using the VideoSDK, analyze them with OpenAI's Vision API, and publish the results back to the meeting. In this example, we'll capture an image from the video stream, send it to the OpenAI API for description, and publish the description as a message in the meeting.

## Prerequisites

1. Install necessary libraries:
   ```bash
   pip install videosdk python-dotenv av openai
   ```
2. Create a `.env` file and add your VideoSDK token, meeting ID, and name:
   ```env
   VIDEOSDK_TOKEN=your_token
   MEETING_ID=your_meeting_id
   NAME=your_name
   OPENAI_API_KEY=your_openai_api_key
   ```

## Code Breakdown

### Imports and Constants

We start by importing necessary libraries and loading environment variables:

```python
import base64
import asyncio
import os
from videosdk import MeetingConfig, VideoSDK, Stream, Participant, Meeting, MeetingEventHandler, ParticipantEventHandler, PubSubPublishConfig
from openai import OpenAI
from PIL import Image
from io import BytesIO

from dotenv import load_dotenv
load_dotenv()
VIDEOSDK_TOKEN = os.getenv("VIDEOSDK_TOKEN")
MEETING_ID = os.getenv("MEETING_ID")
NAME = os.getenv("NAME")
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
openai_client = OpenAI(api_key=OPENAI_API_KEY)

loop = asyncio.get_event_loop()
meeting: Meeting = None
participant: Participant = None
task: asyncio.Task = None
```

### Capture Image

This function captures an image from the participant video stream asynchronously using `async_capture_image`, sends it to the `vision_ai` function for analysis, and publishes the result back to the meeting:

```python
async def capture_video() -> str:
    global participant
    filepath = "capture_video.png"

    # asynchronously capture image from video
    # highlight-next-line
    img: Image = await participant.async_capture_image(filepath)

    # Convert the image to a base64-encoded string
    buffer = BytesIO()
    img.save(buffer, format="JPEG")

    image_frame = base64.b64encode(buffer.getvalue()).decode("utf-8")

    # highlight-next-line
    await vision_ai(image_frame)
```

### Analyse Image

This function analyse the given image and publish the result into meeting using `gpt-4o` and `videosdk pubsub`.
output will be stored in `videosdk.txt` file.

```python

async def vision_ai(image_frame: str):
    try:
        # Prepare the messages for the OpenAI API request
        messages = [
            {"role": "system", "content": "You are a helpful assistant."},
            {
                "role": "user",
                "content": [
                    "Describe the image",
                    {"image": image_frame, "resize": 768},
                ],
            },
        ]

        # Make a request to the OpenAI API to generate a description of the image
        # highlight-start
        result = openai_client.chat.completions.create(
            model="gpt-4o",
            max_tokens=200,
            messages=messages
        )
        # highlight-end

        # Extract the description from the API response
        description = result.choices[0].message.content
        print(description)

        # Create a Pub/Sub publish configuration
        pubsub_config = PubSubPublishConfig(
            topic="CHAT",
            message=description
        )

        # Publish the description to the specified Pub/Sub topic
        # highlight-next-line
        await meeting.pubsub.publish(pubsub_config)

        # Write the description into the file
        with open("videosdk.txt", "w") as f:
            f.write(f"Content {result.choices[0].message.content}")
    except Exception as e:
        print("Error:", e)
```

### Event Handlers

Define event handlers to handle meeting and participant events:

```python
class MyMeetingEventHandler(MeetingEventHandler):
    def __init__(self):
        super().__init__()

    def on_meeting_left(self, data):
        if task is not None:
            task.cancel()

    # highlight-start
    def on_participant_joined(self, p: Participant):
        global participant
        p.add_event_listener(
            MyParticipantEventHandler()
        )
        participant = p
    # highlight-end

    def on_participant_left(self, p: Participant):
        if task is not None:
            task.cancel()


class MyParticipantEventHandler(ParticipantEventHandler):
    def __init__(self):
        super().__init__()

    # highlight-start
    def on_stream_enabled(self, stream: Stream):
        global task, participant
        if stream.kind == "video":
            print("stream is video..")
            task = loop.create_task(capture_video())
    # highlight-end

    def on_stream_disabled(self, stream: Stream):
        if task is not None:
            task.cancel()

```

### Main Function

Initialize the meeting and start the event loop:

```python
def main():
    global meeting
    # Example usage:
    meeting_config = MeetingConfig(
        meeting_id=MEETING_ID,
        name=NAME,
        mic_enabled=False,
        webcam_enabled=False,
        token=VIDEOSDK_TOKEN,
    )
    meeting = VideoSDK.init_meeting(**meeting_config)

    print("adding event listener...")
    meeting.add_event_listener(MyMeetingEventHandler())

    print("joining into meeting...")
    meeting.join()

if __name__ == "__main__":
    main()
    loop.run_forever()
```

## Running the Code

To run the code, simply execute the script:

```bash
python vision_ai.py
```

This script will join the meeting specified by `MEETING_ID` with the provided `VIDEOSDK_TOKEN` and `NAME`, capture video frames, analyze them with OpenAI's Vision API, and publish the results back to the meeting.

Feel free to modify the vision analysis logic inside the `vision_ai` function to apply different kinds of analysis or processing.

## Output

<img src="https://cdn.videosdk.live/website-resources/docs-resources/python_vision_ai.png" width="100%" />

:::tip

Stuck anywhere? Check out this [example code](https://github.com/videosdk-live/videosdk-rtc-python-sdk-example/tree/main/vision-ai) on GitHub.

:::

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [CustomTrack](/python/api/sdk-reference/classes/stream/track)
- [Stream](/python/api/sdk-reference/classes/stream/introduction)
- [pubsub](/python/api/sdk-reference/classes/meeting/pubsub)


---

# Chat using PubSub - Python

For communication or any kind of messaging between participants, VideoSDK provides the `pubsub` in meeting, which utilizes the Publish-Subscribe mechanism. It can be employed to develop a wide variety of functionalities. For example, participants could use it to send chat messages to each other, share files or other media, or even trigger actions like muting or unmuting audio or video.

This guide focuses on using PubSub to implement Chat functionality. If you are not familiar with the PubSub mechanism and `pubsub` in meeting, you can [follow this guide](./pubsub).

## Implementing Chat

In this example, we are going to use `pubsub.publish()`, `pubsub.subscribe()` and custom `topic` to implement group chat feature. let's join this participant from server side.

### `Group Chat Example`

```py
import asyncio
from videosdk import (
    MeetingConfig,
    VideoSDK,
    Meeting,
    MeetingEventHandler,
    PubSubSubscribeConfig,
    PubSubPublishConfig
)
VIDEOSDK_TOKEN = "<VIDEOSDK_TOKEN>"
MEETING_ID = "<MEETING_ID>"
NAME = "<NAME>"
loop = asyncio.get_event_loop()

class MyMeetingEventHandler(MeetingEventHandler):
    def __init__(self, meeting: Meeting):
        super().__init__()
        self.meeting = meeting

    def on_meeting_joined(self, data):
        pubsub_config = PubSubSubscribeConfig(
            topic="CHAT",
            cb=self.on_pubsub_message
        )
        # Schedule the coroutine to run in the background
        asyncio.create_task(self.subscribe_to_pubsub(pubsub_config))

    # highlight-start
    async def subscribe_to_pubsub(self, pubsub_config):
        old_messages = await self.meeting.pubsub.subscribe(pubsub_config)
        print("Old messages: ", old_messages)
    # highlight-end

    def on_pubsub_message(self, data):
        pubsub_config = PubSubPublishConfig(
            topic="CHAT",
            message="we are using videosdk pubsub"
        )
        if data["senderId"]!=self.meeting.local_participant.id:
            print(
                f"Received message from {data['senderId']}: {data['message']}")
            # Schedule the coroutine to run in the background
            asyncio.create_task(self.publish_to_pubsub(pubsub_config))

    # highlight-start
    async def publish_to_pubsub(self, pubsub_config):
        print("Publishing to the pubsub...")
        await self.meeting.pubsub.publish(pubsub_config)
    # highlight-end

def main():
    meeting_config = MeetingConfig(
        meeting_id=MEETING_ID,
        name=NAME,
        mic_enabled=True,
        webcam_enabled=True,
        token=VIDEOSDK_TOKEN,
    )
    meeting = VideoSDK.init_meeting(**meeting_config)
    meeting.add_event_listener(MyMeetingEventHandler(meeting=meeting))
    meeting.join()
    print("Joined into the meeting..")

if __name__ == "__main__":
    main()
    loop.run_forever()
```

#### Explanation:

Environment Setup: Load necessary environment variables like VIDEOSDK_TOKEN, MEETING_ID, and NAME using dotenv.

1. **Environment Setup**: Load necessary environment variables like `VIDEOSDK_TOKEN`, `MEETING_ID`, and `NAME`.

2. **Meeting Event Handler**: Define a custom `MeetingEventHandler` to handle meeting events, particularly subscribing to and receiving messages from PubSub.

3. **Main Functionality**:

   - **Meeting Initialization**: Initialize the meeting and join it asynchronously using `VideoSDK.init_meeting()` and `meeting.join()`.
   - **Message Publishing**: Define an asynchronous function `publish_message()` to publish messages to the "CHAT" topic using `meeting.pubsub.publish()`.

4. **Asyncio Execution**: Use `asyncio.get_event_loop()` to run the `code` coroutine, which handles all interactions and event processing asynchronously.

### `Private Chat Example`

In the above example, to convert the chat into a private one between two participants, set the `sendOnly` property.

```py

        pubsub_config = PubSubPublishConfig(
            topic="CHAT",
            message="we are using videosdk pubsub",
            options={
              "persist": True,
              # highlight-next-line
              "sendOnly": ["xyz"] # participantId
            }
        )
        await meeting.pubsub.publish(pubsub_config)
```

## Downloading Chat Messages

All the messages from PubSub published with `persist : true` can be downloaded as an `.csv` file. This file will be accessible in the VideoSDK dashboard and through the [Sessions API](/api-reference/realtime-communication/fetch-session-using-sessionid).

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [pubsub](/python/api/sdk-reference/classes/meeting/pubsub)


---

# PubSub - Python

PubSub is a concise acronym for the Publish-Subscribe mechanism. This mechanism is employed to send and receive messages within a specified topic. As the name implies, to send a message, one must specify the topic and the message to be published. Similarly, to receive a message, a subscriber must be connected to that particular topic.

Here is a visual to better understand the publish-subscribe mechanism.

![pubsub](/img/pubsub.png)

Using PubSub with VideoSDK
To utilize PubSub in a meeting with VideoSDK, you need to set up the meeting configuration, join the meeting, and handle the PubSub events. Below is a guide on how to achieve this in Python.

## Publishing the messages

1. **Import Necessary Modules**:
   Ensure you import the necessary modules and classes from the `videosdk` package.

2. **Publish Configuration**:
   Define the configuration for publishing a message using `PubSubPublishConfig`.It will accept following parameters as input.

- `topic`: This parameter represents the actual topic to where published and should be in `str` format.
- `message`: This parameter represents the actual message to be published and should be in `str` format.
- `options`: This object specifies the options for publishing. You can set following properties :
  - `persist` : When set to true, this option retains the message for the duration of the session. If persist is true, the message will be available for upcoming participants and can be accessed in the [VideoSDK Session Dashboard](https://app.videosdk.live/meetings/sessions) in CSV format after the session is completed.
  - `sendOnly`: If you want to send a message to specific participants, you can pass their respective `participantId` here. If you don't provide any IDs, the message will be sent to all participants by default.
- `payload`: If you need to include additional information along with a message, you can pass it here as an

3. **Publish Method**:
   Use the `publish` method to send the message to the specified topic.

```py
import asyncio
from videosdk import (
    MeetingConfig,
    VideoSDK,
    Meeting,
    MeetingEventHandler,
    PubSubPublishConfig,
)
VIDEOSDK_TOKEN = "<VIDEOSDK_TOKEN>"
MEETING_ID = "<MEETING_ID>"
NAME = "<NAME>"
loop = asyncio.get_event_loop()

class MyMeetingEventHandler(MeetingEventHandler):
    def __init__(self, meeting: Meeting):
        super().__init__()
        self.meeting = meeting

    def on_meeting_joined(self, data):
        pubsub_config = PubSubPublishConfig(
            topic="CHAT",
            message="hello there"
        )
        # Schedule the coroutine to run in the background
        # highlight-next-line
        asyncio.create_task(self.publish_to_pubsub(pubsub_config))

    # highlight-start
    async def publish_to_pubsub(self, pubsub_config):
        await self.meeting.pubsub.publish(pubsub_config)
    # highlight-end

def main():
    meeting_config = MeetingConfig(
        meeting_id=MEETING_ID,
        name=NAME,
        mic_enabled=True,
        webcam_enabled=True,
        token=VIDEOSDK_TOKEN,
    )
    meeting = VideoSDK.init_meeting(**meeting_config)
    meeting.add_event_listener(MyMeetingEventHandler(meeting=meeting))
    meeting.join()

if __name__ == "__main__":
    main()
    loop.run_forever()
```

## Receiving the messages

- For Receiving the messages, This method is used to subscribe for particular topic. This method returns a list of messages which were sent earlier.

1. **Import Necessary Modules**:
   Ensure you import the necessary modules and classes from the `videosdk` package.

2. **Subscribe Configuration**:
   Define the configuration for subscribing a topic using `PubSubSubscribeConfig`.It will accept following parameters as input.

   - `topic`: This parameter represents the actual topic to be subscribed and should be in `str` format.
   - `cb`: This is callback when new message will received on the same `topic`.

3. **Subscribe Method**:
   Use the `subscribe` method to listen the new/old message to the specified topic.

```py
import asyncio
from videosdk import (
    MeetingConfig,
    VideoSDK,
    Meeting,
    MeetingEventHandler,
    PubSubSubscribeConfig,
)
VIDEOSDK_TOKEN = "<VIDEOSDK_TOKEN>"
MEETING_ID = "<MEETING_ID>"
NAME = "<NAME>"
loop = asyncio.get_event_loop()

class MyMeetingEventHandler(MeetingEventHandler):
    def __init__(self, meeting: Meeting):
        super().__init__()
        self.meeting = meeting

    def on_meeting_joined(self, data):
        # highlight-start
        pubsub_config = PubSubSubscribeConfig(
            topic="CHAT",
            cb=self.on_pubsub_message
        )
        # Schedule the coroutine to run in the background
        asyncio.create_task(self.subscribe_to_pubsub(pubsub_config))
        # highlight-end

    async def subscribe_to_pubsub(self, pubsub_config):
        # highlight-next-line
        old_messages = await self.meeting.pubsub.subscribe(pubsub_config)
        print("Old messages: ", old_messages)

    def on_pubsub_message(self, message):
        print("on_pubsub_message ::", message)

def main():
    meeting_config = MeetingConfig(
        meeting_id=MEETING_ID,
        name=NAME,
        mic_enabled=True,
        webcam_enabled=True,
        token=VIDEOSDK_TOKEN,
    )
    meeting = VideoSDK.init_meeting(**meeting_config)
    meeting.add_event_listener(MyMeetingEventHandler(meeting=meeting))
    meeting.join()
    print("Joined into the meeting..")

if __name__ == "__main__":
    main()
    loop.run_forever()
```

here `on_pubsub_message` called when new message will be published and [message](/python/api/sdk-reference/classes/meeting/pubsub#pubsub-message-data) object contains the following properties:

- `senderId`: Represents the `participantId` of the participant who sent the message.
- `senderName`: Represents the `displayName` of the participant who sent the message.
- `message`: The actual message that was sent.
- `timestamp`: The timestamp for when the message was published.
- `topic`: The name of the topic the message was published to.
- `payload`: The data that was sent along with message.

## Applications of PubSub

PubSub is a powerful mechanism that can be employed to enhance the interactive aspects of your meeting experience. Some common use cases for PubSub during a meeting include:

1. **Chat**: Implement features like Private Chat or Group Chat.
2. **Raise Hand**: Allow attendees to raise their hands at any point during the meeting.
3. **Layout Switching**: Change the meeting's layout for every participant at once.
4. **Whiteboard**: Develop an interactive whiteboard functionality.
5. **Poll**: Create polls, let users respond to them, and display the results.
6. **Question Answer Session**: Design interactive features based on a question-and-answer format.
7. **AI chat agents Session**: Design interactive Chat features using implementation of AI.

## Downloading PubSub Messages

All the messages from PubSub published with `persist : true` can be downloaded as an `.csv` file. This file will be accessible in the VideoSDK dashboard and through the [Sessions API](/api-reference/realtime-communication/fetch-session-using-sessionid).

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [pubsub](/python/api/sdk-reference/classes/meeting/pubsub)


---

# Upload and Retrieve the Temporary File - Python

This guide demonstrates how to upload and retrieve files from VideoSDK's temporary file storage system using Python.

This is a server-side implementation where a Python participant(bot) will join an existing meeting, capture an image once the participant's video stream is available, and fetch the image once the video stream is disabled.

## upload_base64

- By using the `upload_base64` method of the `Meeting` class, you can upload your file to VideoSDK's temporary storage.
- The `upload_base64` method works with `base64` encoded data. Therefore, it is necessary to convert your file into `base64` format.
- You have to pass `base64_data`, `token`, and `file_name` as parameters to the `upload_base64` method.
- The method will return the corresponding `file_url`, which you can then use to retrieve the file.

## fetch_base64

- By using the `fetch_base64` method of the `Meeting` class, you can retrieve your file from VideoSDK's temporary storage.
- You have to pass the `url` (returned by the `upload_base64` method) and the `token` as parameters to retrieve the file.
- The method will return the image in the form of `base64` encoded string.

#### Example

This example demonstrates how to use these methods in a server-side Python script.

The Python participant(bot) will join an existing meeting, capture an image once the participant's video stream is available, and fetch the image once the video stream is disabled.

```python
from videosdk import MeetingConfig, VideoSDK, MeetingEventHandler, ParticipantEventHandler, Meeting, Participant
import asyncio
loop = asyncio.get_event_loop()
VIDEOSDK_TOKEN = "<VIDEOSDK_TOKEN>"
MEETING_ID = "<MEETING_ID>"
NAME = "VideoSDK Python"
file_url: str = None

async def capture_image_and_upload(meeting: Meeting, participant: Participant):
    global file_url
    img_str = await participant.async_capture_image()
    # highlight-start
    # upload_base64
    file_url = meeting.upload_base64(
        base64_data=img_str,
        token=VIDEOSDK_TOKEN,
        file_name="videosdk_testing.jpg"
    )
    # highlight-end
    print("Uploaded URL:", file_url)

class MyParticipantEventHandler(ParticipantEventHandler):
    def __init__(self, meeting: Meeting, participant: Participant) -> None:
        super().__init__()
        self.meeting = meeting
        self.participant = participant

    def on_stream_enabled(self, stream) -> None:
        print("Stream enabled:", stream.kind)
        if stream.kind == "video":
            asyncio.ensure_future(capture_image_and_upload(
                self.meeting, self.participant))

    def on_stream_disabled(self, stream) -> None:
        print("Stream disabled:", stream.kind)
        if stream.kind == "video":
            # highlight-start
            # fetch_base64
            base64_data = self.meeting.fetch_base64(
                url=file_url, token=VIDEOSDK_TOKEN)
            # highlight-end
            print("Base64 data:", base64_data)

class MyMeetingEventHandler(MeetingEventHandler):
    def __init__(self, meeting: Meeting) -> None:
        super().__init__()
        self.meeting = meeting

    def on_participant_joined(self, participant) -> None:
        print("Participant joined:", participant)
        participant.add_event_listener(
            MyParticipantEventHandler(
                meeting=self.meeting,
                participant=participant
            ))

async def main():
    meeting_config = MeetingConfig(
        token=VIDEOSDK_TOKEN,
        meeting_id=MEETING_ID,
        name=NAME,
        mic_enabled=False,
        webcam_enabled=False,
    )
    meeting = VideoSDK.init_meeting(**meeting_config)
    meeting.add_event_listener(MyMeetingEventHandler(
        meeting=meeting
    ))
    await meeting.async_join()

if __name__ == "__main__":
    loop.run_until_complete(main())
    loop.run_forever()
```

:::note

- The file stored in the system will be automatically deleted once the current room/meeting comes to an end.
- Ensure that you have the necessary packages installed and environment variables set correctly before running the script.

:::

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [upload_base64](/python/api/sdk-reference/classes/meeting/methods#upload_base64)
- [fetch_base64](/python/api/sdk-reference/classes/meeting/methods#fetch_base64)


---

# Mute All Participants - Python

When hosting a meeting, it's essential for the host to have the capability to mute all the participants at once. This can be useful in various scenarios, such as when the host wants to deliver a presentation or when there is background noise causing distractions. This guide focuses on this very aspect of muting all other participants' microphone.

- To achieve this, iterate over the list of all participants from the `meeting` class and call the `disable_mic` method from the `participant` class.

### Setup

```py

from videosdk import Meeting, MeetingConfig, VideoSDK
import asyncio

VIDEOSDK_TOKEN = "VIDEOSDK_TOKEN"
MEETING_ID = "MEETING_ID"
NAME = "NAME"
loop = asyncio.get_event_loop()
```

### Example

```py
async def mute_all(meeting: Meeting):
    for paricipant in meeting.participants.values():
        print("Participant Mute Called: ", paricipant.display_name)
        # highlight-next-line
        paricipant.disable_mic()

async def main():
    meeting_config = MeetingConfig(
        meeting_id=MEETING_ID,
        name=NAME,
        mic_enabled=True,
        webcam_enabled=True,
        token=VIDEOSDK_TOKEN,
    )
    meeting = VideoSDK.init_meeting(**meeting_config)
    # asynchronously join the meeting
    await meeting.async_join()

    print("Muting all participants")
    await mute_all(meeting)
if __name__ == "__main__":
    loop.run_until_complete(main())
    loop.run_forever()
```

:::note
The Participant with the capability to mute all other participants' microphones, should have permission **`allow_mod`** passed in the token. To know more about permissions [**visit here**](/python/guide/introduction/authentication-and-token).

:::

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [disable_mic()](/python/api/sdk-reference/classes/participant/methods#disable_mic)


---

# Toggle Remote Participant Media - Python

When hosting a meeting, it's essential for the host to have the capability to request that someone's microphone or camera be turned on, or to turn them off as needed. This guide focuses on this very aspect of controlling other participant's media.

:::note
The Participant with the capability to control other participant's media should have permission **`allow_mod`** passed in the token. To know more about permissions [**visit here**](/python/guide/introduction/authentication-and-token).
:::

Before delving into the methods and events associated with this functionality, explore how the flow would unfold.

![img1](../../../../../static/img/toggle-remote-media.png)

## Methods

### `enable_mic()`

- If the host wishes to activate a participant's microphone, the `enable_mic()` method from the `participant` object should be employed.

- Upon invoking this method, the participant whose microphone is requested for, will receive the `on_mic_requested` event. This event contains the `participantId` of the host making the request, along with two callback functions—`accept` and `reject`. The participant can decide to accept or reject the incoming request.

- For instance, if a meeting involves **Participant A** and **Participant B**, and the host (**Participant A**) desires to enable the microphone of **Participant B**, the host will utilize the `enable_mic()` function to send a request to **Participant B**. Subsequently, **Participant B** will receive the `on_mic_requested` event and can choose to either accept or reject the incoming request.

### `enable_webcam()`

- If the host wishes to activate a participant's camera, the `enable_webcam()` method from the `participant` object should be employed.

- Upon invoking this method, the participant whose camera is requested for, will receive the `on_webcam_requested` event. This event contains the `participantId` of the host making the request, along with two callback functions—`accept` and `reject`. The participant can decide to accept or reject the incoming request.

- For instance, if a meeting involves **Participant A** and **Participant B**, and the host (**Participant A**) desires to enable the camera of **Participant B**, the host will utilize the `enable_webcam()` function to send a request to **Participant B**. Subsequently, **Participant B** will receive the `on_mic_requested` event and can choose to either accept or reject the incoming request.

### `disbale_mic()`

- If the host wishes to deactivate a participant's microphone, the `disbale_mic()` method from the `participant` object should be employed.

- This will automatically disable the microphone of the participant.

### `disable_webcam()`

- If the host wishes to deactivate a participant's camera, the `disable_webcam()` method from the `Participant` object should be employed.

- This will automatically disable the camera of the participant.

#### Example 1

In this example, we have covered `participant.disable_webcam()` & `participant.disable_mic()` whenever stream enabled.

```py
class ParticipantEventHandler(ParticipantEventHandler):
  def __init__(self, participant: Participant):
      super().__init__()
      self.participant = participant

  def on_stream_enabled(self, stream: Stream):
      print(
          self.participant.id,
          "stream enabled ====",
          stream.kind,
      )
      if stream.kind == "audio":
        # highlight-next-line
        self.participant.disable_mic()

      if stream.kind == "video":
        # highlight-next-line
        self.participant.disable_webcam()

class MyMeetingEventHandler(MeetingEventHandler):
    def __init__(self):
        super().__init__()

    def on_participant_joined(self, participant: Participant)
        participant.add_event_listener(
            ParticipantEventHandler(participant=participant)
        )
```

#### Example 2

In this example, we have covered `participant.enable_webcam()` & `participant.enable_mic()` whenever new participant joined.

```py
class MyMeetingEventHandler(MeetingEventHandler):
    def __init__(self):
        super().__init__()

    def on_participant_joined(self, participant):
        # highlight-start
        participant.enable_mic()
        participant.enable_webcam()
        # highlight-end
```

## Events

### `on_webcam_requested()`

This event is triggered for a participant (`Participant B`) when the host (`Participant A`), requests to enable their webcam. The event handler for this event will receive the following three arguments:

- `accept()` - Callback function to accept the request.
- `reject()` - Callback function to reject the request.
- `participantId` - ParticipantId of the requesting participant.

### `on_mic_requested()`

This event is triggered for a participant (`Participant B`) when the host (`Participant A`), requests to enable their microphone. The event handler for this event will receive the following three arguments:

- `accept()` - Callback function to accept the request.
- `reject()` - Callback function to reject the request.
- `participantId` - ParticipantId of the requesting participant.

###### Usage

```py
class MyMeetingEventHandler(MeetingEventHandler):
    def __init__(self):
        super().__init__()

    def on_webcam_requested(self, data):
        wanted_to_accept = True
        if wanted_to_accept:
            accept = data["accept"]
            accept()
        else:
            reject = data["reject"]
            reject()

    def on_mic_requested(self, data):
        wanted_to_accept = True
        if wanted_to_accept:
            accept = data["accept"]
            accept()
        else:
            reject = data["reject"]
            reject()

```

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [enable_mic()](/python/api/sdk-reference/classes/participant/methods#enable_mic)
- [enable_webcam()](/python/api/sdk-reference/classes/participant/methods#enable_webcam)
- [on_webcam_requested()](/python/api/sdk-reference/classes/meeting/events#on_webcam_requested)
- [on_mic_requested()](/python/api/sdk-reference/classes/meeting/events#on_mic_requested)


---

# Remove Participant - Python

When hosting a meeting, it's essential for the host to have the capability to remove a participant from the meeting.
This can be useful in various scenarios where a participant is causing disturbance, behaving inappropriately, or is not following meeting guidelines.
This guide focuses on this very aspect of removing a particpant in a meeting from server side.

VideoSDK provides three ways to do so:

1. [Using Server SDK](#1-using-sdk)
2. [Using VideoSDK Dashboard](#2-using-videosdk-dashboard)
3. [Using Rest API](#3-using-rest-api)

## 1. Using SDK

### `remove()`

The `remove()` method allows for the removal of a participant during an on-going session. This can be helpful when moderation is required in a particular meeting.

#### MeetingEventHandler

```py
from videosdk import MeetingEventHandler, MeetingConfig, VideoSDK
import asyncio

VIDEOSDK_TOKEN = os.getenv("VIDEOSDK_TOKEN")
MEETING_ID = os.getenv("MEETING_ID")
NAME = os.getenv("NAME")
loop = asyncio.get_event_loop()

class MyMeetingEventListener(MeetingEventHandler):
    def __init__(self):
        super().__init__()

    def on_participant_joined(self, participant):
        print("Participant joined")
        # highlight-next-line
        participant.remove()

    def on_participant_left(self, participant):
        print("Participant left", participant.display_name)
```

#### join the meeting

```py
async def main():
    meeting_config = MeetingConfig(
        meeting_id=MEETING_ID,
        name=NAME,
        mic_enabled=True,
        webcam_enabled=True,
        token=VIDEOSDK_TOKEN,
    )
    meeting = VideoSDK.init_meeting(**meeting_config)

    meeting.add_event_listener(MyMeetingEventListener())

    # asynchronously join the meeting
    await meeting.async_join()

    print("Meeting joined")

if __name__ == "__main__":
    loop.run_until_complete(main())
    loop.run_forever()
```

### Events associated with remove()

Following callbacks are received when a participant is removed from the meeting.

- The participant who was removed from the meeting will receive a callback on the [`on_meeting_left`](/python/api/sdk-reference/classes/meeting/events#on_meeting_left) callback event of the `MeetingEventHandler`.
- All other [remote participants](../../introduction/concept-and-architecture.md#2-participant) will receive a callback on the [`on_participant_left`](/python/api/sdk-reference/classes/meeting/events#on_participant_left) event with the Participant object.

## 2. Using VideoSDK Dashboard

- For removing a participant using the VideoSDK Dashboard, navigate to the session page on [VideoSDK Dashboard](https://app.videosdk.live/meetings/sessions). Select the specific meeting, and from the list of participants, choose the participant you wish to remove. Utilize the provided options to remove the selected participant from the meeting.


<div style={{textAlign: 'center'}}>



</div>

## 3. Using Rest API

- You can also remove a particular participant from the meeting [using the REST API](/api-reference/realtime-communication/remove-participant).
- To employ this method, you need the `sessionId` of the meeting and the `participantId` of the individual you intend to remove.

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [remove()](/python/api/sdk-reference/classes/participant/methods#remove)
- [on_meeting_left()](/python/api/sdk-reference/classes/meeting/events#on_meeting_left)
- [on_participant_left()](/python/api/sdk-reference/classes/meeting/events#on_participant_left)


---

# Data Channel

This guide explains how to **send** and **receive** messages (string or bytes) using the VideoSDK **DataChannel**.

The DataChannel supports two reliability modes:
- `RELIABLE` → guaranteed delivery (ordered, slower).
- `UNRELIABLE` → faster, but delivery is not guaranteed (unordered).

---

## Sending Messages

Messages can be sent using the `meeting.send(...)` method. Both **string** and **bytes** payloads are supported.

```python
# Send a string (reliable)
await meeting.send(
    "Hello from Python!",
    {"reliability": ReliabilityModes.RELIABLE.value}
)

# Send a string (unreliable)
await meeting.send(
    "Quick update",
    {"reliability": ReliabilityModes.UNRELIABLE.value}
)

# Send bytes (unreliable)
await meeting.send(
    b"\x00\x01\x02\x03",
    {"reliability": ReliabilityModes.UNRELIABLE.value}
)

```

:::note
Remember that while using the data channel, the message payload will be broadcast to all participants in the room by default.
:::

## Receiving Messages

To receive DataChannel messages, implement the `on_data` event handler in your custom event class.  

It can be implemented using the `MeetingEventHandler` class:

```python
def on_data(self, data):
    print("Message received:")
    print(f"Payload: {data['payload']}")
    print(f"From: {data['from']}")
    print(f"Reliability: {data['reliability']}")
    print(f"Timestamp: {data['timestamp']}")

```     

When working with DataChannel in VideoSDK, keep the following limits in mind:

- **MAX_PAYLOAD_SIZE** → `15 * 1024` (15 KB)  
  - The maximum size for a single message payload.  
  - If you try to send a larger payload, it will be rejected.

- **MAX_BUFFER_SIZE** → `65535` (≈ 64 KB)  
  - The maximum buffer size available for queued messages.  
  - If the buffer is full, new messages may fail until space is cleared.


---

# Error Events - Python

VideoSDK provides the `on_error()` event which informs you about any error happening during the meeting.

### on_error()

- This event is triggered whenever an invalid configuration is provided or server/network errors arise. In such cases, the event will trigger with a specific error code and message.
- It is particularly useful for development-level troubleshooting during SDK integration.
- It can be implement to using the `MeetingEventHandler` class

### Example

Here is an example demonstrating the usage of the event mentioned on this page.

```py
class MyMeetingEventHandler(MeetingEventHandler):
  def __init__(self):
      super().__init__()

  def on_error(self, data):
    print("meeting error", data)
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [on_error()](/python/api/sdk-reference/classes/meeting/events#on_error)


---

# Media Events - Python

VideoSDK offers various events that can be monitored to obtain information about the media status of participants in the meeting.

Here are the events specifically related to the stream:

### on_stream_enabled()

- This event is triggered whenever a participant's video, audio or screen share stream is enabled.
- It can be implement to using the `ParticipantEventHandler` class.

### on_stream_disabled()

- This event is triggered whenever a participant's video, audio or screen share stream is disabled.
- It can be implement to using the `ParticipantEventHandler` class.

### on_media_status_changed()

- This event is triggered whenever a participant's video or audio stream is disabled or enabled.
- It can be implement to using the `ParticipantEventHandler` class.

### on_video_quality_changed()

- This event is triggered whenever a participant's video quality changed.
- It can be implement to using the `ParticipantEventHandler` class.

### Example

Here is an example demonstrating the usage of all the events mentioned on this page.

```py

class MyParticipantEventHandler(ParticipantEventHandler):
  def __init__(self):
    super().__init__()

  def on_stream_enabled(self, stream):
    print("paricipant :: stream enabled", stream.kind)

  def on_stream_disabled(self, stream):
    print("paricipant :: stream disabled", stream.kind)

  def on_media_status_changed(self, data):
    print("paricipant :: media status changed", data)

  def on_video_quality_changed(self, data):
    print("paricipant :: video quality changed", data)
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [on_stream_enabled()](/python/api/sdk-reference/classes/participant/events#on_stream_enabled)
- [on_stream_disabled()](/python/api/sdk-reference/classes/participant/events#on_stream_disabled)
- [on_media_status_changed()](/python/api/sdk-reference/classes/participant/events#on_media_status_changed)
- [on_video_quality_changed()](/python/api/sdk-reference/classes/participant/events#on_video_quality_changed)


---

# Meeting Connection Events - Python

VideoSDK offers the `on_meeting_state_change()` event, providing information about the current connection state of the meeting.

### on_meeting_state_change()

- This event is triggered when the state of a meeting changes.
- The event callback will include the current state of the meeting, which can be one of the following: `CONNECTING`, `CONNECTED`, `FAILED`, `DISCONNECTED`, `CLOSING`, `CLOSED`.
- It can be implement to using the `MeetingEventHandler` class.

### Example

Here is an example demonstrating the usage of the event mentioned on this page.

```py
class MyMeetingEventHandler(MeetingEventHandler):
  def __init__(self):
      super().__init__()

  def on_meeting_state_change(self, data):
    print("meeting state changed", data)
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [on_meeting_state_change()](/python/api/sdk-reference/classes/meeting/events#on_meeting_state_change)


---

# Meeting Event Handler - Python

VideoSDK provides several types of events that can be listened to in order to determine the current state of the meeting.

Here are the events specifically related to the meeting:

### on_meeting_joined()

- This event is triggered when the meeting is successfully joined.
- It can be implement to using the `MeetingEventHandler` class.

### on_meeting_left()

- This event is triggered when the meeting is left.
- It can be implement to using the `MeetingEventHandler` class.

### on_speaker_changed()

- This event is triggered when there is a change in the active speaker during the meeting.
- It can be implement to using the `MeetingEventHandler` class.

### on_participant_joined()

- This event is triggered when the participant is successfully joined in the meeting.
- It can be implement to using the `MeetingEventHandler` class.

### on_participant_left()

- This event is triggered when the participant is left from the meeting.
- It can be implement to using the `MeetingEventHandler` class.

### Example

Here is an example demonstrating the usage of all the events mentioned on this page.

```python
class MyMeetingEventHandler(MeetingEventHandler):
  def __init__(self):
      super().__init__()

  def on_meeting_joined(self, data):
    print("meeting joined")

  def on_meeting_left(self, data):
    print("meeting left")

  def on_speaker_changed(self, data):
    print("active speaker changed", data)

  def on_participant_joined(self, participant):
    print("participant joined", participant)

  def on_participant_left(self, participant):
    print("participant left", participant)
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [on_meeting_joined()](/python/api/sdk-reference/classes/meeting/events#on_meeting_joined)
- [on_meeting_left()](/python/api/sdk-reference/classes/meeting/events#on_meeting_left)
- [on_speaker_changed()](/python/api/sdk-reference/classes/meeting/events#on_speaker_changed)
- [on_participant_joined()](/python/api/sdk-reference/classes/meeting/events#on_participant_joined)
- [on_participant_left()](/python/api/sdk-reference/classes/meeting/events#on_participant_left)


---

# Participant Events - Python

VideoSDK provides various events that can be utilized to gather information about the participants in the meeting.

Here are the events specifically related to the participant:

### on_participant_joined()

- This event is triggered when someone joins the meeting, returning the `Participant` object as parameter.
- It can be implement to using the `MeetingEventHandler` class.

### on_participant_left()

- This event is triggered when someone leaves the meeting.
- It can be implement to using the `MeetingEventHandler` class.

### on_webcam_requested()

- This event is triggered for participant `B`, when another participant, `A` requests to enable their webcam.
- Upon accepting the request, participant `B`'s webcam will be enabled.
- It can be implement to using the `MeetingEventHandler` class.

### on_mic_requested()

- This event is triggered for participant `B`, when another participant, `A` requests to enable their mic.
- Upon accepting the request, participant `B`'s mic will be enabled.
- It can be implement to using the `MeetingEventHandler` class.

### Example

Here is an example demonstrating the usage of all the events mentioned on this page.

```py
class MyMeetingEventHandler(MeetingEventHandler):
    def __init__(self):
        super().__init__()

    def on_participant_joined(self, participant):
        print("participant joined", participant)

    def on_participant_left(self, participant):
        print("participant left", participant)

    def on_webcam_requested(self, data):
      wanted_to_accept = True
      if wanted_to_accept:
        accept = data["accept"]
        accept()
      else:
        reject = data["reject"]
        reject()

    def on_mic_requested(self, data):
      wanted_to_accept = True
      if wanted_to_accept:
        accept = data["accept"]
        accept()
      else:
        reject = data["reject"]
        reject()

```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [on_participant_joined()](/python/api/sdk-reference/classes/meeting/events#on_participant_joined)
- [on_participant_left()](/python/api/sdk-reference/classes/meeting/events#on_participant_left)
- [on_webcam_requested()](/python/api/sdk-reference/classes/meeting/events#on_webcam_requested)
- [on_mic_requested()](/python/api/sdk-reference/classes/meeting/events#on_mic_requested)


---

# Recording Events - Python

VideoSDK provides the `on_recording_state_changed()` event, which notifies you of the current state of recording for the meeting.

### on_recording_state_changed()

- This event is triggered when the recording status of the meeting changes.
- It can be implement to using the `MeetingEventHandler` class

### Example

Here is an example demonstrating the usage of the event mentioned on this page.

```py
  class MyMeetingEventHandler(MeetingEventHandler):
    def __init__(self):
        super().__init__()

    def on_recording_state_changed(self, data):
        print("recording state changed", data)

    def on_recording_started(self, data):
        print("recording started", data)

    def on_recording_stopped(self, data):
        print("recording stopped", data)
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [on_recording_state_changed()](/python/api/sdk-reference/classes/meeting/events#on_recording_state_changed)
- [on_recording_stopped()](/python/api/sdk-reference/classes/meeting/events#on_recording_stopped)
- [on_recording_started()](/python/api/sdk-reference/classes/meeting/events#on_recording_started)


---

# Cloud Proxy - Python


Our SDK features a Cloud Proxy that allows you to manage how your streaming content is routed through different network paths. This feature ensures compliance with various regional internet regulations by restricting traffic to specified proxy servers, based on your needs and the geographical location of users.

This capability is crucial for adhering to local data protection laws and optimizes the streaming experience by overcoming geographical network constraints. By directing user connections to appropriate regional servers, Cloud Proxy enhances overall service performance and reliability.

Cloud Proxy offers three straightforward operating modes to fit different business and firewall requirements:

- **UDP_OVER_TCP (Default)**: In this mode, the connection starts by attempting to establish a UDP connection for media transmission. If that fails, it will automatically shifts to a secure TCP connection, which is compatible with most firewalls.

- **Force UDP**: This mode uses only UDP to send media, ensuring high-quality streams. It's ideal for environments where media quality is critical and the firewall can be configured accordingly.

- **Force TCP**: Only uses TCP for secure media transmission, suitable for strict firewall settings that only permit TCP traffic over centain ports. This might require additional firewall configuration and could affect media quality under poor network conditions.




### In this sequence diagram:
- Client to Proxy Server: The client sends a request to the proxy server, which processes and forwards it based on predefined rules.
- Proxy Server to Destination Server: The proxy server sends the request to the destination server, receives the response, and relays it back to the client.

:::info

Cloud Proxy is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Implementation

```python
from videosdk import (
    MeetingConfig,
    VideoSDK,
)
  meeting = VideoSDK.init_meeting(**MeetingConfig(
      meeting_id=MEETING_ID,
      name=NAME,
      mic_enabled=True,
      webcam_enabled=True,
      token=VIDEOSDK_TOKEN,

      # cloud proxy
      preferred_protocol="UDP_ONLY",
      signaling_base_url="proxy.yourwebsite.com"
  ))
```

### Parameters

- preferredProtocol:
  - UDP_OVER_TCP (default): Initially the server attempts to establish a connection using UDP, if that fails it automatically switches to TCP protocol.
  - UDP_ONLY: Force UDP protocol
  - TCP_ONLY: Force TCP protocol
- signalingBaseUrl: Proxy URL to origin signaling and media.

## API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [MeetingConfig](/python/api/sdk-reference/types#meetingconfig)


---

# Geo Fencing - Python


Our SDK includes a region geofencing feature to comply with local laws and regulations worldwide. It restricts connections to servers within specified regions, ensuring users connect only to designated areas, regardless of their location. 

This helps meet regional data protection requirements and enhances user experience by addressing geographical network limitations.




### In this sequence diagram:
- User 1 (India) tries to connect to a meeting. In a regular scenario, the meeting would connect to the India region, but due to the geofence configuration, the meeting will connect to North America.

## Considerations
- If the user’s location differs from the chosen region, the network quality between these locations may be poor, affecting audio and video quality.
- Avoid using geofencing unless your scenario requires regional compliance.

:::info

Geo Fencing is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Available Regions
- INDIA
- USA
- UAE
- EUROPE
- SINGAPORE
- AUSTRALIA


---

# Geo IP Restrictions - Python


Our SDK features Geo IP Restriction to ensure adherence to location-based access controls. It determines the user's location using their IP address and allows or restricts content based on geographic rules. This is essential for businesses needing to comply with international content distribution laws or provide localized services.

By implementing Geo IP Restriction, you can control who accesses your services based on where they are, ensuring compliance with legal regulations and enhancing security. This feature also improves the user experience by ensuring content relevance and availability is tailored to the user's location.




### In this sequence diagram:
- User 1 (India) attempts to connect to a meeting that is geo-restricted to only allow connections from North America. The server denies the connection due to the geographic restrictions.
- User 2 (North America) successfully connects because their location complies with the geo-restricted rules set on the meeting.


## Considerations
- Avoid using geo ip restriction unless your scenario requires regional or VPN/Proxy restrictions.

:::info

Geo IP Restriction is only available under Enteprise Plan, [<ins>Contact Sales</ins>](https://www.videosdk.live/contact) for more information.

:::

## Available Regions
- INDIA
- USA
- UAE
- EUROPE
- SINGAPORE
- AUSTRALIA


---

# Active Speaker Indication - Python

The Active Speaker Indication feature in VideoSDK allows you to identify the participant who is currently the active speaker in a meeting. This feature proves especially valuable in larger meetings or webinars, where numerous participants can make it challenging to identify the active speaker.

Whenever any participant speaks in a meeting, the `on_speaker_changed` event will trigger, providing the participant ID of the active speaker.

For example, the meeting is running with **Alice** and **Bob**. Whenever any of them speaks, `on_speaker_changed` event will trigger in MeetingEventHandler and return the speaker's `participantId`.

### Event

```python
from videosdk import (
    MeetingConfig,
    VideoSDK,
    MeetingEventHandler,
)
VIDEOSDK_TOKEN = "<VIDEOSDK_TOKEN>"
MEETING_ID = "<MEETING_ID>"
NAME = "<NAME>"
class MyMeetingEventHandler(MeetingEventHandler):
  def __init__(self):
      super().__init__()

  def on_speaker_changed(self, data):
    print("speaker changed", data)
def main():
  meeting_config = MeetingConfig(
      meeting_id=MEETING_ID,
      name=NAME,
      mic_enabled=False,
      webcam_enabled=False,
      token=VIDEOSDK_TOKEN,
  )
  meeting = VideoSDK.init_meeting(**meeting_config)
  meeting.add_event_listener(MyMeetingEventHandler())
  meeting.join()
if __name__ == "__main__":
    main()
    loop.run_forever()
```

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [on_speaker_changed()](/python/api/sdk-reference/classes/meeting/events#on_speaker_changed)


---

# Enable / Disable Mic - Python

Enabling and Disabling your microphone refers to turning your microphone on and off, respectively.

Disabling your microphone prevents the transmission of any sound from your microphone to other meeting participants, while Enabling allows them to hear you.

### `enable_mic()`

- By using the `enable_mic()` function, the local participant can publish their audio to other participants.

  - You can only call this method when the local participant is not broadcasting audio to others.

- You can also pass a customised audio track in the `enable_mic()` method by using [Custom Audio Track](/python/guide/video-and-audio-calling/stream-ingestion/custom-audio-track).

### `disable_mic()`

- By using the `disable_mic()` function, the local participant can stop publishing their audio to other participants.

- You can only call this method when the local participant is broadcasting audio to others.

#### Example

```py title="main.py"
import asyncio
from videosdk import MeetingConfig, VideoSDK

VIDEOSDK_TOKEN = "

</div>

:::tip
Stuck anywhere? Check out this [example code](https://github.com/videosdk-live/quickstart/tree/main/python-rtc) on GitHub
:::

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [enable_mic()](/python/api/sdk-reference/classes/meeting/methods#enable_mic)
- [disable_mic()](/python/api/sdk-reference/classes/meeting/methods#disable_mic)
- [on_stream_enabled()](/python/api/sdk-reference/classes/participant/events#on_stream_enabled)
- [on_stream_disabled()](/python/api/sdk-reference/classes/participant/events#on_stream_disabled)
- [on_media_status_changed()](/python/api/sdk-reference/classes/participant/events#on_media_status_changed)


---

# On / Off Camera - Python

Participants in the meeting have the ability to toggle their cameras on or off using the methods outlined below.

### `enable_webcam()`

- By using the `enable_webcam()` function, the local participant can publish their video to other participants.

- You can only call this method when the local participant is not broadcasting video to others.

- You can also pass a customised video track in `enable_webcam()` by using [Custom Video Track](/python/guide/video-and-audio-calling/stream-ingestion/custom-video-track).

### `disable_webcam()`

- By using the `disable_webcam()` function, the local participant can stop publishing their video to other participants.

- You can only call this method when the local participant is broadcasting video to others.

#### Example

```py title="main.py"
import asyncio
from videosdk import MeetingConfig, VideoSDK

VIDEOSDK_TOKEN = "

</div>

:::tip
Stuck anywhere? Check out this [reference code](https://github.com/videosdk-live/quickstart/tree/main/python-rtc) on GitHub
:::

### API Reference

The API references for all the methods and events utilized in this guide are provided below.

- [enable_webcam()](/python/api/sdk-reference/classes/meeting/methods#enable_webcam)
- [disable_webcam()](/python/api/sdk-reference/classes/meeting/methods#disable_webcam)
- [on_stream_enabled()](/python/api/sdk-reference/classes/participant/events#on_stream_enabled)
- [on_stream_disabled()](/python/api/sdk-reference/classes/participant/events#on_stream_disabled)
- [on_media_status_changed()](/python/api/sdk-reference/classes/participant/events#on_media_status_changed)


---

Recording meetings is an essential feature that ensures all important discussions, decisions, and interactions are documented for future reference. VideoSDK offers three types of recordings: Meeting Recording, Participant Recording, and Participant Track Recording. Each type serves a specific purpose to cater to different recording needs during a meeting.

## Meeting Recording

Meeting Recording captures the entire meeting, including all participants, audio, video, and shared content. This comprehensive recording is ideal for reviewing the entire meeting, ensuring that nothing is missed. It provides a holistic view of the meeting, capturing every interaction and piece of information shared during the session.

![Meeting Recording](https://cdn.videosdk.live/website-resources/docs-resources/MeetingRecording.png)

## Participant Recording

Participant Recording focuses on individual participants, capturing both their audio and video into a single file. This type of recording is particularly useful for tracking the contributions of specific participants or for scenarios where detailed analysis of an individual’s participation is needed. When a participant mutes their audio or turns off their video, the recording continues but with silenced audio or a black screen, respectively. This ensures a continuous recording without interruptions, reflecting the participant's involvement throughout the meeting.

![Participant Recording](https://cdn.videosdk.live/website-resources/docs-resources/ParticipantRecording.png)

## Participant Track Recording

Participant Track Recording allows you to record specific tracks of a participant, either audio or video, based on user input. This targeted approach is perfect for capturing particular aspects of a participant’s contribution, such as only their audio or only their video. Multiple files are generated whenever there is a change in the track's status (e.g., starting after being muted ), ensuring focused documentation of each continuous segment. This method is especially useful in scenarios where detailed analysis of specific media (audio or video) is required.

![Participant Track Recording](https://cdn.videosdk.live/website-resources/docs-resources/TrackRecording.png)



---

https://sdk.videosdk.live/js-sdk/0.2.6/videosdk.jsVideoSDK offers a range of video streaming tools and solutions for content creators, publishers, and developers.

- A custom template is a specialized layout for a live stream that allows users to integrate real-time graphics into their broadcasts.

- With custom templates, users can enhance their video content by overlaying graphics, text, images, and animations onto their live streams. These elements can be customized to align with specific branding requirements.

- By leveraging custom templates, users can craft dynamic and engaging video experiences. Whether incorporating live scoreboards, social media feeds, or other personalized elements, users have the flexibility to create visually appealing streams that stand out and capture audience attention.

:::note

Custom templates can also be used with recordings and RTMP service provided by VideoSDK.

:::

### What you can do with Custom Template

By utilizing a custom template, you have the flexibility to create various modes for your live stream. Here are some popular modes that you can design:

- **`PK Host:`** The host can organize a player vs. player battle, as illustrated in the example of a gaming battle shown below.

![pk host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_pk_battle.png)

- **`Watermark:`** The host has the ability to add and update watermarks anywhere in the template; for instance, the image below features a VideoSDK watermark on the top right side of the screen.

![watermark host](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_water_mark.png)

- **`News Mode:`** Additionally, the host can incorporate dynamic text in the lower third banner, as demonstrated by the sample text in the bottom left of the screen.

![news mode](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_news_live.png)

### Custom template with VideoSDK

In this section, we will discuss how Custom Templates work with VideoSDK.

- **`Host`**: The host initiates live streaming by providing the `templateURL`. The `templateURL` is the URL of the hosted template webpage. The host is also responsible for managing the template, including tasks such as altering text, logos, and switching template layouts.

- **`VideoSDK Template Engine`** : The VideoSDK Template Engine accepts and opens the templateURL in the browser, actively listening to all events initiated by the Host. It facilitates the customization of the template in accordance with the host's preferences.

- **`Viewer`**: Viewers can stream the content, experiencing the live stream with added real-time graphics. This feature contributes to a distinctive and engaging viewing experience.

![custom template](https://cdn.videosdk.live/website-resources/docs-resources/custom_template.png)

### Understanding Template URL

The template URL is a webpage that VideoSDK Template Engine will open while composing the live stream.

It will appear as shown below.

![template url](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_url.png)

The Template URL comprises of two essential parts:

- Your actual page URL, resembling something like `https://example.com/videosdk-template`.
- Query parameters, designed to enable the VideoSDK Template Engine to seamlessly join the meeting upon opening the URL. There are three key query parameters in total:
  - `token`: Your token, serving as the authentication key to join the meeting.
  - `meetingId`: The meeting Id of the meeting that the VideoSDK Template Engine will join.
  - `participantId`: The participant ID of the VideoSDK Template Engine. This should be included when joining the template engine in your template, ensuring that the template engine participant remains invisible to other participants. **This parameter is automatically added by the VideoSDK**.

:::info

Above mentioned query parameters are mandatory. Apart from these parameters, you can pass any other extra parameters which are required according to your use-case.

:::

### **Creating Template**

**`Step 1:`** Import VideoSDK using `<script>` tag or install it using the below-mentioned npm command.
Make sure you are in your app directory before you run this command.



**Tab:**

" label="<script>" default>

```html
<html>
  <head></head>
  <body>
// highlight-next-line
<script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
  </body>
</html>
```

---

**npm:**

```bash
npm install @videosdk.live/js-sdk
```

---

**yarn:**

```bash
yarn add @videosdk.live/js-sdk
```

:::note

You can use VideoSDK's React or JavaScript SDK to create custom template. Following is the example of building custom template with JavaScript SDK.

:::

###### Structure of the Project

```jsx title="Project Structure"
  root
   ├── index.html
   ├── index.js
```

**`Step 2:`** Craft a user interface (UI) tailored for your live stream presentation.

```html title="index.html"
<!DOCTYPE html>
<html>
  <head> </head>

  <body>
    <div id="textDiv">Starting live stream...</div>

    
    <div class="row" id="videoContainer"></div>

    <script src="https://sdk.videosdk.live/js-sdk/0.1.6/videosdk.js"></script>
    <script src="index.js"></script>
  </body>
</html>
```

**`Step 3:`** Next, fetch the query parameters, from the URL which will be later used to initialize the meeting and get the elements from DOM.

```js title=index.js
const url = window.location;
const urlParams = new URLSearchParams(url.search);

const meetingId = urlParams.get("meetingId");
const token = urlParams.get("token");
const participantId = urlParams.get("participantId");

const videoContainer = document.getElementById("videoContainer");
const textDiv = document.getElementById("textDiv");
```

**`Step 4:`** Subsequently, initialize the meeting with the parameters that were extracted from the URL. Ensure direct initialization so that the template engine seamlessly joins the meeting upon page load.

```js title=index.js
window.VideoSDK.config(token);

const meeting = window.VideoSDK.initMeeting({
  meetingId: meetingId, // required
  name: "recorder", // required
  micEnabled: false,
  webcamEnabled: false,
  participantId: participantId,
});

meeting.join();

meeting.on("meeting-joined", () => {
  textDiv.style.display = "none";
});
```

**`Step 5:`** Next step is to create the container that will render the meeting view on the `participant-joined` event.

```js title=index.js
//  participant joined
meeting.on("participant-joined", (participant) => {
  let videoElement = createVideoElement(
    participant.id,
    participant.displayName
  );
  let audioElement = createAudioElement(participant.id);

  participant.on("stream-enabled", (stream) => {
    setTrack(stream, audioElement, participant, false);
  });
  videoContainer.appendChild(videoElement);
  videoContainer.appendChild(audioElement);
});

// participants left
meeting.on("participant-left", (participant) => {
  let vElement = document.getElementById(`f-${participant.id}`);
  vElement.remove(vElement);

  let aElement = document.getElementById(`a-${participant.id}`);
  aElement.remove(aElement);
});

// creating video element
function createVideoElement(pId, name) {
  let videoFrame = document.createElement("div");
  videoFrame.setAttribute("id", `f-${pId}`);

  //create video
  let videoElement = document.createElement("video");
  videoElement.classList.add("video-frame");
  videoElement.setAttribute("id", `v-${pId}`);
  videoElement.setAttribute("playsinline", true);
  videoElement.setAttribute("width", "300");
  videoElement.muted = true;
  videoFrame.appendChild(videoElement);

  let displayName = document.createElement("div");
  displayName.innerHTML = `Name : ${name}`;
  videoFrame.appendChild(displayName);

  return videoFrame;
}

// creating audio element
function createAudioElement(pId) {
  let audioElement = document.createElement("audio");
  audioElement.setAttribute("autoPlay", "false");
  audioElement.setAttribute("playsInline", "true");
  audioElement.setAttribute("controls", "false");
  audioElement.setAttribute("id", `a-${pId}`);
  audioElement.style.display = "none";
  return audioElement;
}

// setting media track
function setTrack(stream, audioElement, participant, isLocal) {
  if (stream.kind == "video") {
    isWebCamOn = true;
    const mediaStream = new MediaStream();
    mediaStream.addTrack(stream.track);
    let videoElm = document.getElementById(`v-${participant.id}`);
    videoElm.srcObject = mediaStream;
    videoElm
      .play()
      .catch((error) =>
        console.error("videoElem.current.play() failed", error)
      );
  }
  if (stream.kind == "audio") {
    if (isLocal) {
      isMicOn = true;
    } else {
      const mediaStream = new MediaStream();
      mediaStream.addTrack(stream.track);
      audioElement.srcObject = mediaStream;
      audioElement
        .play()
        .catch((error) => console.error("audioElem.play() failed", error));
    }
  }
}
```

**`Step 6:`** Now, listen to PubSub messages from the `CHANGE_BACKGROUND` topic, triggering a change in the meeting's background color accordingly.

:::note

The PubSub mechanism is utilized to communicate with the template. You can learn more about [PubSub from here](/javascript/guide/video-and-audio-calling-api-sdk/collaboration-in-meeting/pubsub).

:::

```js title=index.js
meeting.on("meeting-joined", () => {
  //  ...

  meeting.pubSub.subscribe("CHANGE_BACKGROUND", (data) => {
    let { message } = data;
    document.body.style.backgroundColor = message;
  });
});
```

**`Step 7:`** Once tested, you can deploy it using your backend or host it on services like [firebase](https://www.geeksforgeeks.org/how-to-deploy-react-project-on-firebase/) or vercel.

:::tip

You can checkout the github repository for sample custom template [created here](https://github.com/videosdk-live/videosdk-custom-recording-template-js-example).

:::

### Setup Livestream Using Custom Template

- To utilize Custom Templates with Livestream, you need to establish both the Host and Viewer setups. The Host initiates the livestream, while Viewers can watch the broadcast.

![template manager](https://cdn.videosdk.live/website-resources/docs-resources/custom_template_manager.png)

- To understand custom templates, clone this example and run it on your system.

```bash
git clone https://github.com/videosdk-live/videosdk-custom-recording-template-js-example.git
```

- You can utilize this custom template in [Start Recording API](/api-reference/realtime-communication/start-recording), [Start HLS API](/api-reference/realtime-communication/start-hlsStream) and [Start Livestream API](/api-reference/realtime-communication/start-livestream). Here is the example of HLS.
- To utilize the custom template that has been deployed, invoke the [Start HLS API](https://docs.videosdk.live/api-reference/realtime-communication/start-hlsStream) instead of the `startHls` method from the `Meeting` class. The necessary code has already been incorporated in the cloned example above.

:::important

You can create your own custom template manager in JavaScript. In this example, we are using one for better understanding.

:::

```js
<button
  onClick={async () => {
    const url = `https://api.videosdk.live/v2/hls/start`;
    //Update your Custom Template URL here if you have deployed your own, if not deployed you can use this template from our URL.
    //highlight-next-line
    const templateUrl = `https://lab.videosdk.live/js-template-demo/?meetingId=${meetingId}&token=${authToken}`;
    const options = {
      method: "POST",
      headers: {
        Authorization: authToken,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        roomId: meetingId,
        templateUrl: templateUrl,
      }),
    };

    const result = await fetch(url, options)
      .then((response) => response.json()) // result will have playbackHlsUrl and livestreamUrl
      .catch((error) => console.error("error", error));
  }}
>
  Start HLS
</button>
```

- In this example, the host has two options on their side, enabling them to change the background and send messages to the viewers.

- Given below is a test run of the example.


<div style={{textAlign: 'center'}}>



</div>

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)
- [Start HLS API](/api-reference/realtime-communication/start-hlsStream)
- [Start Livestream API](/api-reference/realtime-communication/start-livestream)
- [recordingState](/react/api/sdk-reference/use-meeting/properties#recordingstate)
- [hlsState](/react/api/sdk-reference/use-meeting/properties#hlsstate)
- [livestreamState](/react/api/sdk-reference/use-meeting/properties#livestreamstate)
- [hlsUrls](/react/api/sdk-reference/use-meeting/properties#hlsurls)
- [onRecordingStateChanged](/react/api/sdk-reference/use-meeting/events#onrecordingstatechanged)
- [onHlsStateChanged](/react/api/sdk-reference/use-meeting/events#onhlsstatechanged)
- [onLivestreamStateChanged](/react/api/sdk-reference/use-meeting/events#onlivestreamstatechanged)



---

You have the option to create presigned URL, allowing you to upload your recordings to AWS, Azure, or GCP securely.
presigned URL provide a secure and temporary way to upload objects to your cloud storage. Instead of sharing your entire credentials, you can create a special URL that allows uploading a specific file for a limited time.

:::important

While presigned URL offer a convenient way to upload files securely, each cloud provider (AWS, Azure, and GCP) might have different restrictions on how they work. It's advisable to refer the respective documentation for **[<u>AWS</u>](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)**, **[<u>Azure</u>](https://learn.microsoft.com/en-us/rest/api/storageservices/delegate-access-with-shared-access-signature)**, and **[<u>GCP</u>](https://cloud.google.com/cdn/docs/using-signed-urls)** to gain a clearer understanding of presigned URL.

:::

### Code Sample

This guide will walk you through the process of generating a presigned URL for uploading recordings to your cloud storage of choice. You can use this generated presigned URL in [Start Recording API](/api-reference/realtime-communication/start-recording#preSignedUrl).



**AWS:**

```js
const { S3Client, PutObjectCommand } = require("@aws-sdk/client-s3");
const { getSignedUrl } = require("@aws-sdk/s3-request-presigner");

const region = <YOUR S3 REGION>;
const bucket = <YOUR S3 BUCKET NAME>;
const key = <YOUR FILE NAME>; // test/abc.mp4
const accessKeyId = <YOUR S3 ACCESS KEY ID>;
const secretAccessKey = <YOUR S3 SECRET ACCESS KEY>;
const expiresIn = <URL EXPIRY IN SECONDS>; // this number should be higher than duraion of recording

const s3Client = new S3Client({
credentials: {
    accessKeyId: accessKeyId,
    secretAccessKey: secretAccessKey,
},
region: region,
});

const createPresignedUrlWithClient = async () => {
const command = new PutObjectCommand({ Bucket: bucket, Key: key });
const preSignedUrl = await getSignedUrl(s3Client, command, { expiresIn: expiresIn });
return preSignedUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await createPresignedUrlWithClient();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

---

**AZURE:**

```js
const { BlobServiceClient, BlobSASPermissions } = require("@azure/storage-blob");

const connectionString = <YOUR AZURE STORAGE CONNECTION STRING>;
const containerName = <YOUR AZURE CONTAINER NAME>;
const blobName = <YOUR AZURE BLOB NAME>;
const startsOn = <YOUR SASURL START TIME>; // (optional, defaults to now)
const expiresOn = <YOUR SASURL EXPIRY TIME>; // expiry time should be higher than duration of recording

const generateSASUrl = async () => {
let blobServiceClient = BlobServiceClient.fromConnectionString(connectionString);
let containerClient = blobServiceClient.getContainerClient(containerName);

await containerClient.createIfNotExists({
    access: "container",
});

const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const sasUrl = await blockBlobClient.generateSasUrl({
    startsOn: startsOn, // sasUrl start time
    expiresOn: expiresOn, // sasUrl expiration time
    permissions: BlobSASPermissions.parse("write"),
});
return sasUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await generateSASUrl();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

---

**GCP:**

```js
const { Storage } = require("@google-cloud/storage");

const projectId = <YOUR GCP PROJECT ID>;
const clientEmail = <YOUR GCP CLIENT EMAIL>;
const privateKey = <YOUR GCP PRIVATE KEY>;
const expires =<URL EXPIRY IN SECONDS>; // this number should be higher than duraion of recording
const bucketName = <YOUR GCP BUCKET NAME>;
const fileName = <YOUR FILE NAME>; // test/abc.mp4

const storage = new Storage({
projectId: projectId,
credentials: {
    client_email: clientEmail,
    private_key: privateKey,
},
});

const generateSignedUrl = async () => {
const options = {
    version: "v4",
    action: "write",
    expires: expires,
    contentType: "video/mp4",
};

const [signedUrl] = storage.bucket(bucketName).file(fileName).getSignedUrl(options);
return signedUrl;
};

// you can use this presigned url like this
async function main() {
  let preSignedUrl = await generateSignedUrl();
  const options = {
method: "POST",
headers: {
  Authorization: "$YOUR_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  roomId: "abcd-efgh-ijkl",
  preSignedUrl: preSignedUrl
}),
  };
  const url = `https://api.videosdk.live/v2/recordings/start`;
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
}

main();

```

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Recording API](/api-reference/realtime-communication/start-recording)



---

# Start and Stop - Python

This guide will provide an overview of how to implement start and stop Meeting Recording.

### `start_recording()`

The `start_recording()` method, accessible from the `meeting` class object, is used to initiate the recording of a meeting. This method accepts the following four parameters:

- `1. webhookUrl (optional)`: This is the webhook URL where you can listen to events related to the recording, such as the start and stop of recording. It triggers when the recording is completed and stored on the server. You can learn more about webhooks [here](https://en.wikipedia.org/wiki/Webhook)

- `2. dirPath (optional)`: This parameter specifies the path to your cloud bucket where you intend to store the recordings. To enable the storage of recordings in your cloud bucket with VideoSDK, follow this guide ([VideoSDK AWS, GCP, Azure Integration](/python/guide/video-and-audio-calling/recording/recording-storage-config))

- `3. config (optional)`: This parameter defines how the recording should be conducted

- `4. transcription (optional)`: This parameter lets you start post transcription for the recording.

We will going to use [RecordingConfig Type](/python/api/sdk-reference/types#recordingconfig). to start recording in the meeting

```py
from videosdk import RecordingConfig, PostTranscriptionConfig

  # highlight-start
  meeting.start_recording(RecordingConfig(
      webhook_url= "https://example.com", # Optional
      config={

      }, # Optional
      dir_path="abcd/abcd", # Optional
      transcription=PostTranscriptionConfig(
          enabled=True
      ) # Optional
  ))
  # highlight-end
  ...
```

### `stop_recording()`

The `stop_recording()` method, accessible from the `meeting` class object, is used to stop the recording of a meeting.

#### Example

```py
  # highlight-next-line
  meeting.stop_recording()
```

:::important

To initiate automatic recording at the beginning of a `session`, simply provide the `autoStartConfig` feature `recording` during `room` creation. For more information on configuring the `autoStartConfig`, please refer to the provided documentation **[<u>here</u>](/api-reference/realtime-communication/create-room#autoStartConfig)**.

:::

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [start_recording](/python/api/sdk-reference/classes/meeting/methods#start_recording)
- [stop_recording](/python/api/sdk-reference/classes/meeting/methods#stop_recording)
- [on_recording_state_changed](/python/api/sdk-reference/classes/meeting/events#on_recording_state_changed)
- [PostTranscriptionConfig](/python/api/sdk-reference/types#posttranscriptionconfig)
- [RecordingConfig](/python/api/sdk-reference/types#recordingconfig)
- [autoStartConfig](/api-reference/realtime-communication/create-room#autoStartConfig)


---

VideoSDK offers individual participant recording, generating a single, continuous file for a participant.

This recording captures the participant's audio and video streams throughout the meeting, regardless of whether they are muted or have their camera turned off. During periods of audio muting or video disengagement, the respective tracks will be silent or display a black screen, respectively.

You can access the recorded files in the developer dashboard or opt to store them in your own cloud storage.

This guide provides an overview of the start and stop functionality for individual participant recording through APIs.


## Start Individual Participant Recording

To start a participant recording, you will have to call `/v2/recordings/participant/start` API with following body parameters.

- `roomId`: RoomId for which the participant recording is to be started
- `participantId`: participantId of the participant to be recorder.
- `fileFormat`: Currently only `webm` is supported as file format. We will add the support for other formats in future.
- `webhookUrl`: The webhook URL where you would like to get the status updates of the recording. To learn more about webhooks refer [here](#participant-track-recording-starting).
- `bucketDirPath`: If you are using your own storage, you can provide the directory path where you want to store the recording. To configure the storage please [refere this quide](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config).

The usual recording path would look like `${sessionId}/${participantId}/${filename}`.

```python
import requests
import json

room_id = "<YOUR ROOM ID>"
participant_id = "<PARTICIPANT ID>"
file_format = "<YOUR FILE FORMAT>"  # (Optional) default: webm
bucket_dir_path = "<YOUR CLOUD STORAGE BUCKET PATH>"  # (Optional) test/abc
webhook_url = "<YOUR WEBHOOK URL>"  # (Optional)

def start_participant_recording():
    url = "https://api.videosdk.live/v2/recordings/participant/start"
    headers = {
        "Authorization": "$YOUR_TOKEN",
        "Content-Type": "application/json",
    }
    payload = {
        "roomId": room_id,
        "participantId": participant_id,
        "fileFormat": file_format,
        "bucketDirPath": bucket_dir_path,
        "webhookUrl": webhook_url,
    }

    response = requests.post(url, headers=headers, data=json.dumps(payload))
    data = response.json()
    print(data)

start_participant_recording()

```

## Stop Individual Participant Recording

To stop a participant recording, you will have to call `/v2/recordings/participant/stop` API with following body parameters.

- `roomId`: RoomId for which the participant recording is to be stopped
- `participantId`: participantId for which the recording is to be stopped.

```python
import requests
import json

room_id = "<YOUR ROOM ID>"
participant_id = "<PARTICIPANT ID>"

def stop_participant_recording():
    url = "https://api.videosdk.live/v2/recordings/participant/stop"
    headers = {
        "Authorization": "$YOUR_TOKEN",
        "Content-Type": "application/json"
    }
    payload = {
        "roomId": room_id,
        "participantId": participant_id
    }

    response = requests.post(url, headers=headers, data=json.dumps(payload))
    data = response.json()
    print(data)

stop_participant_recording()

```

## Webhook associated with Participant Recording

### participant-recording-starting

- A "Participant Recording Starting" webhook is triggered when the participant recording process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-started

- Participant Recording started webhook will be received when successfully participant recording is started in meeting

###### Example

```javascript
{
    "webhookType": "participant-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopping

- A "Participant Recording Stopping" webhook is triggered when the participant recording end process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileFormat": "webm",
    },
}
```

---

### participant-recording-stopped

- Participant Recording stopped webhook will be received when participant recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "participant-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-recording-failed

- A "Participant Recording Failed" webhook is generated when the participant recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "participant-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
    },
}
```

---

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Participant Recording API](/api-reference/realtime-communication/start-participant-recording)
- [Stop Participant Recording API](/api-reference/realtime-communication/stop-participant-recording)



---

VideoSDK provides participant track recording, creating separate audio or video files for participant.

New files are generated when a participant starts their audio or video again after turning it off (e.g., unmuting the microphone or restarting the camera). This ensures that each file represents a continuous segment of audio or video content.

Once track recording is complete, all audio files for a participant are consolidated into a single directory, as are the video files.


## Start Participant Track Recording

To start a participant track recording, you will have to call `/v2/recordings/participant/track/start` API with following body parameters.

- `roomId`: RoomId for which the participant track recording is to be started
- `participantId`: participantId of the participant to be recorder.
- `kind`: The kind of tracks you want to record.
  - You can pass following values: _`audio`_ | _`video`_ | _`screen_audio`_ | _`screen_video`_
- `fileFormat`: Currently only `webm` is supported as file format. We will add the support for other formats in future.
- `webhookUrl`: The webhook URL where you would like to get the status updates of the recording. To learn more about webhooks refer [here](#participant-track-recording-starting).
- `bucketDirPath`: If you are using your own storage, you can provide the directory path where you want to store the recording. To configure the storage please [refere this quide](/javascript/guide/video-and-audio-calling-api-sdk/recording/recording-storage-config).

The usual recording path would look like `${sessionId}/${participantId}/${kind}/${filename}`.

```python
import requests

def start_track_recording():
    roomId = "<YOUR ROOM ID>"
    participantId = "<PARTICIPANT ID>"
    kind = "<YOUR STREAM KIND>"
    fileFormat = "<YOUR FILE FORMAT>"
    bucketDirPath = "<YOUR CLOUD STORAGE BUCKET PATH>"
    webhookUrl = "<YOUR WEBHOOK URL>"

    url = "https://api.videosdk.live/v2/recordings/participant/track/start"
    headers = {
        "Authorization": "$YOUR_TOKEN",
        "Content-Type": "application/json",
    }
    body = {
        "roomId": roomId,
        "participantId": participantId,
        "kind": kind,
        "fileFormat": fileFormat,
        "bucketDirPath": bucketDirPath,
        "webhookUrl": webhookUrl,
    }

    response = requests.post(url, json=body, headers=headers)
    print(response.json())

# Example usage
start_track_recording()

```

## Stop Participant Track Recording

To stop a participant track recording, you will have to call `/v2/recordings/participant/track/stop` API with following body parameters.

- `roomId`: RoomId for which the participant track recording is to be stopped
- `participantId`: participantId for which the recording is to be stopped.
- `kind`: The kind of track recording you want to stop for the given participant.
  - You can pass following values: _`audio`_ | _`video`_ | _`screen_audio`_ | _`screen_video`_

```python
import requests

def stop_track_recording():
    roomId = "<YOUR ROOM ID>"
    participantId = "<PARTICIPANT ID>"
    kind = "<YOUR STREAM KIND>"

    url = "https://api.videosdk.live/v2/recordings/participant/track/stop"
    headers = {
        "Authorization": "$YOUR_TOKEN",
        "Content-Type": "application/json",
    }
    body = {
        "roomId": roomId,
        "participantId": participantId,
        "kind": kind,
    }

    response = requests.post(url, json=body, headers=headers)
    print(response.json())

# Example usage
stop_track_recording()

```

## Webhook associated with Participant Track Recording

### participant-track-recording-starting

- A "Participant Track Recording Starting" webhook is triggered when the track recording process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-started

- Participant Track Recording started webhook will be received when successfully track recording is started in meeting

###### Example

```javascript
{
    "webhookType": "participant-track-recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopping

- A "Participant Track Recording Stopping" webhook is triggered when the track recording end process for a participant is initiated.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

### participant-track-recording-stopped

- Participant Track Recording stopped webhook will be received when track recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
        "fileDetails" : [
            {
                "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
                "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",
            }
        ]
    },
}
```

---

### participant-track-recording-failed

- A "Participant Track Recording Failed" webhook is generated when the track recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "participant-track-recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "participantId": "abcd",
        "kind": "audio",
    },
}
```

---

## API Reference

The API references for all the methods utilized in this guide are provided below.

- [Start Track Recording API](/api-reference/realtime-communication/start-track-recording)
- [Stop Track Recording API](/api-reference/realtime-communication/stop-track-recording)



---

### Storage Configuration

While recording your meetings, you have the flexibility to store them either on VideoSDK's storage or configure your own storage solution such as **`AWS S3 Storage, Azure Blob or GCP Cloud Storage`**. To set up your own storage, you can navigate to the [API section](https://app.videosdk.live/api-keys) in the VideoSDK Dashboard.

- This feature allows you to configure storage provider for your meeting recordings.

- You can configure multiple storage provider with multiple API Keys.

- Currently, we support `AWS S3`, `Azure Blob` and `GCP Cloud Storage`. We will add support for other storage provider soon !!

## Prerequisites

- An active [VideoSDK Developer Account](https://app.videosdk.live)
- `Aws S3`, `Azure Blob Storage` or `GCP Cloud Storage` Credentials

## How to setup ?

### Step 1 : Select Api Key

<div style={{textAlign: 'center'}}>

![Dashboard](/img/tutorial/dashboard/api-key-dashboard.png)

</div>

- Go to [VideoSDK Dashboard](https://app.videosdk.live/api-keys).
- Select API Key for which, you want to set storage configuration.
- Then click on `Storage Config` Icon in Actions.

### Step 2 : Choose Cloud Storage Provider

![Dashboard](/img/tutorial/dashboard/storage-config.png)

- As you can see in the image, there are 3 Cloud Storage Provider (`Aws`, `Azure`, `GCP`).
- You can select a Cloud Storage Provider as per your requirements.

### Step 3 : Configure Bucket or Container

<h4> For Aws S3 Storage </h4>

![Aws S3](/img/tutorial/dashboard/s3.png)

- You will need AWS S3 Bucket. [Learn to create S3 Bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html).

- As you can see in the image, you will need enter `accessKeyId`, `secretAccessKey`, `region`, `bucket`, and `ACL` to setup for Aws S3 Storage.

- Click on `Save` button.

<hr />

<h4> For Azure Blob Storage: </h4>

![Azure Blob](/img/tutorial/dashboard/blob.png)

- You will need Azure Blob Container. [Learn to create Blob Container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal#create-a-container).

- As you can see in the image, you will need to enter `connectionString` and `containerName` to setup for Azure Blob.

- Click on `Save` button.

<hr />

<h4> For Google Cloud Storage: </h4>

<img src="/img/tutorial/dashboard/gcp.png" alt="GCP Cloud Storage" width="436" height="632"/>

1. You will need Google Cloud Storage Bucket. [Learn to create Google Cloud Storage Bucket](https://cloud.google.com/storage/docs/creating-buckets).

2. After creation, click on the <b> &#xFE19; </b>button in the upper right corner and select **`Project settings`**.

3. Under **`IAM and Admin`**, select **`Service Accounts`**. In the service account list, click on the <b> &#xFE19; </b> button for the account just added or created before, and select **`Manage keys`**.

4. Click **`ADD KEY > Create new key`**. Select **`JSON`** in the pop-up box and click **`CREATE`**. A json file is downloaded with the name format `projectId-xxxxxxxx.json`.

5. Open the downloaded json file, which looks like the following example:

```
{
  "type": "service_account",
  "project_id": "videosdk-12345",
  "private_key_id": "yourprivateidkeyyourprivateidkeyyourprivateidkey",
  "private_key": "-----BEGIN PRIVATE KEY-----\nThisisYourPrivateKeyThisisYourPrivateKeyThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\n-----END PRIVATE KEY-----\n",
  "client_email": "xxxx-xxxx@videosdk-12345.iam.gserviceaccount.com",
  "client_id": "123456789012345678901",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/videosdk%40videosdk-404307.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}
```

- As you can see in the image, you will need to enter `Project Id`, `Client Email`, `Bucket`, `Private Key` to setup for Google Cloud Storage Bucket. You can retrieve these details from the json file.

- Click on `Save` button.

### Step 4 : Test

- It's time to test !!
- [Create Room](https://docs.videosdk.live/api-reference/realtime-communication/create-room) with token generated with the API Key, you have configured for.
- Start meeting with the roomId created and Start Recording !!
- Then, you can see that recording will be available in your Bucket or Container.

:::note

- Only a single Recording Storage Config can be possible for a particular Api Key at a time.
- In order to add new Recording Configuration, first you need to delete current configuration.

:::


---

# Webhooks and Events - Python

### Event associated with Recording

- **on_recording_state_changed** - The `on_recording_state_changed()` event is triggered whenever the state of meeting recording changes.

```py
from videosdk import MeetingEventHandler
class MyMeetingEventHandler(MeetingEventHandler):
  def __init__(self):
      super().__init__()

  def on_recording_state_changed(self, data):
      print("recording state changed", data)

  def on_recording_started(self, data):
      print("recording started", data)

  def on_recording_stopped(self, data):
      print("recording stopped", data)
```

:::important

You can access your recordings on our **[<u>Dashboard</u>](https://app.videosdk.live/meetings/recordings)**. Additionally, you can access your recordings using our **[<u>Recording API</u>](/api-reference/realtime-communication/fetch-recordings)**.

You can access your post transcriptions using our **[<u>Post Transcription API</u>](/api-reference/realtime-communication/fetch-post-transcriptions-summary)**

:::

## Webhook associated with Recording

### recording-starting

- A "Recording Starting" webhook is triggered when the recording process for a meeting is initiated.

###### Example

```javascript
{
    "webhookType": "recording-starting",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-started

- Recording started webhook will be received when successfully recording is started in meeting

###### Example

```javascript
{
    "webhookType": "recording-started",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopping

- A "Recording Stopping" webhook is triggered when the recording end process for a meeting is initiated.

###### Example

```javascript
{
    "webhookType": "recording-stopping",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```

---

### recording-stopped

- Recording stopped webhook will be received when recording is successfully stopped in meeting.

###### Example

```javascript
{
    "webhookType": "recording-stopped",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
        "filePath" : "/encoded/videos/62d148951a1eb20029fc9b05.mp4",
        "fileUrl" : "https://cdn.videosdk.live/encoded/videos/62d148951a1eb20029fc9b05.mp4",

    },
}
```

---

### recording-failed

- A "Recording Failed" webhook is generated when the recording process encounters an interruption or issue during either the starting or stopping phases.

###### Example

```javascript
{
    "webhookType": "recording-failed",
    "data": {
        "meetingId": "jvsg-8rjn-j304",
        "sessionId": "613731342f27f56e4fc4b6d0",
    },
}
```


---

SIP Connect allows you to connect any SIP-compatible device or softphone to a VideoSDK room. This guide explains how to configure SIP for your VideoSDK account and connect a SIP user to an existing meeting.

## Architecture

The following diagram illustrates how SIP Connect works. A SIP user connects to the VideoSDK SIP Gateway, which then bridges the call to the VideoSDK Room.

![VideoSDK Telephony Workflow](https://strapi.videosdk.live/uploads/SIP_CONNECT_c81702f580.png)

## Steps

In this guide, we are using Twilio as the SIP provider, but you can choose from other providers like Plivo, Exotel, Telnyx, Ozontel, etc. The configuration process is similar across most providers.

### 1. Create VideoSDK Meeting


:::note
Ensure you have a VideoSDK meeting setup. If you don't have one, follow the <a href={props.quickStartLink}>Quick Start Guide</a> to create a basic video calling app.
:::

You can connect a SIP user to any active VideoSDK meeting. If you already have a meeting ID, you can proceed to the next step.



### 2. Create Inbound Gateway


An **Inbound Gateway** is required to receive calls from a SIP provider (like Twilio, Vonage, Telnyx) and route them to VideoSDK.

**twilio:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/inbound-gateways).
2. Navigate to **Telephony > Inbound Gateways**.
3. Click **Add Inbound Gateway**.
4. Enter a name and the phone number you purchased from your SIP provider.
5. Select the Geo Region option and choose where inbound SIP traffic should be routed (currently supported: India, US).
6. Click **Create**.
7. Copy the **Inbound Gateway SIP URI**
- Default: `sip:orgId.sip.videosdk.live`
- Regional (to restrict calls to a specific region): `sip:orgId.<region>.sip.videosdk.live`
8. Configure this URI as the **Origination SIP URI** in your SIP provider's dashboard (e.g., Twilio, Vonage, Telnyx).

<div style={{textAlign: 'center'}}>
  
</div>

---

**vonage:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/inbound-gateways).
2. Navigate to **Telephony > Inbound Gateways**.
3. Click **Add Inbound Gateway**.
4. Enter a name and the phone number you purchased from Vonage.
5. Select the Geo Region option and choose where inbound SIP traffic should be routed (currently supported: India, US).
6. Click **Create**.
7. Copy the **Inbound Gateway SIP URI**
- Default: `sip:orgId.sip.videosdk.live`
- Regional (to restrict calls to a specific region): `sip:orgId.<region>.sip.videosdk.live`
8. In your **Vonage Console**, go to your SIP Trunk settings.
9. Under **Inbound Calls**, select your region.
10. In the **URI** section, paste the Inbound Gateway SIP URI you copied.
11. Link the phone number you purchased to this trunk.

<div style={{textAlign: 'center'}}>
  
</div>

---

**telnyx:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/inbound-gateways).
2. Navigate to **Telephony > Inbound Gateways**.
3. Click **Add Inbound Gateway**.
4. Enter a name and the phone number you purchased from Telnyx.
5. Select the Geo Region option and choose where inbound SIP traffic should be routed (currently supported: India, US).
6. Click **Create**.
7. Copy the **Inbound Gateway SIP URI**
- Default: `sip:orgId.sip.videosdk.live`
- Regional (to restrict calls to a specific region): `sip:orgId.<region>.sip.videosdk.live`
8. In your **Telnyx Console**, go to **Connections** and create a new SIP Connection.
9. Set the type as **FQDN**.
10. Under **FQDN**, add the VideoSDK Inbound Gateway SIP URI you copied.
11. Assign the phone number you purchased to this connection.

<div style={{textAlign: 'center'}}>
  
</div>

---

**api:**

You can create an inbound gateway programmatically using the API.

```bash title="cURL"
curl --request POST \
  --url https://api.videosdk.live/v2/sip/inbound-gateways \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
"name": "My Inbound Gateway",
"numbers": ["+1234567890"]
  }'
```

> **API Reference**: [Create Inbound Gateway](/api-reference/realtime-communication/sip/inbound-gateway/create-inbound-gateway)



### 3. Create Outbound Gateway


An **Outbound Gateway** is used if you want to dial out to a SIP user from a VideoSDK meeting.

**twilio:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/outbound-gateways).
2. Navigate to **Telephony > Outbound Gateways**.
3. Click **Add Outbound Gateway**.
4. Enter a name.
5. Enter the **Termination SIP URI** provided by your SIP provider.
6. Enter the **Username** and **Password** for your SIP provider.
7. Set the Geo Region to route outbound calls through a specific region (currently supported: India, US).
8. Click **Create**.

<div style={{textAlign: 'center'}}>
  
</div>

---

**vonage:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/outbound-gateways).
2. Navigate to **Telephony > Outbound Gateways**.
3. Click **Add Outbound Gateway**.
4. Enter a name.
5. Enter the **Domain** you set up in your Vonage SIP Trunk settings.
6. Enter the **Username** and **Password** you configured in Vonage under **Outbound Calls**.
7. Set the Geo Region to route outbound calls through a specific region (currently supported: India, US).
8. Click **Create**.
9. **Note:** For outbound gateway numbers, do not use the `+` sign—just use the country code and number.

<div style={{textAlign: 'center'}}>
  
</div>

---

**telnyx:**

1. Go to the [VideoSDK Dashboard](https://app.videosdk.live/telephony/outbound-gateways).
2. Navigate to **Telephony > Outbound Gateways**.
3. Click **Add Outbound Gateway**.
4. Enter a name.
5. Enter the **SIP Domain** you configured in your Telnyx SIP Connection.
6. Enter the **Username** and **Password** you set up in Telnyx under **Outbound Authentication**.
7. Set the Geo Region to route outbound calls through a specific region (currently supported: India, US).
8. Click **Create**.

<div style={{textAlign: 'center'}}>
  
</div>

---

**api:**

To route outbound calls through a specific region, set the `geoRegion` property in the API request. By default, the SIP server region is automatically selected based on the location nearest to the dialed number (currently supported: India, US).

```bash title="cURL"
curl --request POST \
  --url https://api.videosdk.live/v2/sip/outbound-gateways \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
"name": "My Outbound Gateway",
"numbers": ["+1234567890"],
"address": "sip.provider.com",
"geoRegion" : "us002",
"auth": {
  "username": "sip_username",
  "password": "sip_password"
}
  }'
```

> **API Reference**: [Create Outbound Gateway](/api-reference/realtime-communication/sip/outbound-gateway/create-outbound-gateway)



### 4. Create Routing Rules


Routing rules determine how calls are handled.

#### Inbound Routing
For inbound calls, you need to route the call to a specific meeting room.

1. Go to **Telephony > Routing Rules**.
2. Click **Add Routing Rule**.
3. Select your **Inbound Gateway**.
4. Select the **Phone Number**.
5. Under **Dispatch**, select **Room**.
6. Choose **Dynamic** (creates a new room) or **Static** (connects to a specific room ID).
7. Click **Create**.

#### Outbound Routing
For outbound calls, the routing rule selects which Outbound Gateway to use based on the dialed number.

1. Go to **Telephony > Routing Rules**.
2. Click **Add Routing Rule**.
3. Select your **Outbound Gateway**.
4. Enter the **Phone Number** pattern (e.g., `+1*`).
5. Click **Create**.

<div style={{textAlign: 'center'}}>
  
</div>



## Connect SIP User

### Inbound Call
Now that everything is configured, a SIP user can join the meeting by simply dialing the phone number configured in the Inbound Gateway.
1. The call reaches your SIP provider.
2. The provider forwards it to VideoSDK.
3. VideoSDK checks the Routing Rule.
4. The user is connected to the VideoSDK Room.

### Outbound Call
To dial a SIP user from the meeting, you can use the `dispatch` API or the SDK method if available.

```bash title="cURL"
curl --request POST \
  --url https://api.videosdk.live/v2/sip/call \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "gatewayId": "outbound-gateway-id",
    "sipCallTo": "+1234567890",
    "destinationRoomId": "room-id"
  }'
```

> **API Reference**: [Make Outbound Call](/api-reference/realtime-communication/sip/calls/call-trigger)

## Webhooks

You can configure webhooks to receive real-time updates about SIP calls.

### Available Webhook Events
Below is the list of all supported webhook events:

| Event Name | Description |
| :--- | :--- |
| `call-started` | Triggered when a new outbound or inbound call is initiated. |
| `call-answered` | Triggered when the call is answered by the recipient. |
| `call-hangup` | Triggered when the call is completed or hung up by either party. |
| `call-transferred` | Call transferred to another destination. |
| `call-missed` | Triggered when the call is not answered or missed by the recipient. |
| `call-update` | Triggered when there is an update in the call status. |
| `call-ringing` | Triggered when the call is ringing at the destination endpoint. |
| `call-transfer-initiated` | Call transfer has been initiated. |
| `call-transfer-accepted` | Call transfer has been accepted by the target. |
| `call-transferring` | Call is being transferred to another destination. |
| `call-transfer-ringing` | Call is ringing at the transfer target. |
| `call-transfer-failed` | Call transfer failed. |

You can configure these in the **Telephony > Webhooks** section of the dashboard.

## Configuring Webhooks

You can set up webhooks using:

- **Dashboard:** Navigate to the SIP section and add a webhook by specifying your target URL and selecting the events you want to subscribe to.
- **API:** Use the `POST /v2/sip/webhooks` endpoint to register a webhook.



## API Reference

- [Create Webhook API](/api-reference/realtime-communication/sip/webhook/create-webhook)
- [Fetch all Webhook API](/api-reference/realtime-communication/sip/webhook/fetch-all-webhooks)
- [Fetch a Webhook API](/api-reference/realtime-communication/sip/webhook/fetch-webhook)
- [Update Webhook API](/api-reference/realtime-communication/sip/webhook/update-webhook)
- [Delete Webhook API](/api-reference/realtime-communication/sip/webhook/delete-webhook)



---

# Custom Audio Track | Python

In VideoSDK, you can ingest a custom audio track from a file into your meeting using a `CustomAudioTrack`.

This example demonstrates how to create a custom audio track from `MP4 file` and integrate it into a VideoSDK meeting.

<div style={{textAlign: 'center'}}>

<img
src="https://cdn.videosdk.live/website-resources/docs-resources/python_stream_source.png"
alt="notification"
width="100%"
/>

</div>
## Setup

Before running the example, ensure you have set up your environment variables for VideoSDK authentication:

```python
VIDEOSDK_TOKEN = "<VIDEOSDK_TOKEN>"
MEETING_ID = "<MEETING_ID>"
NAME = "<NAME>"
```

## Custom Audio Track Class

The `AudioFileTrack` class extends `CustomAudioTrack` to handle audio stream ingestion from an MP4 file:

```python
import time
import fractions
import asyncio
from av import AudioFrame, open, AudioResampler
from vsaiortc.mediastreams import MediaStreamError
from videosdk import CustomAudioTrack, MeetingConfig, VideoSDK, Participant, MeetingEventHandler, ParticipantEventHandler

VIDEOSDK_TOKEN = "VIDEOSDK_TOKEN"
MEETING_ID = "MEETING_ID"
NAME = "NAME"
loop = asyncio.get_event_loop()

class AudioFileTrack(CustomAudioTrack):
    def __init__(self, file_path: str):
        super().__init__()
        self.file_path = file_path
        self.container = open(file_path)
        self.stream = self.container.streams.audio[0]
        self.decoder = self.container.decode(self.stream)
        self._start = None
        self._timestamp = 0
        self.resampler = AudioResampler(format='s16', layout='mono', rate=90000)
        self.frame_buffer = []

    async def recv(self) -> AudioFrame:
        """
        Receive the next :class:`~av.audio.frame.AudioFrame` from the MP4 file.
        """
        # implementing in next step
```

### `AudioFileTrack.recv()`

#### Purpose:

The `recv` method in `AudioFileTrack` class is responsible for retrieving the next audio frame from the source(file, url, Buffer or any).

#### Key Components:

- **Frame Buffering**: Frames are read from the file and stored in `self.frame_buffer` after resampling them to match the desired audio format (`'s16'` format, mono channel, specified sample rate).
- **Timestamp Synchronization**: It ensures that audio frames are delivered at the correct timestamps to maintain audio-video synchronization.
- **Asynchronous Waiting**: Uses `asyncio.sleep()` to synchronize the frame delivery based on calculated wait time (`wait`).

#### Code Snippet:

```python
    async def recv(self) -> AudioFrame:
        """
        Receive the next :class:~av.audio.frame.AudioFrame from the MP4 file.
        """
        if self.readyState != "live":
            raise MediaStreamError

        if self._start is None:
            self._start = time.time()

        # Frame Buffering
        if not self.frame_buffer:
            try:
                frame = next(self.decoder)
                frames = self.resampler.resample(frame)
                self.frame_buffer.extend(frames)
            except StopIteration:
                raise MediaStreamError("End of stream")

        frame = self.frame_buffer.pop(0)

        # Ensure the audio frame has the correct format
        # Calculate the wait time to synchronize playback
        sample_rate = 90000
        self._timestamp += frame.samples
        wait = self._start + (self._timestamp / sample_rate) - time.time()
        if wait > 0:
            await asyncio.sleep(wait)

        frame.pts = self._timestamp
        frame.time_base = fractions.Fraction(1, sample_rate)

        return frame
```

## Event Handlers

Define custom event handlers to handle meeting and participant events:

```python
class MyMeetingEventHandler(MeetingEventHandler):
    def on_meeting_joined(self, data):
        print("Meeting joined")

    def on_meeting_left(self, data):
        print("Meeting left")


class MyParticipantEventHandler(ParticipantEventHandler):
    def __init__(self, participant_id: str):
        super().__init__()
        self.participant_id = participant_id

    def on_stream_enabled(self, stream):
        print(f"Participant {self.participant_id} stream enabled: {stream.kind}")

    def on_stream_disabled(self, stream):
        print(f"Participant {self.participant_id} stream disabled: {stream.kind}")
```

- You can learn more about [MeetinEventHandler](/python/guide/video-and-audio-calling/events/meeting-events) & [ParticipantEventHandler](/python/guide/video-and-audio-calling/events/participant-events) class in upcoming guide.

## Main Function

Configure and run the main function to initialize the meeting with the custom audio track:

```python
def main():
    # Initialize custom audio track
    audio_track = AudioFileTrack("./example-video.mp4")

    # Configure meeting
    meeting_config = MeetingConfig(
        meeting_id=MEETING_ID,
        name=NAME,
        mic_enabled=True,
        webcam_enabled=False,
        token=VIDEOSDK_TOKEN,
        # highlight-next-line
        custom_microphone_audio_track=audio_track
    )

    # Initialize VideoSDK meeting
    meeting = VideoSDK.init_meeting(**meeting_config)

    # Add event listeners
    meeting.add_event_listener(MyMeetingEventHandler())
    meeting.local_participant.add_event_listener(MyParticipantEventHandler(participant_id=meeting.local_participant.id))

    # Join the meeting
    print("Joining the meeting...")
    meeting.join()

    print("Meeting setup complete")

if __name__ == '__main__':
    main()
    loop.run_forever()
```

:::tip

Stuck anywhere? Check out this [example code](https://github.com/videosdk-live/videosdk-rtc-python-sdk-example/tree/main/custom-track) on GitHub

:::

#### Conclusion

This setup demonstrates how to integrate a custom audio track from file into a VideoSDK meeting, with event handling for meeting and participant interactions.

## API Reference

Refer to the following API documentation for methods and events used in this guide:

- [Custom Tracks](/python/api/sdk-reference/classes/stream/track)
- [on_stream_enabled()](/python/api/sdk-reference/classes/participant/events#on_stream_enabled)
- [on_stream_disabled()](/python/api/sdk-reference/classes/participant/events#on_stream_disabled)


---

# Custom Video Track | Python

In VideoSDK, you can ingest a custom video track from a file into your meeting using a `CustomVideoTrack`.

This example demonstrates how to create a custom video track from `MP4 file` and integrate it into a VideoSDK meeting.

<div style={{textAlign: 'center'}}>

<img
src="https://cdn.videosdk.live/website-resources/docs-resources/python_stream_source.png"
alt="notification"
width="100%"
/>

</div>
## Requirements

- Python 3.11+
- videosdk Python library
- `av` library for handling video frames
- `asyncio` for asynchronous operations

## Setup

Before running the example, ensure you have set up your environment variables for VideoSDK authentication:

```python
VIDEOSDK_TOKEN = "<VIDEOSDK_TOKEN>"
MEETING_ID = "<MEETING_ID>"
NAME = "<NAME>"
```

## Custom Video Track Class

The `VideoFileTrack` class extends `CustomVideoTrack` to handle video stream ingestion from an MP4 file:

```python
import av
import time
import fractions
import asyncio
from av import VideoFrame
from vsaiortc.mediastreams import MediaStreamError
from videosdk import CustomVideoTrack, MeetingConfig, VideoSDK, Participant, MeetingEventHandler, ParticipantEventHandler

VIDEOSDK_TOKEN = "VIDEOSDK_TOKEN"
MEETING_ID = "MEETING_ID"
NAME = "NAME"
loop = asyncio.get_event_loop()

class VideoFileTrack(CustomVideoTrack):
    """
    A video track that plays a video file in a continuous loop.
    """

    def __init__(self, path: str):
        super().__init__()  # Initialize the parent class
        self.kind = "video"
        self.path = path
        self.container = av.open(path)
        self.stream = self.container.streams.video[0]
        self._start = time.time()
        self._timestamp = 0

    async def recv(self) -> VideoFrame:
        """
        Receive the next :class:`~av.video.frame.VideoFrame`.
        """
        # implementing in next step
```

### `VideoFileTrack.recv()`

#### Purpose:

The `recv` method in `VideoFileTrack` class retrieves the next video frame from the source(file, Url, Buffer, or any).

#### Key Components:

- **Timestamp Management**: Manages the delivery of video frames based on calculated timestamps (`pts`) and time base (`time_base`).
- **Packet Decoding**: Iterates through packets and decodes video frames until a valid frame is obtained.
- **Error Handling**: Handles end-of-stream by seeking back to the beginning of the file (`self.container.seek(0)`) to loop the video.

#### Code Snippet:

```python
    async def recv(self) -> VideoFrame:
        """
        Receive the next :class:`~av.video.frame.VideoFrame`.
        """

        # Timestamp Management
        pts, time_base = await self.next_timestamp()

        # Packet Decoding & Error Handling
        # Read next frame from the video file
        frame = None
        for packet in self.container.demux(self.stream):
            try:
                for video_frame in packet.decode():
                    frame = video_frame
                    break
                if frame:
                    break
            except EOFError:
                self.container.seek(0)
            finally:
                pass

        frame.pts = pts
        frame.time_base = time_base
        return frame

    async def next_timestamp(self) -> Tuple[int, fractions.Fraction]:
        VIDEO_PTIME = 1 / 30  # Packet time for 30fps
        VIDEO_CLOCK_RATE = 90000  # Clock rate for video
        VIDEO_TIME_BASE = fractions.Fraction(1, VIDEO_CLOCK_RATE)

        if self.readyState != "live":
            raise MediaStreamError

        if hasattr(self, "_timestamp"):
            self._timestamp += int(VIDEO_PTIME * VIDEO_CLOCK_RATE)
            wait = self._start + (self._timestamp /
                                  VIDEO_CLOCK_RATE) - time.time()
            await asyncio.sleep(max(0, wait))
        else:
            self._start = time.time()
            self._timestamp = 0
        return self._timestamp, VIDEO_TIME_BASE
```

## Event Handlers

Define custom event handlers to handle meeting and participant events:

```python
class MyMeetingEventHandler(MeetingEventHandler):
    def on_meeting_joined(self, data):
        print("Meeting joined")

    def on_meeting_left(self, data):
        print("Meeting left")

class MyParticipantEventHandler(ParticipantEventHandler):
    def __init__(self, participant_id: str):
        super().__init__()
        self.participant_id = participant_id

    def on_stream_enabled(self, stream):
        print(f"Participant {self.participant_id} stream enabled: {stream.kind}")

    def on_stream_disabled(self, stream):
        print(f"Participant {self.participant_id} stream disabled: {stream.kind}")
```

- You can learn more about [MeetingEventHandler](/python/guide/video-and-audio-calling/events/meeting-events) & [ParticipantEventHandler](/python/guide/video-and-audio-calling/events/participant-events) class in upcoming guide.

## Main Function

Configure and run the main function to initialize the meeting with the custom video track:

```python
def main():
    # Initialize custom video track
    video_track = VideoFileTrack("./example-video.mp4")

    # Configure meeting
    meeting_config = MeetingConfig(
        meeting_id=MEETING_ID,
        name=NAME,
        mic_enabled=False,
        webcam_enabled=True,
        token=VIDEOSDK_TOKEN,
        # highlight-next-line
        custom_camera_video_track=video_track
    )

    # Initialize VideoSDK meeting
    meeting = VideoSDK.init_meeting(**meeting_config)

    # Add event listeners
    meeting.add_event_listener(MyMeetingEventHandler())
    meeting.local_participant.add_event_listener(MyParticipantEventHandler(participant_id=meeting.local_participant.id))

    # Join the meeting
    print("Joining the meeting...")
    meeting.join()

    print("Meeting setup complete")

if __name__ == '__main__':
    main()
    loop.run_forever()
```

#### Conclusion

This setup demonstrates how to integrate a custom video track from an MP4 file into a VideoSDK meeting, with event handling for meeting and participant interactions.

## API Reference

Refer to the following API documentation for methods and events used in this guide:

- [Custom Tracks](/python/api/sdk-reference/classes/stream/track)
- [on_stream_enabled()](/python/api/sdk-reference/classes/participant/events#on_stream_enabled)
- [on_stream_disabled()](/python/api/sdk-reference/classes/participant/events#on_stream_disabled)


---

# Stream Ingestion | Python

Stream Ingestion in VideoSDK Meeting allows capturing or processing streams from custom audio/video inputs. You can ingest streams from various custom audio/video sources such as files, HTTP streams, or buffers.

<div style={{textAlign: 'center'}}>

<img
src="https://cdn.videosdk.live/website-resources/docs-resources/python_stream_source.png"
alt="notification"
width="100%"
/>

</div>

## Understanding MediaPlayer

`MediaPlayer` is a component provided by the `vsaiortc` library for handling media streams in WebRTC applications. It enables capturing or processing streams from custom audio and video inputs, like files, HTTP streams, or buffers.

### How MediaPlayer Works

1. **Initialization**: Initialize a `MediaPlayer` instance with a source URL or file path, specifying the type of media input.
2. **Stream Handling**: The `MediaPlayer` decodes the media stream, making it accessible for further processing or transmission.
3. **Integration**: Use `MediaPlayer` to feed media streams into a VideoSDK meeting, allowing participants to view or hear the ingested content.

## Basic Stream Ingestion

```python
import asyncio
from videosdk import MeetingConfig, VideoSDK
from vsaiortc.contrib.media import MediaPlayer

VIDEOSDK_TOKEN = "

</div>

## API Reference

Refer to the following API documentation for methods and events used in this guide:

- [enable_mic()](/python/api/sdk-reference/classes/meeting/methods#enable_mic)
- [enable_webcam()](/python/api/sdk-reference/classes/meeting/methods#enable_webcam)
- [on_stream_enabled()](/python/api/sdk-reference/classes/participant/events#on_stream_enabled)
- [on_stream_disabled()](/python/api/sdk-reference/classes/participant/events#on_stream_disabled)
- [on_media_status_changed()](/python/api/sdk-reference/classes/participant/events#on_media_status_changed)


---

# Post Transcription & Summary - Python

Welcome to the developer guide for implementing a post-transcription feature using the Python SDK. This guide will walk you through the necessary steps to enable post-transcription functionality in your application, allowing users to access transcriptions of recorded meetings.

Moreover, VideoSDK offers flexibility in configuring post-time transcription, allowing you to set up webhooks for this purpose.

## Integrating Post Transcription Feature

![alt text](/img/transcription/post-transcription.png)

In the image above, the recording begins with transcription and summary features turned on. This triggers a webhook call for the start of recording. When the recording stops, another webhook is activated. After the recording, our transcriber starts transcribing, which in turn activates a webhook. Once the transcription is finished, it's sent to the summarizer for summary generation, and then another webhook is triggered.

### Step 1: Configure Post Transcription & Summary

- In this step, we set up the configuration for post transcription and summary generation. We define the webhook URL where the webhooks will be received.

```py
from videosdk import RecordingConfig, PostTranscriptionConfig, SummaryConfig

recording_config = RecordingConfig(
    webhook_url="example.com",
    transcription=PostTranscriptionConfig(
        enabled=True,
        summary=SummaryConfig(
          enabled=True,
          prompt="Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
        )
    )
  )
```

### Step 2: Start Recording with Transcription Configuration

- Once the configuration is set, we initiate the recording process for the meeting, incorporating the transcription configuration we defined earlier.

```py
  # Start Recording
  # highlight-next-line
  meeting.start_recording(recording_config)
```

### Step 3: Stop Recording

- When the meeting concludes or recording is no longer needed, we stop the recording process.

```python
  # Stop Recording
  # highlight-next-line
  meeting.stop_recording()
```

### Step 4: Fetch Post Transcriptions

- After the meeting recording is stopped, post transcription and summary data can be obtained using the [Post Transcription API](/api-reference/realtime-communication/fetch-post-transcriptions-summary).

- The API provides information such as the status of transcription, file paths for transcription data in various formats (JSON, SRT, TXT, TSV, VTT), and a summarized text file.

- The transcription document is structured as follows:

```json
{
  "id": "40b0a4ed-9842-40c9-a288-e4b1bf98a90a",
  "status": "completed",
  "roomId": "abc-xyzw-lmno",
  "sessionId": "621497578bea0d0404c35c4c",
  "recordingId": "65d303d6d2c373dfd71b38a2",
  "filePath": "https://cdn.videosdk.live/encoded/videos/dummy.mp4",
  "transcriptionFilePaths": {
    "json": "https://cdn.videosdk.live/transcriptions/dummy/dummy.json",
    "srt": "https://cdn.videosdk.live/transcriptions/dummy/dummy.srt",
    "txt": "https://cdn.videosdk.live/transcriptions/dummy/dummy.txt",
    "tsv": "https://cdn.videosdk.live/transcriptions/dummy/dummy.tsv",
    "vtt": "https://cdn.videosdk.live/transcriptions/dummy/dummy.vtt"
  },
  "summarizedFilePaths": {
    "txt": "https://cdn.videosdk.live/transcriptions/dummy/dummy-summary.txt"
  },
  "userStorage": null,
  "start": "2024-02-27T16:00:36.828Z",
  "end": "2024-02-27T16:01:46.939Z"
}
```

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [start_recording()](/python/api/sdk-reference/classes/meeting/methods#start_recording)
- [stop_recording()](/python/api/sdk-reference/classes/meeting/methods#stop_recording)
- [fetchPostTranscriptions](/api-reference/realtime-communication/fetch-post-transcriptions-summary)


---

# Realtime Transcription - Python

Realtime transcription allows you to transcribe audio content into text in real-time during a session. This guide will walk you through using the `start_transcription()` and `stop_transcription()` functions to manage realtime transcription in your server.

Moreover, VideoSDK offers flexibility in configuring real-time transcription, allowing you to set up webhooks for this purpose.

## Integrating Realtime Transcription Feature

![alt text](/img/transcription/realtime-transcription.png)

The above image represents,

1. **Start Transcription:** The SDK Client initiates real-time transcription using the `startTranscription` method.

2. **Resource Acquisition:** VideoSDK server requests necessary resources from transcription service.

   - If the request is denied, the server sends a `transcription-failed` event to the SDK Client.
   - If the request is successful, the server sends a `transcription-started` event to the client, indicating that transcription has begun.

3. **Transcription Data:** As transcription progresses, the client receives `transcription-text` event with data such as the text itself, participant ID, and timestamp.

4. **Stop Transcription:** When the client decides to stop transcription, it informs the VideoSDK server to release resources.
   - The server then sends a `transcription-stopped` event to confirm that transcription has ended and resources are released.

### Step 1: Configure Realtime Transcription

- In this step, we set up the configuration for realtime transcription. We define the webhook URL where the webhooks will be received.

```python
#  Configurations for Realtime Transcription
#  highlight-next-line
webhook_url = "https://www.example.com"
```

### Step 2: Listen for the transcription events

- Here, we configure the callback methods for transcription events.

```py
from videosdk import Meeting, MyMeetingEventHandler
  class MyMeetingEventHandler(MeetingEventHandler):
    def __init__(self):
        super().__init__()

    def on_transcription_state_changed(self, data):
        print("transcription state changed", data)

    def on_transcription_text(self, data):
        print("transcription text", data)
```

### Step 3: Start realtime transcription

- Initiate the realtime transcription using the `start_transcription()` method.

```py
  transcription_config = TranscriptionConfig(
    webhook_url = webhook_url
    summary=SummaryConfig(
      enabled=True,
      prompt="Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
    )
  )

  # highlight-next-line
  meeting.start_transcription(transcription_config)
```

### Step 4: Stop realtime transcription

- Terminate the realtime transcription using the `stop_transcription() `method.

```py
  # highlight-next-line
  meeting.stop_transcription()
```

#### Example

- The following python code snippet allows you to start and stop realtime transcription with just a second.

```python
import asyncio
from videosdk import (
    MeetingConfig,
    VideoSDK,
    MeetingEventHandler,
    SummaryConfig,
    TranscriptionConfig
)

VIDEOSDK_TOKEN = "<VIDEOSDK_TOKEN>"
MEETING_ID = "<MEETING_ID>"
NAME = "<NAME>"
loop = asyncio.get_event_loop()

class MyMeetingEventHandler(MeetingEventHandler):
    def on_transcription_state_changed(self, data):
        print(f"===== transcription state changed -> {data} =====")

    def on_transcription_text(self, data):
        print(f"===== transcription text -> {data} =====")


async def main():
  meeting = VideoSDK.init_meeting(**MeetingConfig(
      meeting_id=MEETING_ID,
      name=NAME,
      mic_enabled=True,
      webcam_enabled=True,
      token=VIDEOSDK_TOKEN,
  ))
  meeting.add_event_listener(MyMeetingEventHandler())

  meeting.join()

  await asyncio.sleep(5)
  # highlight-start
  meeting.start_transcription(TranscriptionConfig(
    summary=SummaryConfig(
      enabled=True,
      prompt="Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
    )
  ))
  # highlight-end

  await asyncio.sleep(60)
  # highlight-next-line
  meeting.stop_transcription()

if __name__ == "__main__":
  loop.run_until_complete(main())
  loop.run_forever()
```

:::important

You can access a summary of your realtime transcription using the **[<u>Fetch Realtime Transcription API</u>](/api-reference/realtime-communication/fetch-a-realtime-transcription)**.

:::

### API Reference

The API references for all the methods utilized in this guide are provided below.

- [start_transcription()](/python/api/sdk-reference/classes/meeting/methods#start_transcription)
- [stop_transcription()](/python/api/sdk-reference/classes/meeting/methods#stop_transcription)
- [on_transcription_state_changed()](/python/api/sdk-reference/classes/meeting/events#on_transcription_state_changed)
- [on_transcription_text()](/python/api/sdk-reference/classes/meeting/events#on_transcription_text)


---

## Custom Video Track - React

- You can create a Video Track using `createCameraVideoTrack()` method of `@videosdk.live/react-sdk`.
- This method can be used to create video track using different encoding parameters, camera facing mode, bitrateMode, maxLayer and optimization mode.

### Parameters

- **cameraId**:

  - type: `String`
  - required: `false`
  - It will be the id of the camera from which the video should be captured.

- **encoderConfig**:

  - type: `String`
  - required: `false`
  - default: `h720p_w1280p`
  - You can choose from the below mentioned list of values for the encoder config.

| Encoder Config | Resolution | Frame Rate | Optimized (kbps) | Balanced (kbps) | High Quality (kbps) |
| -------------- | :--------: | :--------: | :----------: | :----------: | :----------: |
| h90p_w160p | 160x90 | 15 fps | 60  | 100 | 150|
| h180p_w320p | 320x180 | 15 fps | 100 | 150 | 250 |
| h216p_w384p | 384x216 | 15 | 120 | 200 | 350 |
| h360p_w640p | 640x360 | 20 | 200 | 400 | 600 |
| h540p_w960p | 960x540 | 25 | 350 | 550 | 800 |
| h720p_w1280p | 1280x720 | 30 | 1000 | 1500 | 2000 |
| h1080p_w1920p | 1920x1080 | 30 | 1600 | 2200 | 2700 |
| h1440p_w2560p | 2560x1440 | 30 | 5000 | 5500 | 6000 |
| h2160p_w3840p | 3840x2160 | 30 | 8000 | 8500 | 9000 |
| h120p_w160p | 160x120 | 15 | 60 | 100 | 150 |
| h180p_w240p | 240x180 | 15 | 100 | 150 | 250 |
| h240p_w320p | 320x240 | 15 | 120 | 200 | 350 |
| h360p_w480p | 480x360 | 20 | 200 | 400 | 600 |
| h480p_w640p | 640×480 | 25 | 300 | 500 | 700 |
| h540p_w720p | 720×540 | 30 | 350 | 550 | 800 |
| h720p_w960p | 960×720 | 30 | 900 | 1300 | 1600 |
| h1080p_w1440p | 1440×1080 | 30 | 1600 | 2200 | 2700 |
| h1440p_w1920p | 1920×1440 | 30 | 3500 | 4000 | 4500 |

:::note

Above mentioned encoder configurations are valid for both, landscape as well as portrait mode.

:::

- **facingMode**:

  - type: `String`
  - required: `false`
  - Allowed values : `front` | `environment`
  - It will specify whether to use front or back camera for the video track.

- **optimizationMode**

  - type: `String`
  - required: `false`
  - Allowed values: `motion` | `text` | `detail`
  - It will specify the optimization mode for the video track being generated.

- **multiStream**

  - type: `boolean`
  - required: `false`
  - default: `true`
  - It will specify if the stream should send multiple resolution layers or single resolution layer.

- **bitrateMode**:

  - type: `String`
  - required: `false`
  - Allowed values : `bandwidth_optimized` | `balanced` | `high_quality`
  - Controls the video quality and bandwidth consumption. You can choose between `high_quality` for the best picture, `bandwidth_optimized` to save data, or `balanced` for a mix of both. Defaults to `balanced`.

- **maxLayer**:

  - type: `Number`
  - required: `false`
  - Allowed values : `2` | `3` 
  - default: `3`
  - Specifies the maximum number of simulcast layers to publish. This parameter only has an effect if `multiStream` is set to true.

:::info

- To learn more about optimizations and best practices for using custom video tracks, [follow this guide](/react/guide/video-and-audio-calling-api-sdk/render-media/optimize-video-track).
- This parameter is only available from `v0.1.53`.

:::

#### Returns

- `MediaStream`

### Example

```javascript

let customTrack = await createCameraVideoTrack({
  optimizationMode: "motion",
  encoderConfig: "h540p_w960p",
  facingMode: "environment",
  multiStream: true,
  bitrateMode: Constants.BitrateMode.HIGH_QUALITY,
  maxLayer: 2
});
```

## Custom Audio Track - React

- You can create a Audio Track using `createMicrophoneAudioTrack()` method of `@videosdk.live/react-sdk`.
- This method can be used to create audio track using different encoding parameters and noise cancellation configration.

### Parameters

- **microphoneId**:

  - type: `String`
  - required: `false`
  - It will be the id of the mic from which the audio should be captured.

- **encoderConfig**:

  - type: `String`
  - required: `false`
  - default: `speech_standard`
  - You can choose from the below mentioned list of values for the encoder config.

| Encoder Config      | Bitrate  | Auto Gain | Echo Cancellation | Noise Suppression |
| ------------------- | :------: | :-------: | :---------------: | :---------------: |
| speech_low_quality  | 16 kbps  |   TRUE    |       TRUE        |       TRUE        |
| speech_standard     | 24 kbps  |   TRUE    |       TRUE        |       TRUE        |
| music_standard      | 32 kbps  |   FALSE   |       FALSE       |       FALSE       |
| standard_stereo     | 64 kbps  |   FALSE   |       FALSE       |       FALSE       |
| high_quality        | 128 kbps |   FALSE   |       FALSE       |       FALSE       |
| high_quality_stereo | 192 kbps |   FALSE   |       FALSE       |       FALSE       |

- **noiseConfig**

  - **echoCancellation**

    - type: `boolean`
    - required: `false`
    - If `true` echo cancellation will turned on else it would be turned off.

  - **autoGainControl**

    - type: `boolean`
    - required: `false`
    - If `true` auto gain will turned on else it would be turned off.

  - **noiseSuppression**
    - type: `boolean`
    - required: `false`
    - If `true` noise suppression will turned on else it would be turned off.

#### Returns

- `MediaStream`

### Example

```javascript

let customTrack = await createMicrophoneAudioTrack({
  encoderConfig: "speech_standard",
  noiseConfig: {
    noiseSuppression: true,
    echoCancellation: true,
    autoGainControl: true,
  },
});
```

## Custom Screen Share Track - React

- You can create a Video Track using `createScreenShareVideoTrack()` method of `@videosdk.live/react-sdk`.
- This method can be used to create video track using different encoding parameters and optimization mode.

### Parameters

- **encoderConfig**:

  - type: `String`
  - required: `false`
  - default: `h720p_15fps`
  - You can choose from the below mentioned list of values for the encoder config.

| Encoder Config | Resolution | Frame Rate | Bitrate (High)       |
| -------------- | ---------- | ---------- | -------------------- |
| h360p_30fps    | 640x360    | 30 fps     | 400 kbps             |
| h480p_15fps    | 854x480    | 15 fps     | 300 kbps             |
| h480p_30fps    | 854x480    | 30 fps     | 500 kbps             |
| h720p_5fps     | 1280x720   | 5 fps      | 400 kbps             |
| h720p_15fps    | 1280x720   | 15 fps     | 1000 kbps (1 Mbps)   |
| h720p_30fps    | 1280x720   | 30 fps     | 1500 kbps (1.5 Mbps) |
| h1080p_15fps   | 1920x1080  | 15 fps     | 1500 kbps (1.5 Mbps) |
| h1080p_30fps   | 1920x1080  | 30 fps     | 2000 kbps (2 Mbps)   |

:::note

- Above mentioned encoder configurations are valid for both, landscape as well as portrait mode.
- The following encoder configurations are newly added in SDK v0.3.4+:
  - `h480p_15fps`
  - `h480p_30fps`
  - `h720p_30fps`

:::

- **optimizationMode**
  - type: `String`
  - required: `false`
  - Allowed values: `motion` | `text` | `detail`
  - It will specify the optimization mode for the video track being generated.

#### Returns

- `MediaStream`

### Example

```javascript

let customTrack = await createScreenShareVideoTrack({
  optimizationMode: "motion",
  encoderConfig: "h720p_15fps",
});
```


---

# Meeting Error Codes - React

If you encounter any of the errors listed below, refer to the [Developer Experience Guide](../../guide/best-practices/developer-experience.md#listen-for-error-events), which offers recommended solutions based on common error categories.



### 1. Errors associated with Organization 

This table lists errors that occur due to the configuration and limitations within your organization’s account. These include account status, participant limits, and add-on service availability.

| Type                                   | Code  | Message                                             |
|----------------------------------------|-------|-----------------------------------------------------|
| ACCOUNT_DEACTIVATED                   | 4006  | Your account has been deactivated. Please contact VideoSDK support. |
| ACCOUNT_DISCONTINUED                  | 4007  | Your account has been discontinued. Please reach out to support for more details. |
| MAX_PARTICIPANT_REACHED               | 4009  | You have reached the maximum participant limit for this meeting. |
| MAX_SPEAKER_REACHED                   | 4010  | The maximum number of speakers for this meeting has been reached. |
| MAX_SPEAKER_LIMIT_REACHED_ON_ORGANIZATION | 4026  | Your organization has reached the maximum number of speakers allowed. |
| MAX_VIEWER_LIMIT_REACHED_ON_ORGANIZATION | 4027  | Your organization has reached the maximum number of viewers allowed. |
| ADD_ON_SERVICES_DISABLED              | 4021  | Add-On services have been disabled. Please contact support to enable them. |
| MAX_RECORDING_LIMIT_REACHED_ON_ORGANIZATION              | 4028  | You have reached max limit of recording on organization. To increase contact at support@videosdk.live |
| MAX_HLS_LIMIT_REACHED_ON_ORGANIZATION  | 4029  | You have reached max limit of hls on organization. To increase contact at support@videosdk.live |
| MAX_LIVESTREAM_LIMIT_REACHED_ON_ORGANIZATION  | 4030  | You have reached max limit of livestream on organization. To increase contact at support@videosdk.live |

### 2. Errors associated with Token

Errors listed here are related to issues with the API key, authentication tokens, or permissions assigned to users. These errors can occur when tokens are missing, expired, or improperly configured.

| Type                                    | Code  | Message                                                |
|-----------------------------------------|-------|--------------------------------------------------------|
| INVALID_API_KEY                        | 4001  | The provided API key is either missing or invalid. |
| INVALID_TOKEN                          | 4002  | The provided token is empty, invalid, or has expired. |
| INVALID_PERMISSIONS                    | 4008  | The permissions in the token are incorrect. Please verify them. |
| UNAUTHORIZED_MEETING_ID                | 4022  | The provided token is not authorized for this meeting ID. |
| UNAUTHORIZED_PARTICIPANT_ID            | 4023  | The provided token is not authorized for this participant ID. |
| UNAUTHORIZED_ROLE                      | 4024  | The role specified in the token is not valid for joining this meeting. |
| UNAUTHORIZED_REQUEST                      | 4025 | Your request does not match the security configuration. |

### 3. Errors associated with Meeting and Participant

This table lists errors resulting from invalid or missing meeting or participant details, including cases where a participant attempts to join with a duplicate ID.

| Type                    | Code  | Message                                         |
|-------------------------|-------|-------------------------------------------------|
| INVALID_MEETING_ID      | 4003  | The meeting ID provided is either invalid or missing. |
| INVALID_PARTICIPANT_ID  | 4004  | The participant ID is either invalid or missing. |
| DUPLICATE_PARTICIPANT   | 4005  | This participant has joined from another device. |

### 4. Errors associated with Add-on Service

This section addresses errors that occur while using VideoSDK's add-on services such as recording, livestreaming, HLS streaming, and transcription.

### Recording-related errors

| Type                        | Code  | Message                                          |
|-----------------------------|-------|--------------------------------------------------|
| START_RECORDING_FAILED      | 4011  | Failed to start recording. Please try again.   |
| STOP_RECORDING_FAILED       | 4012  | Failed to stop recording. Please try again.    |
| RECORDING_FAILED            | 5001  | Recording was stopped due to an error.         |
| START_PARTICIPANT_RECORDING_FAILED | 4035 | Failed to start participant recording. Please check the request. |
| STOP_PARTICIPANT_RECORDING_FAILED  | 4036 | Failed to stop participant recording. |
| PARTICIPANT_RECORDING_FAILED       | 5012 | Participant recording has stopped due to an error. |
| START_TRACK_RECORDING_FAILED | 4037 | Failed to start track recording.                |
| STOP_TRACK_RECORDING_FAILED  | 4038 | Failed to stop track r