### Start Example App Packager

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/CONTRIBUTING.md

Starts the Metro server for the example application. This is necessary to run the example app.

```sh
yarn example start
```

--------------------------------

### Run iOS Example with New Architecture

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/CONTRIBUTING.md

Enables the new architecture for the iOS example app by setting the RCT_NEW_ARCH_ENABLED environment variable and installing pods.

```sh
RCT_NEW_ARCH_ENABLED=1 yarn pod-install example/ios
yarn example ios
```

--------------------------------

### Run Example App on iOS

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/CONTRIBUTING.md

Builds and runs the example application on an iOS simulator or device.

```sh
yarn example ios
```

--------------------------------

### Install iOS Dependencies

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/README.md

After installing the package, navigate to your ios folder and run 'pod install' to install native dependencies.

```shell
pod install
```

--------------------------------

### Run Example App on Android

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/CONTRIBUTING.md

Builds and runs the example application on an Android device or emulator.

```sh
yarn example android
```

--------------------------------

### Run Android Example with New Architecture

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/CONTRIBUTING.md

Enables the new architecture for the Android example app by setting the ORG_GRADLE_PROJECT_newArchEnabled environment variable.

```sh
ORG_GRADLE_PROJECT_newArchEnabled=true yarn example android
```

--------------------------------

### Install Expo Build Properties

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/examples/expo/README.md

Install expo-build-properties as a dev dependency to configure minimum SDK versions.

```bash
npx expo install expo-build-properties --save-dev
```

--------------------------------

### Install Dependencies (Skip Pods)

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/CONTRIBUTING.md

Installs project dependencies using Yarn. The POD_INSTALL=0 environment variable can be used to skip the installation of CocoaPods.

```sh
yarn POD_INSTALL=0
```

--------------------------------

### Install React Native Agora SDK

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/examples/expo/README.md

Install the React Native Agora package after testing your Expo app.

```bash
npx expo install react-native-agora
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/CONTRIBUTING.md

Run this command in the root directory to install all project dependencies using Yarn workspaces. Do not use npm for development.

```sh
yarn
```

--------------------------------

### Install Expo Dev Client

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/examples/expo/README.md

Install expo-dev-client to enable the usage of native modules within your Expo project.

```bash
npx expo install expo-dev-client
```

--------------------------------

### Install react-native-agora with npm

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/README.md

Install the react-native-agora package using npm. Ensure your React Native version is 0.60.0 or higher.

```shell
npm i --save react-native-agora
```

--------------------------------

### Install react-native-agora with Yarn

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/README.md

Install the react-native-agora package using Yarn. Ensure your React Native version is 0.60.0 or higher.

```shell
yarn add react-native-agora
```

--------------------------------

### Start and Stop Screen Capture

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Initiates screen sharing with customizable parameters for audio, video, dimensions, frame rate, and bitrate. Ensure `publishScreenCaptureVideo` is set to `true` in `ChannelMediaOptions`. To stop, call `stopScreenCapture` and update channel options.

```typescript
import { ScreenCaptureParameters2 } from 'react-native-agora';

const captureParams: ScreenCaptureParameters2 = {
  captureAudio: true,
  captureVideo: true,
  videoParams: {
    dimensions: { width: 1280, height: 720 },
    frameRate: 15,
    bitrate: 600,
  },
};

engine.startScreenCapture(captureParams);

// Update channel options to publish screen track
engine.updateChannelMediaOptions({
  publishScreenCaptureVideo: true,
  publishScreenCaptureAudio: true,
  publishCameraTrack: false,
});

// Stop screen sharing
engine.stopScreenCapture();
engine.updateChannelMediaOptions({
  publishScreenCaptureVideo: false,
  publishCameraTrack: true,
});
```

--------------------------------

### engine.enableVideo / engine.disableVideo

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Control the video module by enabling or disabling it. `enableVideo()` must be called before any video capture or rendering can occur. This section also covers related configurations like setting encoder parameters, starting previews, and muting local or remote video streams.

```APIDOC
## `engine.enableVideo` / `engine.disableVideo` — Toggle video module

Enables or disables the entire video module. Must call `enableVideo()` before rendering or capturing video.

```typescript
// Enable video (required before camera capture or rendering)
engine.enableVideo();

// Set video encoder configuration (resolution, framerate, bitrate)
engine.setVideoEncoderConfiguration({
  dimensions: { width: 1280, height: 720 },
  frameRate: 30,
  bitrate: 1600,
  orientationMode: OrientationMode.OrientationModeAdaptive,
});

// Start local preview without joining a channel
engine.startPreview();

// Mute/unmute local video stream
engine.muteLocalVideoStream(true);   // mute
engine.muteLocalVideoStream(false);  // unmute

// Mute specific remote user's video
engine.muteRemoteVideoStream(remoteUid, true);

// Disable entire video module
engine.disableVideo();
```
```

--------------------------------

### Enable/Disable Video Module and Control Streams

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Manage the video module by enabling or disabling it, configuring encoder settings, starting previews, and muting local or remote video streams. Ensure `enableVideo()` is called before any video-related operations.

```typescript
// Enable video (required before camera capture or rendering)
engine.enableVideo();

// Set video encoder configuration (resolution, framerate, bitrate)
engine.setVideoEncoderConfiguration({
  dimensions: { width: 1280, height: 720 },
  frameRate: 30,
  bitrate: 1600,
  orientationMode: OrientationMode.OrientationModeAdaptive,
});

// Start local preview without joining a channel
engine.startPreview();

// Mute/unmute local video stream
engine.muteLocalVideoStream(true);   // mute
engine.muteLocalVideoStream(false);  // unmute

// Mute specific remote user's video
engine.muteRemoteVideoStream(remoteUid, true);

