华为云用户手册

接口总览 本章节介绍了Android SDK的HRTCConnection接口详情。 HRTCConnection按照其功能可分类为：初始化等基础接口、房间功能、音频管理、视频管理、屏幕共享。 单击下图中相应接口名称，可快速跳转到相应接口位置查看其使用方法。 表1 初始化等基础接口 接口 描述 release 释放Connection setEncryption 设置端到端加密模式 setNetworkBandwidth 设置网络带宽限制 表2 房间功能接口 接口 描述 joinRoom 加入房间 leaveRoom 离开房间 getRoomId 获取房间id renewAuthorization 更新签名 changeUserRole 切换角色 changeUserName 修改用户昵称 表3 视频管理接口 接口 描述 setPriorRemoteVideoStreamType 设置优先选看档位 pullRemoteVideo 订阅或取消订阅远端用户 setupRemoteView 设置远端用户窗口 startRemoteStreamView 按档位选看远端用户，并设置用户窗口 stopRemoteStreamView 取消订阅远端用户，并清除此用户的窗口 pullAllRemoteVideo 订阅或取消订阅全部远端用户，对未入会用户也有影响 setRemoteVideoStreamType 切换用户指定档位的视频 updateRemoteRenderMode 设置远端视频渲染模式，镜像模式 setRemoteVideoAdjustResolution 远端流自动调整分辨率开关 startAllRemoteView 批量设置远端流视图 表4 音频管理接口 接口 描述 muteRemoteAudio 远端用户静音开关 muteAllRemoteAudio 所有远端用户静音开关 adjustPlaybackVolume 调整单个用户播放音量 表5 自定义渲染接口 接口 描述 setExternalAudioFrameOutputEnable 音频流第三方播放开关（音频自渲染） setExternalVideoFrameOutputEnable 视频流第三方渲染开关（视频自渲染） setExternalDataFrameOutputEnable 辅流第三方渲染开关（辅流自渲染） 表6 辅流管理接口 接口 描述 startRemoteAuxiliaryStreamView 订阅远端用户辅流，并设置窗口 stopRemoteAuxiliaryStreamView 取消订阅远端用户辅流，并清除用户窗口 updateRemoteAuxiliaryStreamRenderMode 设置辅流渲染填充方式，镜像模式 setRemoteAuxiliaryStreamViewRotation 设置辅流旋转角度 父主题： HRTCConnection

自定义视频采集和渲染 表10 自定义视频采集和渲染接口 接口 描述 setExternalVideoCapture 设置是否开启外部视频采集 pushExternalVideoFrame 输入外部视频数据 setExternalMediaFrameOutput 设置媒体数据自渲染 setExternalVideoFrameOutputWithFormat 带Format参数设置媒体数据自渲染 pushAuxExternalVideoFrame 辅流输入外部视频数据

音效文件播放管理 表7 音频文件播放管理接口 接口 描述 startAudioFile 开始播放音频文件 stopAudioFile 停止播放音频文件 pauseAudioFile 暂停播放音频文件 resumeAudioFile 恢复播放音频文件 adjustAudioFileVolume 调节音频文件播放音量 adjustAudioFilePlayoutVolume 设置本地播放音频音量 getAudioFileVolume 获取音频文件播放音量 getAudioFilePlayoutVolume 获取音频文件本地播放音量 getAudioFileDuration 获取音频文件时长 getAudioFileCurrentPosition 获取当前音频播放位置 setAudioFilePosition 设置音频播放位置 getAudioClipsVolume 获取音效总音量 getVolumeOfAudioClip 获取指定音效音量 setAudioClipsVolume 设置音效总音量 setVolumeOfAudioClip 设置指定音效音量 playAudioClip 播放音效文件 stopAudioClip 停止播放指定音效 stopAllAudioClips 停止播放所有音效 pauseAudioClip 暂停播放指定音效 pauseAllAudioClips 暂停播放所有音效 resumeAudioClip 恢复播放指定音效 resumeAllAudioClips 恢复播放所有音效 getAudioClipCurrentPosition 获取指定音效当前播放位置 setAudioClipPosition 设置指定音效播放位置 getAudioClipDuration 获取音效文件时长

