> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Settings

> Configure CometChat Calls SDK v5 session settings on React Native for call behavior, UI options, participant controls, and features.

Configure call sessions using a plain `sessionSettings` object. This allows you to customize the call UI, behavior, and features.

## Session Settings Object

The `sessionSettings` object is a plain JavaScript object whose properties configure the call session. Pass it to `CometChatCalls.Component` via the `sessionSettings` prop:

```tsx theme={null}
import { CometChatCalls } from '@cometchat/calls-sdk-react-native';

const sessionSettings = {
  sessionType: 'VIDEO',
  layout: 'TILE',
  hideLeaveSessionButton: false,
  hideToggleAudioButton: false,
  hideToggleVideoButton: false,
  hideSwitchCameraButton: false,
  hideAudioModeButton: false,
  startAudioMuted: false,
  startVideoPaused: false,
  audioMode: 'SPEAKER',
  hideRecordingButton: true,
  autoStartRecording: false,
  idleTimeoutPeriodBeforePrompt: 180000,
  enableSpotlightSwap: true,
  enableSpotlightDrag: true,
};
```

## Configuration Options

### Call Type

| Property      | Type   | Default   | Description                                                        |
| ------------- | ------ | --------- | ------------------------------------------------------------------ |
| `sessionType` | string | `'VIDEO'` | Set to `'VOICE'` for audio-only calls or `'VIDEO'` for video calls |

```tsx theme={null}
// Audio-only call
const audioCallSettings = {
  sessionType: 'VOICE',
};

// Video call (default)
const videoCallSettings = {
  sessionType: 'VIDEO',
};
```

### Layout Mode

| Property | Type   | Default  | Description      |
| -------- | ------ | -------- | ---------------- |
| `layout` | string | `'TILE'` | Call layout mode |

Available layouts:

| Layout        | Description                                       |
| ------------- | ------------------------------------------------- |
| `'TILE'`      | Grid layout with all participants visible         |
| `'SIDEBAR'`   | Focus on one participant with others in a sidebar |
| `'SPOTLIGHT'` | Focus on one participant with others overlaid     |

```tsx theme={null}
const sessionSettings = {
  layout: 'SPOTLIGHT',
};
```

### UI Controls

| Property                 | Type    | Default | Description                    |
| ------------------------ | ------- | ------- | ------------------------------ |
| `hideControlPanel`       | boolean | `false` | Hide the default button layout |
| `hideLeaveSessionButton` | boolean | `false` | Hide the leave session button  |
| `hideToggleAudioButton`  | boolean | `false` | Hide the mute audio button     |
| `hideToggleVideoButton`  | boolean | `false` | Hide the pause video button    |
| `hideSwitchCameraButton` | boolean | `false` | Hide the switch camera button  |
| `hideAudioModeButton`    | boolean | `false` | Hide the audio mode button     |
| `hideRecordingButton`    | boolean | `true`  | Hide the recording button      |

```tsx theme={null}
const sessionSettings = {
  hideControlPanel: false,
  hideLeaveSessionButton: false,
  hideToggleAudioButton: false,
  hideToggleVideoButton: false,
  hideSwitchCameraButton: false,
  hideAudioModeButton: false,
  hideRecordingButton: false,
};
```

### Initial State

| Property           | Type    | Default | Description                       |
| ------------------ | ------- | ------- | --------------------------------- |
| `startAudioMuted`  | boolean | `false` | Start call with audio muted       |
| `startVideoPaused` | boolean | `false` | Start call with video paused      |
| `audioMode`        | string  | -       | Set the default audio output mode |

Available audio modes:

| Mode           | Description      |
| -------------- | ---------------- |
| `'SPEAKER'`    | Phone speaker    |
| `'EARPIECE'`   | Phone earpiece   |
| `'BLUETOOTH'`  | Bluetooth device |
| `'HEADPHONES'` | Wired headphones |

```tsx theme={null}
const sessionSettings = {
  startAudioMuted: true,
  startVideoPaused: false,
  audioMode: 'SPEAKER',
};
```

### Recording

| Property              | Type    | Default | Description                           |
| --------------------- | ------- | ------- | ------------------------------------- |
| `hideRecordingButton` | boolean | `true`  | Hide the recording button             |
| `autoStartRecording`  | boolean | `false` | Auto-start recording when call begins |

```tsx theme={null}
const sessionSettings = {
  hideRecordingButton: false,
  autoStartRecording: true,
};
```

### Idle Timeout

