Release notes

The On-Premise Recording SDK provides recording functionality for the Agora Realtime Communication SDK. For more information see Product overview.

v4.x

With the 4.x release, the On Premise Recording SDK version 3.x and earlier have entered the retirement phase. For detailed retirement schedule and migration plan, refer to Service Sunset Plans.

v4.4.151

Released on September 30, 2025.

New Features

Video frame screenshots

This release adds the video frame screenshot feature. After initialization, call enableRecorderVideoFrameCapture to enable and configure video frame screenshots. You can then get the captured video data in callbacks of IRecorderVideoFrameObserver.

For implementation details, see Local screenshots.

Single-stream recording without transcoding

This release adds the recordEncodedOnly parameter to IAgoraMediaRtcRecorder::initialize, enabling single-stream recording without transcoding. After you enable this parameter, the server writes remote H.264 or H.265 video data directly to MP4 files.

This parameter is mainly for high-concurrency recording scenarios. Use it with VideoSubscriptionOptions.encodedFrameOnly set to true to maximize concurrency.

v4.4.150

Released on June 30, 2025.

This is the first release of the On-Premise Recording 4.x SDK. It includes the following features:

• Record real-time audio and video.
• Record audio and video content from all participants in a single channel.
• Record audio and video content from all participants in multiple channels simultaneously.
• Record audio-only content from all participants in one or more channels simultaneously.
• Support recording of encrypted channels using the built-in encryption of the Agora SDK.

v3.x

Known issues

• When you record using an Android client, the image is turned upside down when you switch from a front-facing camera to a rear one.
• If the user calls the leaveChannel method in the channel to stop recording, the recording file ends with a period of silence determined by the idleLimitSec field set for the configuration when calling the joinChannel method.
• The recorded voice or video files are not encrypted. To be compliant with HIPAA, encrypt the disk with a disk encryption tool, such as cryptsetup.

v3.0.6

v3.0.6 was released on May 18, 2021.

New feature

AES-GCM encryption

For use-cases requiring high security, to guarantee the confidentiality, integrity, and authenticity of the data and to improve the computational efficiency of the data encryption, this release adds the following options in decryptionMode:

• "aes-128-gcm": 128-bit AES encryption, GCM mode.
• "aes-256-gcm": 256-bit AES encryption, GCM mode.

Once you enable the built-in encryption, all users in the same channel must use the same encryption mode and key.

MP3 format in composite recording mode

v3.0.6 adds Audio_Only_Record and Secondary_Recorder in cfgFilePath to get a MP3 file after a composite recording. See Record a Call and cfgFilePath for details.

Improvements

• You can set the sample rate of the raw audio data in PCM format (getAudioFrame is 2 or 3) through the cfgFilePath parameter. See Record a Call for details.

• Optimize the sensitivity and accuracy of onActiveSpeaker and onAudioVolumeIndication callbacks.

• You can call mixedVideoAudio to get a MP4 file after a composite recording or an individual recording without transcoding.

  Earlier than v3.0.6	v3.0.6 or later
  Generates video files in TS format during the recording. When the recording ends, you can use the transcoding script to convert the TS file to MP4 format.	Generates video files in TS format and MP4 format during the recording.

API changes

Adds enumerators for MIXED_AV_CODEC_TYPE： AV_CODEC_INDIVIDUAL_TS_ONLY: Generates video files in TS format, and audio files in AAC format in the individual recording mode. AV_CODEC_INDIVIDUAL_TS_AND_MP4: Generates video files in TS format and MP4 format, and audio files in AAC format in the individual recording mode. AV_CODEC_MIXED_TS_ONLY: Mixes the audio and video in real time into an TS file in the composite recording mode. AV_CODEC_MIXED_TS_AND_MP4: Mixes the audio and video in real time into an TS file and an MP4 file in the composite recording mode.

Issues fixed

Fix the issue that the transcoding script does not support UIDs with underscores, resulting in parsing errors.

v3.0.5

v3.0.5 was released on January 13, 2021.

New feature

This release adds VIDEO_JPG_FILE in VIDEO_FRAME_TYPE to get video data in JPG file format.