// Disable entire video module
engine.disableVideo();
```

--------------------------------

### Join an RTC Channel with Media Options

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Joins an RTC channel, allowing configuration of media publishing and subscription. Returns 0 on success; negative values indicate errors. The example shows joining as both a broadcaster and an audience member.

```typescript
import {
  ChannelMediaOptions,
  ClientRoleType,
  ChannelProfileType,
} from 'react-native-agora';

// As a broadcaster (host)
const options: ChannelMediaOptions = {
  publishCameraTrack: true,
  publishMicrophoneTrack: true,
  autoSubscribeAudio: true,
  autoSubscribeVideo: true,
  clientRoleType: ClientRoleType.ClientRoleBroadcaster,
  channelProfile: ChannelProfileType.ChannelProfileLiveBroadcasting,
};

const ret = engine.joinChannel('YOUR_TOKEN', 'testChannel', 12345, options);
if (ret < 0) {
  console.error('Failed to join channel:', ret);
}

// As an audience member
engine.joinChannel('YOUR_TOKEN', 'testChannel', 0, {
  publishCameraTrack: false,
  publishMicrophoneTrack: false,
  autoSubscribeAudio: true,
  autoSubscribeVideo: true,
  clientRoleType: ClientRoleType.ClientRoleAudience,
});
```

--------------------------------

### Start RTMP Streaming with `startRtmpStreamWithTranscoding`

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Pushes a transcoded composite stream to an RTMP endpoint for live distribution. Handles state changes via `onRtmpStreamingStateChanged` and can be stopped with `stopRtmpStream`.

```typescript
import { LiveTranscoding } from 'react-native-agora';

const transcoding: LiveTranscoding = {
  width: 1280,
  height: 720,
  videoBitrate: 1500,
  videoFramerate: 30,
  audioSampleRate: AudioSampleRateType.AudioSampleRate44100,
  audioBitrate: 128,
  audioChannels: 2,
  transcodingUsers: [
    { uid: localUid, x: 0, y: 0, width: 640, height: 720, zOrder: 1, alpha: 1.0 },
    { uid: remoteUid, x: 640, y: 0, width: 640, height: 720, zOrder: 1, alpha: 1.0 },
  ],
};

engine.startRtmpStreamWithTranscoding('rtmp://live.example.com/live/streamKey', transcoding);

engine.addListener('onRtmpStreamingStateChanged', (url, state, reason) => {
  console.log(`RTMP ${url}: state=${state}, reason=${reason}`);
});

// Stop streaming
engine.stopRtmpStream('rtmp://live.example.com/live/streamKey');
```

--------------------------------

### Disable Flipper for Pod Install Issues

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/README.md

If you encounter 'libcrypto.a' conflicts during 'pod install' on React Native >= 0.62.0, disable Flipper by commenting out the relevant lines in your Podfile and AppDelegate.

```ruby
  # Enables Flipper.
  #
  # Note that if you have use_frameworks! enabled, Flipper will not work and
  # you should disable these next few lines.
  add_flipper_pods!
  post_install do |installer|
    flipper_post_install(installer)
  end
```

--------------------------------

### Play Background Music / Audio Mixing

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Plays a local or online audio file mixed into the stream for all channel participants. Supports loop playback, starting from a specific position, and adjusting volume for local playback and remote publishing independently. Listen for state and position changes.

```typescript
engine.startAudioMixing(
  '/path/to/music.mp3',   // local path or URL
  false,                  // loopback: false = publish to remote
  -1,                     // loopCount: -1 = infinite
  0                       // startPos in ms
);

engine.addListener('onAudioMixingStateChanged', (state, reason) => {
  console.log(`Mixing state: ${state}, reason: ${reason}`);
});

engine.addListener('onAudioMixingPositionChanged', (position) => {
  console.log(`Playback position: ${position}ms`);
});

// Pause / resume / stop
engine.pauseAudioMixing();
engine.resumeAudioMixing();
engine.stopAudioMixing();

// Volume control
engine.adjustAudioMixingVolume(70);         // both local + publish [0,100]
engine.adjustAudioMixingPlayoutVolume(80);   // local only
engine.adjustAudioMixingPublishVolume(60);   // remote only
```

--------------------------------

### engine.startScreenCapture

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Captures the device screen and publishes it as a video track in the channel. Requires `publishScreenCaptureVideo: true` in `ChannelMediaOptions`.

```APIDOC
## `engine.startScreenCapture` — Screen sharing

Captures the device screen and publishes it as a video track in the channel (requires `publishScreenCaptureVideo: true` in `ChannelMediaOptions`).

```typescript
import { ScreenCaptureParameters2 } from 'react-native-agora';

const captureParams: ScreenCaptureParameters2 = {
  captureAudio: true,
  captureVideo: true,
  videoParams: {
    dimensions: { width: 1280, height: 720 },
    frameRate: 15,
    bitrate: 600,
  },
};

engine.startScreenCapture(captureParams);

// Update channel options to publish screen track
engine.updateChannelMediaOptions({
  publishScreenCaptureVideo: true,
  publishScreenCaptureAudio: true,
  publishCameraTrack: false,
});

// Stop screen sharing
engine.stopScreenCapture();
engine.updateChannelMediaOptions({
  publishScreenCaptureVideo: false,
  publishCameraTrack: true,
});
```
```

--------------------------------

### Create Expo App

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/examples/expo/README.md

Use this command to create a new Expo project and navigate into its directory.

```bash
npx create-expo-app my-agora-app && cd my-agora-app
```

--------------------------------

### Initialize and Use 3D Spatial Audio

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Enables 3D spatial audio by initializing `ILocalSpatialAudioEngine`. Allows setting the local user's position and orientation, positioning remote users in 3D space, and defining sound isolation zones. Remember to clear remote positions when no longer needed.

```typescript
import { ILocalSpatialAudioEngine, RemoteVoicePositionInfo } from 'react-native-agora';

