AliRTC 3.0 升级说明_音视频通信(RTC)-阿里云帮助中心

通过本文，开发者完成RTC 2.5 升级到 RTC 3.0。

一、背景介绍

AliRTC 3.0版本是基于钉钉音视频能力开发的新一代RTC，沉淀了钉钉音视频服务海量用户的技术经验。自2024年4月10日起，所有新建的应用都要求是AliRTC 3.0版本，不再提供AliRTC2.x版本的应用新建。新建的3.0应用必须使用配套RTC 3.0版本的集成客户端SDK和API目录。

目前有很多老客户线上运行的是AliRTC 2.5.7版本，因此需要尽快完成升级。升级过程，有几点需要重点注意：

AliRTC 2.x 与 AliRTC 3.x 不能互通。
集成AliRTC 3.x 需要重新注册新的AppId。
客户端和服务端（若调用了RTC OpenAPI）都需要集成新的SDK。
Native客户端（Android/iOS/Mac/Windows）SDK API变化较小。
Web端 SDK API变化较大。

二、AliRTC 3.0优势

体验与钉钉会议对齐

超大容量：2000 人同时参会
高清画质：1080P 高清视频
高清语音：300+ 噪音智能降噪
全球部署：2800+ 全球加速节点
超低延时：150ms 保障流畅交流
稳定运行：70% 抗丢包、抗抖动

计划支持鸿蒙平台

计划25年推出

计划支持会议白板

支持虚拟背景

新老RTC对比

		AliRTC 2.0（老）	AliRTC 3.0（新）
包大小	Android（arm64）	8M	15.8M（算法优化带来包大小增加）
包大小	iOS（arm64）	5.4M	10.6M（算法优化带来包大小增加）
大方会		50方	2000方
信令可靠性		需重入会	完善的failover机制
多层分辨率		2层	3层
延时		300ms左右	150ms左右
稳定性		QA测试保障	QA测试保障 + 钉钉线上打磨

三、计费变更说明

音视频通话计费

老的计费方式视频按照单路流进行计费，而新的计费方式按照集合分辨率进行计费。

老的计费方式

通信类型	订阅分辨率	价格（元/千分钟）
语音通话	纯音频	6
视频通话 480P及一下	不高于640 × 480（含）	12
视频通话 720P及以下	640 × 480 ~ 1280 × 720（含）	24
视频通话 1080P及以下	高于1280 × 720	90

新的计费方式

通信类型	订阅分辨率	价格（元/千分钟）
语音通话	纯音频	6
视频通话 480P及以下	集合分辨率 ≤ 307,200（640 × 480）	12
视频通话 720P及以下	307,200（640×480）< 集合分辨率 ≤ 921,600（1280 × 720）	24
视频通话 1080P及以下	921,600（1280 × 720）< 集合分辨率 ≤ 2,073,600（1920 × 1080）	60
视频通话 2K及以下	2,073,600（1920 × 1080）< 集合分辨率 ≤ 3,686,400 （2560 × 1440）	108
视频通话 4K及以下	3,686,400 （2560 × 1440）< 集合分辨率 ≤ 8,847,360 （4096 × 2160）	252

价格对比

假设一个客户端订阅3路480P的视频流，按照老的计费方式计算：

$单个客户端视频订阅成本 = 3 \times 12 = 36 元 / 千分钟$

现在按照新的计费方式计算：

$集合分辨率 = 640 \times 480 \times 3 = 921600$

$单个客户端视频订阅成本 = 24 元 / 千分钟$

旁路转推计费

老的计费方式视频按照输入流的数量以及输出流的分辨率进行计费，而新的计费方式按照输入流的集合分辨率进行计费。

老的计费方式

规格	480P及以下（元/千分钟）	720P及以下（元/千分钟）	1080P及以下（元/千分钟）
16IN	50	145	270
12IN	42	119	220
9IN	36	98	177
4IN	25	65	110
2IN	20	52	84
1IN	18	45	71
纯音频	5

新的计费方式

通信类型	规格	价格（元/千分钟）
音频	纯音频	9
视频通话 480P及以下	集合分辨率 ≤ 307,200（640 × 480）	36
视频通话 720P及以下	307,200（640×480）< 集合分辨率 ≤ 921,600（1280 × 720）	48
视频通话 1080P及以下	921,600（1280 × 720）< 集合分辨率 ≤ 2,073,600（1920 × 1080）	108

价格对比

场景描述：将频道中的两路480P的视频流，通过旁路混流为720P的视频流。

按照旧的计费规则：

旁路转推TaskProfile = 2IN_720P

按照老的计费方式单价为： 52元/千分钟。

按照新的计费规则：

集合面积 = 480P视频面积 x 2 = 614400

因此，按照新的计费方式单价为： 48元/千分钟。

四、升级步骤

1. 参考方案（一）

对于端侧版本可控的业务，即全体用户会按照业务推荐统一使用某一版本，建议采用此方案。如果无法确保所有用户都是用某一版本，若采用此方案，则对于老版本，访问到相关功能时，需要提示进行升级，否则相关功能不可用。

优点：实施周期短，同正常发版周期。

缺点：没有回退机制和很好的灰度机制，对版本的稳定性要求比较高，发版前需要充分测试。

第一阶段：预埋升级提醒

在现有版本中，预埋升级提醒，当SDK版本升级之后，老版本app访问相关功能时提醒用户进行升级。

第二阶段：升级新RTC SDK的版本上线

阿里云RTC：提供新版本RTC SDK。

业务方：升级新版本RTC SDK，对接新版本RTC的OpenAPI，同时限制老RTC客户端不会参与新版本的会议。

阿里云RTC：支持业务方完成集成，功能和体验对齐老版本。

第三阶段：采取各种手段推动用户进行版本升级

2. 参考方案（二）

对于端侧版本不可控的业务，即用户是否会升级到新版本app无法有效控制，建议采用此方案。

优点：有较好回退机制和灰度机制；

缺点：实施周期长，按照用户版本自然升级规律，预计3个月以上。

第一阶段：集成新RTC SDK的版本上线

阿里云RTC：提供新版本RTC SDK。

业务方：集成新版本RTC SDK，对接新版本RTC的OpenAPI，同时开发新老RTC的灰度机制。

