Recording

createMediaRecorder

Creates an audio and video recorder instance.

virtual agora_refptr<IMediaRecorder> createMediaRecorder(const RecorderStreamInfo& info) = 0;

Before starting to record audio and video streams, you need to call this method to create a recorder instance. The SDK supports recording multiple audio and video streams from local or remote users. You can call this method multiple times to create multiple recorder instances and specify the channel name and remote user ID to record via the info parameter. After successful creation, you need to call setMediaRecorderObserver to register an observer for the recorder instance to listen for related callbacks, and then call startRecording to start recording.

Parameters

info: Audio and video stream information. See RecorderStreamInfo.

Return Values

If the method call succeeds, returns an IMediaRecorder instance. See IMediaRecorder. If the method call fails, returns NULL.

destroyMediaRecorder

Destroys the audio and video recorder object.

virtual int destroyMediaRecorder(agora_refptr<IMediaRecorder> mediaRecorder) = 0;

When you no longer need to record audio and video streams, you can call this method to destroy the corresponding recorder instance. Before calling this method, make sure you have called stopRecording to stop recording.

Parameters

mediaRecorder: The recorder instance to destroy. See IMediaRecorder.

Return Values

0: Success.
< 0: Failure.

setMediaRecorderObserver

Registers the IMediaRecorderObserver observer.

virtual int setMediaRecorderObserver(media::IMediaRecorderObserver* callback) = 0;

Since: Available since v4.0.0.

This method sets the callback for audio and video recording, allowing the application to receive recording status and information notifications during the recording process. Before calling this method, make sure:

You have created and initialized the IRtcEngine object.
You have created a media recorder object using createMediaRecorder.

Parameters

callback: Callback for audio and video stream recording. See IMediaRecorderObserver.

Return Values

0: Success.
< 0: Failure.

startAudioRecording [1/3]

Starts client-side audio recording and sets the recording sample rate.

virtual int startAudioRecording(const char* filePath, AUDIO_RECORDING_QUALITY_TYPE quality) = 0;

After calling this method, you can record the audio of all users in the channel during a call and generate a recording file that contains all voices. The recording file supports the following formats only:

.wav: Large file size, high audio fidelity.
.aac: Small file size, lower audio fidelity.

Note:

Make sure the specified path exists and is writable.
You must call this method after calling joinChannel. If leaveChannel is called during recording, the recording stops automatically.

Parameters

filePath: The absolute path (including the file name and extension) where the recording file is saved locally. For example: C:\music\audio.aac.
Note: Make sure the specified path exists and is writable.
quality: Recording quality. See AUDIO_RECORDING_QUALITY_TYPE.

Return Values

0: Success.
< 0: Failure.

startAudioRecording [2/3]

Starts client-side audio recording and sets the recording sample rate.

virtual int startAudioRecording(const char* filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality) = 0;

After calling this method, you can record the audio of all users in the channel on the client during the call and generate a recording file that contains all voices. The recording file supports the following formats only:

.wav: Large file size, high audio fidelity.
.aac: Small file size, low audio fidelity.

Note:

Ensure that the specified path in this method exists and is writable.
You must call this method after calling joinChannel. If you call leaveChannel during recording, the recording stops automatically.
To ensure recording quality, when sampleRate is set to 44.1 kHz or 48 kHz, it is recommended to set quality to AUDIO_RECORDING_QUALITY_MEDIUM or AUDIO_RECORDING_QUALITY_HIGH.

Parameters

filePath

The absolute path to save the recording file locally, including the file name and extension. For example: C:\music\audio.aac.

Note: Ensure the specified path exists and is writable.

sampleRate

Recording sample rate (Hz). You can set it to one of the following values:

16000
32000 (default)
44100
48000

quality

Recording quality. See AUDIO_RECORDING_QUALITY_TYPE.

Return Values

0: Success.
< 0: Failure.

startAudioRecording [3/3]

Starts client-side audio recording and sets recording parameters.

virtual int startAudioRecording(const AudioRecordingConfiguration& config) = 0;

After calling the startAudioRecording method, you can record the audio of users in the channel on the client during the call and obtain the recording file. The recording file supports the following formats:

