The LiveKit icon, the name of the repository and some sample code in the background. # React Native client SDK for LiveKit Use this SDK to add realtime video, audio and data features to your React Native app. By connecting to LiveKit Cloud or a self-hosted server, you can quickly build applications such as multi-modal AI, live streaming, or video calls with just a few lines of code. > [!NOTE] > This is v2 of the React-Native SDK. When migrating from v1.x to v2.x you might encounter a small set of breaking changes. > Read the [migration guide](https://docs.livekit.io/recipes/migrate-from-v1/) for a detailed overview of what has changed. > [!IMPORTANT] > If you're building Voice AI, [LiveKit Agents](https://github.com/livekit/agents) is the SDK for code-first realtime voice agents. STT, LLM, TTS, turn detection, [expressive speech](https://docs.livekit.io/agents/models/tts/expressive/), [keyterm accuracy](https://docs.livekit.io/agents/models/stt/keyterms/), tool usage, and telephony all come bundled in the framework. It's available in both [Python](https://github.com/livekit/agents) and [Node.js](https://github.com/livekit/agents-js). > > ```python > # agent.py > from livekit import agents > from livekit.agents import Agent, AgentServer, AgentSession, STTContextOptions, TurnHandlingOptions, inference > > server = AgentServer() > > > @server.rtc_session(agent_name="my-agent") > async def my_agent(ctx: agents.JobContext): > session = AgentSession( > stt=inference.STT(model="deepgram/nova-3", language="multi"), > llm=inference.LLM(model="google/gemma-4-31b-it"), > tts=inference.TTS(model="inworld/inworld-tts-2", voice="Ashley"), > turn_handling=TurnHandlingOptions(turn_detection=inference.TurnDetector()), > stt_context_options=STTContextOptions(keyterms=["LiveKit", "Acme Corp"]), > expressive=True, > ) > await session.start(room=ctx.room, agent=Agent(instructions="You are a helpful voice AI assistant.")) > await session.generate_reply(instructions="Greet the user and offer your assistance.") > > > if __name__ == "__main__": > agents.cli.run_app(server) > ``` > > Models come from [LiveKit Inference](https://docs.livekit.io/agents/models/) with no per-provider API keys, and LiveKit Cloud handles [deployment](https://docs.livekit.io/deploy/agents/) and [observability](https://docs.livekit.io/deploy/observability/). Visit the docs for more info at [docs.livekit.io/agents](https://docs.livekit.io/agents/). > > Using a coding agent? Install the LiveKit skill with `npx skills add livekit/agent-skills` and add the docs MCP at `https://docs.livekit.io/mcp/` (see [coding agent support](https://docs.livekit.io/intro/coding-agents/)). ## Installation ### NPM ```sh npm install @livekit/react-native @livekit/react-native-webrtc livekit-client ``` ### Yarn ```sh yarn add @livekit/react-native @livekit/react-native-webrtc livekit-client ``` This library depends on `@livekit/react-native-webrtc`, which has additional installation instructions found here: - [iOS Installation Guide](https://github.com/livekit/react-native-webrtc/blob/master/Documentation/iOSInstallation.md) - [Android Installation Guide](https://github.com/livekit/react-native-webrtc/blob/master/Documentation/AndroidInstallation.md) ### iOS Podfile This package depends on the `LiveKitWebRTC` pod, which is published to the [livekit/podspecs](https://github.com/livekit/podspecs) spec repo and the CocoaPods trunk. The CocoaPods trunk stops accepting new pods on December 2, 2026, so later `LiveKitWebRTC` versions will only be available from livekit/podspecs. Add both sources to the top of your `ios/Podfile`: ```ruby source 'https://github.com/livekit/podspecs.git' source 'https://cdn.cocoapods.org/' ``` Keep the `cdn.cocoapods.org` line: once a `Podfile` lists any `source`, CocoaPods stops using trunk by default, and your other pods still come from there. Expo users don't need to edit the `Podfile` by hand: version 1.1.0 and later of the [Expo plugin](https://github.com/livekit/client-sdk-react-native-expo-plugin) adds these sources during prebuild. --- Once the `@livekit/react-native-webrtc` dependency is installed, one last step is needed to finish the installation: ### Android
Java In your [MainApplication.java](https://github.com/livekit/client-sdk-react-native/blob/main/example/android/app/src/main/java/com/example/livekitreactnative/MainApplication.java) file: ```java import com.livekit.reactnative.LiveKitReactNative; import com.livekit.reactnative.audio.AudioType; public class MainApplication extends Application implements ReactApplication { @Override public void onCreate() { // Place this above any other RN related initialization // When AudioType is omitted, it'll default to CommunicationAudioType. // Use MediaAudioType if user is only consuming audio, and not publishing. LiveKitReactNative.setup(this, new AudioType.CommunicationAudioType()); //... } } ```
Kotlin In your **MainApplication.kt** file: ```kotlin import com.livekit.reactnative.LiveKitReactNative import com.livekit.reactnative.audio.AudioType class MainApplication : Application, ReactApplication() { override fun onCreate() { // Place this above any other RN related initialization // When AudioType is omitted, it'll default to CommunicationAudioType. // Use MediaAudioType if user is only consuming audio, and not publishing. LiveKitReactNative.setup(this, AudioType.CommunicationAudioType()) //... } } ```
### iOS
Objective-C In your [AppDelegate.m](https://github.com/livekit/client-sdk-react-native/blob/main/example/ios/LivekitReactNativeExample/AppDelegate.mm) file: ```objc #import "LivekitReactNative.h" #import "WebRTCModuleOptions.h" @implementation AppDelegate - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { // Place this above any other RN related initialization [LivekitReactNative setup]; // Uncomment the following lines if you want to use the camera in the background // Requires voip background mode and iOS 18+. // WebRTCModuleOptions *options = [WebRTCModuleOptions sharedInstance]; // options.enableMultitaskingCameraAccess = YES; //... } ```
Swift In your **AppDelegate.swift** file: ```swift import livekit_react_native import livekit_react_native_webrtc @main class AppDelegate: UIResponder, UIApplicationDelegate { func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil ) -> Bool { // Place this above any other RN related initialization LivekitReactNative.setup() // Uncomment the following lines if you want to use the camera in the background // Requires voip background mode and iOS 18+. // let options = WebRTCModuleOptions.sharedInstance() // options.enableMultitaskingCameraAccess = true // ... } } ```
### Expo LiveKit is available on Expo through development builds. You can find our Expo plugin and setup instructions [here](https://github.com/livekit/client-sdk-react-native-expo-plugin). ## Example app You can try our standalone example app [here](https://github.com/livekit-examples/react-native-meet/). ## Usage In your `index.js` file, setup the LiveKit SDK by calling `registerGlobals()`. This sets up the required WebRTC libraries for use in Javascript, and is needed for LiveKit to work. ```js import { registerGlobals } from '@livekit/react-native'; // ... registerGlobals(); ``` In your app, wrap your component in a `LiveKitRoom` component, which manages a Room object and allows you to use our hooks to create your own real-time video/audio app. ```js import * as React from 'react'; import { StyleSheet, View, FlatList, ListRenderItem, } from 'react-native'; import { useEffect } from 'react'; import { AudioSession, LiveKitRoom, useTracks, TrackReferenceOrPlaceholder, VideoTrack, isTrackReference, registerGlobals, } from '@livekit/react-native'; import { Track } from 'livekit-client'; const wsURL = "wss://example.com" const token = "your-token-here" export default function App() { // Start the audio session first. useEffect(() => { let start = async () => { await AudioSession.startAudioSession(); }; start(); return () => { AudioSession.stopAudioSession(); }; }, []); return ( ); }; const RoomView = () => { // Get all camera tracks. // The useTracks hook grabs the tracks from LiveKitRoom component // providing the context for the Room object. const tracks = useTracks([Track.Source.Camera]); const renderTrack: ListRenderItem = ({item}) => { // Render using the VideoTrack component. if(isTrackReference(item)) { return () } else { return () } }; return ( ); }; const styles = StyleSheet.create({ container: { flex: 1, alignItems: 'stretch', justifyContent: 'center', }, participantView: { height: 300, }, }); ``` [API documentation is located here.](https://htmlpreview.github.io/?https://raw.githubusercontent.com/livekit/client-sdk-react-native/main/docs/modules.html) Additional documentation for the LiveKit SDK can be found at https://docs.livekit.io/ ## Audio sessions As seen in the above example, we've introduced a class `AudioSession` that helps to manage the audio session on native platforms. This class wraps either [AudioManager](https://developer.android.com/reference/android/media/AudioManager) on Android, or [AVAudioSession](https://developer.apple.com/documentation/avfaudio/avaudiosession) on iOS. You can customize the configuration of the audio session with `configureAudio`. ### Android #### Media playback By default, the audio session is set up for bidirectional communication. In this mode, the audio framework exhibits the following behaviors: - The volume cannot be reduced to 0. - Echo cancellation is available and is enabled by default. - A microphone indicator can be displayed, depending on the platform. If you're leveraging LiveKit primarily for media playback, you have the option to reconfigure the audio session to better suit media playback. Here's how: ```js useEffect(() => { let connect = async () => { // configure audio session prior to starting it. await AudioSession.configureAudio({ android: { // currently supports .media and .communication presets audioTypeOptions: AndroidAudioTypePresets.media, }, }); await AudioSession.startAudioSession(); await room.connect(url, token, {}); }; connect(); return () => { room.disconnect(); AudioSession.stopAudioSession(); }; }, [url, token, room]); ``` #### Customizing audio session Instead of using our presets, you can further customize the audio session to suit your specific needs. ```js await AudioSession.configureAudio({ android: { preferredOutputList: ['earpiece'], // See [AudioManager](https://developer.android.com/reference/android/media/AudioManager) // for details on audio and focus modes. audioTypeOptions: { manageAudioFocus: true, audioMode: 'normal', audioFocusMode: 'gain', audioStreamType: 'music', audioAttributesUsageType: 'media', audioAttributesContentType: 'unknown', }, }, }); await AudioSession.startAudioSession(); ``` ### iOS For iOS, `registerGlobals()` automatically configures and activates the audio session based on WebRTC audio engine lifecycle events. This is enabled by default and is usually enough for voice and video apps: ```js registerGlobals(); ``` If your app manages `AVAudioSession` directly, disable the automatic setup: ```js registerGlobals({ autoConfigureAudioSession: false }); ``` For custom categories/modes, disable the default setup and pass a static policy to `setupIOSAudioManagement` once during app startup: ```js import { registerGlobals, setupIOSAudioManagement } from '@livekit/react-native'; registerGlobals({ autoConfigureAudioSession: false }); const cleanup = setupIOSAudioManagement(true, { recording: { audioCategory: 'playAndRecord', audioCategoryOptions: ['allowBluetooth', 'mixWithOthers'], audioMode: 'videoChat', }, playout: { audioCategory: 'playback', audioCategoryOptions: ['mixWithOthers'], audioMode: 'spokenAudio', }, }); ``` The older `useIOSAudioManagement(room, ...)` hook is still exported for backward compatibility, but it is deprecated. New code should prefer the startup-level audio engine integration above. ## Screenshare Enabling screenshare requires extra installation steps: ### Android Android screenshare requires a foreground service with type `mediaProjection` to be present. From version 2.4.0 onwards, the foreground service is handled internally, but you must declare the permission yourself in your app's AndroidManifest.xml file. ``` ``` ### iOS iOS screenshare requires adding a Broadcast Extension to your iOS project. Follow the integration instructions here: https://jitsi.github.io/handbook/docs/dev-guide/dev-guide-ios-sdk/#screen-sharing-integration It involves copying the files found in this [sample project](https://github.com/jitsi/jitsi-meet-sdk-samples/tree/18c35f7625b38233579ff34f761f4c126ba7e03a/ios/swift-screensharing/JitsiSDKScreenSharingTest/Broadcast%20Extension) to your iOS project, and registering a Broadcast Extension in Xcode. It's also recommended to use [CallKeep](https://github.com/react-native-webrtc/react-native-callkeep), to register a call with CallKit (as well as turning on the `voip` background mode). Due to background app processing limitations, screen recording may be interrupted if the app is restricted in the background. Registering with CallKit allows the app to continue processing for the duration of the call. Once setup, iOS screenshare can be initiated like so: ```js const screenCaptureRef = React.useRef(null); const screenCapturePickerView = Platform.OS === 'ios' && ( ); const startBroadcast = async () => { if (Platform.OS === 'ios') { const reactTag = findNodeHandle(screenCaptureRef.current); await NativeModules.ScreenCapturePickerViewManager.show(reactTag); room.localParticipant.setScreenShareEnabled(true); } else { room.localParticipant.setScreenShareEnabled(true); } }; return ( /*...*/ // Make sure the ScreenCapturePickerView exists in the view tree. {screenCapturePickerView} ); ``` ### Note You will not be able to publish camera or microphone tracks on iOS Simulator. ## Background Processing ### Android To support staying connected to LiveKit in the background, you will need a foreground service on Android. The example app uses [@supersami/rn-foreground-service](https://github.com/Raja0sama/rn-foreground-service) for this. Add the following permissions to your `AndroidManifest.xml` file: ```xml ``` Declare the the service and ensure it's labelled a `mediaProjection` service like so: ```xml ``` The camera and microphone permissions/foreground service types can be omitted if you are not using those. Once setup, [start the foreground service](https://github.com/livekit/client-sdk-react-native/blob/main/example/src/callservice/CallService.android.ts) to keep the app alive in the background. ### iOS By default, simple background processing can be enabled by selecting the `audio` and `voip` [UIBackgroundModes](https://developer.apple.com/documentation/bundleresources/information_property_list/uibackgroundmodes) in your XCode project. In your project, select your app target -> Signing & Capabilities -> Add Capability -> Background Modes. These background modes will keep the app alive in the background as long as a mic or audio track is playing. For a more robust background that isn't sensitive to the above conditions, we suggest using [CallKit](https://developer.apple.com/documentation/callkit/) to maintain the connection while in the background. The example uses [react-native-callkeep](https://github.com/react-native-webrtc/react-native-callkeep) for simple integration with CallKit. Our example code can be found [here](https://github.com/livekit/client-sdk-react-native/blob/main/example/src/callservice/CallService.ios.ts). For apps planning to use CallKit to handle incoming calls in the background, [it is important to call `RTCAudioSession.audioSessionDidActivate/Deactivate` when the call provider activates/deactivates the audio session.](https://github.com/livekit/react-native-webrtc/blob/master/Documentation/iOSInstallation.md#callkit) ## Troubleshooting #### Cannot read properties of undefined (reading 'split') This error could happen if you are using yarn and have incompatible versions of dependencies with livekit-client. To fix this, you can either: - use another package manager, like npm - use [yarn-deduplicate](https://www.npmjs.com/package/yarn-deduplicate) to deduplicate dependencies #### CocoaPods could not find compatible versions for pod "LiveKitWebRTC" This usually happens after upgrading `@livekit/react-native-webrtc`. The error may also say the matching specs "required a higher minimum deployment target", which is misleading. Make sure both [Podfile sources](#ios-podfile) are in your `ios/Podfile`, then run: ```sh cd ios && pod update LiveKitWebRTC ``` You may also see a `Found multiple specifications for LiveKitWebRTC` warning. It is harmless: some versions are published to both livekit/podspecs and CocoaPods trunk, and the two are identical. ## Contributing See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow. ## License Apache License 2.0
LiveKit Ecosystem
Agents SDKsPython · Node.js
LiveKit SDKsBrowser · Swift · Android · Flutter · React Native · Rust · Node.js · Python · Unity · Unity (WebGL) · ESP32 · C++
Starter AppsPython Agent · TypeScript Agent · React App · SwiftUI App · Android App · Flutter App · React Native App · Web Embed
UI ComponentsReact · Android Compose · SwiftUI · Flutter
Server APIsNode.js · Golang · Ruby · Java/Kotlin · Python · Rust · PHP (community) · .NET (community)
ResourcesDocs · Docs MCP Server · CLI · LiveKit Cloud
LiveKit Server OSSLiveKit server · Egress · Ingress · SIP
CommunityDeveloper Community · Slack · X · YouTube