阿里云RTC：支持业务方完成集成，功能和体验对齐老版本。

第二阶段：等待新版本升级百分比达到期望值

业务方：推进新版本的升级，根据情况决定是否强制升级。

第三阶段：按照会议进行灰度

业务方：按照1%，2%，5%，10%，20% ......逐步切量灰度。

第四阶段：完成整体切量。

第五阶段：剔除老版本RTC SDK

业务方：剔除老版本RTC SDK。

五、API升级补充说明

1. 大小流API 升级说明

老版RTC，只支持两层视频流（大流和小流）；在新版RTC中，支持三层视频流，接口调用形式也做了较大改变。

1）推流端：原publishLocalDualStream 在新版本中已经废弃，相应的老版本的onDualStreamPublishStateChanged回调接口也已经废弃。新版本中不需要调用任何API，SDK实现了按需推流，根据订阅需求自主决定是否分层推流。根据最大分辨率的规格，最大可支持3档同时推流（Full HD/HD, SD, LD）。

2）订阅端：新版本保留了setRemoteVideoStreamType接口，但是streamType参数类型发生了变化。新的参数枚举类型为DingRtcVideoStreamType，根据需要可以选择订阅DingRtcVideoStreamTypeLD（流畅）、DingRtcVideoStreamTypeSD（标清 360P左右）、DingRtcVideoStreamTypeHD（高清 720P）、DingRtcVideoStreamTypeFHD（超高清 1080P）。

2. 音视频缺省订阅API升级说明

老版本RTC的setDefaultSubscribeAllRemoteAudioStreams 和 setDefaultSubscribeAllRemoteVideoStreams 已经废弃，全部由subscribeAllRemoteAudioStreams 和 subscribeAllRemoteVideoStreams 来替代。

3. 单个音频订阅API 升级说明

老版本RTC的subscribeRemoteAudioStream接口已经废弃。新版本对音频订阅做了较大的改造，不再支持对单个用户音频的订阅，取而代之的是音频分组。

我们可以把频道理解为大厅，分组理解为小房间。一旦用户加入到小房间，就能订阅到小房间的音频；离开小房间回到大厅，则只能订阅到大厅的音频。如果一个用户仅需要订阅个别用户的音频，那么这几个用户需要单独加入音频组，并进行订阅。

1）加入音频组

/**
 * @since 3.4
 * @brief 加入音频分组。如果分组当前不存在，则自动创建一个。
 * @param groupId 指定加入的音频分组。不可以是大厅、DingRtcEngine::HALL_ID，也不可以为空。
 * @param usrData 可以额外提供一个字符串，业务层自行解释。长度不超过64字节。
 * @return int 如果返回0，结果将会通过DingRtcEngineEventListener#onAudioGroupJoinResult通知app。如果返回<0，则调用失败，不会有通知消息onAudioGroupJoinResult。
 * @note usrData暂时未支持。
 */
public abstract int joinGroup(String groupId, String usrData);

2）离开音频组

/**
 * @since 3.4
 * @brief 离开音频分组。
 * @param groupId 要离开的音频分组。不可以是大厅{@link com::ding::rtc::DingRtcEngine::HALL_ID}，也不可以为空。
 * @return int 如果返回0，结果将会通过{@link com::ding::rtc::DingRtcEngineEventListener#onAudioGroupLeaveResult}通知app。如果返回<0，则调用失败，不会有通知消息onAudioGroupLeaveResult。
 * @note 如果离开了分组，那么没有权限再订阅该分组的音频，也没有权限向该分组mix音频流。
 */
public abstract int leaveGroup(String groupId);

3）解散音频组

/**
 * @since 3.4
 * @brief 解散音频分组，所有成员被迫离开该音频分组。
 * @param groupId 要解散的音频分组。不可以是大厅{@link com::ding::rtc::DingRtcEngine::HALL_ID}，也不可以为空。
 * @return int 如果返回0，结果将会通过{@link com::ding::rtc::DingRtcEngineEventListener#onAudioGroupDismissResult}通知app。如果返回<0，则调用失败，不会有通知消息OnAudioGroupDismissResult。
 */
public abstract int dismissGroup(String groupId);

4）本地音频合并进音频组或者大厅

/**
 * @since 3.4
 * @brief 本地音频合并进分组音频或者大厅音频中。
 * @param mix true表示合并，false表示不合并。
 * @param groupId 目标分组。如果是DingRtcEngine::HALL_ID，则表示目标为大厅的音频。不可以为空。
 * @return int 如果返回0，结果将会通过DingRtcEngineEventListener#onAudioGroupMixResult通知app。如果返回<0，则调用失败，不会有通知消息OnAudioGroupMixResult。
 * @note 前提条件：1，已经做了音频的publish; 2，权限要求：用户需要在目标分组或者大厅中。
 */
public abstract int mixAudioToGroup(boolean mix, String groupId);

5）切换订阅指定分组或大厅的音频。

 /**
 * @since 3.4
 * @brief 切换订阅的音频流到指定的分组或者大厅音频。
 * @param groupId 指定的音频分组。如果是DingRtcEngine::HALL_ID，则表示目标为大厅的音频。不可以为空。
 * @return int 如果返回0，结果将会通过DingRtcEngineEventListener#onAudioSubscribeStateChanged通知app。如果返回<0，则调用失败，不会有通知消息OnAudioSubscribeStateChanged。
 * @note 业务层监听OnAudioSubscribeStateChanged通知，如果uid为""，检查newState == DingRtcStatsSubscribed，再查询当前订阅成功的音频类型（通过DingRtcEngineEventListener#getCurrentSubscribedAudio），可判断是否切换成功。
 * @note 切换过程会有多次OnAudioSubscribeStateChanged通知。
 */
public abstract int switchSubscriptionToGroup(String groupId);

6）查询当前订阅音频的分组。

/**
 * @since 3.4
 * @brief 查询当前订阅的音频的类型，可能是大厅音频，也可能是某个分组的音频。
 * @return groupId 如果空，表示无订阅，如果是{@link com::ding::rtc::DingRtcEngine::HALL_ID}，表示大厅音频，否则，返回分组音频对应的分组ID。
 */
public abstract String getCurrentSubscribedAudio();