const spatialEngine: ILocalSpatialAudioEngine = engine.getLocalSpatialAudioEngine();
spatialEngine.initialize();

// Set the local user's position and facing direction
spatialEngine.updateSelfPosition(
  [0, 0, 0],    // position: [forward, right, up]
  [1, 0, 0],    // axisForward: unit vector
  [0, 1, 0],    // axisRight: unit vector
  [0, 0, 1]     // axisUp: unit vector
);

// Position a remote user 5 units to the right
const remotePosition: RemoteVoicePositionInfo = {
  position: [0, 5, 0],
  forward: [1, 0, 0],
};
spatialEngine.updateRemotePosition(remoteUid, remotePosition);

// Add a sound isolation zone
spatialEngine.setZones([{
  zoneSetId: 1,
  position: [10, 0, 0],
  forward: [1, 0, 0],
  right: [0, 1, 0],
  up: [0, 0, 1],
  forwardLength: 5,
  rightLength: 5,
  upLength: 5,
  audioAttenuation: 0.8,
}]);

// Clear remote user position
spatialEngine.removeRemotePosition(remoteUid);
```

--------------------------------

### Create and Control In-Channel Media Player

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Creates an `IMediaPlayer` instance to play media files and optionally publish their streams to the channel. Supports playback controls, seeking, speed adjustment, and looping. Remember to stop and destroy the player when done.

```typescript
import { IMediaPlayer, MediaPlayerState } from 'react-native-agora';

const player: IMediaPlayer = engine.createMediaPlayer();

// Register state observer
player.addListener('onPlayerSourceStateChanged', (state, reason) => {
  console.log(`Player state: ${state}`);
  if (state === MediaPlayerState.PlayerStateOpenCompleted) {
    player.play();
    console.log(`Duration: ${player.getDuration()}ms`);
  }
});

player.addListener('onPositionChanged', (positionMs) => {
  console.log(`Position: ${positionMs}ms`);
});

// Open and play a file
player.open('https://example.com/video.mp4', 0);

// Playback controls
player.seek(30000);         // seek to 30s
player.pause();
player.resume();
player.setPlaybackSpeed(150); // 1.5x speed
player.setLoopCount(2);       // play 3 times total

// Publish player audio into the channel
engine.updateChannelMediaOptions({
  publishMediaPlayerAudioTrack: true,
  publishMediaPlayerId: player.getMediaPlayerId(),
});

// Cleanup
player.stop();
engine.destroyMediaPlayer(player);
```

--------------------------------

### Probe Network Quality with `startLastmileProbeTest`

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Probes network quality before joining a channel to optimize configuration. Listen for `onLastmileQuality` and `onLastmileProbeResult` events.

```typescript
import { LastmileProbeConfig } from 'react-native-agora';

const probeConfig: LastmileProbeConfig = {
  probeUplink: true,
  probeDownlink: true,
  expectedUplinkBitrate: 1000,   // kbps
  expectedDownlinkBitrate: 1000, // kbps
};

engine.startLastmileProbeTest(probeConfig);

engine.addListener('onLastmileQuality', (quality) => {
  console.log('Quick quality estimate:', quality); // QualityType enum
});

engine.addListener('onLastmileProbeResult', (result) => {
  console.log('Uplink RTT:', result.uplinkReport?.rtt, 'ms');
  console.log('Downlink RTT:', result.downlinkReport?.rtt, 'ms');
  console.log('Uplink bandwidth:', result.uplinkReport?.availableBandwidth, 'kbps');
  engine.stopLastmileProbeTest();
});
```

--------------------------------

### engine.initialize

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Initializes the RTC engine with essential configurations including App ID, channel profile, audio scenario, area codes, and log settings. This configuration is required before joining any channel.

```APIDOC
## `engine.initialize` — Initialize the RTC engine

Configures the engine with App ID, channel profile, audio scenario, area codes, and log settings before any channel operation.

```typescript
import {
  createAgoraRtcEngine,
  ChannelProfileType,
  AudioScenarioType,
  AreaCode,
  LogLevel,
} from 'react-native-agora';

const engine = createAgoraRtcEngine();

engine.initialize({
  appId: 'YOUR_APP_ID',
  channelProfile: ChannelProfileType.ChannelProfileCommunication,
  audioScenario: AudioScenarioType.AudioScenarioGameStreaming,
  areaCode: AreaCode.AreaCodeGlob,
  logConfig: {
    level: LogLevel.LogLevelInfo,
    fileSizeInKB: 1024,
  },
  autoRegisterAgoraExtensions: true,
  domainLimit: false,
});
```
```

--------------------------------

### Run Expo Project on Android

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/examples/expo/README.md

Execute this command to run the Expo project on an Android emulator or device.

```bash
npx expo run:android

```

--------------------------------

### Run Expo Project on iOS

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/examples/expo/README.md

Execute this command to run the Expo project on an iOS simulator or device.

```bash
npx expo run:ios

```

--------------------------------

### engine.createMediaPlayer / IMediaPlayer

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Creates an `IMediaPlayer` instance for playing local or remote media files. The player's audio/video stream can optionally be published into the channel.

```APIDOC
## `engine.createMediaPlayer` / `IMediaPlayer` — In-channel media player

Creates an `IMediaPlayer` instance for playing local or remote media files, with optional publishing of the player's audio/video stream into the channel.

