Voice SDK v1.3.1_3.1 API Reference for Cocos Creator

Agora provides ensured quality of experience (QoE) for worldwide Internet-based voice and video communications through a virtual global network optimized for real-time web and mobile-to-mobile applications.

The agora namespace is the entry point of the Voice SDK v1.3.1_3.1 API Reference for Cocos Creator providing API methods for applications to quickly start a voice and video call or the live interactive audio and video streaming.
The AgoraRtcEvents class reports runtime events to the applications.

During API calls, the SDK may returns error codes and warning codes. See Error Codes and Warning Codes.

Channel Management

Method	Description
init	Initializes the Agora engine.
initWithAreaCode	Initializes the Agora engine and specifies the region for connection.
release	Releases all resources of the Agora engine.
setChannelProfile	Sets the channel profile.
setClientRole	Sets the role of the user.
joinChannel	Allows a user to join a channel.
switchChannel	Switches to a different channel in the live interactive streaming.
leaveChannel	Allows a user to leave a channel.
renewToken	Renews the Token.
getConnectionState	Gets the current connection state of the SDK.

Channel Events

Event	Description
onConnectionStateChanged	Occurs when the connection state between the SDK and the server changes.
onJoinChannelSuccess	Occurs when a user joins a channel.
onRejoinChannelSuccess	Occurs when a user rejoins the channel.
onLeaveChannel	Occurs when a user leaves the channel.
onClientRoleChanged	Occurs when the user role switches in the live interactive streaming.
onUserJoined	Occurs when a remote user (`COMMUNICATION`)/ host (`LIVE_BROADCASTING`) joins the channel.
onUserOffline	Occurs when a remote user (`COMMUNICATION`)/ host (`LIVE_BROADCASTING`) leaves the channel.
onNetworkTypeChanged	Occurs when the local network type changes.
onConnectionLost	Occurs when the SDK cannot reconnect to Agora's edge server 10 seconds after its connection to the server is interrupted.
onTokenPrivilegeWillExpire	Occurs when the token expires in 30 seconds.
onRequestToken	Occurs when the token expires.

Audio Management

Method	Description
enableAudio	Enables the audio module.
disableAudio	Disables the audio module.
setAudioProfile	Sets the audio parameters and application scenarios.
adjustRecordingSignalVolume	Adjusts the recording volume.
adjustUserPlaybackSignalVolume	Adjusts the playback volume of a specified remote user.
adjustPlaybackSignalVolume	Adjusts the playback volume of all remote users.
enableLocalAudio	Enables/Disables the local audio sampling.
muteLocalAudioStream	Stops/Resumes sending the local audio stream.
muteRemoteAudioStream	Stops/Resumes receiving the audio stream from a specified remote user.
muteAllRemoteAudioStreams	Stops/Resumes receiving all remote users' audio streams.
setDefaultMuteAllRemoteAudioStreams	Stops/Resumes receiving all remote users' audio streams by default.

Video Management

Method	Description
enableVideo	Enables the video module.
disableVideo	Disables the video module.
setVideoEncoderConfiguration	Sets the video encoder configuration.
startPreview	Starts the local video preview before joining the channel.
stopPreview	Stops the local video preview and disables video.
enableLocalVideo	Enables/Disables the local video capture.
muteLocalVideoStream	Stops/Resumes sending the local video stream.
muteRemoteVideoStream	Stops/Resumes receiving the video stream from a specified remote user.
muteAllRemoteVideoStreams	Stops/Resumes receiving all video stream from a specified remote user.
setDefaultMuteAllRemoteVideoStreams	Stops/Resumes receiving all remote users' video streams by default.

Local Media Events

Event	Description
onLocalAudioStateChanged	Occurs when the local audio state changes.
onLocalVideoStateChanged	Occurs when the local video state changes.
onFirstLocalAudioFramePublished	Occurs when the first audio frame is published.
onFirstLocalVideoFramePublished	Occurs when the first video frame is published.
onFirstLocalVideoFrame	Occurs when the first local video frame is rendered.
onAudioPublishStateChanged	Occurs when the audio publishing state changes.
onVideoPublishStateChanged	Occurs when the video publishing state changes.

Remote Media Events

Event	Description
onRemoteAudioStateChanged	Occurs when the remote audio state changes.
onRemoteAudioStateChanged	Occurs when the remote audio state changes.
onRemoteVideoStateChanged	Occurs when the remote video state changes.
onUserMuteVideo	Occurs when a remote user's video stream playback pauses/resumes.
onFirstRemoteVideoFrame	Occurs when the first remote video frame is rendered.
onAudioSubscribeStateChanged	Occurs when the audio subscribing state changes.
onVideoSubscribeStateChanged	Occurs when the audio subscribing state changes.

Statistics Events

After joining a channel, SDK triggers this group of callbacks once every two seconds.