7）通知当前频道内所有的分组列表。

    /**
     * @since 3.4
     * @brief 返回当前频道内所有的分组列表。
     * @param groups 分组列表。
     * @note 该回调发生在加入频道的时候。App通过该回调可以获得当前频道内所有的分组。后续分组变化，通过回调{@link onAudioGroupListUpdate}获得。
     */
    public void onListAllAudioGroups(List<String> groups) {}

8）加入音频分组回调。

    /**
     * @since 3.4
     * @brief 当调用{@link joinGroup}加入某个group，触发此回调。注意：如果JoinGroup返回非0值，那么不会产生回调。
     * @param result 0表示成功，其他值表示失败。
     * @param errMsg 如果result不为0，补充说明错误原因。
     * @param group 加入的group。
     * @param members 该group的成员用户列表。
     */
    public void onAudioGroupJoinResult(int result, String errMsg, String group, List<DingRtcEngine.DingRtcAudioGroupMember> members) {}

9）离开音频分组回调。

    /**
     * @since 3.4
     * @brief 当调用{@link leaveGroup}离开某个group，触发此回调。注意：如果LeaveGroup返回非0值，那么不会产生回调。
     * @param result 0表示成功，其他值表示失败。
     * @param errMsg 如果result不为0，补充说明错误原因。
     * @param group 离开的group。
     */
    public void onAudioGroupLeaveResult(int result, String errMsg, String group) {}

10）解散音频分组回调。

    /**
     * @since 3.4
     * @brief 当调用{@link dismissGroup}解散某个group，触发此回调。注意：如果DismissGroup返回非0值，那么不会产生回调。
     * @param result 0表示成功，其他值表示失败。
     * @param errMsg 如果result不为0，补充说明错误原因。
     * @param group 解散的group。
     */
    public void onAudioGroupDismissResult(int result, String errMsg, String group) {}

11）本地音频合并进音频组或者大厅回调。

    /**
     * @since 3.4
     * @brief 当调用{@link mixAudioToGroup}向分组或者大厅混流，触发此回调。注意：如果mixAudioToGroup返回非0值，那么不会产生回调。
     * @param groupId 目标分组。如果是{@link HALL_ID}，则表示目标为大厅的音频，否则是普通分组的ID。非空。
     * @param mix true表示将本地音频流混进指定的channel audio或者分组音频中; false表示取消。
     * @param result 0表示成功，其他值表示失败。
     * @param reason 如果result不为0，用该字符串解释失败的原因。
     */
    public void onAudioGroupMixResult(String group, boolean mix, int result, String reason) {}

12）音频分组成员变化回调。

    /**
     * @since 3.4
     * @brief 分组中成员变化，触发此回调。
     * @param updateOpt 1表示新增成员列表，-1表示离开的成员列表。
     * @param group 该回调发生的分组。
     * @param members 变动的成员列表。
     */
    public void onAudioGroupMemberUpdate(int updateOpt, String group, List<DingRtcEngine.DingRtcAudioGroupMember> members) {}

13）大厅成员变化回调。

    /**
     * @since 3.4
     * @brief 当前留在大厅中的所有的成员列表。
     * @param hallMembers 大厅中的成员列表。
     * @note 大方会场景下，回调如果比较频繁，存在一定的cpu开销。
     * @note 留在大厅是指不在任何分组中。如果加入某个分组，意味着离开了大厅；从所有分组中离开，意味着回到了大厅。
     */
    public void onAudioGroupHallMembers(List<DingRtcEngine.DingRtcAudioGroupMember> hallMembers) {}

14）音频分组列表变化回调。

    /**
     * @since 3.4
     * @brief 分组列表变化，触发此回调。
     * @param updateOpt 1表示新增的分组，-1表示删除的分组。
     * @param group 该回调指示的分组。
     */
    public void onAudioGroupListUpdate(int updateOpt, String group) {}

4. 语音激励API升级说明

老版本RTC的语音激励通过enableAudioVolumeIndication接口进行开启或关闭。然后通过registerAudioVolumeObserver接口来注册AliRtcAudioVolumeObserver，通过AliRtcAudioVolumeObserver接口的onAudioVolume和onActiveSpeaker方法来获取说话的人，以及说话的音量。

在新的版本中enableAudioVolumeIndication接口继续保留，但是回调接口不需要注册，回调方法在通用的回调类DingRtcEngineEventListener中，对应的回调方法为onAudioVolumeIndication：

/**
 * @since 3.0
 * @brief 远端用户音量提示回调。
 * @param speakers 用户音量信息，详见参考DingRtcAudioVolumeInfo，如果 speakers 为空，则表示远端用户不发流或没有远端用户。uid为"0"表示本地说话人。
 */
public void onAudioVolumeIndication(List<DingRtcAudioVolumeInfo> speakers)

5. 静音远端音频API升级说明

老版本RTC的muteAllRemoteAudioPlaying已经废弃，在新版本中可以使用setPlayoutVolume接口可以实现同样的功能。

    /**
     * @since 3.1
     * @brief 设置音频播放音量，音量范围[0, 100]。
     * @param volume 音量值。
     * @return
     * - 0：成功；
     * - 非0：失败。
     */
    public abstract int setPlayoutVolume(int volume);

6. 智能降噪API升级说明

老版本RTC的startIntelligentDenoise接口在新版本重新命名为setAudioDenoise，对应的接口描述：

   /**
     * @since 3.4
     * @brief 设置音频降噪功能。
     * @param options 音频降噪参数。
     * @return
     * - 0：成功；
     * - 非0：失败。
     * @remark music mode，自动关闭降噪。
     */
    public abstract int setAudioDenoise(DingRtcEngineAudioDenoiseOptions options);

可以设置的参数为

音频去噪关：DingRtcEngineAudioDenoiseOff
音频去噪采用传统降噪：DingRtcEngineAudioDenoiseDsp
音频去噪采用智能降噪：DingRtcEngineAudioDenoiseEnhance

7. 基础美颜API升级说明