Improvements

• To enable faster playback of the MP4 file generated from the recording, this release moves the moov atom to the start of the MP4 file, which allows for playback of the file during buffering.
• This release removes the restriction that you cannot get the raw audio data and raw video data at the same time from an individual recording session.

Issues fixed

This release fixed the following issues:

• The captured screenshots in JPG format had rotation information missing when the video decoding format was set as VIDEO_FORMAT_JPG_VIDEO_FILE_TYPE.
• Crashes when calling the leaveChannel method to leave a channel.

v3.0.4

v3.0.4 was released on November 25, 2020.

New feature

v3.0.4 adds Chunk_Time_Span in cfgFilePath to set time interval between two successive recorded files in individual recording mode of a live interactive streaming channel.

Issues fixed

• When a host repeatedly joins and leaves a channel, the physical memory consumption of the recording server increased significantly.
• Calling OnActiveSpeaker cannot get the corresponding callback.
• Calling OnAudioVolumeIndication cannot get the corresponding callback.
• Calling the Java API setUserBackground caused the recording service to crash.
• Failure to merge videos shorter than 0.02 s by using the transcoding script after the recording finishes.
• In composite recording mode, failure to output stereo audio by setting audioProfile as 2.

v3.0.3

v3.0.3 was released on September 17, 2020.

New feature

Repair of recording files after crashes

Before v3.0.3, the MP4 files generated after a recording might not be playable due to recording crashes. To solve this issue, as of v3.0.3, the Agora Recording SDK provides the following solutions:

• The SDK generates video files in TS format during the recording. When the recording ends, the SDK automatically converts the TS files to MP4 format. Even if occasional crashes occur during the recording, the MP4 files can still be played.
• The SDK adds the crash_restore.sh script. If the recording service quits abnormally after multiple crashes, you can run the script to convert the TS files to MP4 files and repair the incomplete uid_UID_timestamp.txt files.

v3.0.2

v3.0.2 was released on July 15, 2020.

Issues fixed

• Timestamps occasionally overflow in uid_UID_timestamp.txt.
• Characters are garbled and contents lost when a line of text becomes too long in a log file.
• MP4 files generated from a composite recording session cannot be played via Windows Media Player.

v3.0.1

v3.0.1 was released on March 16, 2020.

Issue fixed

Recorded files from an individual recording session have an incorrect timestamp in their names.

v3.0.0

v3.0.0 was released on February 20, 2020.

New features

1. Watermarks

Supports adding image watermarks, text watermarks, or a timestamp watermark in composite recording mode.

You can either configure watermark settings in the setVideoMixingLayout method, or add, update, and remove watermark settings with the updateWatermarkConfigs method. See Watermark for details.

2. Selective recording

Supports recording the audio or video of specified users.

To enable selective recording when calling joinChannel:

1. Set autoSubscribe as false in RecordingConfig.
2. Set the subscribeVideoUids or subscribeAudioUids parameter in RecordingConfig to specify the users to record.

Afterwards, you can call updateSuscribeVideoUids or updateSuscribeAudioUids methods to update the list of uids to record.

3. Last frame

Retains the last video frame from when the user leaves the channel in composite recording mode.

You can set the keepLastFrame parameter when calling the setVideoMixingLayout method to enable this feature.

4. Cloud proxy

Supports the cloud proxy service. See Use Cloud Proxy for details.

5. New callbacks

Channel events

• onRejoinChannelSuccess Occurs when the recording server rejoins a channel.
• onConnectionStateChanged Occurs when the network connection state changes.

Statistics events

• onRemoteVideoStats Reports the statistics of the video stream from each remote user/host.
• onRemoteAudioStats Reports the statistics of the audio stream from each remote user/host.
• onRecordingStats Reports the statistics of the recording session.

Media events

• onRemoteAudioStreamStateChanged Occurs when the state of a remote audio stream changes.
• onRemoteVideoStreamStateChanged Occurs when the state of a remote video stream changes.

Improvement