设备管理 表11 设备管理接口 接口 描述 setSpeakerModel 设置声音播放模式（只支持iphone） setCameraConfig 设置摄像头相关参数 switchCamera 切换前后镜头（只支持iphone） recordingDeviceTest 音频采集设备测试（只支持macOS） finishRecordingDeviceTest 结束音频采集设备测试（只支持macOS） playbackDeviceTest 音频播放设备测试（只支持macOS） finishPlaybackDeviceTest 结束音频播放设备测试（只支持macOS） echoTest 音频设备回路测试（只支持macOS） finishEchoTest 结束音频设备回路测试（只支持macOS） cameraDeviceTest 视频采集设备测试 finishCameraDeviceTest 结束视频采集设备测试

视频管理 表4 视频管理接口 接口 描述 enableLocalVideo 设置是否开启摄像头采集视频 setVideoEncoderConfig 设置视频编码参数 enableSmallVideoStream 大小流模式设置是否开启小流并设置小流编码参数 startLocalPreview 开启本地预览 stopLocalPreview 关闭本地预览 setupLocalVideo 设置/取消本地预览视图 updateLocalRenderMode 设置本地视频显示模式和镜像模式 setupRemoteView 设置远端流视图 updateRemoteRenderMode 设置远端视图显示模式，镜像模式 setRemoteVideoStreamType 设置选看指定用户的大流或者小流 setPriorRemoteVideoStreamType 设置默认选看远端的大流或者小流 pushLocalVideo 设置是否发送本地视频流 pullRemoteVideo 订阅或取消订阅远端某个用户视频流 pullAllRemoteVideo 订阅或取消订阅全部远端用户视频流 startRemoteStreamView 设置远端用户渲染视图（发起选看-旧接口） stopRemoteStreamView 关闭远端用户的渲染视图（停止选看） setRemoteVideoAdjustResolution 设置远端下行视频流的分辨率自适应 setVideoEncoderMirror 设置视频编码镜像模式 startPublishStream 开始旁路推流 updateTransCoding 更新旁路推流 stopPublishStream 停止旁路推流 startAllRemoteView 批量设置远端流视图 appendLocalView 设置本地视频另一个窗口显示 appendRemoteView 设置远端视频另一个窗口显示

辅流管理 表5 辅流管理接口 接口 描述 startRemoteAuxiliaryStreamView 开启辅流渲染视图（发起辅流选看） stopRemoteAuxiliaryStreamView 关闭辅流渲染视图（停止辅流选看） updateRemoteAuxiliaryStreamRenderMode 设置辅流视图渲染模式，镜像模式 setRemoteAuxiliaryStreamViewRotation 设置辅流视图角度 setAuxiliaryVideoEncoderConfig 设置辅流编码能力 setAuxiliaryVideoEncodeSmooth 设置是否开启辅流的流畅度优先 pushAuxExternalVideoFrame 推送辅流数据

房间功能 表2 房间功能接口 接口 描述 joinRoom 加入房间 changeUserRole 设置用户的角色，角色切换时使用 renewAuthorization 签名更新 leaveRoom 离开房间 changeUserName 设置用户自己的昵称 createConnection 创建 跨房（HWRtcConnection）对象，跨房前需先创建连接 addMultiRoomMediaRelay 添加单个跨房 removeMultiRoomMediaRelay 删除单个跨房 stopMultiRoomMediaRelay 停止所有跨房

音频管理 表3 音频管理接口 接口 描述 muteLocalAudio 设置是否发送本地音频流 enableLocalAudioStream 设置是否开启麦克风采集音频 muteRemoteAudio 订阅或取消订阅远端某个用户音频流 muteAllRemoteAudio 订阅或取消订阅全部远端用户音频流 setVolumeNotifyInterval 设置最大音量上报频率 adjustRecordingVolume 设置麦克风采集的音量（0-100） adjustPlaybackVolume 调整扬声器播放的音量（0-100） setShareComputerSound 共享声音 (只支持macOS) sendAudioSeiMsg 发送音频SEI消息 setDefaultSpeakerModel 设置默认的声音播放模式，在房间外调用 setAudioFrameRecordParameters 设置音频采集回调参数 setAudioConfig 设置音频场景