老版本RTC的setBeautyEffect接口在新版本重新命名为enableBeautyFace，对应的接口描述：

   /**
     * @brief 开启或关闭美颜功能，并设置美颜效果参数
     * @private
     * @param enable 
     * - true：开启美颜功能。
     * - false：关闭美颜功能。
     * @param options 美颜效果参数，详细定义见{@link com::ding::rtc::DingRtcEngine::DingRtcBeautyFaceOptions}。
     * @return - 0：成功；
     * - < 0：失败。
     * @brief 开启或关闭美颜功能，并设置美颜效果参数。
     */
    public abstract int enableBeautyFace(boolean enable, DingRtcBeautyFaceOptions options);

通过DingRtcBeautyFaceOptions可以设置如下参数

开启美肤：enableSkinBuffing（true / false）
磨皮系数：skinBuffingFactor = 0.6f （0.0f ~ 1.0f）
锐化系数：skinSharpenFactor = 0.8f（0.0f～1.0f）
美白系数：enableSkinWhitening （true / false）
美白系数：skinWhitingFactor = 0.8f （0.0f ~ 1.0f）

8. 踢人OpenAPI升级说明

踢人OpenAPI接口在新版本中做了重构，调用形式发生了变化。

老接口参考描述：RemoveTerminals

新接口参考描述：RemoveUsers - 踢出用户

备注：对接时，可下载对应语言的SDK进行集成。下载地址

9. 旁路混流OpenAPI升级说明

旁路混流OpenAPI在新版本中了重构，调用形式发生了变化。

老接口参考描述：StartMPUTask

新接口参考描述：StartStreamingOut - 开始旁路推流任务

备注：对接时，可下载对应语言的SDK进行集成。下载地址

六、客户端API变化说明清单

1. iOS端接口升级说明详情

接口名称	描述	备注
sharedInstance:extras	初始化	一致
destroy	反初始化	一致
setChannelProfile	设置频道模式	已取消无相应的限制
setClientRole	设置客户端角色	已取消无相应的限制
getCurrentClientRole	获取客户端角色	已取消无相应的限制
setAudioOnlyMode	纯音频模式	已取消通过关闭视频推流及订阅可代替该接口
joinChannel:name:onResult	入会的回调	一致
leaveChannel	离开频道（参数有修改）	一致
setLocalViewConfig:forTrack	设置本地视频渲染参数	一致
setVideoEncoderConfiguration	设置分辨率	一致
publishLocalVideoStream	设置是否允许发布相机流。	一致
publishLocalAudioStream	设置是否允许发布音频流。	一致
publishLocalDualStream	设置是否允许发布次要视频流。	默认打开
muteLocalCamera:forTrack	是否发送黑帧	一致
muteLocalMic:mode	设置是否静音	一致
stopPreview	停止预览	一致
startPreview	开始预览	一致
switchCamera	切换摄像头	一致
enableSpeakerphone	设置听筒开关	一致
setAudioSessionOperationRestriction	设置AudioSession模式	一致
setDefaultSubscribeAllRemoteAudioStreams	默认是否订阅所有音频流	参见： subscribeAllRemoteAudioStreams
setDefaultSubscribeAllRemoteVideoStreams	默认是否订阅所有视频流	参见： subscribeAllRemoteVideoStreams
setRemoteViewConfig:forTrack	设置远端视频渲染参数	一致
setRemoteVideoStreamType:type	设置是否订阅远端相机流。	type 数据类型有变化
subscribeRemoteVideoStream:track	设置是否订阅远端视频流。	一致
subscribeRemoteAudioStream	设置试听订阅远端音频流。	参见： subscribeAllRemoteAudioStreams
setLogLevel	设置日志	一致
getSdkVersion	获取版本号	一致
isUserOnline	判断用户是否在线	一致
enablePlugin:pluginName	注册插件（降噪插件）	参见 setAudioDenoise
startIntelligentDenoise	开启智能降噪	参见 setAudioDenoise
enableDelegateMainQueue	设置callback在主线程回调	一致
setBeautyEffect	设置美颜	参见 enableBeautyFace
enableAudioVolumeIndication	设置音量回调频率和平滑系数	一致
sendMediaExtensionMsg	发送媒体扩展信息	一致

回调接口名称	回调接口描述	备注
onAudioPublishStateChanged:newState:elapseSinceLastState:channel	音频推流回调	一致
onVideoPublishStateChanged:newState:elapseSinceLastState:channel	视频推流回调	一致
onDualStreamPublishStateChanged:newState:elapseSinceLastState:channel	视频次级流推流回调	有变化
onFirstRemoteVideoFrameDrawn:videoTrack:width:height:elapsed	首帧渲染回调（新增参数）	一致
onFirstLocalVideoFrameDrawn:height:elapsed	本地首帧回调	一致
onVideoSubscribeStateChanged:oldState:newState:elapseSinceLastState:channel	视频流变更回调	一致
onSubscribeStreamTypeChanged:oldStreamType:newStreamType:elapseSinceLastState:channel	订阅流变更回调	一致
onFirstRemoteAudioDecodedWithUid:elapsed	音频首帧回调	一致
onAudioSubscribeStateChanged:oldState:newState:elapseSinceLastState:channel	音频订阅状态回调	一致
onRemoteUserOnLineNotify:elapsed	用户入会回调（新增参数）	一致
onRemoteUserOffLineNotify:offlineReason	用户离会回调（新增参数）	一致
onRemoteTrackAvailableNotify:audioTrack:videoTrack	他人推流回调	一致
onLeaveChannelResult:stats	离开回调	一致
onOccurWarning:message	警告回调	一致
onOccurError:message	错误回调	一致
onPerformanceLow	设备性能不足回调	废弃
onPerformanceRecovery	设备性能恢复回调	废弃
onRtcStats	性能数据回调	一致
onRtcLocalVideoStats	性能数据回调	一致
onRtcRemoteVideoStats	性能数据回调	一致
onNetworkQualityChanged:upNetworkQuality:downNetworkQuality	网络状况回调	一致
onBye	会议结束或被踢回调	一致
onConnectionLost	网络连接断开回调	一致
onTryToReconnect	网络连接正在尝试重连中回调	一致
onConnectionRecovery	网络连接重连成功回调	一致
onUpdateRoleNotifyWithOldRole	客户端角色变化通知	已取消无相应的限制
onMediaExtensionMsgReceived	收到媒体扩展信息回调	一致
onUserAudioInterruptedBegin	用户audio被中断通知（一般用户打电话等音频被抢占场景）。	已取消客户业务侧实现
onUserAudioInterruptedEnded	用户audio中断结束通知（对应onUserAudioInterruptedBegin）。	已取消客户业务侧实现
onPublishLiveStreamStateChanged	旁路推流状态改变回调。	已取消
onPublishTaskStateChanged	旁路任务状态改变回调。	已取消