| Property                        | Type   | Default  | Description                                                  |
| ------------------------------- | ------ | -------- | ------------------------------------------------------------ |
| `idleTimeoutPeriodBeforePrompt` | number | `180000` | Milliseconds of inactivity before the prompt appears         |
| `idleTimeoutPeriodAfterPrompt`  | number | `120000` | Milliseconds the user has to respond before the session ends |

```tsx theme={null}
const sessionSettings = {
  idleTimeoutPeriodBeforePrompt: 300000, // 5 minutes
  idleTimeoutPeriodAfterPrompt: 120000,  // 2 minutes
};
```

### Video Tile Interaction

| Property              | Type    | Default | Description                                           |
| --------------------- | ------- | ------- | ----------------------------------------------------- |
| `enableSpotlightSwap` | boolean | `true`  | Enable clicking video tiles to swap in Spotlight mode |
| `enableSpotlightDrag` | boolean | `true`  | Enable dragging video tiles in Spotlight mode         |

```tsx theme={null}
const sessionSettings = {
  enableSpotlightSwap: true,
  enableSpotlightDrag: true,
};
```

## Event Subscription

Subscribe to call events with `CometChatCalls.addEventListener`. Pass an `AbortSignal` to each listener and call `controller.abort()` once to remove them all on cleanup:

```tsx theme={null}
const controller = new AbortController();

CometChatCalls.addEventListener('onParticipantJoined', (participant) => {
  console.log('Participant joined:', participant);
}, { signal: controller.signal });

CometChatCalls.addEventListener('onParticipantLeft', (participant) => {
  console.log('Participant left:', participant);
}, { signal: controller.signal });

CometChatCalls.addEventListener('onParticipantListChanged', (participants) => {
  console.log('Participant list changed:', participants);
}, { signal: controller.signal });

CometChatCalls.addEventListener('onSessionLeft', () => {
  console.log('Session left');
}, { signal: controller.signal });

CometChatCalls.addEventListener('onLeaveSessionButtonClicked', () => {
  console.log('Leave session button clicked');
}, { signal: controller.signal });

CometChatCalls.addEventListener('onAudioModeChanged', (mode) => {
  console.log('Audio mode changed:', mode);
}, { signal: controller.signal });

CometChatCalls.addEventListener('onRecordingStarted', () => {
  console.log('Recording started');
}, { signal: controller.signal });

CometChatCalls.addEventListener('onRecordingStopped', () => {
  console.log('Recording stopped');
}, { signal: controller.signal });

CometChatCalls.addEventListener('onParticipantAudioMuted', (participant) => {
  console.log('Participant muted:', participant);
}, { signal: controller.signal });

CometChatCalls.addEventListener('onSessionTimedOut', () => {
  console.log('Session timed out');
}, { signal: controller.signal });

// Later, on cleanup
controller.abort();
```

## Complete Example

```tsx theme={null}
import React, { useEffect, useMemo } from 'react';
import { CometChatCalls } from '@cometchat/calls-sdk-react-native';

function useCallEvents() {
  useEffect(() => {
    const controller = new AbortController();
    const { signal } = controller;

    CometChatCalls.addEventListener('onParticipantJoined', (participant) => {
      console.log('Participant joined:', participant.name);
    }, { signal });
    
    CometChatCalls.addEventListener('onParticipantLeft', (participant) => {
      console.log('Participant left:', participant.name);
    }, { signal });
    
    CometChatCalls.addEventListener('onSessionLeft', () => {
      console.log('Session left');
      // Navigate back or update UI
    }, { signal });

    return () => controller.abort();
  }, []);
}

function createSessionSettings(isAudioOnly: boolean = false) {
  return {
    sessionType: isAudioOnly ? 'VOICE' : 'VIDEO',
    layout: 'TILE',
    hideControlPanel: false,
    hideLeaveSessionButton: false,
    hideToggleAudioButton: false,
    hideToggleVideoButton: isAudioOnly,
    hideSwitchCameraButton: isAudioOnly,
    hideAudioModeButton: false,
    startAudioMuted: false,
    startVideoPaused: false,
    audioMode: 'SPEAKER',
    hideRecordingButton: false,
    idleTimeoutPeriodBeforePrompt: 180000,
  };
}

// Create video session settings
const videoSessionSettings = createSessionSettings(false);

// Create audio session settings
const audioSessionSettings = createSessionSettings(true);
```

## Related Documentation

* [Join Session](/calls/react-native/join-session) - Start a call with these settings
* [Events](/calls/react-native/events) - Detailed event documentation
* [Actions](/calls/react-native/actions) - Control the call programmatically