```typescript
import { IMediaPlayer, MediaPlayerState } from 'react-native-agora';

const player: IMediaPlayer = engine.createMediaPlayer();

// Register state observer
player.addListener('onPlayerSourceStateChanged', (state, reason) => {
  console.log(`Player state: ${state}`);
  if (state === MediaPlayerState.PlayerStateOpenCompleted) {
    player.play();
    console.log(`Duration: ${player.getDuration()}ms`);
  }
});

player.addListener('onPositionChanged', (positionMs) => {
  console.log(`Position: ${positionMs}ms`);
});

// Open and play a file
player.open('https://example.com/video.mp4', 0);

// Playback controls
player.seek(30000);         // seek to 30s
player.pause();
player.resume();
player.setPlaybackSpeed(150); // 1.5x speed
player.setLoopCount(2);       // play 3 times total

// Publish player audio into the channel
engine.updateChannelMediaOptions({
  publishMediaPlayerAudioTrack: true,
  publishMediaPlayerId: player.getMediaPlayerId(),
});

// Cleanup
player.stop();
engine.destroyMediaPlayer(player);
```
```

--------------------------------

### Create and Initialize Agora RTC Engine

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Creates the singleton IRtcEngine instance and initializes it with essential configurations. Must be called before any other SDK method. Ensure you replace 'YOUR_APP_ID' with your actual App ID.

```typescript
import { createAgoraRtcEngine, ChannelProfileType, AudioScenarioType } from 'react-native-agora';

const engine = createAgoraRtcEngine();

const result = engine.initialize({
  appId: 'YOUR_APP_ID',
  channelProfile: ChannelProfileType.ChannelProfileLiveBroadcasting,
  audioScenario: AudioScenarioType.AudioScenarioDefault,
});

if (result < 0) {
  console.error('Engine initialization failed:', result);
} else {
  console.log('Engine initialized, SDK version:', engine.getVersion());
}
```

```typescript
import {
  createAgoraRtcEngine,
  ChannelProfileType,
  AudioScenarioType,
  AreaCode,
  LogLevel,
} from 'react-native-agora';

const engine = createAgoraRtcEngine();

engine.initialize({
  appId: 'YOUR_APP_ID',
  channelProfile: ChannelProfileType.ChannelProfileCommunication,
  audioScenario: AudioScenarioType.AudioScenarioGameStreaming,
  areaCode: AreaCode.AreaCodeGlob,
  logConfig: {
    level: LogLevel.LogLevelInfo,
    fileSizeInKB: 1024,
  },
  autoRegisterAgoraExtensions: true,
  domainLimit: false,
});
```

--------------------------------

### engine.getLocalSpatialAudioEngine

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Initializes and configures 3D spatial audio, allowing remote users to be positioned in a 3D coordinate space for immersive audio experiences.

```APIDOC
## `engine.getLocalSpatialAudioEngine` — 3D spatial audio

Positions remote users in a 3D coordinate space for immersive audio experiences in gaming or virtual environments.

```typescript
import { ILocalSpatialAudioEngine, RemoteVoicePositionInfo } from 'react-native-agora';

const spatialEngine: ILocalSpatialAudioEngine = engine.getLocalSpatialAudioEngine();
spatialEngine.initialize();

// Set the local user's position and facing direction
spatialEngine.updateSelfPosition(
  [0, 0, 0],    // position: [forward, right, up]
  [1, 0, 0],    // axisForward: unit vector
  [0, 1, 0],    // axisRight: unit vector
  [0, 0, 1]     // axisUp: unit vector
);

// Position a remote user 5 units to the right
const remotePosition: RemoteVoicePositionInfo = {
  position: [0, 5, 0],
  forward: [1, 0, 0],
};
spatialEngine.updateRemotePosition(remoteUid, remotePosition);

// Add a sound isolation zone
spatialEngine.setZones([{
  zoneSetId: 1,
  position: [10, 0, 0],
  forward: [1, 0, 0],
  right: [0, 1, 0],
  up: [0, 0, 1],
  forwardLength: 5,
  rightLength: 5,
  upLength: 5,
  audioAttenuation: 0.8,
}]);

// Clear remote user position
spatialEngine.removeRemotePosition(remoteUid);
```
```

--------------------------------

### Initialize Agora RTC Engine (JavaScript)

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/README.md

Initialize the Agora RTC engine using JavaScript. Replace 'YOUR APP ID' with your actual Agora App ID.

```javascript
const createAgoraRtcEngine = require('react-native-agora');
const engine = createAgoraRtcEngine();
engine.initialize({ appId: 'YOUR APP ID' });
```

--------------------------------

### Initialize Agora RTC Engine (TypeScript)

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/README.md

Initialize the Agora RTC engine using TypeScript. Replace 'YOUR APP ID' with your actual Agora App ID.

```typescript
import { createAgoraRtcEngine } from 'react-native-agora';

const engine = createAgoraRtcEngine();
engine.initialize({ appId: 'YOUR APP ID' });
```

--------------------------------

### Configure Main Activity for PiP (Android)

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/examples/expo/app/examples/advanced/PictureInPicture/PictureInPicture.md

Extend AgoraPIPActivity in your MainActivity to handle PiP mode automatically when the app goes to the background on Android 12+. For older versions, manual implementation in onUserLeaveHint() is required, or implement AgoraPIPActivityProxy for customization.

```kotlin
import io.agora.rtc.ng.react.AgoraPIPActivity

class MainActivity: AgoraPIPActivity() {
    ...
}

```

--------------------------------

### Verify TypeScript and ESLint

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/CONTRIBUTING.md

Runs TypeScript for type checking and ESLint for linting the codebase. These commands should pass before committing.

```sh
yarn typecheck
yarn lint
```

--------------------------------

### Publish New Versions

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/CONTRIBUTING.md

Uses release-it to automate the process of publishing new versions to npm, including version bumping, tagging, and release creation.

```sh
yarn release
```

--------------------------------

### createAgoraRtcEngine

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Creates and returns the singleton IRtcEngine instance for the application. This must be called before any other SDK method.

```APIDOC
## `createAgoraRtcEngine` — Create the engine singleton

Returns the single `IRtcEngine` instance for the app. Must be called before any other SDK method.