2 Android端接口升级说明详情

接口名称	接口描述	备注
getInstance	初始化	一致
destroy	销毁	一致
setChannelProfile	设置频道模式	已取消无相应的限制
setClientRole	设置客户端角色	已取消无相应的限制
getCurrentClientRole	获取客户端角色	已取消无相应的限制
setAudioOnlyMode	设置纯音频模式	已取消通过关闭视频推流及订阅可代替该接口
setAudioProfile	设置音频规格	音频场景待对齐音乐模式等
joinChannel	加入会议	一致
leaveChannel	离开会议	一致
setLocalViewConfig	设置本地渲染	一致
setVideoEncoderConfiguration	设置视频流编码配置	一致
publishLocalAudioStream	发布本地音频流	一致
publishLocalVideoStream	发布本地视频流	一致
publishLocalDualStream	发布本地次要视频流	默认开启
muteLocalCamera	本地摄像头开关	一致
muteLocalMic	本地麦克风开关	一致
startPreview	开始预览	一致
stopPreview	停止预览	一致
switchCamera	切换摄像头	一致
setCameraCapturerConfiguration	设置摄像头配置	一致
setCameraZoom	设置摄像头缩放	一致
setCameraFlash	设置摄像头聚焦	一致
setCameraAutoFocusFaceModeEnabled	设置摄像头自动聚焦	一致
getCurrentCameraDirection	获取摄像头方向	一致
enableSpeakerphone	开启扬声器	一致
setDefaultSubscribeAllRemoteAudioStreams	设置默认订阅远端音频流	参见： subscribeAllRemoteAudioStreams
setDefaultSubscribeAllRemoteVideoStreams	设置默认订阅远端视频流	参见： subscribeAllRemoteVideoStreams
setRemoteViewConfig	设置远端渲染	一致
setRemoteVideoStreamType	设置视频流类型	type 数据类型有变化
subscribeRemoteAudioStream	订阅远端音频流	参见： subscribeAllRemoteAudioStreams
subscribeRemoteVideoStream	订阅远端视频流	一致
setPlayoutVolume	设置音量	一致
setRtcEngineNotify	设置RTC通知回调	已取消合并到RtcEngineEventListener
setRtcEngineEventListener	设置RTC事件回调	一致
setLogLevel	设置日志等级	一致
getSdkVersion	获取SDK版本	一致
isInCall	是否在会	一致
getUserInfo	获取远端用户	一致
startIntelligentDenoise	开启降噪	参见 setAudioDenoise
setBeautyEffect	设置美颜	参见 enableBeautyFace
enableAudioVolumeIndication	设置音量回调频率和平滑系数	一致
sendMediaExtensionMsg	发送媒体扩展信息	一致
startNetworkQualityProbeTest	开始网络质量探测	已取消
stopNetworkQualityProbeTest	停止网络质量探测	已取消

回调接口名称	回调接口描述	备注
onJoinChannelResult	加入会议时调用	一致
onLeaveChannelResult	离开会议时调用	一致
onAudioPublishStateChanged	音频发布流发生变化	一致
onVideoPublishStateChanged	视频发布流发生变化	一致
onDualStreamPublishStateChanged	次要视频发布流发生变化	有变化
onAudioSubscribeStateChanged	音频订阅流发生变化	一致
onVideoSubscribeStateChanged	视频订阅流发生变化	一致
onSubscribeStreamTypeChanged	视频订阅流类型发生变化	一致
onNetworkQualityChanged	网络状态变化	一致
onConnectionLost	失去连接	一致
onTryToReconnect	尝试重新连接	一致
onConnectionRecovery	重新连接完成	一致
onPerformanceLow	设备性能不足	废弃
onPermormanceRecovery	设备性能恢复	废弃
onOccurError	发生错误	一致
onOccurWarning	发生警告	一致
onBye	被服务器踢出或者频道关闭	一致
onRemoteUserOnLineNotify	远端用户上线	一致
onRemoteUserOffLineNotify	z用户下线	一致
onUserWillBecomeActive	远端用户应用返回前台	一致
onUserWillResignActive	远端用户应用退到后台	一致
onRemoteTrackAvailableNotify	远端用户的流发生变化	一致
onFirstAudioPacketSent	音频首包发送回调	一致
onFirstVideoPacketSent	视频首包发送回调	一致
onFirstAudioPacketReceived	音频首包接收回调	一致
onFirstVideoPacketReceived	视频首包接收回调	一致
onFirstVideoFrameReceived	视频首帧接收回调	一致
onFirstRemoteVideoFrameDrawn	视频首帧绘制完成	一致
onAliRtcStats	当前会话统计信息回调	一致
onRtcLocalAudioStats	本地音频统计信息	一致
onRtcRemoteAudioStats	远端音频统计信息	一致
onRtcLocalVideoStats	本地视频统计信息回调	一致
onRtcRemoteVideoStats	远端视频统计信息回调	一致
onLocalVideoSample	本地视频流源数据	一致
onRemoteVideoSample	远端视频流源数据	一致
onUpdateRoleNotifyWithOldRole	客户端角色变化通知	已取消无相应的限制
onMediaExtensionMsgReceived	收到媒体扩展信息回调	一致
onUserAudioInterruptedBegin	用户audio被中断通知（一般用户打电话等音频被抢占场景）。	已取消客户业务侧实现
onUserAudioInterruptedEnded	用户audio中断结束通知（对应onUserAudioInterruptedBegin）。	已取消客户业务侧实现
onNetworkQualityProbeTest	网络质量探测回调。	已取消
onPublishLiveStreamStateChanged	旁路推流状态改变回调。	已取消
onPublishTaskStateChanged	旁路任务状态改变回调。	已取消

3. Windows 端接口升级说明详情

