Migration from SDK 3.x
Updated
Sunset plans for Agora services.
The On-Premise Recording SDK 4.x is the latest version that enables audio and video recording during real-time interactions. For a complete list of features and applicable use cases, refer to the Product Overview.
This guide highlights the major changes introduced in version 4.x compared to version 3.x.
Key improvements in 4.x
The On-Premise Recording SDK 4.x is built on top of the latest Agora RTC SDK 4.x. It provides significant improvements in compatibility, performance, and codec support.
New capabilities
- Supports the latest Agora cloud agent
- Improved resilience in weak network conditions and adaptive feedback
- Compatibility with Video SDK 4.x and later
- Support for AV1 and other peer codecs
- Easier upgrades due to shared RTC engine between the RTC SDK and the recording SDK
Functionality changes
Version 4.x focuses on recording audio and video streams in the RTC channel and generating MP4 files.
Deprecated features
The following features are not available in SDK 4.x. If needed, use the Agora RTC Server SDK:
- Access to raw audio and video (For example, YUV or PCM data)
- Built-in cloud container deployment
Version 4.x is designed for self-hosted deployment. It is not a cloud or aPaaS service.
Changes in service behavior
The following runtime behaviors from version 3.x have been removed in version 4.x:
- Multi-process service management
- Automatic crash recovery
You must implement service management and failover handling in your own infrastructure.
API comparison
The following table compares key APIs between version 4.x and 3.x:
| Functional module | 4.x API | Older versions |
|---|---|---|
| Create and initialize a recording instance | - createAgoraService- IAgoraService::initialize- createAgoraMediaComponentFactory- createMediaRtcRecorder- IAgoraMediaRtcRecorder::initialize | createAgoraRecordingEngine |
| Join a channel | joinChannelIf the String UID function is enabled, you can directly use the String UID to pass parameters when calling joinChannel, without calling other APIs. | - joinChannel- joinChannelWithUserAccount- getUserInfoByUserAccount- getUserInfoByUid |
| Implement subscription logic | - subscribeAllAudio- unsubscribeAllAudio- subscribeAllVideo- unsubscribeAllVideo- subscribeAudio- unsubscribeAudio- subscribeVideo- unsubscribeVideo | Use the following fields in RecordingConfig when calling joinChannel:- autoSubscribe- subscribeVideoUids- subscribeAudioUids |
| Start or stop recording | Individual recording: - startSingleRecordingByUid- stopSingleRecordingByUid- setRecorderConfigByUidComposite recording: - startRecording- stopRecording- setRecordingConfigUse with enable_mix set in initialize | - startService- stopServiceUse with isMixingEnabled in RecordingConfig |
| Watermark | - enableAndUpdateVideoWatermarks- disableVideoWatermarks- enableAndUpdateVideoWatermarksByUid- disableVideoWatermarksByUid | Use updateWatermarkConfigs with wm_num and wm_configs in VideoMixingLayout |
Callback comparison
The following table compares key callbacks between version 4.x and 3.x:
| Event | 4.x API | Older versions |
|---|---|---|
| Local user joins the channel | onConnected | onJoinChannelSuccess |
| Local user leaves the channel | onDisconnected | onLeaveChannel |
| Local user rejoins after reconnecting | onReconnected | onRejoinChannelSuccess |
| Remote user leaves the channel | onUserLeft | onUserOffline |
| First frame of remote audio is received | onFirstRemoteAudioDecoded | onFirstRemoteAudioFrame |
| Remote user's audio state changes | onUserAudioStateChanged | onRemoteAudioStreamStateChanged |
| Remote user's video state changes | onUserVideoStateChanged | onRemoteVideoStreamStateChanged |
For more information, refer to the API reference.