```typescript
import { createAgoraRtcEngine, ChannelProfileType, AudioScenarioType } from 'react-native-agora';

const engine = createAgoraRtcEngine();

const result = engine.initialize({
  appId: 'YOUR_APP_ID',
  channelProfile: ChannelProfileType.ChannelProfileLiveBroadcasting,
  audioScenario: AudioScenarioType.AudioScenarioDefault,
});

if (result < 0) {
  console.error('Engine initialization failed:', result);
} else {
  console.log('Engine initialized, SDK version:', engine.getVersion());
}
```
```

--------------------------------

### Prebuild Expo Project for Native Changes

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/examples/expo/README.md

After modifying native configurations, rebuild your Expo project to apply the changes to the native platform folders.

```bash
npx expo prebuild

```

--------------------------------

### Join and Manage Multiple Channels

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Supports joining a second channel simultaneously using `joinChannelEx`. Allows setting different configurations for the second channel, such as video encoder settings and muting remote streams. Use `leaveChannelEx` to leave a specific channel.

```typescript
import { RtcConnection, ChannelMediaOptions } from 'react-native-agora';

const secondConnection: RtcConnection = {
  channelId: 'secondChannel',
  localUid: 99999,
};

const secondOptions: ChannelMediaOptions = {
  publishCameraTrack: false,
  publishMicrophoneTrack: false,
  autoSubscribeAudio: true,
  autoSubscribeVideo: true,
};

engine.joinChannelEx('TOKEN_2', secondConnection, secondOptions);

// Set different video encoder config for the second channel
engine.setVideoEncoderConfigurationEx(
  { dimensions: { width: 640, height: 360 }, frameRate: 15 },
  secondConnection
);

// Mute remote audio only on second channel connection
engine.muteRemoteAudioStreamEx(remoteUid, true, secondConnection);

// Leave only the second channel
engine.leaveChannelEx(secondConnection);
```

--------------------------------

### Configure Minimum Deployment Targets

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/examples/expo/README.md

Set minimum Android SDK and iOS deployment targets in app.json using expo-build-properties.

```json
{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "minSdkVersion": 24 // depends on react-native and expo version that you choose
          },
          "ios": {
            "deploymentTarget": "12.4" // depends on react-native and expo version that you choose
          }
        }
      ]
    ]
  }
}
```

--------------------------------

### engine.joinChannelEx

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Joins a second channel simultaneously, useful for co-hosting across channels or subscribing to multiple live streams. This method is part of `IRtcEngineEx`.

```APIDOC
## `engine.joinChannelEx` — Multi-channel support (IRtcEngineEx)

Joins a second channel simultaneously, useful for co-hosting across channels or subscribing to multiple live streams.

```typescript
import { RtcConnection, ChannelMediaOptions } from 'react-native-agora';

const secondConnection: RtcConnection = {
  channelId: 'secondChannel',
  localUid: 99999,
};

const secondOptions: ChannelMediaOptions = {
  publishCameraTrack: false,
  publishMicrophoneTrack: false,
  autoSubscribeAudio: true,
  autoSubscribeVideo: true,
};

engine.joinChannelEx('TOKEN_2', secondConnection, secondOptions);

// Set different video encoder config for the second channel
engine.setVideoEncoderConfigurationEx(
  { dimensions: { width: 640, height: 360 }, frameRate: 15 },
  secondConnection
);

// Mute remote audio only on second channel connection
engine.muteRemoteAudioStreamEx(remoteUid, true, secondConnection);

// Leave only the second channel
engine.leaveChannelEx(secondConnection);
```
```

--------------------------------

### Run Unit Tests

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/CONTRIBUTING.md

Executes the unit tests for the project using Jest.

```sh
yarn test
```

--------------------------------

### Enable Face Beautification

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Applies real-time skin smoothing, brightness, and redness corrections to the local video stream. Configure various beauty effect options and adjust them on the fly. Remember to disable when not needed.

```typescript
import { BeautyOptions } from 'react-native-agora';

const beautyOptions: BeautyOptions = {
  lighteningContrastLevel: 1,   // 0=low, 1=normal, 2=high
  lighteningLevel: 0.5,          // [0,1] skin brightness
  smoothnessLevel: 0.7,          // [0,1] skin smoothing
  rednessLevel: 0.3,             // [0,1] rosiness
  sharpnessLevel: 0.5,           // [0,1] image sharpness
};

// Enable
engine.setBeautyEffectOptions(true, beautyOptions);

// Adjust on the fly
engine.setBeautyEffectOptions(true, { ...beautyOptions, lighteningLevel: 0.8 });

// Disable
engine.setBeautyEffectOptions(false, beautyOptions);
```

--------------------------------

### Relay Media Across Channels with `startChannelMediaRelay`

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Relays streams across multiple channels simultaneously. Configure source and destination channels, tokens, and UIDs. Listen for state changes and events via `onChannelMediaRelayStateChanged` and `onChannelMediaRelayEvent`.

```typescript
import { ChannelMediaRelayConfiguration } from 'react-native-agora';

const config: ChannelMediaRelayConfiguration = {
  srcInfo: {
    channelName: 'sourceChannel',
    token: 'SOURCE_TOKEN',
    uid: 0,
  },
  destInfos: [
    { channelName: 'destChannel1', token: 'DEST_TOKEN_1', uid: 0 },
    { channelName: 'destChannel2', token: 'DEST_TOKEN_2', uid: 0 },
  ],
  destCount: 2,
};

engine.startChannelMediaRelay(config);

engine.addListener('onChannelMediaRelayStateChanged', (state, code) => {
  console.log(`Relay state: ${state}, code: ${code}`);
});

engine.addListener('onChannelMediaRelayEvent', (code) => {
  console.log('Relay event:', code);
});