接口名称	接口描述	备注
Create	初始化	一致
Destroy	销毁	一致
SetChannelProfile	设置频道模式	已取消无相应的限制
SetClientRole	设置客户端角色	已取消无相应的限制
GetCurrentClientRole	获取客户端角色	已取消无相应的限制
SetAudioOnlyMode	设置纯音频模式	已取消通过关闭视频推流及订阅可代替该接口
JoinChannel	加入会议	一致
LeaveChannel	离开会议	一致
EnableLocalVideo	打开本地视频采集	一致
SetLocalViewConfig	设置本地渲染	一致
SetVideoEncoderConfiguration	设置视频流编码配置	一致
PublishLocalAudioStream	发布本地音频流	一致
PublishLocalVideoStream	发布本地视频流	一致
PublishLocalDualStream	发布本地次要视频流	默认开启
MuteLocalCamera	本地摄像头开关	对应MuteLocalVideo接口
MuteLocalMic	本地麦克风开关	对应MuteLocalAudio接口
StartPreview	开始预览	一致
StopPreview	停止预览	一致
SetCameraZoom	设置摄像头缩放	缺失
SetCameraFlash	设置摄像头聚焦	缺失
SetCameraAutoFocusFaceModeEnabled	设置摄像头自动聚焦	缺失
GetCurrentCameraDirection	获取摄像头方向	缺失
SetDefaultSubscribeAllRemoteAudioStreams	设置默认订阅远端音频流	参见： SubscribeAllRemoteAudioStreams
SetDefaultSubscribeAllRemoteVideoStreams	设置默认订阅远端视频流	参见： SubscribeAllRemoteVideoStreams
SetRemoteViewConfig	设置远端渲染	一致
SetRemoteVideoStreamType	设置视频流类型	type 数据类型有变化
SubscribeRemoteAudioStream	订阅远端音频流	参见： SubscribeAllRemoteAudioStreams
SubscribeRemoteVideoStream	订阅远端视频流	一致
MuteAllRemoteAudio	静音所有远端播放声音	参考： SetPlayoutDeviceVolume
SetEngineEventListener	设置RTC事件回调	一致
SetLogLevel	设置日志等级	一致
GetSDKVersion	获取SDK版本	一致
IsUserOnline	是否在会	一致
GetUserInfo	获取远端用户	一致
enableAudioVolumeIndication	设置音量回调频率和平滑系数	一致
sendMediaExtensionMsg	发送媒体扩展信息	一致


AliRtcVideoCanvas	renderMode	AliRtcRenderModeAuto
	mirrorMode	AliRtcRenderMirrorModeAllEnabled
	rotationMode	AliRtcRotationMode_270 AliRtcRotationMode_90

回调接口名称	回调接口描述	备注
onRemoteUserOnLineNotify	远端用户上线	一致
onRemoteUserOffLineNotify	远端用户下线	一致
onJoinChannelResult	加入会议时调用	一致
onRemoteTrackAvailableNotify	远端用户的流发生变化	一致
onConnectionStatusChange	网络状态变化时通知	一致
onUserVideoEnable	对端用户关闭相机流采集	一致
onNetworkQualityChanged	网络质量变化通知	一致
onRtcRemoteVideoStats	远端视频统计信息回调	一致
onRtcLocalVideoStats	本地视频统计信息回调	一致
onUpdateRoleNotifyWithOldRole	客户端角色变化通知	已取消无相应的限制
onMediaExtensionMsgReceived	收到媒体扩展信息回调	一致
onPublishLiveStreamStateChanged	旁路推流状态改变回调。	已取消
onPublishTaskStateChanged	旁路任务状态改变回调。	已取消

4、Web端接口升级说明详情

新版本Web 是全量重构版本，在继承了旧版本功能的基础上，优化了 SDK 的内部架构，提高了 API 的易用性，具体包括以下优势：

接口异步化，基于 Promise-based 的 API 使代码更健壮；
支持 TypeScript；
以 Track 轨道代替 Stream概念来控制音视频数据，逻辑各自独立，更为灵活。
优化了事件通知机制，统一了频道内事件的命名和回调参数的格式。

1. 接口相关

被移除且无替代性的接口

旧版接口名称	接口描述	备注
getAvailableResolutions	获取可支持的分辨率。	可参考新版VideoDimension 类型定义
isSupportScreenShare	是否支持屏幕共享。	可参考浏览器支持文档有注明
setChannelProfile	设置频道模式。	模式可由业务调用方利用API新增参数灵活组合
setClientRole	设置角色。	由业务接入方维护
setAudioOnlyMode	设置是否为纯音频模式。	可通过仅订阅/发布音频实现
dispose	释放实例。	在调用client.leave是会自动清理实例状态
enableAudioVolumeIndicator	设置接收音量值回调。	新版本暂未支持获取具体用户音量
enableHighDefinitionPreview	设置是否开启高清预览。	新版本具体分辨率由用户设置决定
getUserInfo	获取用户信息。	remoteUsers返回用户信息里已包含全量信息，无需额外调用该接口

功能类似可替代的接口