初始化等基础接口 表1 初始化等基础接口 接口 描述 sharedEngine 创建连麦引擎实例 destroy 注销引擎 initWithConfig 初始化引擎配置信息 logUpload 上传日志 setEnableRtcStats 打点开关 getVersion 获取SDK版本号 setEncrytionParam 设置端到端加密模式 setAccessResourceType 设置接入的环境 setNetworkBandwidth 设置网络带宽限制

createStream (static) createStream(config: StreamConfig): Stream 【功能说明】 创建本地流对象。 【请求参数】 config：必选，StreamConfig类型，指定创建流的参数。 StreamConfig 定义为：{ screen：可选，boolean类型，如果为true表示该流对象采集的是辅流音视频。辅流即共享屏幕的流。默认值为false，即该流对象采集的是主流音视频。 video：可选，boolean类型，指定是否采集主流的视频，主流即摄像头的流。默认值为false。 audio：可选，boolean类型，指定是否采集主流的音频。默认值为false。screen为false的时候该参数有效。 microphoneId：可选，string类型，在audio为true的时候有效，表示采集音频的源麦克风设备Id。如果不传，系统自动设置默认值。 cameraId：可选，string类型，在video为true的时候有效，表示采集视频的摄像头设备Id。如果不传，系统自动设置默认值。 facingMode：可选，string类型，在video为true的时候有效，user表示前置摄像头，environment表示后置摄像头。 screenAudio：可选，boolean类型，是否包含屏幕共享背景音。默认值为false。该功能仅支持Windows平台Chrome浏览器 74及以上版本。该字段为1.4.0版本新增。 audioSource：可选，MediaStreamTrack类型，表示输入音轨对象。通过指定Track设置音频。MediaStreamTrack为Web API基本接口。 videoSource：可选，MediaStreamTrack类型，表示输入视轨对象。通过指定Track设置主流视频。MediaStreamTrack为Web API基本接口。 mirror：可选，boolean类型，表示主流的本地视频是否镜像。默认值为false。 userId：可选，string类型，表示该流归属的userId。 } 【返回参数】 Stream：流对象。 在采集主流有两种方式： 通过“audioSource”和“videoSource”设置音频和视频主流。这种模式下不支持大小流。 通过“audio/microphoneId”和“video/cameraId/facingMode”设置音频和视频主流。 如果未指定任何的音频源和视频源，则创建的流对象不包含音频流和视频流，无法播放。 如果采集视频，同一个Stream对象不能同时采集主流和辅流。 如果需要包含屏幕共享背景音，需要设置screen和screenAudio均为true，该参数仅在1.4.0 及以上版本生效。

setLogLevel (static) setLogLevel(level: LogLevel): void 【功能说明】 设置日志输出等级。默认输出info等级日志。 【请求参数】 level：必选，LogLevel类型，设置日志级别。 LogLevel表示日志级别，枚举取值如下： none：string类型，表示关闭SDK日志打印。 error：string类型，表示开启SDK错误日志级别。 warn：string类型，表示开启SDK警告日志级别。 info：string类型，表示开启SDK信息日志级别。 debug：string类型，表示开启SDK调试日志级别。 【返回参数】 无

createClient (static)createClient(config: ClientConfig): Client 【功能说明】 创建一个 实时音视频 通话的客户端对象。一个客户端对象只能同时加入一个房间。可以创建多个客户端对象同时加入多个房间。 【请求参数】 config：必选，ClientConfig类型, 客户端对象配置信息。 ClientConfig定义为：{ appId：必选，string[128]类型，应用ID，只有App ID相同的应用程序才能进入同一个房间进行互动。应用的appId请参考应用管理进行获取。 domain：可选，string[128]类型，服务器的 域名 。需要与注册到SparkRTC平台的合法企业域名保持一致，该参数在SDK 1.0+版本中必填，SDK 2.0+版本中非必填。 countryCode: 可选，string[2]类型，需要满足ISO 3166-1的2位字母的国家码要求。表示业务接入点的国家码，SDK会根据设置将业务接入到对应区域的服务，如：CN表示中国大陆，US表示美国，HK表示中国香港。countryCode值的填写具体请参见国家码对照表。该参数为2.0.3版本新增，且为必选参数，从2.0.7版本开始，修改为可选参数。 } 【返回参数】 Client：客户端对象。