// Stop relay
engine.stopChannelMediaRelay();
```

--------------------------------

### Configure Agora App ID

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/examples/expo/README.md

Create a JavaScript file to store your Agora App ID and add it to .gitignore to prevent exposure.

```javascript
export const appId = 'YOUR_AGORA_APP_ID';
```

--------------------------------

### Apply Voice Effects with `setAudioEffectPreset`

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Applies real-time voice transformation presets for music or chat. Ensure to disable presets before applying custom pitch or equalization.

```typescript
import {
  AudioEffectPreset,
  VoiceBeautifierPreset,
  VoiceConversionPreset,
} from 'react-native-agora';

// Voice beautifier (for music or chat)
engine.setVoiceBeautifierPreset(VoiceBeautifierPreset.ChatBeautifierMagnetic);

// Audio scene effects
engine.setAudioEffectPreset(AudioEffectPreset.RoomAcousticsKtv);
engine.setAudioEffectPreset(AudioEffectPreset.VoiceChangerEffectOldMan);

// Voice conversion (changes gender/age)
engine.setVoiceConversionPreset(VoiceConversionPreset.VoiceChangerNeutral);

// Custom pitch + equalization (disable presets first)
engine.setAudioEffectPreset(AudioEffectPreset.AudioEffectOff);
engine.setLocalVoicePitch(1.2);
engine.setLocalVoiceEqualization(AudioEqualizationBandFrequency.AudioEqualizationBand1k, 6);

// AI noise suppression
engine.setAINSMode(true, AudioAinsMode.AinsModeAggressive);
```

--------------------------------

### Configure Android Permissions

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/examples/expo/README.md

Add necessary Android permissions to your app.json for Agora SDK functionality.

```json
{
  "expo": {
    "android": {
      "permissions": [
        "android.permission.CAMERA",
        "android.permission.RECORD_AUDIO",
        "android.permission.MODIFY_AUDIO_SETTINGS",
        "android.permission.ACCESS_WIFI_STATE",
        "android.permission.ACCESS_NETWORK_STATE",
        "android.permission.BLUETOOTH",
        "android.permission.FOREGROUND_SERVICE"
      ]
    }
  }
}
```

--------------------------------

### Toggle Audio Module

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Controls the local audio module, including microphone capture and audio playback. This allows for enabling or disabling the audio functionality as needed.

```APIDOC
## `engine.enableAudio` / `engine.disableAudio` — Toggle audio module

Controls the local audio module including microphone capture and audio playback.

### Enable Audio
```typescript
engine.enableAudio();
```

### Disable Audio
```typescript
// Assuming disableAudio() is the counterpart to enableAudio()
// engine.disableAudio(); // This method is implied but not explicitly shown in the source.
```

### Set Audio Profile and Scenario
```typescript
engine.setAudioProfile(
  AudioProfileType.AudioProfileMusicHighQualityStereo,
  AudioScenarioType.AudioScenarioGameStreaming
);
```

### Mute/Unmute Local Microphone
```typescript
// Mute self
engine.muteLocalAudioStream(true);
// Unmute self
engine.muteLocalAudioStream(false);
```

### Mute All Remote Audio Streams
```typescript
engine.muteAllRemoteAudioStreams(true);
```

### Enable Volume Indication
```typescript
// Enable volume indication — fires onAudioVolumeIndication every 200ms
engine.enableAudioVolumeIndication(200, 3, false);

engine.addListener('onAudioVolumeIndication', (connection, speakers, speakerNumber, totalVolume) => {
  speakers.forEach(({ uid, volume, vad }) => {
    console.log(`uid=${uid} volume=${volume} speaking=${vad === 1}`);
  });
});
```
```

--------------------------------

### Basic Video Call Integration in React Native Expo

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/examples/expo/README.md

Implement a basic video call by initializing the Agora engine, requesting media permissions, joining a channel, and rendering local and remote video streams. Handles user joining and leaving events.

```javascript
import React, { useEffect, useState } from 'react';
import { Button, StyleSheet, View } from 'react-native';
import {
  ChannelProfileType,
  ClientRoleType,
  createAgoraRtcEngine,
  IRtcEngineEventHandler,
  RtcSurfaceView,
  VideoSourceType,
} from 'react-native-agora';

import Config from '../config/agora.config';
import { askMediaAccess } from '../utils/permissions';

export default function BasicVideoCall() {
  const [engine, setEngine] = useState(undefined);
  const [isJoined, setIsJoined] = useState(false);
  const [remoteUsers, setRemoteUsers] = useState([]);

  useEffect(() => {
    // Initialize Agora engine when component mounts
    const init = async () => {
      if (!Config.appId) {
        console.error('App ID is missing');
        return;
      }

      // Create Agora engine instance
      const rtcEngine = createAgoraRtcEngine();
      setEngine(rtcEngine);

      // Initialize the engine
      rtcEngine.initialize({
        appId: Config.appId,
        channelProfile: ChannelProfileType.ChannelProfileLiveBroadcasting,
      });

      // Request permissions and enable video
      await askMediaAccess([
        'android.permission.CAMERA',
        'android.permission.RECORD_AUDIO',
      ]);
      rtcEngine.enableVideo();

      // Register event handlers
      rtcEngine.addListener('onJoinChannelSuccess', () => {
        setIsJoined(true);
        console.log('Successfully joined the channel');
      });

      rtcEngine.addListener('onUserJoined', (connection, uid) => {
        console.log('Remote user joined:', uid);
        setRemoteUsers((prev) => [...prev, uid]);
      });

      rtcEngine.addListener('onUserOffline', (connection, uid) => {
        console.log('Remote user left:', uid);
        setRemoteUsers((prev) => prev.filter((id) => id !== uid));
      });
    };

    init();
    return () => {
      // Clean up
      engine?.leaveChannel();
      engine?.unregisterEventHandler({});
    };
  }, []);

  const joinChannel = async () => {
    if (!engine) return;

    // Join a channel
    engine.joinChannel(Config.token, Config.channelId, 0, {
      clientRoleType: ClientRoleType.ClientRoleBroadcaster,
    });
  };

  const leaveChannel = () => {
    if (!engine) return;
    engine.leaveChannel();
    setIsJoined(false);
    setRemoteUsers([]);
  };

  return (
    <View style={styles.container}>
      {isJoined && (
        <View style={styles.videoContainer}>
          {/* Local video */}
          <RtcSurfaceView
            style={styles.localVideo}
            canvas={{
              uid: 0,
              sourceType: VideoSourceType.VideoSourceCamera,
            }}
          />

          {/* Remote videos */}
          {remoteUsers.map((uid) => (
            <RtcSurfaceView
              key={uid}
              style={styles.remoteVideo}
              canvas={{
                uid,
                sourceType: VideoSourceType.VideoSourceRemote,
              }}
            />
          ))}
        </View>
      )}

      <View style={styles.buttonContainer}>
        {!isJoined ? (
          <Button title="Join Channel" onPress={joinChannel} />
        ) : (
          <Button title="Leave Channel" onPress={leaveChannel} />
        )}
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  videoContainer: {
    flex: 1,
    width: '100%',
  },
  localVideo: {
    width: '100%',
    height: 300,
  },
  remoteVideo: {
    width: '100%',
    height: 300,
    marginTop: 10,
  },
  buttonContainer: {
    width: '100%',
    padding: 20,
  },
});