旧版接口名称	接口描述	新版接口名称	新版接口备注
new AliRtcEngine()	初始化引擎,支持配置自动订阅与发布	createClient()	创建客户端实例,支持多实例，不支持配置自动订阅和发布，可监听"user-published"事件订阅，调用publish() 接口推流实现自动推流
getDevices	获取设备信息，返回摄像头和音频设备。	getDevices() getCameras() getMicrophones() getPlaybackDevices()	新版本可选择按照类别来枚举可用设备。
isSupport	检测浏览器是否支持Web SDK。	checkSystemRequirements()	接口返回调整，仅判断浏览器是否支持rtc能力。h264 支持检测需要getSupportedCodec()接口返回
joinChannel	加入会议	join()	JoinParam有所调整
leaveChannel	离开会议	leave()	调整为同步调用
configLocalAudioPublish	设置是否允许发布音频流。	publish()	用户自己决定是否发布音视频轨道，支持同时发布多个，promise调用保障顺序
configLocalCameraPublish	设置是否允许发布相机流。
configLocalScreenPublish	设置是否允许发布屏幕共享流。
publish	发布本地视频流。
unPublish	结束发布本地流。	unpublish()	用户自己决定是否取消发布音视频轨道，支持同时取消发布多个，promise调用保障顺序
setDisplayRemoteVideo	为远端的视频设置渲染窗口以及绘制参数。	play()	新版本SDK在play 的时候第一个参数来指定容器元素，无需接入方创建video标签， sdk来管理视频流的播放；
stopPreview	停止预览	cameraTrack.stop
startPreview	开始预览	play()
muteLocalCamera	是否停止本地视频采集。	cameraTrack.setMuted	基本一致
currentCamera	指定摄像头设备。	cameraTrack.setDevice
videoProfile	设置视频流或共享流参数。	cameraTrack.setEncoderConfiguration screenTrack.setEncoderConfiguration
setVideoProfile	设置视频流或共享流参数。
enableCamera	设置是否使用摄像头。	cameraTrack.setEnabled
currentAudioCapture	指定麦克风设备。	microphoneTrack.setDevice
setAudioOutput	设置音频播放设备。	remoteAudioTrack.setSpeaker
muteLocalMic	是否停止本地音频采集。	microphoneTrack.setMuted
muteRemoteAudioPlaying	设置是否停止播放远端音频流。	remoteAudioTrack.stop	当前订阅远端音频仅支持订阅mcu，相当于订阅远端所有音频流。仅订阅一次即可，无需重复订阅。
muteAllRemoteAudioPlaying	设置是否停止远端的所有音频流的播放。	remoteAudioTrack.stop	当前订阅远端音频仅支持订阅mcu，相当于订阅远端所有音频流。仅订阅一次即可，无需重复订阅。
setAudioVolume	设置订阅用户音量。	remoteAudioTrack.setVolume	无需指定用户
getAudioVolume	获取订阅用户音量	remoteAudioTrack.getVolume	无需指定用户
getUserList	获取当前房间在线用户	client.remoteUsers	一致
setExternalMediaTrack	设置外部输入	DingRTC.createCustomAudioTrack、DingRTC.createCustomVideoTrack	注意与摄像头轨道和麦克风轨道不能同时发布。
configRemoteAudio	设置是否订阅远端音频流。	client.subscribe clienr.unsubscribe client.batchSubscribe client.batchUnsubscribe client.setRemoteVideoStreamType client.setRemoteDefaultVideoStreamType	新版本参数有变化，接口需用户主动调用，具体参考API文档订阅音频限制：当前仅支持订阅mcu音频，将userId置为字符串mcu 订阅视频需在第三个参数指定为true时代表订阅共享流，否则订阅的为摄像头流
configRemoteCameraTrack	设置是否订阅远端相机流。
configRemoteScreenTrack	设置是否订阅远端屏幕流。
subscribe	订阅远程发布流。
unSubscribe	取消订阅该用户所有的流。
on	订阅事件。	client.on DingRTC.on track.on	新版本丰富了事件透出类型与调用层级，具体可参考API文档
off	取消订阅事件	client.off DingRTC.off track.off	新版本丰富了事件透出类型与调用层级，具体可参考API文档

其余新版本新增功能

功能模块	API	说明
音视频轨道通用操作	track.getMediaStreamTrack	获取浏览器原生的 MediaStreamTrack 对象
	track.getTrackId	获取由 SDK 生成的对于媒体轨道来说的唯一 ID
	track.getTrackLabel	获取本地轨道的来源描述
	track.close	关闭本地轨道，并释放相关采集设备
	track.replaceTrack	替换本地音视频轨道
音频轨道	track.getVolumeLevel	获取音频轨道的音量等级
视频轨道	track.getCurrentFrameData	获取当前渲染的视频帧数据返回'image/png' 类型的 dataURL
远端音视频轨道操作	track.getUserId	获取发布远端轨道的远端用户 ID
支持度	oneRTC.getSupportedCodec	获取 DingRtc Web SDK 对正在使用的浏览器支持的编解码格式
日志	DingRTC.setLogLevel	设置 SDK 的日志输出级别。
全局设置项	setClientConfig	设置SDK集成选项设置,例如自定义的gslb地址
质量统计	client.getLocalAudioStats	获取本地音频相关信息。
	client.getLocalVideoStats	获取本地视频相关信息。
	client.getRemoteVideoStats	获取远端用户的视频统计信息。
	client.getRemoteNetworkQuality	获取远端用户的网络统计信息，远端用户也需要在3.3.0版本及以上时才能获取到信息。

其中涉及主要几种类的新增属性信息如下：

类名	属性名	说明
client 客户端实例	remoteUsers	远端用户信息列表
	localTracks	保存当前正在发布的本地轨道对象列表
	uid	本地用户的用户 ID。
	channelName	当前加入的频道名称
user 用户信息	audioTrack	订阅远端用户音频保存的远端音频轨道对象
	audioMuted	远端当前麦克风是否静音。
	videoTrack	订阅远端用户视频保存的远端视频轨道对象
	videoMuted	远端当前摄像头是否关闭。
	auxiliaryTrack	如果成功订阅了远端用户的桌面共享，这里会保存远端的桌面共享视频轨道对象。
	auxiliaryMuted	远端当前屏幕共享是否关闭。
	uid	远端用户的用户 ID
	hasAuxiliary	远端当前是否在发送屏幕共享。
	hasVideo	远端当前是否在发送视频
	hasAudio	远端当前是否在发送视频频
localTrack 本地轨道	enabled	本地轨道当前的启用状态
	isPlaying	媒体轨道是否正在播放
	muted	本地媒体轨道当前的静音状态
	trackMediaType	媒体轨道的类型"audio"\| "video"
remoteTrack 远端轨道	isPlaying	媒体轨道是否正在播放
remoteTrack 远端轨道	trackMediaType	媒体轨道的类型"audio"\| "video"

新版本尚待补齐旧版本接口（伴奏相关）

接口名称	接口描述
startAudioMixing	开始播放音乐文件。
stopAudioMixing	停止播放音乐文件。
pauseAudioMixing	暂停播放音乐文件。
resumeAudioMixing	恢复播放音乐文件。
adjustAudioMixingVolume	调节伴奏音量。
setAudioMixingPosition	设置音乐文件的播放位置。
getAudioMixingDuration	获取音乐文件时长。
getAudioMixingCurrentPosition	获取音乐文件播放进度。

2. 回调相关

被移除且无替代性的回调