• As of v3.0.0, you can disable the keyframe request by setting the enableIntraRequest parameter in RecordingConfig. After this setting:
  • All senders in the channel send the keyframe at an interval of 2 seconds.
  • You can play the video file recorded in individual recording mode from a specified position without the need to transcode.
• As of v3.0.0, setting the recording file path in the custom configuration file is no longer mandatory. If you have specified a custom configuration file by setting cfgFilePath, you do not have to set Recording_Dir in the configuration file.

Issues fixed

• In composite recording mode, the layout of the recorded video occasionally has an extra user region.
• The playback speed of the recorded video is occasionally too fast.
• The recording service creates too many Syslogs.
• Setting the alpha parameter in the method call of setVideoMixingLayout causes the recording service to crash.
• The recording service cannot record the specified uids if you set the server to record audio only, or to record video only.
• The information reported by the onRemoteAudioStreamStateChanged and onRemoteVideoStreamStateChanged callbacks is inaccurate under poor network conditions.
• The recorded audio is occasionally extended.
• A black frame appears at the beginning of a video in composite recording mode.

v2.x

v2.3.4

v2.3.4 was released on August 5, 2019.

Improvements

• The following private Java API methods are now public:
  • The setUserBackground method which sets the background image of a specified user. When the user is online but does not send any video stream, the background image is displayed.
  • The setLogLevel method which sets the logging level. The SDK generates logs in the selected level and in the levels preceding the selected level.
• Improves the robustness of Java API methods.
• Enhances the SDK's ability to collect the information of abnormal crashes.

Issues fixed

• File splitting in composite recording mode caused by switching channel profiles.
• Failure to only record audio in composite recording mode in the Live Broadcast profile.
• Libyuv crashes.
• Crashes when calling the leaveChannel method to leave a channel.

v2.3.3

v2.3.3 was released on April 1, 2019.

New features

1. Supports monitoring the network connection status

v2.3.3 adds the following callbacks to inform the app of the connection status between the recording SDK and Agora's edge server:

• onConnectionLost: Informs that the SDK loses connection to the server.
• onConnectionInterrupted: Informs that the connection between the SDK and the server is interrupted.

2. Informs the app of receiving the first frame

v2.3.3 adds the following callbacks to inform the app of receiving the first remote audio or video frame:

• onFirstRemoteAudioFrame: Informs that the first remote audio frame is received.
• onFirstRemoteVideoDecoded: Informs that the first remote video frame is decoded.

3. Supports monitoring status changes of the receiving stream

v2.3.3 adds the onReceivingStreamStatusChanged callback to get status changes of the receiving audio or video stream.

4. Supports the volume indication

v2.3.3 adds the onAudioVolumeIndication callback to get the list of users who are speaking and their volumes.

Issues fixed

• Fails to run the transcoding script when the recording SDK exits the channel and then enters the channel again in manual mode.
• Occasional crashes when using invalid parameters in the mixedVideoAudio method.
• Freezes in HD video recordings.
• Setting the recording video frame rate does not take effect.
• Occasional crashes when compiling the recording Java sample code in Manual Mode.
• Fails to run the transcoding command -f . -m 3.

v2.3.0

v2.3.0 was released on January 14, 2019.

The calculation of the usage of the On-Premise Recording SDK v2.3.0 or later is separated from that of the Agora Voice Call/Interactive Audio Streaming SDK and the Agora Video Call/Interactive Video Streaming SDK. Contact support@agora.io for details.

New features

1. Supports Stereo Audio in Composite Recording Mode

v2.3.0 supports high audio quality (a sample rate of 48 kHz, stereo, and a bitrate of up to 192 Kbps) in Composite Recording Mode.

Stereo is not applicable to raw data.

audio profile can be set as 0 or 1:

• Individual recording (file mode):
  • By default or set audio profile=0: A sample rate of 48 kHz, the same number of audio channels as the original audio, and an adaptive bitrate.
• Individual recording (raw data):
  • The sample rate is fixed at 48 kHz and the number of audio channels is the same as the original audio:
    • PCM: The bitrate may change.
    • AAC: The bitrate is the same as in the file mode.