```

--------------------------------

### Configure Camera Settings with react-native-agora

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Customize camera behavior using `setCameraCapturerConfiguration`. Options include camera direction, focal length, and aspect ratio following. Use `switchCamera` to toggle between front and rear cameras, and `setCameraZoomFactor` for zoom.

```typescript
import { CameraDirection, CameraFocalLengthType } from 'react-native-agora';

// Switch to front camera
engine.setCameraCapturerConfiguration({
  cameraDirection: CameraDirection.CameraFront,
  followEncodeDimensionRatio: true,
});

// Use ultra-wide rear camera (iOS multi-lens)
engine.setCameraCapturerConfiguration({
  cameraDirection: CameraDirection.CameraRear,
  cameraFocalLengthType: CameraFocalLengthType.CameraFocalLengthUltraWide,
});

// Dynamically switch camera during call
engine.switchCamera();

// Camera zoom
if (engine.isCameraZoomSupported()) {
  engine.setCameraZoomFactor(2.0);  // 2x zoom
}

// Tap-to-focus
engine.setCameraFocusPositionInPreview(0.5, 0.5); // center
```

--------------------------------

### Cleanup Build Folders

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/CONTRIBUTING.md

Removes all build folders to ensure a clean build, especially when switching architectures.

```sh
yarn clean
```

--------------------------------

### engine.enableEncryption

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Encrypts all audio/video streams in the channel using AES or SM4 cipher modes. Call with `false` to disable encryption.

```APIDOC
## `engine.enableEncryption` — Media stream encryption

Encrypts all audio/video streams in the channel using AES or SM4 cipher modes.

```typescript
import { EncryptionMode } from 'react-native-agora';

engine.enableEncryption(true, {
  encryptionMode: EncryptionMode.Aes128Gcm2,
  encryptionKey: 'my-32-char-secret-key-here!!!!!',
  encryptionKdfSalt: new Uint8Array(32),  // 32-byte random salt
});

engine.addListener('onEncryptionError', (connection, errorType) => {
  console.error('Encryption error:', errorType);
});

// Disable
engine.enableEncryption(false, {});
```
```

--------------------------------

### engine.takeSnapshot

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Captures a screenshot of the local or remote video stream and saves it to a specified file path. It supports basic capture and capture with configuration options.

```APIDOC
## `engine.takeSnapshot` — Capture video frame as image

Captures a screenshot of the local or remote video stream and saves it to a file path.

```typescript
import { SnapshotConfig } from 'react-native-agora';

// Capture local video (uid=0)
engine.takeSnapshot(0, '/sdcard/snapshot_local.jpg');

// Capture remote user video
engine.takeSnapshot(remoteUid, '/sdcard/snapshot_remote.jpg');

// With config (filePath and format)
const config: SnapshotConfig = {
  filePath: '/sdcard/snapshot.jpg',
};
engine.takeSnapshotWithConfig(0, config);

engine.addListener('onSnapshotTaken', (connection, uid, filePath, width, height, errCode) => {
  if (errCode === 0) {
    console.log(`Snapshot saved: ${filePath} (${width}x${height})`);
  } else {
    console.error('Snapshot failed:', errCode);
  }
});
```
```

--------------------------------

### engine.joinChannel

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Joins a specified RTC channel. This method allows configuration of media options to control track publishing and subscription, enabling participation as a broadcaster or audience member.

```APIDOC
## `engine.joinChannel` — Join an RTC channel

Joins a channel with media options controlling which tracks are published and subscribed. Returns 0 on success; negative values indicate errors.

```typescript
import {
  ChannelMediaOptions,
  ClientRoleType,
  ChannelProfileType,
} from 'react-native-agora';

// As a broadcaster (host)
const options: ChannelMediaOptions = {
  publishCameraTrack: true,
  publishMicrophoneTrack: true,
  autoSubscribeAudio: true,
  autoSubscribeVideo: true,
  clientRoleType: ClientRoleType.ClientRoleBroadcaster,
  channelProfile: ChannelProfileType.ChannelProfileLiveBroadcasting,
};

const ret = engine.joinChannel('YOUR_TOKEN', 'testChannel', 12345, options);
if (ret < 0) {
  console.error('Failed to join channel:', ret);
}

// As an audience member
engine.joinChannel('YOUR_TOKEN', 'testChannel', 0, {
  publishCameraTrack: false,
  publishMicrophoneTrack: false,
  autoSubscribeAudio: true,
  autoSubscribeVideo: true,
  clientRoleType: ClientRoleType.ClientRoleAudience,
});
```
```

--------------------------------

### Configure iOS Permissions

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/examples/expo/README.md

Configure permission request messages for camera and microphone on iOS using the expo-camera plugin in app.json.

```json
{
  "expo": {
    "plugins": [
      [
        "expo-camera",
        {
          "cameraPermission": "Allow $(PRODUCT_NAME) to access your camera for video calls",
          "microphonePermission": "Allow $(PRODUCT_NAME) to access your microphone for audio calls"
        }
      ]
    ]
  }
}
```

--------------------------------

### engine.setCameraCapturerConfiguration

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Configures the camera direction, focal length, resolution, and frame format for local video capture. It also includes methods for switching cameras, applying zoom, and setting focus points.

```APIDOC
## `engine.setCameraCapturerConfiguration` — Camera configuration

