Cocos Creator SDK API Reference

声网通过全球部署的虚拟网络，提供可以灵活搭配的 API 组合，为移动端到移动端以及移动端到 Web 端提供质量可靠的实时音视频通信。

• agora 命名空间包含应用程序调用的主要方法。
• AgoraRtcEvents 类用于向应用程序发送回调通知。

在调用 API 过程中，SDK 可能会返回错误码和警告码，详见错误码和警告码。

频道管理

方法	描述
init	初始化声网引擎
initWithAreaCode	初始化声网引擎（指定访问区域）
release	销毁声网引擎
setChannelProfile	设置频道场景
setClientRole	设置直播场景下的用户角色
joinChannel	加入频道
switchChannel	快速切换直播频道
leaveChannel	离开频道
renewToken	更新 Token
getConnectionState	获取网络连接状态

频道事件

事件	描述
onConnectionStateChanged	网络连接状态已改变回调
onJoinChannelSuccess	加入频道回调
onRejoinChannelSuccess	重新加入频道回调
onLeaveChannel	离开频道回调
onClientRoleChanged	用户角色已切换回调
onUserJoined	远端用户加入当前频道回调
onUserOffline	远端用户离开当前频道回调
onNetworkTypeChanged	本地网络类型发生改变回调
onConnectionLost	网络连接丢失回调
onTokenPrivilegeWillExpire	Token 服务即将过期回调
onRequestToken	Token 已过期回调

音频管理

方法	描述
enableAudio	启用音频模块
disableAudio	关闭音频模块
setAudioProfile	设置音频编码属性
adjustRecordingSignalVolume	调节录音音量
adjustUserPlaybackSignalVolume	调节本地播放的指定远端用户音量
adjustPlaybackSignalVolume	调节本地播放的所有远端用户音量
enableLocalAudio	开关本地音频采集
muteLocalAudioStream	停止/恢复发送本地音频流
muteRemoteAudioStream	停止/恢复接收指定音频流
muteAllRemoteAudioStreams	停止/恢复接收所有音频流
setDefaultMuteAllRemoteAudioStreams	设置是否默认接收音频流

视频管理

方法	描述
enableVideo	启用视频模块
disableVideo	关闭视频模块
setVideoEncoderConfiguration	设置视频编码属性
startPreview	开启视频预览
stopPreview	停止视频预览
enableLocalVideo	开关本地视频采集
muteLocalVideoStream	开关本地视频发送
muteRemoteVideoStream	接收／停止接收指定远端用户的视频流
muteAllRemoteVideoStreams	接收／停止接收所有远端视频流
setDefaultMuteAllRemoteVideoStreams	设置是否默认停止接收视频流

本地媒体事件

事件	描述
onLocalAudioStateChanged	本地音频状态改变回调
onLocalVideoStateChanged	本地视频状态发生改变回调
onFirstLocalAudioFramePublished	已发布本地音频首帧回调
onFirstLocalVideoFramePublished	已发布本地视频首帧回调
onFirstLocalVideoFrame	已显示本地视频首帧回调
onAudioPublishStateChanged	音频发布状态改变回调
onVideoPublishStateChanged	视频发布状态改变回调

远端媒体事件

事件	描述
onRemoteAudioStateChanged	远端用户音频状态已改变回调
onRemoteVideoStateChanged	远端用户视频流状态已变化回调
onFirstRemoteVideoFrame	已显示远端视频首帧回调
onAudioSubscribeStateChanged	音频订阅状态改变回调
onVideoSubscribeStateChanged	视频订阅状态发生改变回调

数据统计事件

加入频道后，SDK 每隔 2 秒自动触发本组回调

事件	描述
onRtcStats	当前通话统计回调
onNetworkQuality	网络上下行质量报告回调
onLocalAudioStats	通话中本地音频流统计信息回调
onRemoteAudioStats	通话中远端音频流的统计信息回调
onRemoteVideoStats	远端视频流统计信息回调

视频前处理及后处理

方法	描述
setBeautyEffectOptions	设置美颜效果选项

音乐文件播放及混音

方法	描述
startAudioMixing	开始播放音乐文件
stopAudioMixing	停止播放音乐文件
pauseAudioMixing	暂停播放音乐文件
resumeAudioMixing	恢复播放音乐文件
adjustAudioMixingVolume	调节音乐文件播放音量
adjustAudioMixingPlayoutVolume	调节音乐文件的本地播放音量
adjustAudioMixingPublishVolume	调节音乐文件的远端播放音量
setAudioMixingPitch	调整本地播放的音乐文件的音调
getAudioMixingPlayoutVolume	获取音乐文件的本地播放音量
getAudioMixingPublishVolume	获取音乐文件的远端播放音量
getAudioMixingDuration	获取音乐文件播放时长
getAudioMixingCurrentPosition	获取音乐文件的播放进度
setAudioMixingPosition	设置音乐文件的播放位置

事件	描述
onAudioMixingStateChanged	本地用户的音乐文件播放状态已改变回调
onRemoteAudioMixingBegin	远端音乐文件播放已开始回调
onRemoteAudioMixingEnd	远端音乐文件播放已结束回调

音效文件播放管理

方法	描述
getEffectsVolume	获取音效文件的播放音量
setEffectsVolume	设置音效文件的播放音量
setVolumeOfEffect	实时调整音效文件的播放音量
playEffect	播放指定音效文件
stopEffect	停止播放指定音效文件
stopAllEffects	停止播放所有音效文件
preloadEffect	将音效文件加载至内存
unloadEffect	从内存释放某个预加载的音效文件
pauseEffect	暂停播放指定音效文件
pauseAllEffects	暂停播放所有音效文件
resumeEffect	恢复播放指定音效文件
resumeAllEffects	恢复播放所有音效文件