Event	Description
onRtcStats	Reports the statistics of the current call.
onNetworkQuality	Reports the network quality of each user.
onLocalAudioStats	Reports the statistics of the local audio stream.
onRemoteAudioStats	Reports the statistics of the audio stream from each remote user/host.
onRemoteVideoStats	Reports the statistics of the video stream from each remote user/host.

Video Pre-process and Post-process

Method	Description
setBeautyEffectOptions	Sets the image enhancement options.

Audio File Playback and Mixing

Method	Description
startAudioMixing	Starts playing and mixing the music file.
stopAudioMixing	Stops playing and mixing the music file.
pauseAudioMixing	Pauses playing and mixing the music file.
resumeAudioMixing	Resumes playing and mixing the music file.
adjustAudioMixingVolume	Adjusts the volume during audio mixing.
adjustAudioMixingPlayoutVolume	Adjusts the volume of audio mixing for local playback.
adjustAudioMixingPublishVolume	Adjusts the volume of audio mixing for remote playback.
setAudioMixingPitch	Sets the audio mixing pitch.
getAudioMixingPlayoutVolume	Gets the audio mixing volume for local playback.
getAudioMixingPublishVolume	Gets the audio mixing volume for publishing.
getAudioMixingDuration	Gets the duration (ms) of the music file.
getAudioMixingCurrentPosition	Gets the playback position (ms) of the music file.
setAudioMixingPosition	Sets the playback position of the music file.

Event	Description
onAudioMixingStateChanged	Occurs when the state of the local user's audio mixing file changes.
onRemoteAudioMixingBegin	Occurs when a remote user starts audio mixing.
onRemoteAudioMixingEnd	Occurs when a remote user finishes audio mixing.

Audio Effect Playback

Method	Description
getEffectsVolume	Gets the volume of the audio effects.
setEffectsVolume	Sets the volume of the audio effects.
setVolumeOfEffect	Sets the volume of the audio effect.
playEffect	Plays a specified audio effect.
stopEffect	Stops playing a specified audio effect.
stopAllEffects	Stops playing all audio effects.
preloadEffect	Preloads a specified audio effect file into the memory.
unloadEffect	Releases a specified audio effect from the memory.
pauseEffect	Pauses a specified audio effect.
pauseAllEffects	Pauses all audio effects.
resumeEffect	Resumes playing a specified audio effect.
resumeAllEffects	Resumes playing all audio effects.

Event	Description
onAudioEffectFinished	Occurs when the local audio effect playback finishes.

Voice Changer and Reverberation

Method	Description
setLocalVoiceChanger	Sets the local voice changer option.
setLocalVoiceReverbPreset	Sets the preset local voice reverberation effect.
setLocalVoicePitch	Changes the voice pitch of the local speaker.
setLocalVoiceEqualization	Sets the local voice equalization effect.
setLocalVoiceReverb	Sets the local voice reverberation.

Sound Position Indication

Method	Description
enableSoundPositionIndication	Enables/Disables stereo panning for remote users.
setRemoteVoicePosition	Sets the sound position and gain of a remote user.

CDN Publisher

This group of methods apply to live interactive streaming only.

Method	Description
setLiveTranscoding	Sets the video layout and audio for CDN live.
addPublishStreamUrl	Adds a CDN stream address.
removePublishStreamUrl	Removes a CDN stream address.

Event	Description
onRtmpStreamingStateChanged	Occurs when the state of the RTMP streaming changes.
onRtmpStreamingEvent	Reports events during the RTMP streaming.
onTranscodingUpdated	Occurs when the publisher's transcoding settings are updated.

Media Stream Relay Across Channels

Method	Description
startChannelMediaRelay	Starts to relay media streams across channels.
updateChannelMediaRelay	Updates the channels for media stream relay.
stopChannelMediaRelay	Stops the media stream relay.

Event	Description
onChannelMediaRelayStateChanged	Occurs when the state of the media stream relay changes.
onChannelMediaRelayEvent	Reports events during the media stream relay.

Audio Volume Indication

Method	Description
enableAudioVolumeIndication	Enables the onAudioVolumeIndication callback at a set time interval to report on which users are speaking and the speakers' volume.

Event	Description
onAudioVolumeIndication	Reports which users are speaking, the speakers' volumes, and whether the local user is speaking.
onActiveSpeaker	Occurs when the most active speaker is detected.

Face Detection

Method	Description
enableFaceDetection	Enables/Disables face detection for the local user.

Event	Description
onFacePositionChanged	Reports the face detection result of the local user.

Audio Routing Control

Method	Description
setDefaultAudioRouteToSpeakerphone	Sets the default audio playback route.
setEnableSpeakerphone	Enables/Disables the audio playback route to the speakerphone.
isSpeakerphoneEnabled	Checks whether the speakerphone is enabled.

Event	Description
onAudioRouteChanged	Occurs when the local audio route changes.