• Composite recording (file mode):
  • audio profile=0: A sample rate of 48 kHz, mono, and a bitrate of 48 Kbps
  • audio profile=1: A sample rate of 48 kHz, mono, and a bitrate of 128 Kbps
  • audio profile=2: A sample rate of 48 kHz, stereo, and a bitrate of 192 Kbps
• Composite recording (raw data):
  • A fixed sample rate of 48 kHz and mono.

2. Supports Web Video Players

Video files transcoded in real time or transcoded by the transcoding script can be played by web browsers on Android, iOS/macOS, and Windows. The following is a list of compatible web browsers on each platform.

3. Supports Custom Background Images in Composite Recording Mode

v2.3.0 adds the function for users to add a background image while recording audio in Composite Recording Mode. A custom image is used for any user who does not have video while recording video in Composite Recording Mode.

This function is not applicable to raw data and screenshots.

4. Adds Two Pre-defined Layout Templates to the Sample Code

v2.3.0 provides two pre-defined layout templates for composite recording to make the On-Premise Recording SDK sample code easier to use.

Best Fit (bestFit)

v2.3.0 adds bestFit as the default layout supporting up to 17 video streams.

This layout automatically scales according to the number of video streams. The number of columns and rows varies depending on the number of video streams. For example:

Vertical Presentation（verticalPresentation）

v2.3.0 adds the function to display a specified user's video in a large window on the left of the screen, while displaying the other users' videos in small windows arranged vertically on the right. At most, two columns with eight video windows in each column are supported.

For example:

5. Screenshots in Composite Recording Mode

v2.3.0 adds the function to capture the screen of every user while recording video in Composite Recording Mode. Recording and screen capturing use the same video stream.

6. Speaker Detection

v2.3.0 adds the onActiveSpeaker callback to return the UID of the active speaker in the channel.

This function is disabled by default and can be enabled by setting the audioIndicationInterval parameter in RecordingConfig. The On-Premise Recording SDK returns the onActiveSpeaker callback at set intervals.

Improvements

• Improves audio and video synchronization in Individual Recording Mode.
• Supports automatic rotation of recorded video streams that are not transcoded in real time in Individual Recording Mode.
• Changed the idle behavior in Manual Mode:
  • For versions earlier than v2.3.0 in Manual Mode, the idle mechanism takes effect immediately after joining a channel, which might cause the recording SDK to exit the channel.
  • For v2.3.0 or later, the idle mechanism does not take effect until the startService method is called.
• Optimizes the log levels and split some logs in INFO into NOTICE, WARN, and ERROR.
• Optimizes the naming of the recording directory to ensure the uniqueness of each folder.

v2.2.3

v2.2.3 was released on October 18, 2018.

Issues fixed

• Coredump loss caused by .backtrace.
• System crashes caused by Java jni. and optimize stability.
• Transcoding script issues in Manual Mode.
• The recording video file splits into two files after a web client joins the channel.
• Occasional system crashes caused by the subthread being active after the main thread is released.

v2.2.2

v2.2.2 was released on August 1, 2018.

Improvements

• The screenshots are named uidYmdHMSms.jpg instead of uidYmdHMS.jpg.
• The transcoding script supports autorotation.
• The structure of the Java folder is modified.

Issues fixed

• Abnormal webm recording times.
• Memory leaks.
• Multi-party intercommunication issues.
• H.264 parser issues.
• Audio and video out of sync.

v2.2.1

v2.2.1 was released on June 5, 2018.

Improvements

• Improves the performance of the Communication profile. The number of recording channels that a system supports with the same performance increases by 150%.
• Improves the efficiency to find the port. The time to find the port is no longer part of the idle time.

Issues fixed

Port conflicts when the search for the port takes too long and exceeds the idle time. As a result, the port is not connected.

v2.2.0

v2.2.0 was released on May 4, 2018.

New features

Support for both Java and C++.

Issues fixed

• Issues of oversized logs.
• Abnormal issues when recording fast-forward videos.
• Intermittent failures.
• Performance issues.
• Some crash issues.

v2.1.0

v2.1.0 was released on March 7, 2018.

