# Migration from SDK 3.x (/en/realtime-media/on-premise-recording/reference/migration-guide)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<_PlatformTabsGroup groupMode="structured" canonicalPlatform="linux-cpp" platforms="[&#x22;linux-cpp&#x22;,&#x22;linux-java&#x22;]" showTabs="true">
  <_PlatformPanel platform="linux-cpp">
    <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="linux-cpp" platform="linux-cpp" />

    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](/en/realtime-media/on-premise-recording).

    This guide highlights the major changes introduced in version 4.x compared to version 3.x.

    ## Key improvements in 4.x [#key-improvements-in-4x]

    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 [#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 [#functionality-changes]

    Version 4.x focuses on recording audio and video streams in the RTC channel and generating MP4 files.

    ### Deprecated features [#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

    <CalloutContainer type="info">
      <CalloutDescription>
        Version 4.x is designed for self-hosted deployment. It is not a cloud or aPaaS service.
      </CalloutDescription>
    </CalloutContainer>

    ## Changes in service behavior [#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 [#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`<br />- `IAgoraService::initialize`<br />- `createAgoraMediaComponentFactory`<br />- `createMediaRtcRecorder`<br />- `IAgoraMediaRtcRecorder::initialize`                                                                                                                   | `createAgoraRecordingEngine`                                                                                                                             |
    | Join a channel                             | `joinChannel`<br />If the String UID function is enabled, you can directly use the String UID to pass parameters when calling `joinChannel`, without calling other APIs.                                                                                                                          | - `joinChannel`<br />- `joinChannelWithUserAccount`<br />- `getUserInfoByUserAccount`<br />- `getUserInfoByUid`                                          |
    | Implement subscription logic               | - `subscribeAllAudio`<br />- `unsubscribeAllAudio`<br />- `subscribeAllVideo`<br />- `unsubscribeAllVideo`<br />- `subscribeAudio`<br />- `unsubscribeAudio`<br />- `subscribeVideo`<br />- `unsubscribeVideo`                                                                                    | Use the following fields in `RecordingConfig` when calling `joinChannel`:<br />- `autoSubscribe`<br />- `subscribeVideoUids`<br />- `subscribeAudioUids` |
    | Start or stop recording                    | **Individual recording:**<br />- `startSingleRecordingByUid`<br />- `stopSingleRecordingByUid`<br />- `setRecorderConfigByUid`<br /><br />&#x2A;*Composite recording:**<br />- `startRecording`<br />- `stopRecording`<br />- `setRecordingConfig`<br />Use with `enable_mix` set in `initialize` | - `startService`<br />- `stopService`<br />Use with `isMixingEnabled` in `RecordingConfig`                                                               |
    | Watermark                                  | - `enableAndUpdateVideoWatermarks`<br />- `disableVideoWatermarks`<br />- `enableAndUpdateVideoWatermarksByUid`<br />- `disableVideoWatermarksByUid`                                                                                                                                              | Use `updateWatermarkConfigs` with `wm_num` and `wm_configs` in `VideoMixingLayout`                                                                       |

    ## Callback comparison [#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](/en/api-reference/api-ref/on-premise-recording).

    <_PlatformProcessedMarker close="true" />
  </_PlatformPanel>

  <_PlatformPanel platform="linux-java">
    <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="linux-cpp" platform="linux-java" />

    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](/en/realtime-media/on-premise-recording).

    This guide highlights the major changes introduced in version 4.x compared to version 3.x.

    ## Key improvements in 4.x [#key-improvements-in-4x-1]

    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 [#new-capabilities-1]

    * 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 [#functionality-changes-1]

    Version 4.x focuses on recording audio and video streams in the RTC channel and generating MP4 files.

    ### Deprecated features [#deprecated-features-1]

    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

    <CalloutContainer type="info">
      <CalloutDescription>
        Version 4.x is designed for self-hosted deployment. It is not a cloud or aPaaS service.
      </CalloutDescription>
    </CalloutContainer>

    ## Changes in service behavior [#changes-in-service-behavior-1]

    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 [#api-comparison-1]

    The following table compares key APIs between version 4.x and 3.x:

    | Functional module                          | 4.x                                                                                                                                                                                                                                                                                                                        | 3.x                                                                                                                                                             |
    | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Create and initialize a recording instance | - `AgoraService`<br /> - `AgoraService.initialize`<br /> - `createAgoraMediaComponentFactory`<br /> - `createMediaRtcRecorder`<br /> - `AgoraMediaRtcRecorder.initialize`                                                                                                                                                  | `RecordingSDK`                                                                                                                                                  |
    | Join a channel                             | `joinChannel`<br />If the String UID function is enabled, you can directly use the String UID to pass parameters when calling `joinChannel`, without calling other APIs.                                                                                                                                                   | - `createChannel`<br /> - `createChannelWithUserAccount`<br /> - `getUidByUserAccount`<br /> - `getUserAccountByUid`                                            |
    | Implement subscription logic               | - `subscribeAllAudio`<br /> - `unsubscribeAllAudio`<br /> - `subscribeAllVideo`<br /> - `unsubscribeAllVideo`<br /> - `subscribeAudio`<br /> - `unsubscribeAudio`<br /> - `subscribeVideo`<br /> - `unsubscribeVideo`                                                                                                      | The following fields of the `RecordingConfig` object in the `create` method:<br /> - `autoSubscribe`<br /> - `subscribeVideoUids` <br /> - `subscribeAudioUids` |
    | Start or stop recording                    | **Individual recording:**<br /> - `startSingleRecordingByUid`<br /> - `stopSingleRecordingByUid`<br /> - `setRecorderConfigByUid`<br /><br />&#x2A;*Composite recording:**<br /> - `startRecording`<br /> - `stopRecording`<br /> - `setRecordingConfig`<br />Use with `enableMix` set to `true` when calling `initialize` | - `startService`<br /> - `stopService`<br />Use with `isMixingEnabled` in `RecordingConfig`                                                                     |
    | Watermark                                  | - `enableAndUpdateVideoWatermarks`<br /> - `disableVideoWatermarks`<br /> - `enableAndUpdateVideoWatermarksByUid`<br /> - `disableVideoWatermarksByUid`                                                                                                                                                                    | `updateWatermarkConfigs`                                                                                                                                        |

    ## Callback comparison [#callback-comparison-1]

    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](/en/api-reference/api-ref/on-premise-recording).

    <_PlatformProcessedMarker close="true" />
  </_PlatformPanel>
</_PlatformTabsGroup>