In-ear Monitoring

Method	Description
enableInEarMonitoring	Enables in-ear monitoring.
setInEarMonitoringVolume	Sets the volume of the in-ear monitor.

Dual Video Stream Mode

Method	Description
enableDualStreamMode	Sets the stream mode to single- (default) or dual-stream mode.
setRemoteVideoStreamType	Sets the remote user’s video stream type received by the local user when the remote user sends dual streams.
setRemoteDefaultVideoStreamType	Sets the default video-stream type for the video received by the local user when the remote user sends dual streams.

Stream Fallback

Method	Description
setLocalPublishFallbackOption	Sets the fallback option for the published video stream under unreliable network conditions.
setRemoteSubscribeFallbackOption	Sets the fallback option for the remote stream under unreliable network conditions.
setRemoteUserPriority	Prioritizes a remote user's stream.

Event	Description
onLocalPublishFallbackToAudioOnly	Occurs: When the published media stream falls back to an audio-only stream due to poor network conditions. When the published media stream switches back to the video after the network conditions improve.
onRemoteSubscribeFallbackToAudioOnly	Occurs: When the remote media stream falls back to audio-only due to poor network conditions. When the remote media stream switches back to the video after the network conditions improve.

Event

Description

onLocalPublishFallbackToAudioOnly

Occurs:

When the published media stream falls back to an audio-only stream due to poor network conditions.
When the published media stream switches back to the video after the network conditions improve.

onRemoteSubscribeFallbackToAudioOnly

Occurs:

When the remote media stream falls back to audio-only due to poor network conditions.
When the remote media stream switches back to the video after the network conditions improve.

Pre-call Network Test

Method	Description
startEchoTest	Starts an audio call test.
stopEchoTest	Stops the audio call test.
enableLastmileTest	Enables the network connection quality test.
disableLastmileTest	Disables the network connection quality test.
startLastmileProbeTest	Starts the last-mile network probe test.
stopLastmileProbeTest	Stops the last-mile network probe test.

Event	Description
onLastmileQuality	Reports the last mile network quality of the local user before the user joins the channel.
onLastmileProbeResult	Reports the last-mile network probe result.

Media Metadata

Method	Description
registerMediaMetadataObserver	Registers the metadata observer.
sendMetadata	Sends the metadata.
setMaxMetadataSize	Sets the maximum size of the metadata.

Event	Description
onMetadataReceived	Occurs when the local user receives the metadata.

Watermark

This group of methods apply to live interactive streaming only.

Method	Event	Description
addVideoWatermark	Adds a watermark image to the local video stream.
clearVideoWatermarks	Removes the added watermark image from the video stream.

Encryption

Method	Description
enableEncryption	Enables/Disables the built-in encryption.
registerPacketObserver	Registers a packet observer.

Audio Recorder

Method	Description
startAudioRecording	Starts an audio recording on the client.
stopAudioRecording	Stops an audio recording on the client.

Inject an Online Media Stream

This group of methods apply to live interactive streaming only.

Method	Description
addInjectStreamUrl	Adds an online media stream to the live interactive streaming.
removeInjectStreamUrl	Removes the online media stream from the live interactive streaming.

Event	Description
onStreamInjectedStatus	Reports the status of the injected online media stream.

Camera Control

Method	Description
switchCamera	Switches between front and rear cameras.

Event	Description
onCameraFocusAreaChanged	Occurs when the camera focus area changes.
onCameraExposureAreaChanged	Occurs when the camera exposure area changes.

Device Manager

Event	Description
onAudioDeviceStateChanged	Occurs when the audio device state changes.
onVideoDeviceStateChanged	Occurs when the video device state changes.
onAudioDeviceVolumeChanged	Occurs when the volume of the playback, microphone, or application changes.

Stream Message

Method	Description
createDataStream	Creates a data stream.
sendStreamMessage	Sends data stream messages.

Event	Description
onStreamMessage	Occurs when the local user receives a remote data stream within five seconds.
onStreamMessageError	Occurs when the local user fails to receive the remote data stream.

Miscellaneous Video Control

Method	Description
setCameraCapturerConfiguration	Sets the camera capturer configuration.

Miscellaneous Methods

Method	Description
sendCustomReportMessage	Reports customized messages.
getCallId	Gets the current call ID.
rate	Allows the user to rate the call and is called after the call ends.
complain	Allows a user to complain about the call quality after a call ends.
getVersion	Gets the SDK version number.
setLogFile	Specifies an SDK output log file.
setLogFilter	Sets the output log level of the SDK.
setLogFileSize	Sets the log file size (KB).
getErrorDescription	Gets the warning or error description.

Miscellaneous Events

Event	Description
onWarning	Reports a warning during SDK runtime.
onError	Reports an error during SDK runtime.
onApiCallExecuted	Occurs when a method is executed.