onVideoResolutionChangedNotify void onVideoResolutionChangedNotify(HRTCConnection conn, String userid, int width, int height); 【功能说明】 远端视频大小改变回调。 【回调参数】 conn：回调对应的HRTCConnection实例。 userId：用户ID。 width：视频流宽度。 height：视频流高度。

onRemoteShareStatusChangeNotify void onRemoteShareStatusChangeNotify(HRTCConnection conn, String userId, boolean isRecving) 【功能说明】 上报下行辅流状态变化通知，接收端探测网络变化，分配给下行辅流，如果有辅流因为带宽不足被停掉或者带宽恢复而恢复，则上报给产品。 【回调参数】 conn: 连接对象。 userId：下行辅流对应的用户ID。 isRecving：是否接受。

onFirstRemoteAuxiliaryStreamDecoded void onFirstRemoteAuxiliaryStreamDecoded(HRTCConnection conn, String roomId, String userId, int width, int height); 【功能说明】 接收到第一帧远端辅流并解码成功，触发此回调。 【回调参数】 conn：回调对应的HRTCConnection实例。 roomId：视频流对应的房间ID。 userId：视频流对应的用户ID。 width：视频流宽。 height：视频流高。

onUserNameChangedNotify void onUserNameChangedNotify(HRTCConnection conn, String oldUserName, String newUserName); 【功能说明】 调用changeUserName接口成功后，上报此事件通知修改昵称结果。 【回调参数】 conn：回调对应的HRTCConnection实例。 oldUserName：修改前的昵称。 newUserName：修改后的昵称。

onTopActiveSpeaker public void onTopActiveSpeaker(HRTCConnection conn, String userId, boolean noStream); 【功能说明】 上报当前最活跃的用户userId。该回调主要用于0号会场场景（额外订阅uid为0的用户音频）。 【回调参数】 userId：返回当前远端音量最活跃的用户ID。 noStream：该用户是否有视频流。 0号会场模式下，SDK会持续监测（根据一定时间内用户音量大小）当前最活跃的用户，如果最活跃用户发生变化，则触发此回调并上报当前最活跃的用户userId。

onConnectionChangedNotify void onConnectionChangedNotify(HRTCConnection conn, HRTCConnStateTypes connStateTypes, HRTCConnChangeReason connChangeReason, String description); 【功能说明】 网络连接状态改变。 【回调参数】 conn：回调对应的HRTCConnection实例。 connStateTypes：网络连接状态，具体请参见HRTCConnStateTypes。 connChangeReason：网络连接状态原因，具体请参见HRTCConnChangeReason。 description：描述。

onUserRoleChangedNotify void onUserRoleChangedNotify(HRTCConnection conn, HRTCRoleType oldRole, HRTCRoleType newRole); 【功能说明】 用户角色改变。 【回调参数】 conn：回调对应的HRTCConnection实例。 oldRole：改变前的角色，具体请参见HRTCRoleType。 newRole：改变后的角色，具体请参见HRTCRoleType。

onRemoteVideoStateChangedNotify void onRemoteVideoStateChangedNotify(HRTCConnection conn, String userId, HRTCRemoteVideoStreamState state, HRTCRemoteVideoStreamStateReason reason); 【功能说明】 远端视频流状态变化回调。 【回调参数】 conn：回调对应的HRTCConnection实例。 userId：远端用户ID。 state：远端视频流状态，具体请参见HRTCRemoteVideoStreamState。 reason：远端视频流状态变化原因，具体请参见HRTCRemoteVideoStreamStateReason。