WAV: High audio fidelity, large file size. For example, with a sample rate of 32000 Hz, a 10-minute recording is about 73 MB.
AAC: Lower audio fidelity, small file size. For example, with a sample rate of 32000 Hz and recording quality set to AUDIO_RECORDING_QUALITY_MEDIUM, a 10-minute recording is about 2 MB.

When the user leaves the channel, the recording stops automatically.

Timing

You must call this method after joining a channel.

Parameters

config: Recording configuration. See AudioRecordingConfiguration.

Return Values

0: Success.
< 0: Failure.

startRecording

Starts recording audio and video streams.

virtual int startRecording(const media::MediaRecorderConfiguration& config) = 0;

Since: Available since v4.0.0.

This method starts recording audio and video streams, supporting simultaneous recording of local and remote users' audio and video streams. Before calling this method, make sure:

You have created a recorder instance using createMediaRecorder.
You have registered a recorder observer using setMediaRecorderObserver to listen for recording callbacks.
You have joined a channel.

This method supports recording the following content:

Microphone audio captured in AAC encoding format.
Camera video captured in H.264 or H.265 encoding format.

After recording starts:

If the video resolution changes during recording, the SDK stops the recording.
If the audio sampling rate or number of channels changes, the SDK continues recording and generates an MP4 file.

A recording file is generated only when recordable audio or video streams are detected. If there are no recordable streams, or if the stream is interrupted for more than 5 seconds during recording, the SDK stops recording and triggers the onRecorderStateChanged (RECORDER_STATE_ERROR, RECORDER_REASON_NO_STREAM) callback.

Note:

If you want to record local audio and video streams, make sure to set the local user's role to broadcaster before starting the recording.
If you want to record remote audio and video streams, make sure to subscribe to the remote user's stream before starting the recording.

Parameters

config: Audio and video stream recording configuration. See MediaRecorderConfiguration.

Return Values

0: Success.
< 0: Failure.
- -2: Invalid parameter. Please ensure:
  - The specified recording file path is correct and writable.
  - The specified recording file format is correct.
  - The maximum recording duration is set correctly.
- -4: The current state of IRtcEngine does not support this operation. This may be due to an ongoing recording or a recording that has stopped due to an error.
- -7: IRtcEngine is not initialized when this method is called. Please ensure the IMediaRecorder object is created before calling this method.

stopAudioRecording

Stops client-side audio recording.

virtual int stopAudioRecording() = 0;

Return Values

0: Success.
< 0: Failure.

stopRecording

Stops recording of audio and video streams.

virtual int stopRecording() = 0;

Since: Available since v4.0.0.

Note: After calling startRecording, you must call this method to stop the recording, otherwise the generated recording file may not play properly.

Return Values

0: Success.
< 0: Failure:
- -7: IRtcEngine is not initialized when this method is called. Please ensure the IMediaRecorder instance is created before calling this method.

onRecorderInfoUpdated

Callback when recording information is updated.

virtual void onRecorderInfoUpdated(const char* channelId, rtc::uid_t uid, const RecorderInfo& info) = 0;

Since: Available since v4.0.0.

After successfully registering this callback and starting audio and video stream recording, the SDK periodically triggers this callback based on the value of recorderInfoUpdateInterval set in MediaRecorderConfiguration, reporting the current recording file name, duration, and size.

Trigger Timing

After successfully registering this callback and starting audio and video stream recording, the SDK periodically triggers this callback.

Parameters

channelId: Channel name.
uid: User ID.
info: Recording file information. See RecorderInfo.

onRecorderStateChanged

Callback when the recording state changes.

virtual void onRecorderStateChanged(const char* channelId, rtc::uid_t uid, RecorderState state, RecorderReasonCode reason) = 0;

Since: Available since v4.0.0.

When the recording state of the audio and video stream changes, the SDK triggers this callback to report the current recording state and the reason for the change.

Parameters

channelId: Channel name.
uid: User ID.
state: Current recording state. See RecorderState.
reason: Reason for the change in recording state. See RecorderReasonCode.