or add it manually with the following JSON: ```json { "mcpServers": { "agora-docs": { "url": "https://mcp.agora.io" } } } ``` * **Claude Code** Run the following command in your terminal to install the MCP server in [Claude Code](https://claude.com/product/claude-code): ```bash claude mcp add --transport http agora-docs https://mcp.agora.io ``` * **Claude Desktop** In **Settings**, select **Connectors** and then choose **Add custom connector**. Enter the following values and click **Add**: * **Name**: `agora-docs` * **Remote MCP server URL**: `https://mcp.agora.io` Run the following command in your terminal to install the server in [OpenAI Codex](https://openai.com/codex/): ```bash codex mcp add --url https://mcp.agora.io agora-docs ``` Run the following command in your terminal to install the server in [Gemini CLI](https://github.com/google-gemini/gemini-cli): ```bash gemini mcp add --transport http agora-docs https://mcp.agora.io ``` Add the server URL `https://mcp.agora.io` to your MCP client of choice. If prompted, set the transport to `http` or "Streamable HTTP". ### Getting started Once installed, your coding assistant has access to Agora's documentation through the MCP server. The assistant will intelligently use this resource when relevant to your questions. For more targeted results, mention Agora along with your target product and platform, such as 'iOS', 'Web', 'Conversational AI', 'Video Calling' in your prompts. ### System prompt This MCP works with all LLMs that support MCP, but performs best when the assistant understands facet-based exploration. Add the following prompt to your LLMs custom instructions: **System prompt for LLMs** ```markdown # Agora MCP Markdown - System Prompt You have access to Agora's documentation search via three tools: - `algolia_search_index_docs_platform_aware_markdown` - Full-text search with facets - `algolia_search_for_facet_values` - Browse products/platforms - `algolia_recommendations` - Find related documentation ## Key Behaviors **1. Use facets for discovery** - When users ask about "what's available", explore facets first - Example: User asks "what video products exist?" → Use `algolia_search_for_facet_values(facetName: "product", facetQuery: "video")` → Shows video-calling is the main product **2. Platform-aware searching** - Include target platform in search queries (iOS, Android, Web, etc.) - Results are intelligently ranked by platform relevance **3. Interpret facet results for refinement** - Search results include facet breakdowns by product and platform - Use these to suggest filtering: "15 results are for video-calling, 8 for voice-calling" **4. Maintain session continuity** - Use same sessionId (UUID) across related searches in a conversation - Improves ranking for follow-up queries ## Available Products & Platforms **Key Products:** conversational-ai, video-calling, broadcast-streaming, interactive-live-streaming, agora-chat, voice-calling, signaling, extensions-marketplace, interactive-whiteboard **Key Platforms:** android, web, ios, windows, macos, unity, flutter, react-native, electron, unreal ## Workflow Example User: "I'm building an iOS app with Video Calling. Where do I start?" 1. Search: "iOS video calling quickstart" 2. Results show facets indicating video-calling is the best match 3. Suggest: "Most results are for Video Calling, here's the quickstart" 4. Follow-up searches: Keep same sessionId for context ``` #### What This Enables * Intelligent facet exploration before deep searches * Platform-aware result refinement suggestions * Cross-search session continuity for better context Without the prompt, searches still work but won't leverage faceted browsing patterns. ## AGENTS.md To get the most out of Agora Skills and the MCP server, Agora recommends that you include an [AGENTS.md](https://agents) or similar file in your repository. This file ensures that your agent always consults Agora docs to produce reliable, working code. Add the following instructions to your own `AGENTS.md` file: ```markdown ## Agora Documentation Agora documentation is updated frequently. You should always refer to the latest documentation when working with Agora products. Agora offers an MCP server that you can use to browse and search its documentation. If the developer has not yet installed this server, recommend that they install it at https://mcp.agora.io. If the Agora Skills files are available in your context, use them for platform-specific API guidance and code examples. ``` # Broadcast Streaming overview (/en/realtime-media/broadcast-streaming/product-overview) Agora's Broadcast Streaming API delivers low-latency, high-definition live video streaming at scale for one-to-many broadcast delivery. With support for cross-platform integration and adaptive streaming technologies, it ensures reliable, high-quality viewing experiences across a wide range of network conditions and devices. Reach global audiences with smooth, uninterrupted broadcasts for large-scale events such as concerts, sports, conferences, live shows, and other live production experiences. Enhance Agora's Video SDK with broadcast production capabilities such as recording, stream management, content moderation, and audience analytics, or leverage the Extensions Marketplace to enable AI-powered features like noise cancellation, video effects, and more. ## Start building ## Product Features * **Global coverage** - Agora’s Software-Defined Real-Time Network (SDRTN®) supports video users in over 200 countries and regions. * **High-quality video at scale** - Consistent high-quality video from few to thousands of concurrent users, even under challenging network conditions. * **Multiple audio and video tracks** - Publish multiple audio and video tracks to one or more channels from a single instance, with support for multi-channel capture cameras and microphones. * **Screen sharing and collaboration** - Enable screen sharing or interactive whiteboards that allow users to draw, annotate, and share content from multiple devices simultaneously. * **AI-powered audio enhancement** - Support for high quality audio with 3D spatial audio, AI noise suppression, and gain control to provide an immersive audio experience. * **Recording** - Record video sessions in the cloud or on premises with control over the format, path of storage, and quality. # Quickstart (/en/realtime-media/broadcast-streaming/quickstart) This page provides a step-by-step guide on how to create a basic Broadcast Streaming app using the Agora Video SDK. ## Understand the tech To start a Broadcast Streaming session, implement the following steps in your app: * **Initialize the Agora Engine**: Before calling other APIs, create and initialize an Agora Engine instance. * **Join a channel**: Call methods to create and join a channel. * **Join as a host**: A live streaming event has one or more hosts. A host publishes audio and video to the channel. Hosts can also subscribe to streams from other hosts. * **Join as audience**: Audience members can only subscribe to streams published by hosts. * **Send and receive audio and video**: Hosts publish streams to the channel. Audience members subscribe to audio and video streams published by hosts. ![Streaming workflow](https://assets-docs.agora.io/images/video-sdk/get-started-ils-bs.svg) ## Prerequisites * [Android Studio](https://developer.android.com/studio) 4.2 or higher. * Android SDK API Level 21 or higher. * Two mobile devices running Android 5.0 or higher. * A camera and a microphone * A valid Agora account and project. Please refer to [Agora account management](/en/introduction/account) for details. ## Set up your project This section shows you how to set up your Android project and install the Agora Video SDK. **Create a new project** 1. Create a [new project](https://developer.android.com/studio/projects/create-project). 1. Open Android Studio and select **File > New > New Project...**. 2. Select **Phone and Tablet** > **Empty Activity** and click **Next**. 3. Set the project name and storage path. 4. Select **Java** or **Kotlin** as the language, and click **Finish** to create the Android project. After you create a project, Android Studio automatically starts gradle sync. Ensure that the synchronization is successful before proceeding to the next step. **Add to an existing project** 1. Add a new activity to your project. 1. Open your project in Android Studio. 2. Right-click on the `app/src/main/java/` folder. 3. Select **New → Activity → Empty Activity**. 4. Enter an activity name and click **Finish**. This guide uses `MainActivity` as the activity name in the sample code. Replace it with your activity name where required. 2. Add a layout file for your activity. Set up two container elements in your activity to display local and remote video streams. Refer to [Create a user interface](#create-a-user-interface) to get a bare bones sample layout. ### Install the SDK Use either of the following methods to add Video SDK to your project. **Maven Central** 1. Open the `settings.gradle` file in the project's root directory and add the Maven Central dependency, if it doesn't already exist: ```text repositories { mavenCentral() } ``` If your Android project uses dependencyResolutionManagement, the method of adding the Maven Central dependency may differ. 2. To integrate the Video SDK into your Android project, add the following to the `dependencies` block in your project module `build.gradle` file: * Groovy `build.gradle` ```json implementation 'io.agora.rtc:full-sdk:x.y.z' ``` * Kotlin `build.gradle.kts` ```kotlin implementation("io.agora.rtc:full-sdk:x.y.z") ``` Replace `x.y.z` with the specific SDK version number, such as `4.5.0`. To get the latest version number, check the [Release notes](reference/release-notes). To integrate the Lite SDK, use `io.agora.rtc:lite-sdk` instead. 3. Prevent code obfuscation Open the `/app/proguard-rules.pro` file and add the following lines to prevent the Video SDK code from being obfuscated: ```java -keep class io.agora.** { *; } -dontwarn io.agora.** ``` **Manual integration** 1. Download the latest version of Video SDK from the [SDKs](/en/api-reference/sdks?product=video\&platform=android) page and unzip it. 2. Open the unzipped file and copy the following files or subfolders to your project path. | File or folder | Project path | | :----------------------------------- | :----------------------- | | `agora-rtc-sdk.jar` file | `/app/libs/` | | `arm64-v8a` folder | `/app/src/main/jniLibs/` | | `armeabi-v7a` folder | `/app/src/main/jniLibs/` | | `x86` folder | `/app/src/main/jniLibs/` | | `x86_64` folder | `/app/src/main/jniLibs/` | | `high_level_api` in `include` folder | `/app/src/main/jniLibs/` | 3. Select the file `/app/libs/agora-rtc-sdk.jar` in the left navigation bar of Android Studio project files, right-click, and select **add as a library** from the drop-down menu. 4. Prevent code obfuscation Open the `/app/proguard-rules.pro` file and add the following lines to prevent the Video SDK code from being obfuscated: ```java -keep class io.agora.** { *; } -dontwarn io.agora.** ``` ## Implement Broadcast Streaming This section guides you through the implementation of basic real-time audio and video interaction in your app. The following figure illustrates the essential steps: ![Quick start sequence](https://assets-docs.agora.io/images/video-sdk/quick-start-sequence.svg) This guide includes [complete sample code](#complete-sample-code) that demonstrates implementing basic real-time interaction. To understand the core API calls in the sample code, review the following implementation steps and use the code in your `MainActivity` file. ### Import Agora classes Import the relevant Agora classes and interfaces: Java Kotlin ```java import io.agora.rtc2.Constants; import io.agora.rtc2.IRtcEngineEventHandler; import io.agora.rtc2.RtcEngine; import io.agora.rtc2.RtcEngineConfig; import io.agora.rtc2.video.VideoCanvas; import io.agora.rtc2.ChannelMediaOptions; ``` ```kotlin import io.agora.rtc2.Constants import io.agora.rtc2.IRtcEngineEventHandler import io.agora.rtc2.RtcEngine import io.agora.rtc2.RtcEngineConfig import io.agora.rtc2.video.VideoCanvas import io.agora.rtc2.ChannelMediaOptions ``` ### Initialize the engine For real-time communication, initialize an `RtcEngine` instance and set up event handlers to manage user interactions within the channel. Use `RtcEngineConfig` to specify the application context, [App ID](/en/introduction/account), and custom [event handler](#subscribe-to--events), then call `RtcEngine.create(config)` to initialize the engine, enabling further channel operations. In your `MainActivity` file, add the following code: Java Kotlin ```java // Fill in the app ID from Agora Console private String myAppId = ""; private RtcEngine mRtcEngine; private void initializeAgoraVideoSDK() { try { RtcEngineConfig config = new RtcEngineConfig(); config.mContext = getBaseContext(); config.mAppId = myAppId; config.mEventHandler = mRtcEventHandler; mRtcEngine = RtcEngine.create(config); } catch (Exception e) { throw new RuntimeException("Error initializing RTC engine: " + e.getMessage()); } } ``` ```kotlin // Fill in the App ID obtained from the Agora Console private val myAppId = "" private var mRtcEngine: RtcEngine? = null private fun initializeRtcEngine() { try { val config = RtcEngineConfig().apply { mContext = applicationContext mAppId = myAppId mEventHandler = mRtcEventHandler } mRtcEngine = RtcEngine.create(config) } catch (e: Exception) { throw RuntimeException("Error initializing RTC engine: ${e.message}") } } ``` ### Join a channel To join a channel, call `joinChannel` with the following parameters: * **Channel name**: The name of the channel to join. Clients that pass the same channel name join the same channel. If a channel with the specified name does not exist, it is created when the first user joins. * **Authentication token**: A dynamic key that authenticates a user when the client joins a channel. In a production environment, you obtain a token from a [token server](build/authenticate-users/deploy-token-server.mdx) in your security infrastructure. For the purpose of this guide [Generate a temporary token](/en/introduction/account). * **User ID**: A 32-bit signed integer that identifies a user in the channel. You can specify a unique user ID for each user yourself. If you set the user ID to `0` when joining a channel, the SDK generates a random number for the user ID and returns the value in the `onJoinChannelSuccess` callback. * **Channel media options**: Configure `ChannelMediaOptions` to define publishing and subscription settings, optimize performance for your specific use-case, and set optional parameters. For Broadcast Streaming, set the `channelProfile` to `CHANNEL_PROFILE_LIVE_BROADCASTING`, the `clientRoleType` to `CLIENT_ROLE_BROADCASTER` (host) or `CLIENT_ROLE_AUDIENCE`, and the `audienceLatencyLevel` to `AUDIENCE_LATENCY_LEVEL_LOW_LATENCY`. Java Kotlin ```java // Fill in the channel name private String channelName = ""; // Fill in the temporary token generated from Agora Console private String token = ""; private void joinChannel() { // Create an instance of ChannelMediaOptions and configure it ChannelMediaOptions options = new ChannelMediaOptions(); // Set the user role to BROADCASTER or AUDIENCE according to the use-case options.clientRoleType = Constants.CLIENT_ROLE_BROADCASTER; // In the broadcast streaming use-case, set the channelProfile to BROADCASTING options.channelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING; // Set the latency level for audience options.audienceLatencyLevel = Constants.AUDIENCE_LATENCY_LEVEL_LOW_LATENCY; // Publish local media options.publishCameraTrack = true; options.publishMicrophoneTrack = true; mRtcEngine.joinChannel(token, channelName, 0, options); } ``` ```kotlin // Fill in the channel name private val channelName = "" // Fill in the temporary token generated from Agora Console private val token = "" private fun joinChannel() { // Create an instance of ChannelMediaOptions and configure it val options = ChannelMediaOptions().apply { // Set the user role to BROADCASTER or AUDIENCE according to the use-case clientRoleType = Constants.CLIENT_ROLE_BROADCASTER // In the broadcast streaming use-case, set the channelProfile to BROADCASTING channelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING // Set the latency level for audience audienceLatencyLevel = Constants.AUDIENCE_LATENCY_LEVEL_LOW_LATENCY // Publish local media publishMicrophoneTrack = true publishCameraTrack = true } mRtcEngine?.joinChannel(token, channelName, 0, options) } ``` ### Subscribe to Video SDK events The Video SDK provides an interface for subscribing to channel events. To use it, create an instance of `IRtcEngineEventHandler` and implement the event methods you want to handle. To ensure that you receive all Video SDK events, set the Agora Engine event handler before joining a channel. Java Kotlin ```java private final IRtcEngineEventHandler mRtcEventHandler = new IRtcEngineEventHandler() { // Triggered when the local user successfully joins the specified channel. @Override public void onJoinChannelSuccess(String channel, int uid, int elapsed) { super.onJoinChannelSuccess(channel, uid, elapsed); showToast("Joined channel " + channel); } // Triggered when a remote user/host joins the channel. @Override public void onUserJoined(int uid, int elapsed) { super.onUserJoined(uid, elapsed); runOnUiThread(() -> { // Initialize and display remote video view for the new user. setupRemoteVideo(uid); showToast("User joined: " + uid); }); } // Triggered when a remote user/host leaves the channel. @Override public void onUserOffline(int uid, int reason) { super.onUserOffline(uid, reason); runOnUiThread(() -> { showToast("User offline: " + uid); }); } }; ``` ```kotlin private val mRtcEventHandler = object : IRtcEngineEventHandler() { override fun onJoinChannelSuccess(channel: String?, uid: Int, elapsed: Int) { super.onJoinChannelSuccess(channel, uid, elapsed) runOnUiThread { showToast("Joined channel $channel") } } override fun onUserJoined(uid: Int, elapsed: Int) { runOnUiThread { showToast("User joined: $uid") } } override fun onUserOffline(uid: Int, reason: Int) { super.onUserOffline(uid, reason) runOnUiThread { showToast("User offline: $uid") } } } ``` ### Enable the video module Follow these steps to enable the video module: 1. Call `enableVideo` to enable the video module. 2. Call `startPreview` to enable local video preview. Java Kotlin ```java private void enableVideo() { mRtcEngine.enableVideo(); mRtcEngine.startPreview(); } ``` ```kotlin private fun enableVideo() { mRtcEngine?.apply { enableVideo() startPreview() } } ``` ### Display the local video Call `setupLocalVideo` to initialize the local view and set the local video display properties. Java Kotlin ```java private void setupLocalVideo() { FrameLayout container = findViewById(R.id.local_video_view_container); SurfaceView surfaceView = new SurfaceView(getBaseContext()); container.addView(surfaceView); mRtcEngine.setupLocalVideo(new VideoCanvas(surfaceView, VideoCanvas.RENDER_MODE_FIT, 0)); } ``` ```kotlin /** * Initializes the local video view and sets the display properties. * This method adds a SurfaceView to the local video container and configures it. */ private fun setupLocalVideo() { val container: FrameLayout = findViewById(R.id.local_video_view_container) val surfaceView = SurfaceView(baseContext) container.addView(surfaceView) mRtcEngine.setupLocalVideo(VideoCanvas(surfaceView, VideoCanvas.RENDER_MODE_FIT, 0)) } ``` ### Display remote video When a remote user joins the channel, call `setupRemoteVideo` and pass in the remote user's `uid`, obtained from the `onUserJoined` callback, to display the remote video. Java Kotlin ```java private void setupRemoteVideo(int uid) { FrameLayout container = findViewById(R.id.remote_video_view_container); SurfaceView surfaceView = new SurfaceView(getBaseContext()); surfaceView.setZOrderMediaOverlay(true); container.addView(surfaceView); mRtcEngine.setupRemoteVideo(new VideoCanvas(surfaceView, VideoCanvas.RENDER_MODE_FIT, uid)); } ``` ```kotlin private fun setupRemoteVideo(uid: Int) { val container = findViewById(R.id.remote_video_view_container) val surfaceView = SurfaceView(baseContext).apply { setZOrderMediaOverlay(true) } container.addView(surfaceView) mRtcEngine.setupRemoteVideo(VideoCanvas(surfaceView, VideoCanvas.RENDER_MODE_FIT, uid)) } ``` ### Handle permissions To access the camera and microphone on Android devices, declare the necessary permissions in the app's manifest and ensure that the user grants these permissions when the app starts. 1. Open your project's `AndroidManifest.xml` file and add the following permissions before ``: ```xml

``` 2. Use the following code to handle runtime permissions in your Android app. The logic ensures that the necessary permissions are granted before starting Broadcast Streaming. In your `MainActivity` file, add the following code: Java Kotlin ```java private boolean checkPermissions() { for (String permission : getRequiredPermissions()) { if (ContextCompat.checkSelfPermission(this, permission) != PackageManager.PERMISSION_GRANTED) { return false; } } return true; } private String[] getRequiredPermissions() { if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.S) { return new String[]{ Manifest.permission.RECORD_AUDIO, Manifest.permission.CAMERA, Manifest.permission.READ_PHONE_STATE, Manifest.permission.BLUETOOTH_CONNECT }; } else { return new String[]{ Manifest.permission.RECORD_AUDIO, Manifest.permission.CAMERA }; } } @Override public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) { if (requestCode == PERMISSION_REQ_ID && checkPermissions()) { startBroadcastStreaming(); } } ``` ```kotlin private val PERMISSION_REQ_ID = 22 private fun requestPermissions() { ActivityCompat.requestPermissions(this, getRequiredPermissions(), PERMISSION_REQ_ID) } private fun checkPermissions(): Boolean { for (permission in getRequiredPermissions()) { if (ContextCompat.checkSelfPermission(this, permission) != PackageManager.PERMISSION_GRANTED) { return false } } return true } private fun getRequiredPermissions(): Array { return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) { arrayOf( Manifest.permission.RECORD_AUDIO, Manifest.permission.CAMERA, Manifest.permission.READ_PHONE_STATE, Manifest.permission.BLUETOOTH_CONNECT ) } else { arrayOf( Manifest.permission.RECORD_AUDIO, Manifest.permission.CAMERA ) } } override fun onRequestPermissionsResult( requestCode: Int, permissions: Array, grantResults: IntArray ) { super.onRequestPermissionsResult(requestCode, permissions, grantResults) if (requestCode == PERMISSION_REQ_ID && checkPermissions()) { startBroadcastStreaming() } } ``` ### Start and close the app When a user launches your app, start real-time interaction. When a user closes the app, stop the interaction. 1. In the `onCreate` callback, check whether the app has been granted the required permissions. If the permissions have not been granted, request the required permissions from the user. If permissions are granted, initialize `RtcEngine` and join a channel. Java Kotlin ```java @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); if (checkPermissions()) { startBroadcastStreaming(); } else { requestPermissions(); } } ``` ```kotlin override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) if (checkPermissions()) { startBroadcastStreaming() } else { requestPermissions() } } ``` 2. When a user closes the app, or switches the app to the background, call `stopPreview` to stop the video preview and then call `leaveChannel` to leave the current channel and release all session-related resources. Java Kotlin ```java private void cleanupAgoraEngine() { if (mRtcEngine != null) { mRtcEngine.stopPreview(); mRtcEngine.leaveChannel(); mRtcEngine = null; } } ``` ```kotlin private fun cleanupAgoraEngine() { mRtcEngine?.apply { stopPreview() leaveChannel() } mRtcEngine = null } ``` ### Complete sample code A complete code sample demonstrating the basic process of real-time interaction is provided for your reference. To use the sample code, copy the following lines into the `MainActivity` file in your project. Then, replace `` in package `com.example.` with your project's name. Java Kotlin ```java package com.example. import android.Manifest; import android.content.pm.PackageManager; import android.os.Bundle; import android.view.SurfaceView; import android.widget.FrameLayout; import android.widget.Toast; import androidx.annotation.NonNull; import androidx.appcompat.app.AppCompatActivity; import androidx.core.app.ActivityCompat; import androidx.core.content.ContextCompat; import io.agora.rtc2.ChannelMediaOptions; import io.agora.rtc2.Constants; import io.agora.rtc2.IRtcEngineEventHandler; import io.agora.rtc2.RtcEngine; import io.agora.rtc2.RtcEngineConfig; import io.agora.rtc2.video.VideoCanvas; public class MainActivity extends AppCompatActivity { private static final int PERMISSION_REQ_ID = 22; // Fill in the app ID from Agora Console private String myAppId = ""; // Fill in the channel name private String channelName = ""; // Fill in the temporary token generated from Agora Console private String token = ""; private RtcEngine mRtcEngine; private final IRtcEngineEventHandler mRtcEventHandler = new IRtcEngineEventHandler() { // Callback when successfully joining the channel @Override public void onJoinChannelSuccess(String channel, int uid, int elapsed) { super.onJoinChannelSuccess(channel, uid, elapsed); showToast("Joined channel " + channel); } // Callback when a remote user or host joins the current channel @Override public void onUserJoined(int uid, int elapsed) { super.onUserJoined(uid, elapsed); runOnUiThread(() -> { // When a remote user joins the channel, display the remote video stream for the specified uid setupRemoteVideo(uid); showToast("User joined: " + uid); // Show toast for user joining }); } // Callback when a remote user or host leaves the current channel @Override public void onUserOffline(int uid, int reason) { super.onUserOffline(uid, reason); runOnUiThread(() -> { showToast("User offline: " + uid); // Show toast for user going offline }); } }; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); if (checkPermissions()) { startBroadcastStreaming(); } else { requestPermissions(); } } private void requestPermissions() { ActivityCompat.requestPermissions(this, getRequiredPermissions(), PERMISSION_REQ_ID); } private boolean checkPermissions() { for (String permission : getRequiredPermissions()) { if (ContextCompat.checkSelfPermission(this, permission) != PackageManager.PERMISSION_GRANTED) { return false; } } return true; } private String[] getRequiredPermissions() { if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.S) { return new String[]{ Manifest.permission.RECORD_AUDIO, Manifest.permission.CAMERA, Manifest.permission.READ_PHONE_STATE, Manifest.permission.BLUETOOTH_CONNECT }; } else { return new String[]{ Manifest.permission.RECORD_AUDIO, Manifest.permission.CAMERA }; } } @Override public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) { super.onRequestPermissionsResult(requestCode, permissions, grantResults); if (requestCode == PERMISSION_REQ_ID && checkPermissions()) { startBroadcastStreaming(); } } private void startBroadcastStreaming() { initializeAgoraVideoSDK(); enableVideo(); setupLocalVideo(); joinChannel(); } private void initializeAgoraVideoSDK() { try { RtcEngineConfig config = new RtcEngineConfig(); config.mContext = getBaseContext(); config.mAppId = myAppId; config.mEventHandler = mRtcEventHandler; mRtcEngine = RtcEngine.create(config); } catch (Exception e) { throw new RuntimeException("Error initializing RTC engine: " + e.getMessage()); } } private void enableVideo() { mRtcEngine.enableVideo(); mRtcEngine.startPreview(); } private void setupLocalVideo() { FrameLayout container = findViewById(R.id.local_video_view_container); SurfaceView surfaceView = new SurfaceView(getBaseContext()); container.addView(surfaceView); mRtcEngine.setupLocalVideo(new VideoCanvas(surfaceView, VideoCanvas.RENDER_MODE_FIT, 0)); } private void joinChannel() { // Create an instance of ChannelMediaOptions and configure it ChannelMediaOptions options = new ChannelMediaOptions(); // Set the user role to BROADCASTER or AUDIENCE according to the use-case options.clientRoleType = Constants.CLIENT_ROLE_BROADCASTER; // In the live broadcast use-case, set the channel profile to BROADCASTING (live broadcast use-case) options.channelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING; // Set the audience latency level options.audienceLatencyLevel = Constants.AUDIENCE_LATENCY_LEVEL_LOW_LATENCY; // Publish local media options.publishCameraTrack = true; options.publishMicrophoneTrack = true; mRtcEngine.joinChannel(token, channelName, 0, options); } private void setupRemoteVideo(int uid) { FrameLayout container = findViewById(R.id.remote_video_view_container); SurfaceView surfaceView = new SurfaceView(getBaseContext()); surfaceView.setZOrderMediaOverlay(true); container.addView(surfaceView); mRtcEngine.setupRemoteVideo(new VideoCanvas(surfaceView, VideoCanvas.RENDER_MODE_FIT, uid)); } @Override protected void onDestroy() { super.onDestroy(); cleanupAgoraEngine(); } private void cleanupAgoraEngine() { if (mRtcEngine != null) { mRtcEngine.stopPreview(); mRtcEngine.leaveChannel(); mRtcEngine = null; } } private void showToast(String message) { runOnUiThread(() -> Toast.makeText(MainActivity.this, message, Toast.LENGTH_SHORT).show()); } } ``` ```kotlin package com.example. import android.Manifest import android.content.pm.PackageManager import android.os.Build import android.os.Bundle import android.view.SurfaceView import android.widget.FrameLayout import android.widget.Toast import androidx.appcompat.app.AppCompatActivity import androidx.core.app.ActivityCompat import androidx.core.content.ContextCompat import io.agora.rtc2.ChannelMediaOptions import io.agora.rtc2.Constants import io.agora.rtc2.IRtcEngineEventHandler import io.agora.rtc2.RtcEngine import io.agora.rtc2.RtcEngineConfig import io.agora.rtc2.video.VideoCanvas class MainActivity : AppCompatActivity() { private val PERMISSION_REQ_ID = 22 private val myAppId = "" private val channelName = "" private val token = "" private var mRtcEngine: RtcEngine? = null private val mRtcEventHandler = object : IRtcEngineEventHandler() { override fun onJoinChannelSuccess(channel: String?, uid: Int, elapsed: Int) { super.onJoinChannelSuccess(channel, uid, elapsed) runOnUiThread { showToast("Joined channel $channel") } } override fun onUserJoined(uid: Int, elapsed: Int) { runOnUiThread { setupRemoteVideo(uid) } } override fun onUserOffline(uid: Int, reason: Int) { super.onUserOffline(uid, reason) runOnUiThread { showToast("User offline: $uid") } } } override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) if (checkPermissions()) { startBroadcastStreaming() } else { requestPermissions() } } private fun requestPermissions() { ActivityCompat.requestPermissions(this, getRequiredPermissions(), PERMISSION_REQ_ID) } private fun checkPermissions(): Boolean { for (permission in getRequiredPermissions()) { if (ContextCompat.checkSelfPermission(this, permission) != PackageManager.PERMISSION_GRANTED) { return false } } return true } private fun getRequiredPermissions(): Array { return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) { arrayOf( Manifest.permission.RECORD_AUDIO, Manifest.permission.CAMERA, Manifest.permission.READ_PHONE_STATE, Manifest.permission.BLUETOOTH_CONNECT ) } else { arrayOf( Manifest.permission.RECORD_AUDIO, Manifest.permission.CAMERA ) } } override fun onRequestPermissionsResult( requestCode: Int, permissions: Array, grantResults: IntArray ) { super.onRequestPermissionsResult(requestCode, permissions, grantResults) if (requestCode == PERMISSION_REQ_ID && checkPermissions()) { startBroadcastStreaming() } } private fun startBroadcastStreaming() { initializeAgoraVideoSDK() enableVideo() setupLocalVideo() joinChannel() } private fun initializeAgoraVideoSDK() { try { val config = RtcEngineConfig().apply { mContext = applicationContext mAppId = myAppId mEventHandler = mRtcEventHandler } mRtcEngine = RtcEngine.create(config) } catch (e: Exception) { throw RuntimeException("Error initializing RTC engine: ${e.message}") } } private fun enableVideo() { mRtcEngine?.apply { enableVideo() startPreview() } } private fun setupLocalVideo() { val container = findViewById(R.id.local_video_view_container) val surfaceView = SurfaceView(this) container.addView(surfaceView) mRtcEngine?.setupLocalVideo(VideoCanvas(surfaceView, VideoCanvas.RENDER_MODE_FIT, 0)) } private fun joinChannel() { val options = ChannelMediaOptions().apply { clientRoleType = Constants.CLIENT_ROLE_BROADCASTER channelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING audienceLatencyLevel = Constants.AUDIENCE_LATENCY_LEVEL_LOW_LATENCY publishMicrophoneTrack = true publishCameraTrack = true } mRtcEngine?.joinChannel(token, channelName, 0, options) } private fun setupRemoteVideo(uid: Int) { val container = findViewById(R.id.remote_video_view_container) val surfaceView = SurfaceView(this).apply { setZOrderMediaOverlay(true) } container.addView(surfaceView) mRtcEngine?.setupRemoteVideo(VideoCanvas(surfaceView, VideoCanvas.RENDER_MODE_FIT, uid)) } override fun onDestroy() { super.onDestroy() cleanupAgoraEngine() } private fun cleanupAgoraEngine() { mRtcEngine?.apply { stopPreview() leaveChannel() } mRtcEngine = null } private fun showToast(message: String) { runOnUiThread { Toast.makeText(this, message, Toast.LENGTH_SHORT).show() } } } ``` For the `myAppId` and `token` variables, replace the placeholders with the values you obtained from Agora Console. Ensure you enter the same `channelName` you used when generating the temporary token. ### Create a user interface To connect the sample code to your existing UI, ensure that your XML layout includes the container UI element IDs used to [Display the local video](#display-the-local-video) and [Display remote video](#display-remote-video). Alternatively, use the following sample code to generate a basic user interface. Replace the existing content in `/app/src/main/res/layout/activity_main.xml` with this code. ![UI design](https://assets-docs.agora.io/images/video-sdk/quickstart-ui-android-design.png) **Sample code to create the user interface** ```xml ``` ## Test the sample code Take the following steps to test the sample code: 1. In `MainActivity` update the values for `myAppId`, and `token` with values from Agora Console. Fill in the same `channelName` you used to generate the token. 2. Enable developer options on your Android test device. Turn on USB debugging, connect the Android device to your development machine through a USB cable, and check that your device appears in the Android device options. 3. In Android Studio, click ![image](https://assets-docs.agora.io/images/video-sdk/icon_android_gradle_sync.png) **Sync Project with Gradle Files** to resolve project dependencies and update the configuration. 4. After synchronization is successful, click ![image](https://assets-docs.agora.io/images/video-sdk/icon_android_run.png) **Run app**. Android Studio starts compilation. After a few moments, the app is installed on your Android device. 5. Launch the App, grant recording and camera permissions. If you set the user role to host, you will see yourself in the local view. 6. On a second Android device, repeat the previous steps to install and launch the app. Alternatively, use the [Web demo](https://webdemo-global.agora.io/example/quickStart/videoAndVoiceCalling/index.html) to join the same channel and test the following use-cases: * If users on both devices join the channel as hosts, they can see and hear each other. * If one user joins as host and the other as audience, the host can see themselves in the local video window; the audience can see the host in the remote video window and hear the host. ## Reference This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product. * If a firewall is deployed in your network environment, refer to [Connect with Cloud Proxy](build/optimize-quality-and-connection/cloud-proxy.mdx) to use Agora services normally. ### Next steps After implementing the quickstart sample, read the following documents to learn more: * To ensure communication security in a test or production environment, best practice is to obtain and use a token from an authentication server. For details, see [Secure authentication with tokens](build/authenticate-users/use-tokens.mdx). ### Sample project Agora provides open source sample projects on [GitHub](https://github.com/AgoraIO/API-Examples) for your reference. Download or view the [JoinChannelVideo](https://github.com/AgoraIO-Community/Agora-RTC-QuickStart/tree/main/Android/Agora-RTC-QuickStart-Android) project for a more detailed example. ### API reference * [`RtcEngineConfig`](https://api-ref.agora.io/en/video-sdk/android/4.x/API/class_rtcengineconfig.html) * [`create`](https://api-ref.agora.io/en/video-sdk/android/4.x/API/class_irtcengine.html#api_irtcengine_create) * [`ChannelMediaOptions`](https://api-ref.agora.io/en/video-sdk/android/4.x/API/class_channelmediaoptions.html) * [`joinChannel`](https://api-ref.agora.io/en/video-sdk/android/4.x/API/class_irtcengine.html#api_irtcengine_joinchannel2) * [`enableVideo`](https://api-ref.agora.io/en/video-sdk/android/4.x/API/class_irtcengine.html#api_irtcengine_enablevideo) * [`startPreview`](https://api-ref.agora.io/en/video-sdk/android/4.x/API/class_irtcengine.html#api_irtcengine_startpreview) * [`leaveChannel`](https://api-ref.agora.io/en/video-sdk/android/4.x/API/class_irtcengine.html#api_irtcengine_leavechannel) * [`IRtcEngineEventHandler`](https://api-ref.agora.io/en/video-sdk/android/4.x/API/class_irtcengineeventhandler.html#class_irtcengineeventhandler) ### Frequently asked questions * [How can I fix black screen issues?](/en/api-reference/faq/quality/video_blank) * [Why can't I turn on the camera?](/en/api-reference/faq/quality/video_camera) * [How can I listen for audience joining or leaving a channel?](/en/api-reference/faq/integration/audience_event) * [How can I solve channel-related issues?](/en/api-reference/faq/integration/channel) * [How can I set the log file?](/en/api-reference/faq/integration/set_log_file) * [Why do apps on some Android versions fail to capture audio and video after screen locking or switching to the background?](/en/api-reference/faq/quality/android_background) ### See also * [Error codes](reference/error-codes.md) * [Connection status management](build/optimize-quality-and-connection/connection-status-management.mdx) ## Platform-specific versions - [Android](/en/realtime-media/broadcast-streaming/quickstart/android.md) - [iOS](/en/realtime-media/broadcast-streaming/quickstart/ios.md) - [macOS](/en/realtime-media/broadcast-streaming/quickstart/macos.md) - [Web](/en/realtime-media/broadcast-streaming/quickstart/web.md) - [Windows](/en/realtime-media/broadcast-streaming/quickstart/windows.md) - [Electron](/en/realtime-media/broadcast-streaming/quickstart/electron.md) - [Flutter](/en/realtime-media/broadcast-streaming/quickstart/flutter.md) - [React Native](/en/realtime-media/broadcast-streaming/quickstart/react-native.md) - [JavaScript](/en/realtime-media/broadcast-streaming/quickstart/javascript.md) - [Unity](/en/realtime-media/broadcast-streaming/quickstart/unity.md) - [Unreal Engine](/en/realtime-media/broadcast-streaming/quickstart/unreal.md) - [Unreal Blueprint](/en/realtime-media/broadcast-streaming/quickstart/blueprint.md) - [Python](/en/realtime-media/broadcast-streaming/quickstart/python.md) # Agora skills (/en/realtime-media/broadcast-streaming/skills) Agora skills is a set of structured reference files that give AI coding assistants deep knowledge of Agora's platform. When you ask your assistant to build something with Agora, it loads the relevant skill files covering products, APIs, and platform-specific code examples, so it can generate working code without guessing. Skills includes integration with the [Agora MCP server](#agora-mcp-server), which gives your assistant access to live Agora documentation. For installation instructions and supported tools, see the [Agora Skills repository](https://github.com/AgoraIO/skills). ### Installation Install Agora Skills using one of the following methods: #### Skills CLI (recommended) Run the following command: ```bash npx skills add github:AgoraIO/skills ``` Skills activate automatically when your agent detects relevant tasks, for example, "build a voice agent", "integrate Agora RTC", or "generate a token". #### Manual installation Clone the repository once and point your AI coding assistant to the skill files directly. 1. Clone the [Agora Skills repo](https://github.com/AgoraIO/skills.git): ```bash git clone https://github.com/AgoraIO/skills.git ~/agora-skills ``` 2. Point your AI assistant to `skills/agora/`. Follow the instructions for your AI coding assistant: Claude Code Cursor Windsurf GitHub Copilot Other tools Run the following commands inside Claude Code: * **User-level** (available across all your projects) ```bash /plugin marketplace add AgoraIO/skills /plugin install agora ``` * **Project-level** (shared with your team via version control) ```bash /plugin marketplace add AgoraIO/skills /plugin install agora --scope project ``` Copy or symlink `skills/agora/` into `.cursor/rules/`. For more information, see [Cursor skill directories](https://cursor.com/docs/skills#skill-directories). Add `skills/agora/` to your Cascade context. For more information, see [Windsurf skills](https://docs.windsurf.com/windsurf/cascade/skills). Reference via `@workspace` or add to `.github/copilot-instructions.md`. For more information, see [Create skills for Copilot in the CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-skills) or [Create skills for the Copilot coding agent](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-skills). The skill files are plain markdown. Point your tool to `skills/agora/` or load individual files directly. Use `SKILL.md` as the entry point. # Subscription packages (/en/realtime-media/broadcast-streaming/subscription-packages) A subscription package is a prepaid billing method. You can purchase a package in the [`Agora Console`](https://console.agora.io/subscriptions/rtc-plans?tab=monthly) to cover usage for the current month. This page explains how to purchase, and manage subscription and top-up packages. ### Purchase and upgrade By default, a new account is assigned the Free package when the first project is created. You can upgrade at any time to the Starter, Pro, Business, Business Advanced, or Business Plus. Higher-tier packages provide greater discounts and lower unit prices. To select your package: 1. Log in to [Agora Console](https://console.agora.io/). 2. Click the username at the bottom of the navigation sidebar to open the account popup menu. 3. Select **Subscriptions**. 4. Switch to the **RTC** tab. 5. Select your package and click **Upgrade** or **Downgrade**. ![Subscription plans](https://assets-docs.agora.io/images/console/subscription-plans.png) * For non-contracted customers, all packages, except the Enterprise package can be purchased directly from the Agora Console. To upgrade to the Enterprise package, contact [Agora sales](mailto\:sales@agora.io). * You can upgrade sequentially or skip levels. For example, you may upgrade from Starter to Business Plus directly. * Package upgrades take effect immediately and apply to the entire calendar month. If you make multiple upgrades on the same day, only the last upgrade is applied. * If your account has a negative balance, purchasing a prepaid package first charges your credit card for the outstanding balance, then for the package fee. #### Upgrade rules When you upgrade to a paid package, it becomes effective for the entire calendar month, regardless of the purchase date. You receive the full monthly allocation of included minutes. The cost of the previous package is deducted from the new package price, so you only pay the difference. If you request an upgrade after auto-renewal has triggered, you may upgrade for the next month as well. ### Renewal By default, your subscription package renews automatically 48 hours before it expires. Ensure your account has sufficient balance or enable auto-pay to avoid renewal failure. You can unsubscribe at any time to prevent renewal. See [Cancel subscription](#cancel-subscription). If renewal fails: * The system sends a notification and retries the renewal. * If renewal still fails by the time the package expires, the package downgrades to the Free package. * To restore the previous package, see [Purchase and Upgrade](#purchase-and-upgrade). ### Downgrade You can downgrade by selecting and purchasing a lower-tier package. A downgrade takes effect when your current package expires if you request it before auto-renewal is triggered. You are charged for the new package when you request the downgrade. You can downgrade only once per month. * If your downgrade for the next month is successful, auto-renewal for the current package is not triggered. * If a package is already active, you must wait until the 1st day of that month to initiate a downgrade for the following month. #### Example * **Requested more than 48 hours before the current package expires**: The downgrade takes effect after the current package expires. * **Requested less than 48 hours before the current package expires**: Since a package is already active for the next month, you must wait until the new package starts to downgrade for the following month. ### Cancel subscription To cancel a prepaid package, downgrade to the Free package. Downgrade rules apply. ## Top-up package A top-up package is a pay-as-you-go plan. You can purchase a top-up package from the [`Agora Console`](https://console.agora.io/subscriptions/rtc-plans?tab=top-up) to cover usage that exceeds your monthly package quota. ### Purchase You can purchase multiple top-up packages. They are deducted in the order of purchase. #### Example: * Purchased 250,000-minutes top-up packages on **August 15** and **August 16**. On **September 1**, minutes consumed in August are deducted from the first package, then from the second. ### Validity Each top-up package is valid for one year, starting from the purchase date to the end of the same month of the following year. #### Example: * Purchased on **August 15, 2025** → valid until **August 31, 2026** Unused minutes expire after the validity period and cannot be carried forward. ### Cancel top-up package Cancelling a top-up package is not supported. ## Free tier overage For Free tier users, exceeding the included minutes and any purchased top-up minutes results in service suspension. Service resumes when you purchase additional top-up minutes or upgrade to a prepaid subscription package. # Core concepts (/en/realtime-media/cloud-recording/core-concepts) Agora Cloud Recording enables you to record video and voice calls or streams in the cloud for storage or on-demand viewing. Cloud Recording works with Voice Calling, Video Calling, Broadcast Streaming and Interactive Live Streaming. This page introduces the key processes and concepts you need to know to use Cloud Recording. ## General concepts Agora relies on the following fundamental concepts to enable seamless real-time communication: ### Agora SDRTN® Agora's core engagement services are powered by its Software-Defined Real-Time Network (SDRTN®), a global infrastructure accessible anytime, anywhere. Unlike traditional networks, Agora SDRTN® is not restricted by devices, phone numbers, or telecom coverage areas. With data centers in over 200 countries and regions, it ensures sub-second latency and high availability for real-time media. Agora SDRTN® enables live user engagement through real-time communication (RTC), offering: * Unmatched quality of service * High availability and accessibility * True scalability * Low cost ### App ID The App ID is a unique key generated by Agora to identify each project and provide billing and other statistical data services. The App ID is critical for connecting users within your app. It is used to initialize the ENGINE in your app, and as one of the required keys to create authentication tokens for secure communication. Retrieve the App ID for your project using the [Agora Console](https://console.agora.io/legacy/project-management). App IDs are stored on the front-end client and do not provide access control. Projects using only an App ID allow any user with the App ID to join. For access control, especially in production environments, choose the **App ID + Token** mechanism for user authentication when creating a new project. Without authentication tokens, your environment is open to anyone with access to your App ID. ### App Certificate An App Certificate is a unique key generated by the Agora Console to secure projects through token authentication. It is required, along with the App ID, to generate a token that proves authorization between your systems and Agora's network. App Certificates are used to generate Cloud Recording authentication tokens. Store the App Certificate securely in your backend systems. If your App Certificate is compromised or to meet security compliance requirements, you can invalidate certificates and create new ones through the Agora Console. ### Tokens A token is a dynamic key generated using the App ID, App Certificate, user ID, and expiration timestamp. Tokens authenticate and secure access to Agora's services, ensuring only authorized users can join a channel and participate in real-time communication. Tokens are generated on your server and passed to the client for use in Cloud Recording. The token generation process involves digitally signing the App ID, App Certificate, user ID, and expiration timestamp using a specific algorithm, preventing tampering or forgery. During development and testing, use the Agora Console to generate temporary tokens. For production environments, implement a token server as part of your security infrastructure to control access to your channels. For information on setting up a token server for generating and managing tokens, refer to [Deploy a token server](/en/realtime-media/cloud-recording/build/set-up-authentication/authentication-workflow). ### Channel A channel organizes users into a group and is identified by a unique channel name. Users who connect to the same channel are able to communicate with each other. A channel is created when the first user joins and ceases to exist when the last user leaves. Channels are created by calling the methods for transmitting real-time data. Agora uses different channels to transmit different types of data: * An RTC channel is used for transmitting audio or video data. * A MESS channel is used for transmitting messaging or signaling data. These channels are independent of each other. Additional services provided by Agora, such as Cloud Recording and STT, join the SDK channel to provide real-time recording, transmission acceleration, media playback, and content moderation. ### User ID In Cloud Recording, the UID is an integer value that uniquely identifies a user within the context of a channel. When joining a channel, you have the option to either assign a specific UID to the user or pass `0` or `null` and allow Agora to automatically generate and assign a UID to the user. If two users attempt to join the same channel with the same UID, it can lead to unexpected behavior. The UID is used by Agora's services and components to identify and manage users within a channel. Ensure that UIDs are properly assigned to prevent conflicts. ### Agora Console To use Agora Cloud Recording, create a project in the [Agora Console](https://console.agora.io/) first. ![Create project in Agora Console](https://assets-docs.agora.io/images/common/create-project.svg) Agora Console provides an intuitive interface for developers to query and manage their Agora account. After registering an Agora account, you use the Agora Console to perform the following tasks: * Manage your account * Create and configure Agora projects and services * Get an App ID and the App certificate * Generate temporary tokens for development and testing * Manage members and roles * Check call quality and usage * Check bills and make payments * Access product resources See [Agora account management](/en/introduction/account) for details on how to manage all aspects of your Agora account. Agora also provides RESTful APIs that you use to implement features such as creating a project and fetching usage numbers programmatically. ## Cloud recording concepts ### Recording modes Agora Cloud Recording supports three recording modes: * Individual recording * Composite recording * Web page recording After the recording is complete, the recorded content is uploaded as a `TS` file to the third-party cloud storage you specified. An `M3U8` file is also generated to serve as an index for the corresponding `TS` file The working principles of different recording modes and the types of files generated by Cloud Recording are as follows: #### Individual recording In individual recording, the recording service records the audio and video streams of each UID in the channel separately. After the recording is complete, the recording service generates the corresponding audio and video files for each UID. For example, if there are 3 UIDs in the channel and each UID sends audio and video, then in the individual recording mode, 3 audio files and 3 video files are generated. #### Composite recording In mixed recording, the recording service combines the audio and video of multiple UIDs in the channel into a single audio and video file. For example, if there are 3 UIDs in the channel and each sends audio and video, the mixed recording mode generates one recording file that includes the audio and video of all UIDs. #### Web page recording In web page recording, the recording service combines the page content and audio of a specified web page into an audio and video file. Web page recording is commonly used in the following use-cases: * In online classrooms, to record the teacher and student audio and video along with courseware, whiteboard, and other visuals. * In video conferences, to capture participants' audio and video, as well as whiteboard, PPT, and other visuals. ### Transcoding and non-transcoding modes In individual recording, audio transcoding and non-transcoding modes have different use cases and characteristics. **Individual recording with transcoding**: This mode is used in use-cases where unified audio encoding parameters are needed to ensure consistent recording file formats and parameters for easier post-processing and playback. It is commonly used in cases requiring high compatibility and standardized output, such as wide player support and standardized storage. **Individual recording without transcoding**: This mode is used when the original audio encoding parameters must be preserved to maintain the sound quality and performance. It is often used in use-cases with high demands for real-time performance and original sound quality, such as high-fidelity audio recording. | Feature | Individual recording with transcoding | Individual recording without transcoding | | :--------------------------------- | :------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Transcoding during audio encoding | Yes | No | | Raw audio data | The sampling rate, number of channels, and bitrate are fixed at 48 kHz, mono, and 48 Kbps respectively. | The bitrate, sampling rate and number of channels are determined by the audio encoding parameters of the streaming end `AudioProfile`. | | Audio encoding format | LC-AAC | Determined by the configuration of the source end `AudioProfile` | | Generated recording files | Each UID generates an audio file in `M3U8` format and multiple audio files in `TS` format. | Same as transcoding recording. If the user stops streaming using `muteLocalAudioStream` or `leaveChannel` audio recording stops immediately, and there is no 15 seconds of silent data. | | Player compatibility | The recorded file can be played by any mainstream player that supports the HLS protocol. | The audio encoding format is determined by the configuration of the streaming end `AudioProfile`. Different audio encoding formats have different compatibility. | ### Delayed transcoding Delayed transcoding is designed for audio-only recording use-cases. When you enable this mode, the recording service merges and transcodes the audio files of all users in the specified channel into an `MP3`, `M4A`, or `AAC` file within 24 hours after the recording ends (or up to 48 hours in special cases) and uploads it to the specified third-party cloud storage. ### Delayed audio mixing Delayed audio mixing is used for individual audio recording use-cases. To obtain a mixed recording file of all users in the channel after recording, you enable the delayed audio mixing feature when starting individual audio recording without transcoding. Once enabled, the recording service merges and transcodes the audio files of all users in the specified channel into an `MP3`, `M4A`, or `AAC` file within 24 hours after the recording is complete (or up to 48 hours in special cases) and uploads it to the specified third-party cloud storage. ### Slicing Slicing involves cutting audio and video data according to specific rules during the recording process to generate multiple recording files. After slicing, several slice files (such as `TS` or `WebM` files) are created, along with `M3U8` files that store the indexes of these slice files. # Cloud Recording overview (/en/realtime-media/cloud-recording) Agora's Cloud Recording is a RESTful API-based solution for recording real-time voice, video, and interactive streaming sessions directly to your cloud storage. It supports leading CDN and cloud hosting providers, offers customizable recording layouts, and supports multiple file formats for playback and distribution. Easily launch multiple recorders within a single channel to ensure redundancy or to capture different layouts and formats simultaneously. This makes Cloud Recording a flexible and reliable solution for recording and preserving real-time communication. ## Features Supports globally distributed cluster deployment and automatically backs up files on Agora’s cloud server when the third-party cloud storage fails. End-to-end security mechanisms for voice and video calls, data transmission, and storage. Supports third-party cloud storage, including Amazon S3, Alibaba Cloud, Tencent Cloud, Kingsoft Cloud, Qiniu Cloud, Microsoft Azure, Google Cloud, Huawei Cloud, and Baidu AI Cloud. Simple implementation and easy to learn with RESTful API calls that allow you to start, stop, and query the recording. # Agora MCP (/en/realtime-media/cloud-recording/mcp) The Agora MCP server gives your AI assistant direct access to Agora's documentation, so it can look up APIs, SDK methods, and platform-specific details in real time. The Agora MCP server is included when you install Agora Skills. If you prefer to install only the MCP server, it is available at: ```text https://mcp.agora.io ``` ## Installation Refer to the installation instructions for your coding assistant. Cursor Claude Codex Gemini CLI Manual installation Click the button below to install the MCP server in [Cursor](https://www.cursor.com/)

or add it manually with the following JSON: ```json { "mcpServers": { "agora-docs": { "url": "https://mcp.agora.io" } } } ``` * **Claude Code** Run the following command in your terminal to install the MCP server in [Claude Code](https://claude.com/product/claude-code): ```bash claude mcp add --transport http agora-docs https://mcp.agora.io ``` * **Claude Desktop** In **Settings**, select **Connectors** and then choose **Add custom connector**. Enter the following values and click **Add**: * **Name**: `agora-docs` * **Remote MCP server URL**: `https://mcp.agora.io` Run the following command in your terminal to install the server in [OpenAI Codex](https://openai.com/codex/): ```bash codex mcp add --url https://mcp.agora.io agora-docs ``` Run the following command in your terminal to install the server in [Gemini CLI](https://github.com/google-gemini/gemini-cli): ```bash gemini mcp add --transport http agora-docs https://mcp.agora.io ``` Add the server URL `https://mcp.agora.io` to your MCP client of choice. If prompted, set the transport to `http` or "Streamable HTTP". ## Getting started Once installed, your coding assistant has access to Agora's documentation through the MCP server. The assistant will intelligently use this resource when relevant to your questions. For more targeted results, mention Agora along with your target product and platform, such as `Cloud Recording`, `Web`, and `REST API` in your prompts. ## AGENTS.md To get the most out of Agora Skills and the MCP server, Agora recommends that you include an [AGENTS.md](https://agents.md) or similar file in your repository. This file ensures that your agent always consults Agora docs to produce reliable, working code. Add the following instructions to your own `AGENTS.md` file: ```markdown ## Agora Documentation Agora documentation is updated frequently. You should always refer to the latest documentation when working with Agora products. Agora offers an MCP server that you can use to browse and search its documentation. If the developer has not yet installed this server, recommend that they install it at https://mcp.agora.io. If the Agora Skills files are available in your context, use them for platform-specific API guidance and code examples. ``` # Quickstart using middleware (/en/realtime-media/cloud-recording/middleware-quickstart) To streamline the use of Agora RESTful APIs within your infrastructure, Agora’s developer community offers the open-source [Agora Go Backend Middleware](https://github.com/AgoraIO-Community/agora-go-backend-middleware). This backend provides RESTful APIs for tasks such as token generation, cloud recording management, and real-time transcription. It simplifies the integration of Agora’s cloud services into your real-time voice and video applications. This guide shows you how to implement cloud recording using the community middleware. ## Understand the tech The following figure illustrates the architecture of the middleware cloud recording micro service. ![](https://assets-docs.agora.io/images/cloud-recording/cloud-recording-middleware.svg) ## Set up and run the Go backend middleware Take the following steps to set up and run the middleware project: 1. **Clone the repository** ```bash git clone https://github.com/AgoraIO-Community/agora-go-backend-middleware.git ``` 2. **Install dependencies** Ensure you have [Go](https://go.dev/doc/install) installed on your system. Navigate to the project directory and install the project dependencies: ```bash cd agora-go-backend-middleware go mod download ``` 3. **Configure environment variables** 1. Copy the example `.env` file. ```bash cp .env.example .env ``` 2. Update the following variables in the `.env` file: * `APP_ID`: Your Agora App ID. * `APP_CERTIFICATE`: Your Agora App Certificate. * `CUSTOMER_ID`: Your customer ID * `CUSTOMER_SECRET`: Your Customer Secret * `STORAGE_VENDOR`: Cloud storage vendor (e.g., AWS, GCP). * `STORAGE_REGION`: Region of your cloud storage. * `STORAGE_BUCKET`: Bucket name. * `STORAGE_ACCESS_KEY`: Cloud storage access key. * `STORAGE_SECRET_KEY`: Cloud storage secret key. 4. **Run the middleware:** Start the middleware server using the following command: ```bash go run cmd/main.go ``` The middleware runs on the default port, for example `localhost:8080`. ## Implement Cloud Recording using middleware This section explains the RESTful API calls to the backend middleware for starting, managing, and stopping a Cloud Recording session. ### Start recording To start a Cloud Recording session refer to the following examples: The command-line examples in this guide are for demonstration purposes only. Do not use them directly in a production environment. Implement RESTful API requests through your application server. * Basic example ```bash curl -X POST http://localhost:8080/cloud_recording/start \ -H "Content-Type: application/json" \ -d '{ "channelName": "test_channel", "sceneMode": "realtime", "recordingMode": "mix", "excludeResourceIds": [] }' ``` * Advanced example ```bash curl -X POST http://localhost:8080/cloud_recording/start \ -H "Content-Type: application/json" \ -d '{ "channelName": "testChannel", "sceneMode": "realtime", "recordingMode": "mix", "excludeResourceIds": [], "recordingConfig": { "channelType": 0, "decryptionMode": 1, "secret": "your_secret", "salt": "your_salt", "maxIdleTime": 120, "streamTypes": 2, "videoStreamType": 0, "subscribeAudioUids": ["#allstream#"], "unsubscribeAudioUids": [], "subscribeVideoUids": ["#allstream#"], "unsubscribeVideoUids": [], "subscribeUidGroup": 0, "streamMode": "individual", "audioProfile": 1, "transcodingConfig": { "width": 640, "height": 360, "fps": 15, "bitrate": 500, "maxResolutionUid": "1", "layoutConfig": [ { "x_axis": 0, "y_axis": 0, "width": 640, "height": 360, "alpha": 1, "render_mode": 1 } ] } } }' ``` ### Stop recording To stop an ongoing cloud recording session: ```bash curl -X POST http://localhost:8080/cloud_recording/stop \ -H "Content-Type: application/json" \ -d '{ "cname": "test_channel", "uid": "uid-from-start-response", "resourceId": "resource-id-from-start-response", "sid": "sid-from-start-response", "recordingMode": "mix", "async_stop": false }' ``` ### Get Recording Status During the recording, call the `status` endpoint to query the recording status as required. ```bash curl -X GET "http://localhost:8080/cloud_recording/status?resourceId=your-resource-id&sid=your-sid&mode=mix" ``` ### Update Subscriber List To update the subscriber list during a recording session, refer to the following example: ```bash curl -X POST http://localhost:8080/cloud_recording/update/subscriber-list \ -H "Content-Type: application/json" \ -d '{ "cname": "test_channel", "uid": "uid-from-start-response", "resourceId": "your-resource-id", "sid": "your-sid", "recordingMode": "mix", "recordingConfig": { "streamSubscribe": { "audioUidList": { "subscribeAudioUids": ["2345", "3456"] }, "videoUidList": { "subscribeVideoUids": ["2345", "3456"] } } } }' ``` ### Update Layout To update the layout of a recording session, refer to the following example: ```bash curl -X POST http://localhost:8080/cloud_recording/update/layout \ -H "Content-Type: application/json" \ -d '{ "cname": "test_channel", "uid": "uid-from-start-response", "resourceId": "your-resource-id", "sid": "your-sid", "recordingMode": "mix", "recordingConfig": { "mixedVideoLayout": 1, "backgroundColor": "#000000", "layoutConfig": [ { "uid": "2345", "x_axis": 0, "y_axis": 0, "width": 360, "height": 640, "alpha": 1, "render_mode": 1 } ] } }' ``` ## Cloud Recording Middleware API Reference This section provides details about the Go middleware Cloud Recording API endpoints. ### Start Recording Starts a cloud recording session. ##### Endpoint **POST:** `/cloud_recording/start` #### Request Body ```json { "channelName": "string", "uid": "string", "recordingConfig": { // RecordingConfig fields }, "storageConfig": { // StorageConfig fields } } ``` #### Response ```json { "resourceId": "string", "sid": "string", "timestamp": "string" } ``` ### Stop Recording Stops an ongoing cloud recording session. #### Endpoint **POST:** `/cloud_recording/stop` #### Request Body ```json { "cname": "string", "uid": "string", "resourceId": "string", "sid": "string", "recordingMode": "string", "async_stop": boolean } ``` #### Response ```json { "resourceId": "string", "sid": "string", "serverResponse": { "fileListMode": "string", "fileList": [ { "fileName": "string", "trackType": "string", "uid": "string", "mixedAllUser": boolean, "isPlayable": boolean, "sliceStartTime": number } ] }, "timestamp": "string" } ``` ### Get Recording Status Retrieves the status of a cloud recording session. #### Endpoint **GET:** `/cloud_recording/status` #### Query Parameters * `resourceId`: string * `sid`: string * `mode`: string #### Response ```json { "resourceId": "string", "sid": "string", "serverResponse": { "fileListMode": "string", "fileList": [ { "fileName": "string", "trackType": "string", "uid": "string", "mixedAllUser": boolean, "isPlayable": boolean, "sliceStartTime": number } ] }, "timestamp": "string" } ``` ### Update Subscriber List Updates the subscriber list for a cloud recording session. #### Endpoint **POST:** `/cloud_recording/update/subscriber-list` #### Request Body ```json { "cname": "string", "uid": "string", "resourceId": "string", "sid": "string", "recordingMode": "string", "recordingConfig": { // UpdateSubscriptionClientRequest fields } } ``` #### Response ```json { "cname": "string", "uid": "string", "resourceId": "string", "sid": "string", "timestamp": "string" } ``` ### Update Layout Updates the layout of a cloud recording session. #### Endpoint **POST:** `/cloud_recording/update/layout` #### Request Body ```json { "cname": "string", "uid": "string", "resourceId": "string", "sid": "string", "recordingMode": "string", "recordingConfig": { // UpdateLayoutClientRequest fields } } ``` #### Response ```json { "cname": "string", "uid": "string", "resourceId": "string", "sid": "string", "timestamp": "string" } ``` Replace `localhost:8080` with your server's address, if it is different. # REST quickstart (/en/realtime-media/cloud-recording/rest-quickstart) Cloud Recording enables you to record and store real-time audio and video streams from channels. To implement Cloud Recording, you set up a self-hosted backend that interacts with Agora servers to manage recording tasks. This guide introduces the essential Cloud Recording RESTful APIs you use to manage the recording process. The command-line examples in this guide are for demonstration purposes only. Do not use them directly in a production environment. Implement RESTful API requests through your application server or use Agora's [Go backend middleware](https://github.com/AgoraIO-Community/agora-go-backend-middleware). For details, see [Quickstart using middleware](/en/realtime-media/cloud-recording/middleware-quickstart) ## Understand the tech The basic process of implementing Cloud Recording is as follows: ![](https://assets-docs.agora.io/images/cloud-recording/cloud-recording-tech.svg) 1. Get a resource ID Before starting a cloud recording, call the [`acquire`](#acquire) method to obtain a cloud recording resource ID. After calling this method successfully, you get a resource ID in the response body. 2. Start cloud recording Call the [`start`](#start) method to join the channel and start a cloud recording. After calling this method successfully, you get a recording ID from the response body to identify the current recording process. 3. Query the recording status Call the [`query`](#query) method to check the recording status during the recording. 4. Stop cloud recording Call the [`stop`](#stop) method to stop the cloud recording. 5. Upload the recording file After the recording ends, the cloud recording service uploads the recording file to the [third-party cloud storage](/en/api-reference/api-ref/cloud-recording#storageconfig) you specify. ## Prerequisites To implement Cloud Recording, ensure that you have: * A valid Agora account and project. Obtain the following parameters from [Agora Console](https://console.agora.io): * The App ID and App certificate for your project. See [Get Started with Agora](/en/introduction/account#get-the-app-id-and-app-certificate) * A valid temporary token * Customer ID and Customer key for RESTful API. See [Authenticate REST calls](/en/api-reference/api-ref/cloud-recording/authentication) * Set up and enabled a supported third-party cloud storage service. Obtain the following parameters for your storage: * Bucket name * Access key * Secret key - [Alibaba Cloud](https://www.alibabacloud.com/product/object-storage-service) - [Amazon S3](https://aws.amazon.com/s3/?nc1=h_ls) - [Baidu AI Cloud](https://intl.cloud.baidu.com/product/bos.html) - [Google Cloud](https://cloud.google.com/storage) - [Huawei Cloud](https://www.huaweicloud.com/intl/en-us/product/obs) - [Kingsoft Cloud](https://en.ksyun.com/nv/product/KS3) - [Microsoft Azure](https://azure.microsoft.com/en-us/services/storage/blobs/) - [Qiniu Cloud](https://www.qiniu.com/en/products/kodo) - [Tencent Cloud](https://intl.cloud.tencent.com/product/cos) * Enabled the Agora Cloud Recording service for your project. In [Agora Console](https://console.agora.io), select **RTC Services** from the sidebar, then locate the **Cloud Recording** card and turn on its toggle. You can now use Agora Cloud Recording and see the usage statistics on the **Usage** page. * If your network has a firewall, follow the instructions in [Firewall Requirements](/en/realtime-media/cloud-recording/reference/firewall). ## Implement cloud recording The following figure shows the API call sequence to start and manage cloud recording: ![](https://assets-docs.agora.io/images/cloud-recording/cloud-recording-sequence.svg) The following APIs are optional and can be called multiple times. However, they must be called during a recording session, that is, after recording starts and before it ends: * [`query`](#query): Query the recording status * [`update`](/en/api-reference/api-ref/cloud-recording#update): Update the subscription list * [`updateLayout`](/en/api-reference/api-ref/cloud-recording#updatelayout): Update the video layout ### Use basic HTTP authentication The Cloud Recording RESTful APIs require basic HTTP authentication. You need to set the `Authorization` parameter in every HTTP request header. For details, see [Basic HTTP authentication](/en/api-reference/api-ref/cloud-recording/authentication). ### Get a resource ID Call the [`acquire`](/en/api-reference/api-ref/cloud-recording#acquire) method to request a resource ID for Cloud Recording. After calling this method successfully, you receive a resource ID in the response body. The resource ID is valid for five minutes. Start recording with this resource ID within the validity period. One resource ID can only be used for a single recording session. * The recording service is equivalent to a non-streaming client in the channel. The `uid` parameter in the request body is used to identify the recording service and cannot be the same as any existing user ID in the channel. For example, if there are two users already in the channel and their user IDs are 123 and 456, the `uid` cannot be `"123"` or `"456"`. * Agora Cloud Recording does not support user IDs in string format (User Accounts). Ensure that every user in the channel has an integer user ID. The string content of the `uid` parameter must also be an integer. #### Sample code For testing purposes, use the following command in the terminal to call the `acquire` method. ```bash # Replace with the App ID of your Agora project curl --location --request POST 'https://api.agora.io/v1/apps//cloud_recording/acquire' \ # Replace with the Base64-encoded credential in basic HTTP authentication --header 'Authorization: Basic ' \ --header 'Content-Type: application/json' \ --data-raw '{ # Replace with the name of the channel you need to record "cname": "", # Replace with your user ID "uid": "", "clientRequest":{} }' ``` ### Start recording Call the [`start`](/en/api-reference/api-ref/cloud-recording#start) method within five minutes of getting a resource ID to join a channel and start recording. You can choose either [individual recording](/en/realtime-media/cloud-recording/build/start-a-recording/individual-mode) or [composite recording](/en/realtime-media/cloud-recording/build/start-a-recording/composite-mode) as the recording mode. If this method call succeeds, you receive a recording ID (sid) in the HTTP response body. This ID identifies the current recording. After you obtain the recording ID `sid`, you can call the `query`, `updateLayout`, and `stop` methods before the time set (in hours) by `resourceExpiredHour` has passed. #### Sample code For testing purposes, use the following command in the terminal to call the `start` method. ```bash # Replace with the App ID of your Agora project # Replace with the resource ID obtained through the acquire method # Replace "" with "individual" for individual recording or "composite" for composite recording curl --location --request POST 'https://api.agora.io/v1/apps//cloud_recording/resourceid//mode//start' \ # Replace with the Base64-encoded credential in basic HTTP authentication --header 'Authorization: Basic ' \ --header 'Content-Type: application/json' \ --data-raw '{ # Replace with the name of the channel you need to record. "cname": "", # Replace with your user ID that identifies the recording service. "uid": "", "clientRequest": { # Replace with the temporary token you obtain from the console. "token": "", # Set the storageConfig related parameters. "storageConfig": { "secretKey": "", "vendor": 0, "region": 0, "bucket": "", "accessKey": "" }, # Set the recordingConfig related parameters. "recordingConfig": { # Which is consistent with the "channelType" of the Agora RTC SDK. "channelType": 0 } } }' ``` ### Query recording status During a recording session, can call the [`query`](/en/api-reference/api-ref/cloud-recording#query) method to query the recording status. You can call this API multiple times. When you call this method successfully, you receive the current recording status and related information about the recording file in the response body. See [Best Practices in Integrating Cloud Recording](/en/realtime-media/cloud-recording/build/best-practices/integration-best-practices) for details about how to [Monitor service status during a recording](../best-practices/integration-best-practices#monitor-service-status-during-a-recording) and[ Obtain the M3U8 file name](../best-practices/integration-best-practices#obtain-the-m3u8-file-name). #### Sample code For testing purposes, use the following command in the terminal to call the `query` method. ```bash # Replace with the App ID of your Agora project # Replace with the resource ID obtained through the acquire method # Replace with the sid obtained through the start method # Replace "" with "individual" for individual recording or "composite" for composite recording curl --location --request GET 'https://api.agora.io/v1/apps//cloud_recording/resourceid//sid//mode//query' \ # Replace with the Base64-encoded credential in basic HTTP authentication --header 'Authorization: Basic ' \ --header 'Content-Type: application/json' ``` ### Stop recording Call the [`stop`](/en/api-reference/api-ref/cloud-recording#stop) API to end the recording session. When you call this method successfully, you receive the status of the recording file upload and information about the recording file in the response body. #### Sample code For testing purposes, use the following command in the terminal to call the `stop` method. ```bash # Replace with the App ID of your Agora project # Replace with the resource ID obtained through the acquire method # Replace with the sid obtained through the start method # Replace "" with "individual" for individual recording or "composite" for composite recording curl --location --request POST 'https://api.agora.io/v1/apps//cloud_recording/resourceid//sid//mode//stop' \ --header 'Content-Type: application/json;charset=utf-8' \ # Replace with the Base64-encoded credential in basic HTTP authentication --header 'Authorization: Basic ' \ --data-raw '{ # Replace with your user ID that identifies the recording service. "uid": "", # Replace with the name of the channel you are recording. "cname": "", "clientRequest":{ } }' ``` Parameter settings * If the `uid` parameter in the request body is the same as a user ID in the channel, or if you use a non-integer user ID, the recording fails. For details, see the notes on the `uid` parameter in the section [Get a cloud recording resource](#acquire). * When the `start` request returns `200`, it only means that the RESTful API request is successful. To ensure that the recording has started successfully and continues normally, call `query` to check the recording status. Errors such as unreasonable `transcodingConfig` parameter settings, incorrect third-party cloud storage information, or incorrect token information cause the `query` method to return `404`. See [Why do I get a 404 error when I call query after successfully starting a cloud recording? ](../reference/common-errors#errors). * Set the `maxIdleTime` parameter based on your business needs. Within the time range set by `maxIdleTime`, the recording continues and billing is generated even if the channel is idle. ## Reference This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product. ### Sample project Agora provides a [Postman collection](https://documenter.getpostman.com/view/6319646/SVSLr9AM), which contains sample requests of RESTful API for a cloud recording. You can use the collection to quickly grasp the basic functionalities of the Cloud Recording RESTful APIs. You only need to import the collection to Postman and set your environment variables. You can also use Postman to generate code snippets written in various programming languages. To do so, select a request, click **Code**, and select the desired language in **GENERATE CODE SNIPPETS**. ![img](https://web-cdn.agora.io/docs-files/1588737379230) ### See also * To streamline the use of Agora RESTful APIs within your infrastructure, see [Quickstart using middleware](/en/realtime-media/cloud-recording/middleware-quickstart). The community middleware project provides RESTful APIs for tasks such as token generation and cloud recording management. * To update the subscription lists during the recording, call [`update`](/en/api-reference/api-ref/cloud-recording#update). You can call this method multiple times. See [Set up subscription lists](/en/realtime-media/cloud-recording/build/customize-the-recording/subscription) for details. * To set or update the video layout during the recording, call the [`updateLayout`](/en/api-reference/api-ref/cloud-recording#updatelayout) method. See [Set Video Layout](/en/realtime-media/cloud-recording/build/customize-the-recording/layout) for details. * [Common errors in cloud recording](/en/realtime-media/cloud-recording/reference/common-errors) lists common error codes and error messages in the response body. * [Agora Cloud Recording RESTful API Callback Service](../reference/rest-api-overview) lists all the callback events of cloud recording. * To learn more about the implementation steps and details of basic functions, you can refer to the following documents: * [Individual recording](/en/realtime-media/cloud-recording/build/start-a-recording/individual-mode) * [Composite recording](/en/realtime-media/cloud-recording/build/start-a-recording/composite-mode) * [Web page recording](/en/realtime-media/cloud-recording/build/start-a-recording/webpage-mode) * [Capture screenshots](/en/realtime-media/cloud-recording/build/start-a-recording/screen-capture) ## Next steps ### Manage recorded files After the recording starts, the Agora server splits the recorded content into multiple TS/WebM files and keeps uploading them to the third-party cloud storage until the recording stops. You can refer to [Manage Recorded Files](/en/realtime-media/cloud-recording/build/process-recorded-files/manage-files) to learn about the naming rules, file sizes, and slicing rules of recording files. ### Token authentication To ensure communication security, in a formal production environment, you need to generate tokens on your app server. See [Authenticate Your Users with Token](/en/realtime-media/cloud-recording/build/set-up-authentication/authentication-workflow). # Agora skills (/en/realtime-media/cloud-recording/skills) Agora skills is a set of structured reference files that give AI coding assistants deep knowledge of Agora's platform. When you ask your assistant to build something with Agora, it loads the relevant skill files covering products, APIs, and platform-specific code examples, so it can generate working code without guessing. Skills includes integration with the [Agora MCP server](./mcp), which gives your assistant access to live Agora documentation. For installation instructions and supported tools, see the [Agora Skills repository](https://github.com/AgoraIO/skills). ### Installation Install Agora Skills using one of the following methods: #### Skills CLI (recommended) Run the following command: ```bash npx skills add github:AgoraIO/skills ``` Skills activate automatically when your agent detects relevant tasks, for example, "build cloud recording workflows", "integrate Agora RTC", or "generate a token". #### Manual installation Clone the repository once and point your AI coding assistant to the skill files directly. 1. Clone the [Agora Skills repo](https://github.com/AgoraIO/skills.git): ```bash git clone https://github.com/AgoraIO/skills.git ~/agora-skills ``` 2. Point your AI assistant to `skills/agora/`. Follow the instructions for your AI coding assistant: Claude Code Cursor Windsurf GitHub Copilot Other tools Run the following commands inside Claude Code: * **User-level** (available across all your projects) ```bash /plugin marketplace add AgoraIO/skills /plugin install agora ``` * **Project-level** (shared with your team via version control) ```bash /plugin marketplace add AgoraIO/skills /plugin install agora --scope project ``` Copy or symlink `skills/agora/` into `.cursor/rules/`. For more information, see [Cursor skill directories](https://cursor.com/docs/skills#skill-directories). Add `skills/agora/` to your Cascade context. For more information, see [Windsurf skills](https://docs.windsurf.com/windsurf/cascade/skills). Reference via `@workspace` or add to `.github/copilot-instructions.md`. For more information, see [Create skills for Copilot in the CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-skills) or [Create skills for the Copilot coding agent](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-skills). The skill files are plain markdown. Point your tool to `skills/agora/` or load individual files directly. Use `SKILL.md` as the entry point. # SDK quickstart (/en/realtime-media/im/get-started-sdk) Instant messaging enhances user engagement by enabling users to connect and form a community within the app. Increased engagement can lead to increased user satisfaction and loyalty to your app. An instant messaging feature can also provide real-time support to users, allowing them to get help and answers to their questions quickly. The Chat SDK enables you to embed real-time messaging in any app, on any device, anywhere. This page guides you through implementing peer-to-peer messaging into your app using the Chat SDK. ## Understand the tech The following figure shows the workflow of sending and receiving peer-to-peer messages using Chat SDK.

Chat SDK workflow

![understand](https://assets-docs.agora.io/images/im/get-started-sdk-understand.png)

1. Clients retrieve an authentication token from your app server. 2. Users log in to Chat using the App ID, their user ID, and token. 3. Clients send and receive messages through Chat as follows: 1. Client A sends a message to Client B. The message is sent to the Agora Chat server. 2. The server delivers the message to Client B. When Client B receives a message, the SDK triggers an event. 3. Client B listens for the event to read and display the message. ## Prerequisites In order to follow the procedure on this page, you must have: * A valid [Agora account](/en/introduction/account#sign-up-for-an-agora-account). * An [Agora project](/en/introduction/account#your-first-agora-project) for which you have [enabled Chat](./get-started/enable#enable-chat). * The [App Key](./get-started/enable#get-chat-project-information) for the project. * Internet access. Ensure that no firewall is blocking your network communication. * An Android emulator or a physical Android device. * Android Studio 3.6 or higher. * Java Development Kit (JDK). You can refer to the [Android User Guide](https://developer.android.com/studio/write/java8-support) for applicable versions. ## Project setup To integrate Chat into your app, do the following: 1. Method 1: Use `mavenCentral` to automatically integrate: 1. In Android Studio, create a new **Phone and Tablet** [Android project](https://developer.android.com/studio/projects/create-project) with an **Empty Activity**. Choose **Java** as the project language, and ensure that the **Minimum SDK** version is set to `21` or higher. Android Studio automatically starts gradle sync. Wait for the sync to succeed before you continue. 2. Add Chat SDK to your project dependencies. To add the SDK to your project: 1. In `/Gradle Scripts/build.gradle (Module: .app)`, add the following line under `dependencies`: ```text dependencies { ... implementation 'io.agora.rtc:chat-sdk:' } ``` Replace `` with the version number for the latest Chat SDK release, for example `1.3.1`. You can obtain the latest version information using [Maven Central Repository Search](https://central.sonatype.com/artifact/io.agora.rtc/chat-sdk/versions). 2. To download the SDK from Maven Central, press **Sync Now**. 3. Add permissions for network and device access. To add the necessary permissions, in `/app/Manifests/AndroidManifest.xml`, add the following permissions after `

`: ```xml

``` 4. Prevent code obfuscation. In `/Gradle Scripts/proguard-rules.pro`, add the following line: ```java -keep class io.agora.** {*;} -dontwarn io.agora.** ``` 2. Method 2: Dynamically load .so library files In order to reduce the size of the application installation package, the SDK provides `ChatOptions#setNativeLibBasePath` method to support dynamic loading of the `.so` files required by the SDK. Taking SDK 1.3.0 as an example, the `.so` file includes two files: `libcipherdb.so` and `.libhyphenate.so`. The steps to implement this function are as follows: 1. Download the latest version of the SDK and unzip it. 2. Integrate the `agorachat_1.3.0.jar` file into your project. 3. Upload `.so` files for all schemas to your server and ensure that the application can download `.so` files for the target schemas over the network. 4. When the application runs, it checks whether the `.so` file exists. If not found, the app downloads the `.so` file and saves it to your custom app's private directory. 5. When calling `ChatClient#init`, set the app private directory where the `.so` file is located as a parameter into the `ChatOptions#setNativeLibBasePath` method. 6. The SDK will automatically load `.so` files from the specified path upon initialization. ```java // Assume that you have put two .so libraries, `libcipherdb.so` and `libagora-chat-sdk.so` in the /data/data/packagename/files directory of the app. String filesPath = mContext.getFilesDir().getAbsolutePath(); ChatOptions options = new ChatOptions(); options.setNativeLibBasePath(filesPath); ChatClient.getInstance().init(mContext, options); ``` This method is applicable when you integrate the SDK manually but not when you integrate the SDK with Maven Central. You can specify the path of `.so` files with the path parameter in the `ChatOptions#setNativeLibBasePath` method. The path must be a valid and private directory of the app. If you set this parameter, the SDK will use `System.load` to load the `.so` library from the directory you specify, so that the app dynamically loads the required `.so` files when it runs, thereby reducing the package size. If you do not set this parameter or set it to `null`, the SDK will use `System.load` to load the `.so` library from the default path when compiling the app, thus increasing the package size compared to the previous method. Since March 6, 2024, using this method to reduce the app size no longer meets the requirements of Google Play. For details, refer to the [Developer Program Policies](https://support.google.com/googleplay/android-developer/answer/14906471?hl=en\&visit_id=638555962315571301-1274648059\&rd=1) issued by Google. If your app needs to be listed on Google Play, please try other ways to reduce the app size. For details, see [App size optimization](/en/realtime-media/rtc/best-practices/app-size-optimization#dynamically-load-so-files). ## Implement peer-to-peer messaging This section shows how to use the Chat SDK to implement peer-to-peer messaging in your app, step by step. ### Create the UI In the quickstart app, you create a simple UI that consists of the following elements: * A `Button` to log in or out of Agora Chat. * An `EditText` box to specify the recipient user ID. * An `EditText` box to enter a text message. * A `Button` to send the text message. * A scrollable layout to display sent and received messages. To add the UI framework to your device project, open `app/res/layout/activity_main.xml` and replace the content with the following: ```xml

Date	Actual usage duration (seconds)					Usage duration displayed on Agora Console (minutes)
Date	Audio	HD video	Full HD video	2K video	2K+ video	Audio	HD video	Full HD video	2K video	2K+ video
2025-02-04	6,000	0	0	0	0	100	0	0	0	0
2025-02-09	12,000	0	0	0	0	200	0	0	0	0
2025-02-13	0	3,500	0	0	0	0	59	0	0	0
2025-02-15	0	0	1,680	0	520	0	0	28	0	9
Monthly usage	18,000	3,500	1,680	0	520	300	59	28	0	9
Billable service minutes	300 minutes	59 minutes	28 minutes	0	9 minutes	The usage displayed on Agora Console is for reference only and not used as the actual billing basis.
Cost of each service ($US)	(300/1000 ) × 0.99 \= 0.297	(59/1000) × 3.99 \= 0.23541	(28/1000) × 8.99 \= 0.25172	0	(9/1000) × 35.99 \= 0.32391
Total cost ($US)	1.11 (0.297 + 2.3541 + 2.5172 + 0.32391 = 1.10804 ≈ 1.11）

Conv AI Tutorial

Agora Notifications demo

Agora Notifications demo

Agora Notifications demo