onStreamPublishStateChange void onStreamPublishStateChange(HRTCConnection conn,int code, const char* taskId, const HRTCUrlStatusList * urlStatus); 【功能说明】 RTMP推流状态回调。 【回调参数】 conn：回调对应的HRTCConnection实例。 code：错误码，0表示成功，非0请参见错误码。 taskId：任务Id。 urlStatus：推流的url结果结构体，具体请参见HRTCUrlStatusList。

onFirstRemoteVideoDecoded void onFirstRemoteVideoDecoded(HRTCConnection conn, String userId, int width, int height); 【功能说明】 远端用户第一帧解码成功回调。 【回调参数】 conn：回调对应的HRTCConnection实例。 userId：用户ID。 width：视频宽度。 height：视频高度。

onRenderSuccessNotify void onRenderSuccessNotify(HRTCConnection conn, String userId, boolean isAux); 【功能说明】 用户视频流渲染成功通知回调。首帧渲染成功、分辨率变化或视频流中断后恢复触发。 【回调参数】 conn：回调对应的HRTCConnection实例。 userId：用户ID。 isAux：是否辅流。true为是辅流，false为不是辅流。

onRemoteUserNameChangedNotify void onRemoteUserNameChangedNotify(HRTCConnection conn, String userId, String userName); 【功能说明】 远端用户修改昵称后，通知本端昵称变更。 【回调参数】 conn：回调对应的HRTCConnection实例。 userId：修改昵称的用户id。 userName：修改后的昵称。

onUserAuxiliaryStreamAvailable void onUserAuxiliaryStreamAvailable(HRTCConnection conn, String userId, boolean available); 【功能说明】 辅流加入房间。 【回调参数】 conn：回调对应的HRTCConnection实例。 userId：用户ID。 available：true为辅流开始推送，false为辅流停止推送。

onRemoteAudioStateChangedNotify void onRemoteAudioStateChangedNotify(HRTCConnection conn, String userId, HRTCRemoteAudioStreamState state, HRTCRemoteAudioStreamStateReason reason); 【功能说明】 远端音频流状态变化回调。 【回调参数】 conn：回调对应的HRTCConnection实例。 userId：远端用户ID。 state：远端音频流状态，具体请参见HRTCRemoteAudioStreamState。 reason：远端音频流状态变化原因，具体请参见HRTCRemoteAudioStreamStateReason。

onMediaConnectStateChangedNotify void onMediaConnectStateChangedNotify(HRTCConnection conn, HRTCMediaConnStateTypes state, HRTCMediaConnChangeReason reason, String description); 【功能说明】 媒体服务器连接状态变更通知。加入房间过后，收到媒体服务的数据包时，返回Connected消息，超过6s没有收到包，则返回Failed消息。 【回调参数】 conn：回调对应的HRTCConnection实例。 state：连接状态，具体请参见HRTCMediaConnStateTypes。 reason：连接状态变化的原因，具体请参见HRTCMediaConnChangeReason。 description：连接状态变化原因描述。

onRemoteMicrophoneStateChanged void onRemoteMicrophoneStateChanged(HRTCConnection conn, String userId, HRTCRemoteMicState state); 【功能说明】 远端麦克风设备状态变更回调。 【回调参数】 conn: 连接对象。 userId：用户id。 state：麦克风设备状态，具体请参见HRTCRemoteMicState。

onLeaveRoom void onLeaveRoom(HRTCConnection conn, HRTCLeaveReason reason, HR TCS tatsInfo statsInfo); 【功能说明】 离开房间回调。 【回调参数】 conn：回调对应的HRTCConnection实例。 reason：自己离开房间的原因，具体请参见HRTCLeaveReason。 statsInfo：会议期间的统计信息，具体请参见HRT CS tatsInfo。

onRenderExternalVideoFrame virtual void onRenderExternalVideoFrame(const char* roomId, HRTCMediaDirection direction, const char* userId, HRTCVideoFrame& videoFrame) 【功能说明】 视频自渲染回调。需要调用setExternalVideoFrameOutput接口开启视频自渲染，从而触发该回调。 【回调参数】 roomId：房间ID。 direction：数据源，本地数据，远端数据，具体请参见HRTCMediaDirection。 userId：视频数据对应的远端用户ID。 videoFrame：视频帧详情，具体请参见HRTCVideoFrame。