New features

Improvements

Issues fixed

• Occasional recording file transcoding failures.
• The video screen occasionally turns upside down.
• Occasional abnormal audio during recording.

v2.0.0

v2.0 was released on November 21, 2017.

• Optimizes the raw data to support various formats:
  • Modifies the decodeAudio and decodeVideo parameters, and adds the VideoJpgFrame struct.
  • Modifies the getAudioFrame and getVideoFrame parameters.
• Adds the captureInterval parameter to set the time interval of capturing screenshots.
• Adds the streamType parameter to support different video stream types.
• Adds the isVideoOnly parameter.
• The transcoding scripts, once used, generate a convert.log file under the same path as the voice/video file.
• Adds the video rotating information in UID_HHMMSSMS.txt.

v1.x

v1.3.0

v1.3 was released on October 20, 2017.

New features:

• Adds mixing the audio and video recording functions by adding the mixedVideoAudio and cfgFilePath parameters in the joinChannel method.
• Adds the function of merging the audio and video file of the same uid as one, see Play the Recording Files.
• Adds the getProperties method to get the recording path immediately after recording is started before joining any channel.
• Modifies the onError and onLeaveChannel callbacks.

v1.2.0

v1.2 was released on August 21, 2017.

New features:

• Supports getting the audio and video raw data.
• Supports detecting sexually explicit content.
• Provides a recordingsys.log log file to check for failures.
• Supports the recording channel timestamp, that is, the first user who starts recording in the channel.

v1.1.0

v1.1 was released on July 25, 2017.

New features:

• Adds recording at the web client.

• Adds the real-time video mixing function.

• Adds a set of callback functions.

• Modifies the file format after transcoding.

• Enables configuring the UDP port.

• Issues fixed:

• Wrong timestamps.

• Transcoding failures.

• Unable to playback VLC files.

v1.0.1

v1.0.1 was released on June 27, 2017, and fixes the crash when you set the channel profile of the recording as live broadcast.

v1.0.0

v1.0.0 was released on June 15, 2017.

This is the first release of the On-Premise Recording SDK with the following functions:

• Communication and interactive live streaming use-cases.
• Recording the voice and video of all users in a channel.
• Recording the voice and video of all users in multiple channels simultaneously.
• Recording the voice of all users in a channel or in multiple channels simultaneously.
• Recording an encrypted channel if the application has integrated the Agora built-in encryption.

The On-Premise Recording SDK provides recording functionality for the Agora Realtime Communication SDK. For more information see Product overview.

v4.x

With the 4.x release, the On Premise Recording SDK version 3.x and earlier have entered the retirement phase. For detailed retirement schedule and migration plan, refer to Service Sunset Plans.

v4.4.151

Released on September 30, 2025.

Compatibility changes

This release removes the AgoraMediaComponentFactory interface class and moves the original createMediaRtcRecorder method into the AgoraService class. If you upgrade from v4.4.150 to v4.4.151, update your integration logic accordingly.

New Features

Video frame screenshots

This release adds the video frame screenshot feature. After initialization, call enableRecorderVideoFrameCapture to enable and configure video frame screenshots. You can then get the captured video data in callbacks of IRecorderVideoFrameObserver.

For implementation details, see Local screenshots.

Single-stream recording without transcoding

This release adds an overloaded initialize method to AgoraMediaRtcRecorder. Use the recordEncodedOnly parameter to enable single-stream recording without transcoding. After you enable this parameter, the server writes remote H.264 or H.265 video data directly to MP4 files.

This parameter is mainly for high-concurrency recording scenarios. Use it with VideoSubscriptionOptions.encodedFrameOnly set to true to maximize concurrency.

v4.4.150

Released on June 30, 2025.

This is the first release of the On-Premise Recording 4.x SDK. It includes the following features:

• Record real-time audio and video.
• Record audio and video content from all participants in a single channel.
• Record audio and video content from all participants in multiple channels simultaneously.
• Record audio-only content from all participants in one or more channels simultaneously.
• Support recording of encrypted channels using the built-in encryption of the Agora SDK.