Configures the camera direction, focal length, resolution, and frame format for local video capture.

```typescript
import { CameraDirection, CameraFocalLengthType } from 'react-native-agora';

// Switch to front camera
engine.setCameraCapturerConfiguration({
  cameraDirection: CameraDirection.CameraFront,
  followEncodeDimensionRatio: true,
});

// Use ultra-wide rear camera (iOS multi-lens)
engine.setCameraCapturerConfiguration({
  cameraDirection: CameraDirection.CameraRear,
  cameraFocalLengthType: CameraFocalLengthType.CameraFocalLengthUltraWide,
});

// Dynamically switch camera during call
engine.switchCamera();

// Camera zoom
if (engine.isCameraZoomSupported()) {
  engine.setCameraZoomFactor(2.0);  // 2x zoom
}

// Tap-to-focus
engine.setCameraFocusPositionInPreview(0.5, 0.5); // center
```
```

--------------------------------

### Capture Video Frame as Image with react-native-agora

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Use `takeSnapshot` to capture a frame from local or remote video streams. Configure snapshot parameters like file path and format using `takeSnapshotWithConfig`. Listen for completion events with `onSnapshotTaken`.

```typescript
import { SnapshotConfig } from 'react-native-agora';

// Capture local video (uid=0)
engine.takeSnapshot(0, '/sdcard/snapshot_local.jpg');

// Capture remote user video
engine.takeSnapshot(remoteUid, '/sdcard/snapshot_remote.jpg');

// With config (filePath and format)
const config: SnapshotConfig = {
  filePath: '/sdcard/snapshot.jpg',
};
engine.takeSnapshotWithConfig(0, config);

engine.addListener('onSnapshotTaken', (connection, uid, filePath, width, height, errCode) => {
  if (errCode === 0) {
    console.log(`Snapshot saved: ${filePath} (${width}x${height})`);
  } else {
    console.error('Snapshot failed:', errCode);
  }
});
```

--------------------------------

### Enable/Disable Audio Module

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Controls the local audio module, including microphone capture and audio playback. Use this to manage audio stream transmission and reception.

```typescript
// Enable audio
engine.enableAudio();

// Set audio profile and scenario
engine.setAudioProfile(
  AudioProfileType.AudioProfileMusicHighQualityStereo,
  AudioScenarioType.AudioScenarioGameStreaming
);

// Mute/unmute local microphone
engine.muteLocalAudioStream(true);   // mute self
engine.muteLocalAudioStream(false);  // unmute

// Mute all remote audio
engine.muteAllRemoteAudioStreams(true);

// Enable volume indication — fires onAudioVolumeIndication every 200ms
engine.enableAudioVolumeIndication(200, 3, false);

engine.addListener('onAudioVolumeIndication', (connection, speakers, speakerNumber, totalVolume) => {
  speakers.forEach(({ uid, volume, vad }) => {
    console.log(`uid=${uid} volume=${volume} speaking=${vad === 1}`);
  });
});
```

--------------------------------

### Run Expo App on Android

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/examples/expo/README.md

Command to compile and run your Expo app in a debug build on an Android emulator or device.

```bash
npx expo run:android
```

--------------------------------

### Voice Effects and Presets

Source: https://context7.com/agoraio-extensions/react-native-agora/llms.txt

Applies real-time voice transformation presets for beautification, audio scenes, and voice conversion. Custom pitch and equalization can also be set after disabling presets. AI noise suppression can be configured.

```APIDOC
## `engine.setAudioEffectPreset` / `engine.setVoiceBeautifierPreset` — Voice effects

Applies real-time voice transformation presets including chat beautifier, singing beautifier, and audio effect scenes.

```typescript
import {
  AudioEffectPreset,
  VoiceBeautifierPreset,
  VoiceConversionPreset,
} from 'react-native-agora';

// Voice beautifier (for music or chat)
engine.setVoiceBeautifierPreset(VoiceBeautifierPreset.ChatBeautifierMagnetic);

// Audio scene effects
engine.setAudioEffectPreset(AudioEffectPreset.RoomAcousticsKtv);
engine.setAudioEffectPreset(AudioEffectPreset.VoiceChangerEffectOldMan);

// Voice conversion (changes gender/age)
engine.setVoiceConversionPreset(VoiceConversionPreset.VoiceChangerNeutral);

// Custom pitch + equalization (disable presets first)
engine.setAudioEffectPreset(AudioEffectPreset.AudioEffectOff);
engine.setLocalVoicePitch(1.2);
engine.setLocalVoiceEqualization(AudioEqualizationBandFrequency.AudioEqualizationBand1k, 6);

// AI noise suppression
engine.setAINSMode(true, AudioAinsMode.AinsModeAggressive);
```
```

--------------------------------

### Run Expo App on iOS

Source: https://github.com/agoraio-extensions/react-native-agora/blob/main/examples/expo/README.md

Command to compile and run your Expo app in a debug build on an iOS simulator or device.

```bash
npx expo run:ios
```