旧版回调名称	描述	备注
onUpdateRole	角色切换回调。	新版本不再有role概念
onMediaStream	订阅流成功回调，返回远程流的Stream对象，通过H5 Video或Audio播放。	在client.subscribe接口调用成功后返回的track 对象可直接调用play播放。
onMediaStreamUpdate	订阅流状态变化回调。	在client.subscribe接口调用成功后返回的track 对象可直接调用play播放。
onSubscribeChange	自动订阅回调。	新版本不再由SDK内部自动订阅，调整为用户推流时间抛出后，主动调用client.subscribe来订阅。
onMedia	推流和订阅的音视频数据回调。	新版本SDK使用stats系列API来主动获取数据监控回调。具体可参考API文档。
onPublishChange	本地发布流回调（自动推流）。	可从client.localTracks 获取本地已发布的流
onError	错误异常回调。当有错误发生时，触发onError回调	新版本错误信息主要由接口调用抛出，更为灵活。
onAudioMixingPlayed	伴奏开始播放回调。	待后续版本设计实现
onAudioMixingFinished	伴奏播放结束回调。
onShareSystemAudioStart	共享声音通知回调。
onAudioLevel	音频能量值回调。

功能类似可替代的回调

旧版回调名称	描述	新版回调名称	备注
onPublisher	当频道里的其他人发布本地流时的回调	client.on('user-published', callback)	功能类似，回调参数有变化，可参考API文档
onUnPublisher	当频道里的其他人取消发布本地流时的回调	client.on('user-unpublished', callback)
onJoin	当有其他用户加入频道时，触发	client.on('user-joined', callback)
onLeave	当有其他用户离开频道时，触发	client.on('user-left', callback)
onBye	被服务器踢出或者频道关闭时回调	client.on('connection-state-change', callback)	connectionState 变为disconnected 时，会在回调里第三个参数透出原因
onNotify	用户静音状态变化回调。	client.on('user-info-updated', callback)	功能类似，回调参数有变化，可参考API文档
onNetworkQuality	网络质量回调。	client.on('netwrok-quality', callback)	功能类似，回调参数有变化，可参考API文档

七、常见问题

Q： RTC 2.0 与 RTC 3.0可以在一个频道开会么？

A：不能， RTC 2.0 与 RTC 3.0不支持互通，不支持同一个会议中，既有2.0的客户端又有3.0的客户端。

Q: AppID是否存在2.0 / 3.0 版本？

A: 是的，所有在2024年4月10日之后新建的AppID，默认是3.0版本，必须使用3.0版本的SDK和服务端接口。在这之前创建的AppID是2.0版本。用户可以通过控制台 - 应用管理，查看某个AppID是2.0还是3.0。

Q: 我是一个RTC 2.0的用户，如果想升级到3.0版本，我需要注意哪些？

A: 我们可以把RTC 3.0 和 RTC 2.0看成是两套完全不同的RTC产品。对接RTC 3.0 需要从新建App开始重新走一遍对接的流程。

需要注意以下情况：

你需要在控制台重新新建一个AppID，并且确认版本是3.0。
3.0版本的Token生成方式和认证与2.0版本不同，需要按照新方式生成Token：见使用Token鉴权
3.0版本的SDK接口与2.0版本不同，客户端接口见：SDK参考
3.0版本的服务端接口与2.0版本不同，服务端接口见：API参考

Q: 我是一个RTC 2.0的用户，如果我还想继续使用RTC 2.0是否可以？

A: 当前RTC 2.0处于维护状态，不再新增功能，2025年3月31日服务会下线。

Q: 我是一个RTC 2.0的用户，如果我还想找RTC2.0相关文档，我可以看到么？

A: 是可以的，所有RTC2.0的文档，都迁移到了XXX（旧版）目录中。例如：快速入门（旧版），操作指南（旧版），开发参考（旧版）

Q: 我是一个RTC 2.0的用户，RTC 2.0 和 RTC 3.0版本不互通，一般可以怎么升级？

A: 一个参考思路：

App同时预埋RTC 2.0 和 RTC 3.0的SDK。
App升级率达到一定程度后，开始通过业务层进行灰度切换创建RTC2.0 还是 RTC3.0的会议，客户端使用相同版本SDK入会。
等App升级到一定比例，强制升级剩余App版本，后续版本删除RTC2.0 SDK。

Q: RTC 2.0 和 RTC 3.0 SDK有哪些主要差异？

A: 主要差异参见

SDK变更公告

入会认证参数有所简化：

authinfo中不要填写gslb字段了。不要把2.x的gslb地址填进来，否则会导致入会失败
去掉了timestamp和nonce字段

Q: RTC 2.0 和 RTC 3.0 Web SDK有哪些主要差异？

A：

1、支持TypeScript;

2、API和参数与旧版不兼容，从单个引擎入口拆分为基于不同功能模块的面向对象风格的多层级类的实现；

3、API调用使用Promise 来实现异步操作，提高程序的鲁棒性；

4、使用Track来取代Stream来控制音视频，音视频互不干扰，更为独立灵活；

5、优化了事件通知机制，丰富事件类型与参数内容，统一命名方式与参数格式，按照功能归属于不同模块；

6、由于采用了全新设计，早期版本有些功能还没有在3.0提供，这些包括：伴奏、角色切换、音频能量值获取、单独订阅某用户音频。

Q: RTC 2.0 和 RTC 3.0 服务端接口有哪些主要差异？

A: RTC 2.0 和 RTC 3.0服务端接口主要有以下差异：

Token生成方式和格式不同，使用Token鉴权 V.S. 使用Token鉴权。
服务端Webhook回调设置不同：
1. 3.0 支持在控制台设置回调地址以及监听的事件类型，参考：概述
2. 2.0 通过需要接口设置
频道接口：接口基本保持一致
推流/录制接口：
1. 3.0版本支持设置推流/录制模板，在推流和录制时可以引用模板。
2. 具体接口见：云端录制、旁路转推
数据接口：接口基本保持一致

Q: RTC web端入会有如图的跨域报错，会是什么原因导致的？

A: 因为用户使用的demo源码和appid的版本不一致导致的，比如用的是2.0版本的demo代码，但是用的appid是3.0的，这样就会报跨域的错误