事件	描述
onAudioEffectFinished	本地音效文件播放已结束回调

变声与混响

方法	描述
setLocalVoiceChanger	设置本地语音变声
setLocalVoiceReverbPreset	设置预设的本地语音混响效果
setLocalVoicePitch	设置本地语音音调
setLocalVoiceEqualization	设置本地语音音效均衡
setLocalVoiceReverb	设置本地音效混响

听声辨位

方法	描述
enableSoundPositionIndication	开启/关闭远端用户的语音立体声
setRemoteVoicePosition	设置远端用户的语音位置

CDN 推流

该组方法仅适用于互动直播

方法	描述
setLiveTranscoding	设置直播转码
addPublishStreamUrl	增加旁路推流地址
removePublishStreamUrl	删除旁路推流地址

事件	描述
onRtmpStreamingStateChanged	旁路推流状态改变回调
onRtmpStreamingEvent	RTMP 推流事件回调
onTranscodingUpdated	旁路推流设置已被更新回调

跨频道媒体流转发

方法	描述
startChannelMediaRelay	开始跨频道媒体流转发
updateChannelMediaRelay	更新媒体流转发的频道
stopChannelMediaRelay	停止跨频道媒体流转发

事件	描述
onChannelMediaRelayStateChanged	跨频道媒体流转发状态发生改变回调
onChannelMediaRelayEvent	跨频道媒体流转发事件回调

音量提示

方法	描述
enableAudioVolumeIndication	启用说话者音量提示

事件	描述
onAudioVolumeIndication	提示频道内谁正在说话及说话者音量的回调
onActiveSpeaker	监测到最活跃用户回调

人脸检测

方法	描述
enableFaceDetection	开启/关闭本地人脸检测

事件	描述
onFacePositionChanged	报告本地人脸检测结果

语音播放路由

方法	描述
setDefaultAudioRouteToSpeakerphone	设置默认的音频播放路由
setEnableSpeakerphone	启用/关闭扬声器播放
isSpeakerphoneEnabled	查询扬声器启用状态

事件	描述
onAudioRouteChanged	语音路由已改变回调

耳返控制

方法	描述
enableInEarMonitoring	开启耳返功能
setInEarMonitoringVolume	设置耳返音量

视频双流模式

方法	描述
enableDualStreamMode	开关视频双流模式
setRemoteVideoStreamType	设置订阅的视频流类型
setRemoteDefaultVideoStreamType	设置默认订阅的视频流类型

视频流回退

方法	描述
setLocalPublishFallbackOption	设置弱网条件下发布的音视频流的回退选项
setRemoteSubscribeFallbackOption	设置弱网条件下订阅的音视频流的回退选项
setRemoteUserPriority	设置远端用户流的优先级

事件	描述
onLocalPublishFallbackToAudioOnly	本地发布流已回退为音频流或恢复为音视频流回调
onRemoteSubscribeFallbackToAudioOnly	远端订阅流已回退为音频流或恢复为音视频流回调

通话前网络测试

方法	描述
startEchoTest	开始语音通话回路测试
stopEchoTest	停止语音通话回路测试
enableLastmileTest	启用网络测试
disableLastmileTest	关闭网络测试
startLastmileProbeTest	开始通话前网络质量探测
stopLastmileProbeTest	停止通话前网络质量探测

事件	描述
onLastmileQuality	本地网络质量报告回调
onLastmileProbeResult	本地网络上下行 Last-mile 质量报告回调

媒体附属信息

方法	描述
registerMediaMetadataObserver	注册媒体 Metadata 观测器
sendMetadata	发送 Metadata
setMaxMetadataSize	设置最大的 Metadata 大小

事件	描述
onMetadataReceived	接收端已收到 Metadata 回调

水印

该组方法仅适用于互动直播。

方法	描述
addVideoWatermark	添加本地视频水印
clearVideoWatermarks	删除已添加的视频水印

加密

方法	描述
enableEncryption	开启/关闭内置加密
registerPacketObserver	注册数据包观测器

音频录制

方法	描述
startAudioRecording	开始客户端录音
stopAudioRecording	停止客户端录音

摄像头控制

方法	描述
switchCamera	切换前置/后置摄像头

事件	描述
onCameraFocusAreaChanged	摄像头对焦区域已改变回调
onCameraExposureAreaChanged	摄像头曝光区域已改变回调

设备管理

事件	描述
onAudioDeviceStateChanged	音频设备变化回调
onVideoDeviceStateChanged	视频设备变化回调
onAudioDeviceVolumeChanged	回放、音频采集设备或 App 的音量发生改变

流消息

方法	描述
createDataStream	创建数据流
sendStreamMessage	发送数据流

事件	描述
onStreamMessage	接收到对方数据流消息的回调
onStreamMessageError	接收对方数据流消息发生错误的回调

其他视频控制

方法	描述
setCameraCapturerConfiguration	设置摄像头采集偏好

其他方法

方法	描述
sendCustomReportMessage	自定义数据上报
getCallId	获取通话 ID
rate	给通话评分
complain	投诉通话质量
getVersion	查询 SDK 版本号
setLogFile	设置日志文件
setLogFilter	设置日志输出等级
setLogFileSize	设置日志文件大小
getErrorDescription	获取警告或错误描述

其他事件

事件	描述
onWarning	发生警告回调
onError	发生错误回调
onApiCallExecuted	API 方法已执行回调