Skip to main content

You are viewing Agora Docs forBeta products and features. Switch to Docs

Record by API

This page shows how to record a call by calling API methods. You can also record calls by using the command line, see Record by Command Line. The command line and API methods implement the same recording functions.

The Agora On-Premise Recording SDK joins a channel as a dummy client. It needs to join the same channel and use the same App ID and channel profile as the Agora Native/Web SDK.

Ensure that you integrate the SDK before proceeding.

Create an instance

IRecordingEngineEventHandler *handler = <prepare>
IRecordingEngine* engine = createAgoraRecordingEngine(<APPID>, handler)

Call the createAgoraRecordingEngine method to create a recording instance and connect it with your app. You can create multiple instances to record simultaneously.

Start recording

RecordingConfig config = {<prepare>}
engine->joinChannel(<channelKey>, <channelId>, <uid>, config)

After creating a recording instance, call the joinChannel method to join the channel and start recording. In this method, fill in the following parameters:

  • channelKey: (Optional) The token used in the channel to be recorded. If the channel uses a token, ensure that you pass a token in this parameter. See Secure authentication.
  • channelId: (Mandatory) The name of the channel to be recorded.
  • uid: (Mandatory) User ID. A 32-bit unsigned integer ranging from 1 to (232-1) that is unique in a channel. If the uid is set as 0, the SDK assigns a uid.
  • config: (Optional) The recording configuration. See RecordingConfig for details.

After joining the channel, the SDK starts recording when detecting other users in the channel.

If you set triggerMode as MANUALLY_MODE in RecordingConfig, you need to call the startService method to start recording manually. During the recording, you can call the stopService method to pause the recording.


Ensure that you call the startService and stopService methods only after joining a channel.

Get the directory of the recording files

RecordingEngineProperites ps = engine->getProperties()

After joining a channel, you can call the getProperties method to get the directory of the recording files.

You can also get the directory in the onUserJoined callback when a remote user joins the channel.

Stop recording


Call the leaveChannel method to stop recording and leave the channel.

To start recording again after calling this method, create another instance.

If the leaveChannel method is not called, the SDK automatically leaves the channel and stops recording when no user is in the channel for more than 300 seconds (you can set this interval by the idelLimitSec parameter in RecordingConfig by default.

Release resources


Call the release method to destroy the recording instance and release all recording resources. After releasing the resources, you must create a new instance to use On-Premise Recording again.

Do not implement the release method in the callback thread.