• Docs /
• RTC /
• Audio and Video SDK /
• iOS /
• iOS /

CloudHubSDK iOS

• Overview
• CloudHubRtcEngineKit
• CloudHubRtcEngineDelegate
• CloudHubRtcChannelKit
• CloudHubRtcChannelDelegate
• CloudHubEnumerates
• CloudHubObjects

CloudHubRtcEngineKit

Delegate settings

delegate:

Set CloudHubRtcEngineKit delegate

@property (nonatomic, weak) id<CloudHubRtcEngineDelegate> _Nullable delegate;

Details

See CloudHubRtcEngineDelegate

Channel management

sharedEngineWithAppId:config:

Creates and initializes Creates and initializes CloudHubRtcEngineKit

+ (instancetype _Nonnull)sharedEngineWithAppId:(NSString * _Nonnull)appId
                                        config:(NSString * _Nullable)config;

Parameter

Returns

• The CloudHubRtcEngineKit instance, if the method call succeeds.
• An error code, if the call fails

Details

Please call the interface function of the ‘CloudHubRtcEngineKit’ class in the main thread

Note

• The SDK supports creating only one ‘CloudHubRtcEngineKit’ instance for an app.

sharedEngineWithAppId:config:externalDevices:

Get the RTC engine singleton object pointer

-(instancetype _Nonnull)sharedEngineWithAppId:(NSString * _Nonnull)appId
                                         config:(NSString * _Nullable)config
                                         externalDevices:(int)extDevices;

Parameter

Returns

• Non-empty: method call succeeded
• nil: method call failed

Details

Please call the interface function of the CloudHubRtcEngineKit class in the main thread

Note

• Can be called repeatedly, in the first call, a singleton will be initialized

setChannelProfile

Set the channel profile

- (int)setChannelProfile:(CloudHubChannelProfile)profile;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

CloudHubRtcEngineKit will adopt different optimization strategies for different use scenarios, such as smooth communication scenarios and picture quality for live broadcast scenarios

Note

• To ensure the quality of real-time communication, All users in a channel use the same channel profile
• This method must be called and set before joinChannel, and cannot be set again after entering the channel

setClientRole

Set the client role

- (int)setClientRole:(CloudHubClientRole)role;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

You can call this method either before or after joining the channel to set the user role as audience or host If you call this method to switch the user role after joining the channel, the SDK triggers the following callbacks:

• The local client rtcEngine:onClientRoleChangedFrom:to:
• The remote client: rtcEngine:didJoinedOfUid:properties:isHistory:fromChannel: 或 rtcEngine:didOfflineOfUid:reason:

Note

• This method is only applicable to live scenes
• When calling publishStream method，the user role will be automatically switched to the anchor role

joinChannelByToken:channelId:properties:uid:autosubscribeAudio:autoSubscribeVideo:joinSuccess:

Join channel

- (int)joinChannelByToken:(NSString * _Nullable)token
                channelId:(NSString * _Nonnull)channelId
               properties:(NSString * _Nullable)properties
                      uid:(NSString * _Nullable)uid
       autoSubscribeAudio:(BOOL)autoSubscribeAudio
       autoSubscribeVideo:(BOOL)autoSubscribeVideo
              joinSuccess:(void(^ _Nullable)(NSString * _Nonnull uid, NSInteger elapsed))joinSuccessBlock;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

This method allows a user to join the channel with the user account. After the user successfully joins the channel, the SDK triggers the following callbacks: leaveChannel exit the current call to enter the next channel

• The remote client: rtcEngine:didJoinChannelwithUid:elapsed: callbacks
• The rtcEngine:didJoinedOfUid:properties:isHistory:fromChannel: callback if the user is in the CloudHubChannelProfileCommunication profile
• When the connection between the client and Cloudhub’s server is interrupted due to poor network conditions, the SDK tries reconnecting to the server, the SDK triggers the rtcEngine:connectionChangedToState: callback. When the local client successfully rejoins the channel rtcEngine:didReJoinChannelwithUid:elapsed: callback on the local client.

Note

*Uid cannot be repeated among users in a channel，If repeated，When a user with the same uid enters, it will trigger the previous user to leave the channel automatically，The previous user will receive rtcEngine:onLocalUserEvicted: callbacks

leaveChannel

Leaves a channel

- (int)leaveChannel:(void(^ _Nullable)(void))leaveChannelBlock;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

This method lets the user leave the channel, for example, by hanging up or exiting the call. After joinChannelByToken:channelId:properties:uid:autosubscribeAudio:autoSubscribeVideo:joinSuccess: , you must call this method to end the call, otherwise, the next call cannot be started. No matter whether you are currently in a call or not, you can call this method without side effects. This method releases all resources related to the session

• This method call is asynchronous, and the user has not left the channel when the method call returns. After you leave the channel, the SDK triggers the rtcEngine:didLeaveChannel: callback
• The remote client rtcEngine:didOfflineOfUid:reason:, if the user joining the channel is in the CloudHubChannelProfileCommunication profile, or is a host in the CloudHubChannelProfileLiveBroadcasting profile

renewToken

Gets a new token when the current token expires after a period of time.

- (int)renewToken:(NSString * _Nonnull)token;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

Passes a new token to the SDK.A token expires after a certain period of time. In the following two cases, the app should call this method to pass in a new token. Failure to do so will result in the SDK disconnecting from the server.

• The SDK triggers the rtcEngine:tokenPrivilegeWillExpire: callback
• The SDK triggers the rtcEngineRequestToken: callback

getConnectionState

Gets the current connection state of the SDK

- (CloudHubConnectionStateType)getConnectionState;

Returns

• See CloudHubConnectionStateType

Audio management

enableAudio

Enables the audio module

- (int)enableAudio;

Returns

• 0 : Success
• Not 0：Failure

Details

The audio mode is enabled by default.

disableAudio

Disables the audio module

- (int)disableAudio;

Returns

• 0 : Success
• Not 0：Failure

Details

The audio mode is enabled by default.

adjustRecordingSignalVolume:

Adjusts the volume of the signal captured by the microphone.

- (int)adjustRecordingSignalVolume:(int)volume;

Parameter

Returns

• 0 : Success
• Not 0：Failure

adjustPlaybackSignalVolume:

Adjusts the playback signal volume of all remote users.

- (int)adjustPlaybackSignalVolume:(int)volume;

Parameter

Returns

• 0 : Success
• Not 0：Failure

adjustUserPlaybackSignalVolume:volume:

Adjust the playback signal volume of a specified remote user.

- (int)adjustUserPlaybackSignalVolume:(NSString* _Nonnull)uid
                               volume:(int)volume;

Parameter

Returns

• 0 : Success
• Not 0：Failure

enableLocalAudio

Enables/Disables the local audio capture

- (int)enableLocalAudio:(BOOL)enabled;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

The audio function is enabled by default. This method disables or re-enables the local audio function to stop or restart local audio capturing This method does not affect receiving or playing the remote audio streams, and enableLocalAudio:(NO) applies to scenarios where the user wants to receive remote audio streams without sending any audio stream to other users in the channel

Note

• This method needs to be called after the enableAudio
• This method is different from the muteLocalAudioStream method:
  • enableLocalAudio Disables/Re-enables the local audio capturing and processing. If you disable or re-enable local audio capturing using the enableLocalAudio method, the local user might hear a pause in the remote audio playback.
  • muteLocalAudioStream Sends/Stops sending the local audio streams.
• In common，They only affect audio streams published after publishStream.

muteLocalAudioStream

Stops or resumes publishing the local audio stream.

- (int)muteLocalAudioStream:(BOOL)mute;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

Whether to stop publishing the local audio stream，When the method is successfully called, the remote will trigger rtcEngine:remoteAudioStateChangedOfUid:state:reason: callback（reason is CloudHubAudioRemoteReasonLocalMuted）

Note

• This method does not affect any ongoing audio recording, because it does not disable the microphone

muteRemoteAudioStream:mute:

Stops or resumes subscribing to the audio stream of a specified user

- (int)muteRemoteAudioStream:(NSString* _Nonnull)uid 
                        mute:(BOOL)mute;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Note

• If muteAllRemoteAudioStreams:YES) has been called before, mute all remote audio，Before calling this API, please ensure that you have called muteAllRemoteAudioStreams:NO
• muteAllRemoteAudioStreams is global control，muteRemoteAudioStream:mute: is fine control

muteAllRemoteAudioStreams

Stops or resumes subscribing to the audio streams of all remote users

- (int)muteAllRemoteAudioStreams:(BOOL)mute;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Video management

enableVideo

Enable the video module.

- (int)enableVideo;

Returns

• 0 : Success
• Not 0：Failure

Details

Call this method either before joining a channel or during a call. If this method is called before joining a channel, the call starts in the video mode. Call disableVideo to disable the video mode.

Note

• This method enables the internal engine and is valid after leaveChannel:
• This method resets the internal engine and takes some time to take effect. Cloudhub recommends using the following API methods to control the video engine modules separately:
  • enableLocalVideo：Whether to enable the camera to create the local video stream
  • muteLocalVideoStream：Whether to publish the local video stream
  • muteRemoteVideoStreamWithUid:mute:：Whether to subscribe to and play the remote video stream
  • muteAllRemoteVideoStreams：Whether to subscribe to and play all remote video streams

disableVideo

Disables the video module

- (int)disableVideo;

Returns

• 0 : Success
• Not 0：Failure

Details

This method disables video. You can call this method either before or after joining a channel. If you call it before joining a channel, an audio call starts when you join the channel. If you call it after joining a channel, a video call switches to an audio call. Call enableVideo to enable video.

setVideoEncoderConfiguration

Sets the video encoder configuration

- (int)setVideoEncoderConfiguration:(CloudHubVideoEncoderConfiguration * _Nonnull)config;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

This method sets the video coding configuration. Each configuration corresponds to a set of video parameters, such as resolution, frame rate, code rate, video direction, etc. all the set parameters are the maximum value under ideal conditions. When the video engine cannot reach the maximum value of the set resolution, frame rate or code rate due to equipment, network environment and other reasons, it will take the value closest to the maximum value

startPlayingLocalVideo:renderMode:mirrorMode:

Set the view for the local video and start playing

- (int)startPlayingLocalVideo:(VIEW_CLASS * _Nonnull)view  
                   renderMode:(CloudHubVideoRenderMode) renderMode  
                   mirrorMode:(CloudHubVideoMirrorMode) mirrorMode;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

To call this method to start previewing the local video, you need to call enableVideo and enableLocalVideo to start the local camera in advance. When you leave the channel and enter again, you need to call this method again to start previewing the local video again

Note

• If you want to update the rendering or mirror mode of the local user view during a call, please use the setLocalRenderMode:mirrorMode: method

startPlayingRemoteVideo:streamId:renderMode:mirrorMode:

Set the view for the remote video and start playing

- (int)startPlayingRemoteVideo:(VIEW_CLASS * _Nonnull)view 
                      streamId:(NSString * _Nonnull)streamId 
                    renderMode:(CloudHubVideoRenderMode) renderMode
                    mirrorMode:(CloudHubVideoMirrorMode) mirrorMode;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

Call this method to start playing remote video. You need to call enableVideo to start the video engine in advance

Note

• If you want to update the rendering or mirror mode of the remote user view during a call, please make setRemoteRenderMode:renderMode:mirrorMode: invalid

setLocalRenderMode:mirrorMode:

Updates the display mode of the local video view

- (int)setLocalRenderMode:(CloudHubVideoRenderMode) renderMode
               mirrorMode:(CloudHubVideoMirrorMode) mirrorMode;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

After initializing the local video view, you can call this method to update its rendering and mirror modes. It affects only the video view that the local user sees, not the published local video stream

Note

• Ensure that you have called the startPlayingLocalVideo:renderMode:mirrorMode: method to initialize the local video view before calling this method
• During a call, you can call this method as many times as necessary to update the display mode of the local video view

setRemoteRenderMode:renderMode:mirrorMode:

Updates the display mode of the video view of a remote user.

- (int)setRemoteRenderMode:(NSString * _Nonnull)streamId
                renderMode:(CloudHubVideoRenderMode) renderMode
                mirrorMode:(CloudHubVideoMirrorMode) mirrorMode;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

After initializing the remote user view, you can adjust this method to update the rendering and mirror mode of the remote user view when displayed locally. This method only affects the video pictures seen by the local user

Note

• Please call this method after initializing the remote view by calling the startPlayingRemoteVideo:streamId:renderMode:mirrorMode: method
• During a call, you can call this method as many times as necessary to update the display mode of the video view of a remote user.

enableLocalVideo

Enables/Disables the local video capture

- (int)enableLocalVideo:(BOOL)enabled;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

This method disables or re-enables the local video capturer, and does not affect receiving the remote video stream

Note

• After callingenableVideo, the local video capturer is enabled by default

muteLocalVideoStream

Stops or resumes publishing the local video stream

- (int)muteLocalVideoStream:(BOOL)mute;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

After the method is successfully called, the remote end will trigger rtcEngine:remoteVideoStateChangedOfUid:streamId:type:state:reason:streamInfo: callback, reason is CloudHubVideoRemoteStateReasonRemoteMuted

Note

• This method executes faster than the enableLocalVideo method, which controls the sending of the local video stream.This method does not affect any ongoing video recording, because it does not disable the camera.

muteRemoteVideoStreamWithUid:mute:

Stops or resumes subscribing to the video stream of a specified user

- (int)muteRemoteVideoStreamWithUid:(NSString * _Nonnull)uid
                               mute:(BOOL)mute;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

After joining the channel

Note

• After successfully adjusting the method, the rtcEngine:remoteVideoStateChangedOfUid:streamId:type:state:reason:streamInfo: callback will be triggered locally，reason is CloudHubVideoRemoteStateReasonLocalMuted

muteRemoteVideoByStreamId:mute:

Stops or resumes subscribing to the video stream of a specified streamId

- (int)muteRemoteVideoByStreamId:(NSString * _Nonnull)streamId
                            mute:(BOOL)mute;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

After joining the channel

muteAllRemoteVideoStreams

Stops or resumes subscribing to the video streams of all remote users

- (int)muteAllRemoteVideoStreams:(BOOL)mute;

Parameter

Returns

• 0 : Success
• Not 0：Failure

stopPlayingLocalVideo

Stop playing the local video and release the local video view

- (int)stopPlayingLocalVideo;

Returns

• 0 : Success
• Not 0：Failure

stopPlayingRemoteVideo

Stop playing remote video and release view

- (int)stopPlayingRemoteVideo:(NSString * _Nonnull)streamId;

Parameter

Returns

• 0 : Success
• Not 0：Failure

setLocalVideoHD

Set local video HD acquisition

- (int)setLocalVideoHD;

Returns

• 0 : Success
• Not 0：Failure

Details

This method enables local video HD acquisition, but does not affect the video size sent to the far end。The sent video will be cropped and stretched, which is controlled bysetVideoEncoderConfiguration

setVideoRotation

Set local video rotation mode

- (int)setVideoRotation:(CloudHubVideoRotation)rotation;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

This method sets the local video rotation mode. By default, no matter the device is at any angle, your video seen from the far end is always head up: when the mobile phone is held vertically, the video sent is also vertical; When the mobile phone is placed horizontally, the video sent out is also horizontal, but you can set this value to fix the video rotation angle to a certain direction to be consistent with your interface. At this time, your video looks positive at the far end only when the mobile phone direction is consistent with the direction you set

Video pre-process and post-process

setBeautyEffectOptions:options:

- (int)setBeautyEffectOptions:(BOOL)enabled options:(CloudHubBeautyOptions *_Nullable)options;

Set beauty parameter

Parameter

Returns

• 0 : Success
• Not 0：Failure

setVideoEffectEnable:options:device:

- (int)setVideoEffectEnable:(BOOL)enabled
                    options:(CloudHubVideoEffectOptions *_Nullable)options
                     device:(NSString *_Nullable)deviceID;

Set beauty parameter

Parameter

Returns

• 0 : Success
• Not 0：Failure

Multi-channel management

createChannel:

Create sub channel

-(CloudHubRtcChannelKit * _Nullable) createChannel:(NSString * _Nonnull)channelId;

Parameter

Returns

• Sub channel

destroyChannel:

Destroy sub-channel

-(int) destroyChannel:(CloudHubRtcChannelKit * _Nonnull)channel;

Parameter

Returns

• 0: Success
• Not 0: Failure

Media file playback

startPlayingMovie:cycle:

Start playing media files

- (int) startPlayingMovie:(NSString * _Nonnull)filepath
                    cycle:(BOOL)cycle;

Parameter

Returns

• 0 : Success
• Not 0：Failure

startPlayingMovie:cycle:view:paused:

Start playing media files

- (int) startPlayingMovie:(NSString * _Nonnull)filepath
                    cycle:(BOOL)cycle
                     view:(VIEW_CLASS * _Nullable)view
                   paused:(BOOL)paused;

Parameter

Returns

• 0 : Success
• Not 0：Failure

stopPlayingMovie:

Stop playing media files

- (int) stopPlayingMovie:(NSString * _Nonnull)filepath;

Parameter

Returns

• 0 : Success
• Not 0：Failure

pausePlayingMovie:

Pause playing media files

- (int) pausePlayingMovie:(NSString * _Nonnull)filepath;

Parameter

Returns

• 0 : Success
• Not 0：Failure

resumePlayingMovie:

Resume playing media files

- (int) resumePlayingMovie:(NSString * _Nonnull)filepath;

Parameter

Returns

• 0 : Success
• Not 0：Failure

getMovieInfo:

Get media file data

- (CloudHubLocalMovieInfo * _Nullable) getMovieInfo:(NSString * _Nonnull)filepath;

Parameter

Returns

• See CloudHubLocalMovieInfo

getMovieCurrentPosition:

Get the progress of media files

- (NSUInteger) getMovieCurrentPosition:(NSString * _Nonnull)filepath;

Parameter

Returns

• Playback progress（ms）

setMoviePosition:withFile:

Set progress for media files in play

- (int) setMoviePosition:(NSUInteger)pos 
                withFile:(NSString * _Nonnull)filepath;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Play Effect

getEffectsVolume

Retrieves the volume of the audio effects.

- (int) getEffectsVolume;

Returns

• Volume of the audio effects, if this method call succeeds.
• <0：Failure.

setEffectsVolume:

Sets the volume of the audio effects.

- (int) setEffectsVolume:(int)volume;

Parameter

Returns

• 0 : Success
• Not 0：Failure

setVolumeOfEffect:volume:

Sets the volume of a specified audio effect.

- (int) setVolumeOfEffect:(int)soundId 
                   volume:(int)volume;

Parameter

Returns

• 0 : Success
• Not 0：Failure

playEffect:filePath:loopCount:gain:publish:startTimeMS:endTimeMS:

This method plays the specified local or online audio effect file.

- (int) playEffect:(int)soundId  
          filePath:(NSString * _Nonnull)filepath  
         loopCount:(int)loopCount  
             pitch:(double)pitch
               pan:(double)pan
              gain:(int)gain  
           publish:(BOOL)publish  
       startTimeMS:(NSUInteger)starttime  
         endTimeMS:(NSUInteger)endtime;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

This method can play the specified local or online effects to increase the effects, such as the effects of specific operations in the game

You can set the number and gain of the play in the method, and whether the remote user can hear the effect. To play multiple audio effect files at the same time, call this method multiple times with different soundID and filePath. For the best user experience, Cloudhub recommends playing no more than three audio effect files at the same time. After the playback of an audio effect file completes, the SDK triggers the rtcEngine:onAudioEffectFinish: callback

stopEffect:

Stops playing a specified audio effect.

- (int) stopEffect:(int)soundId;

Parameter

Returns

• 0 : Success
• Not 0：Failure

stopAllEffects

Stops playing all audio effects.

- (int) stopAllEffects;

Returns

• 0 : Success
• Not 0：Failure

preloadEffect:filePath:

Preloads a specified audio effect file into the memory.

- (int) preloadEffect:(int)soundId 
             filePath:(NSString * _Nonnull)filepath;

Parameter

Returns

• 0 : Success
• Not 0：Failure

unloadEffect:

Releases a specified preloaded audio effect from the memory.

- (int) unloadEffect:(int)soundId;

Parameter

Returns

• 0 : Success
• Not 0：Failure

pauseEffect:

Pauses a specified audio effect.

- (int) pauseEffect:(int)soundId;

Parameter

Returns

• 0 : Success
• Not 0：Failure

pauseAllEffects

Pauses all audio effects.

- (int) pauseAllEffects;

Returns

• 0 : Success
• Not 0：Failure

resumeEffect:

Resumes playing a specified audio effect.

- (int) resumeEffect:(int)soundId;

Parameter

Returns

• 0 : Success
• Not 0：Failure

resumeAllEffects

Resumes playing all audio effects.

- (int) resumeAllEffects;

Returns

• 0 : Success
• Not 0：Failure

translateWavFileToText:

Recognize text from sound files

- (int)translateWavFileToText:(NSString* _Nonnull)wavFile;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

After the call is successful ,the user will receive rtcEngine:onVoiceTranslateTextReady:text: callback

Voice changer and reverberation

If you want to use the functions related to vocal effect, please contact us first to open it for you

setAudioQuality

Set local send audio quality

- (int)setAudioQuality:(CloudHubAudioQuality)quality;

Parameter

Returns

• 0 : Success
• Not 0：Failure

setLocalVoicePitch:

Changes the voice pitch of the local speaker.

- (int)setLocalVoicePitch:(double)pitch

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

This method changes the pitch of the local speaker’s voice. This method needs to be called after enableLocalAudio. Note that calling the enableLocalAudio interface and passing in no will reset the pitch to the default state (i.e. there is no need to modify the tone)

setLocalVoiceEqualizationOfBandFrequency:withGain:

Sets the local voice equalization effect.

- (int)setLocalVoiceEqualizationOfBandFrequency:(CloudHubAudioEqualizationBandFrequency)bandFrequency 
                                       withGain:(NSInteger)gain

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

This method changes the pitch of the local speaker’s voice. This method needs to be called after enableLocalAudio. Note that calling the enableLocalAudionterface and passing in NO will reset the sound equalization to the initial state

setLocalVoiceReverbOfType:withValue:

Sets the local voice reverberation

- (int)setLocalVoiceReverbOfType:(CloudHubAudioReverbType)reverbType
                       withValue:(double)value

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

This method changes the pitch of the local speaker’s voice. This method needs to be called after enableLocalAudio. Note that calling the enableLocalAudionterface and passing in NO will reset the sound equalization to the initial state

setAudioEffectPreset:

Sets an SDK preset audio effect

- (int)setAudioEffectPreset:(CloudHubAudioEffectPreset)preset

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

This method changes the pitch of the local speaker’s voice. This method needs to be called after enableLocalAudio. Note that calling the enableLocalAudionterface and passing in NO will reset the sound equalization to the initial state. This method cannot be mixed with setLocalVoicePitch: 、 setLocalVoiceEqualizationOfBandFrequency:withGain: 、 setLocalVoiceReverbOfType:withValue:

enableDeepLearningDenoise:

Turn on/off AI noise reduction mode

- (int)enableDeepLearningDenoise:(BOOL)enabled

Parameter

Returns

• 0 : Success
• Not 0：Failure

Sound localization

enableSoundPositionIndication:

Enables/Disables stereo panning for remote users.

- (int)enableSoundPositionIndication:(BOOL)enabled

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

Ensure that you call this method to enable stereo panning for remote users before enableAudio so that the local user can track the position of a remote user by calling setRemoteVoicePosition:pan:gain:

setRemoteVoicePosition:pan:gain:

Sets the sound position and gain of a remote user.

- (int)setRemoteVoicePosition:(NSString * _Nonnull)uid
                          pan:(double)pan
                         gain:(double)gain

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

This method sets the sound position and gain of a remote user.

When the local user calls this method to set the sound position of a remote user, the sound difference between the left and right channels allows the local user to track the real-time position of the remote user, creating a sense of space. This method applies to massive multiplayer online games, such as Battle Royale games.

Note

• This method needs to be called after joining the channel. Using this method, we need to call enableSoundPositionIndication: to turn on the voice stereo of the remote users before enableAudio.
• For the best hearing experience, we recommend:
  • Wear headphones when using this method on iOS
  • When using this method in macOS, stereo external amplifier is used

Media stream relay across channels

startChannelMediaRelay:

Starts relaying media streams across channels. This method can be used to implement scenarios such as co-host across channels.

- (int) startChannelMediaRelay: (CloudHubChannelMediaRelayConfig* _Nonnull) config;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

After a successful method call, the SDK triggers the rtcEngine:onChannel:MediaRelayStateChanged:error: callbacks, and these callbacks return the state and events of the media stream relay.

• If the rtcEngine:onChannel:MediaRelayStateChanged:error: callback returns CloudHub_RELAY_STATE_RUNNING and CloudHub_RELAY_OK， it means that the SDK starts relaying media streams between the source channel and the destination channel.
• If the rtcEngine:onChannel:MediaRelayStateChanged:error: callback returns CloudHub_RELAY_STATE_FAILURE， an exception occurs during the media stream relay.

Note

• This method takes effect only when you are a host in a live streaming channel.
• Cross channel media streaming forwarding function requires connection technology
• Call this method after joining the channel.
• After a successful method call, if you want to call this method again, ensure that you call the stopChannelMediaRelay method to quit the current relay.

updateChannelMediaRelay:

Updates the channels for media stream relay.

- (int) updateChannelMediaRelay: (CloudHubChannelMediaRelayConfig* _Nonnull) config;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

After the media relay starts, if you want to relay the media stream to more channels, or leave the current relay channel, you can call the updateChannelMediaRelay method.

Note

• Call this method after the startChannelMediaRelay: method to update the destination channel.
• The maximum number of channels is 4.

stopChannelMediaRelay

Stops the media stream relay. Once the relay stops, the host quits all the destination channels.

- (int) stopChannelMediaRelay;

Returns

• 0 : Success
• Not 0：Failure

Details

After a successful method call, the SDK triggers the rtcEngine:onChannel:MediaRelayStateChanged:error: callback. If the callback reports CloudHub_RELAY_STATE_IDLE and CloudHub_RELAY_OK, the host successfully stops the relay.

Note

• If the method call fails, the SDK triggers the rtcEngine:onChannel:MediaRelayStateChanged:error: callback with the CloudHub_RELAY_ERROR_SERVER_NO_RESPONSE or CloudHub_RELAY_ERROR_SERVER_CONNECTION_LOST status code

• You can call the leaveChannel: method to leave the channel, and the media stream relay automatically stops.

Volume indication

enableAudioVolumeIndication:smooth:reportVAD:

Enables the reporting of users' volume indication

- (int)enableAudioVolumeIndication:(NSInteger)interval 
                            smooth:(NSInteger)smooth 
                         reportVAD:(BOOL)reportVad;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Switch speakers or earpieces

setEnableSpeakerphone:

Set whether to use speakers

- (int)setEnableSpeakerphone:(BOOL)enableSpeaker;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

This method sets whether to route voice to the speaker (external), which can be called before joinChannelByToken:channelId:properties:uid:autosubscribeAudio:autoSubscribeVideo:joinSuccess:

isSpeakerphoneEnabled

Are speakers currently in use

- (BOOL)isSpeakerphoneEnabled;

Returns

• 0 : Success
• Not 0：Failure

Details

When connecting to a wired or Bluetooth headset, the sound will be automatically switched to the headset. At this time, the returns value of isSpeakerphoneEnabled is still the setting before connecting to the headset. When the headset is disconnected, the sound will also return to the playback path set before connecting to the headset

In-ear monitoring

enableInEarMonitoring:

Enables in-ear monitoring.

- (int)enableInEarMonitoring:(BOOL)enabled

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

You can call this method either before or after joining a channel.

Note

• This method is only applicable to iOS platforms
• Users must use wired earphones to hear their own voices.

setInEarMonitoringVolume:

Sets the volume of the in-ear monitor.

- (int)setInEarMonitoringVolume:(NSInteger)volume

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

You can call this method either before or after joining a channel.

Note

• This method is only applicable to iOS platforms
• Users must use wired earphones to hear their own voices.

Pre-call network test

startEchoTest:

Starts an audio call test.

- (int)startEchoTest: (int)intervalInSeconds;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Note

• enableVideo and enableAudio needs to be called in advance

stopEchoTest

Stops the audio call test.

- (int)stopEchoTest;

Returns

• 0 : Success
• Not 0：Failure

startLastmileProbeTest:

Starts the last mile network probe test.

- (int)startLastmileProbeTest:(CloudHubLastmileProbeConfig* _Nonnull)config;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

This method starts the last-mile network probe test before joining a channel to get the uplink and downlink last mile network statistics, including the bandwidth, packet loss, jitter, and round-trip time (RTT).

Once this method is enabled, the SDK returns the following callbacks:

• lastmileQuality，The SDK triggers this callback within two seconds depending on the network conditions. This callback rates the network conditions and is more closely linked to the user experience.
• lastmile，The SDK triggers this callback within 30 seconds depending on the network conditions. This callback returns the real-time statistics of the network conditions and is more objective.

Note

• enableVideo and enableAudio needs to be called in advance

stopLastmileProbeTest

Stops the last mile network probe test.

- (int)stopLastmileProbeTest;

Returns

• 0 : Success
• Not 0：Failure

Audio self-capture（only push）

setExternalAudioSourceSampleRate:channels:

-(int) setExternalAudioSourceSampleRate:(int)sampleRate
                                channels:(int)channels;

Set the format of the collected data.

Details This method needs to be called before joining the channel.

Parameter

Returns

• 0: Success
• Not 0: Failure

pushAudioFrame:

- (int) pushAudioFrame:(NSData * _Nonnull)buffer;

Push external audio frame

Parameter

Returns

• 0 : Success
• Not 0：Failure

Audio self-rendering（only pull））

setExternalAudioSinkSampleRate:channels:

-(int) setExternalAudioSinkSampleRate:(int)sampleRate
                              channels:(int)channels;

Set the format of the rendering data.

Details This method needs to be called before joining the channel.

Parameter

Returns

• 0: Success
• Not 0: Failure

pullAudioFrame:

pullAudioFrame:

-(int) pullAudioFrame:(NSData * _Nonnull)buffer;

Pull playback (after mixing) data (pulling 10ms data at a time) (the user needs to continue to call at 10ms intervals).

After calling this method, the App will take an active pull method to obtain the remote-end decoded and mixed audio data for audio playback.

Parameter

Returns

• 0: Success
• Not 0: Failure

Raw audio data

setRecordingAudioFrameSampleRate:channels:samples:

-(int) setRecordingAudioFrameSampleRate:(int)sampleRate
                                 channels:(int)channel
                                  samples:(int)samplesPerCall;

This method sets the collected audio format of the rtcEngine:onRecordAudioFrame:sampleRate:channels: callback.

Details This method needs to be called before joining the channel.

Parameter

Returns

• 0: Success
• Not 0: Failure

setPlaybackAudioFrameSampleRate:channels:samples:

-(int) setPlaybackAudioFrameSampleRate:(int)sampleRate
                                channels:(int)channel
                                 samples:(int)samplesPerCall;

This method sets the collected audio format of the rtcEngine:onPlaybackAudioFrame:sampleRate:channels: callback.

Details This method needs to be called before joining the channel.

Parameter

Returns

• 0: Success
• Not 0: Failure

Audio recorder

startRecordingVoiceClip:duration:fileType:

Start recording sound clip

- (int)startRecordingVoiceClip:(NSString* _Nonnull) clipBaseName
                      duration:(NSInteger)clipDurationSeconds
                      fileType:(CloudHubMediaFileType) type;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

After the call is successful, the user will receive rtcEngine:voiceClipFileReady:clip:ts: callback

stopRecordingVoiceClip:

Stop recording sound clip

- (int)stopRecordingVoiceClip:(NSString* _Nonnull) clipBaseName;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Switch cameras

switchCamera:

Switches between front and rear cameras.

- (int)switchCamera:(BOOL)front;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

This method needs to be called after the camera is started joinChannelByToken:channelId:properties:uid:autosubscribeAudio:autoSubscribeVideo:joinSuccess:

setCameraFlipMode

Set the flip mode of the camera

- (int)setCameraFlipMode:(BOOL)horizontalFlip  Vertivcal:(BOOL)verticalFlip

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

This method flips the data collected by the camera horizontally and vertically. For the same camera, after the camera is turned off, the engine will still remember the flip settings of the camera. The previous settings will be loaded automatically after the camera is turned on next time, unless the user turns off the video indexing through enableVideo: NO

correctCameraKeystoning

Correcting trapezoidal distortion of camera

- (int)correctCameraKeystoning:(float)fromX FromY:(float)fromY ToX:(float)toX ToY:(float)toY

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

This method corrects the trapezoidal distortion of the camera through the mode of incremental interaction. The vector AB composed of the starting point a (fromx, fromy) and the ending point B (tox, toy) represents the displacement of this correction, which is equivalent to the user dragging the mouse from a to B. the engine will automatically judge which corner of the picture is the corner of this correction according to the position of the starting point A

The coordinates of the upper left corner and the lower right corner of the view are (0.0, 0.0) and (1.0, 1.0). The view is divided into four equal 1 / 4 areas, namely upper left area, upper right area, lower right area and lower left area. Point a and point B must be located in an equal division of the view, and cross region correction is invalid.

resetCameraKeystoning

Cancel correcting the trapezoidal distortion of the camera

- (int)resetCameraKeystoning

Returns

• 0 : Success
• Not 0：Failure

Details

This method disables the trapezoidal correction function of the camera and restores the default behavio

Data stream

sendStreamMessage:

- (int) sendStreamMessage:(NSData * _Nonnull)message;

Sends data stream messages.

Sends data stream messages to all users in a channel. The SDK has the following restrictions on this method.Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 KB. Each client can send up to 6 KB of data per second.Each user can have up to five data streams simultaneously.

After successfully calling this method, the remote end will trigger the rtcEngine:onStreamMessagWithUid:data: callback, and the remote user can get the received stream message in this callback.

Parameter

Returns

• 0：Success
• < 0：Failure

Publisher management

setPublishStreamInfo:

Set user data when publishing local audio and video (Json string format)

- (int)setPublishStreamInfo:(NSString * _Nonnull)info;

Returns

• 0 : Success
• Not 0：Failure

Details

This method must be executed after [rtcengine: didjoinchannelwithuid: elapsed:] callback succeeds If the remote successfully subscribes to this video stream, When the callback rtcEngine:remoteVideoStateChangedOfUid:streamId:type:state:reason:streamInfo: is received, the remote end will be notified through the streaminfo parameter

publishStream

Start publishing local audio and video

- (int)publishStream;

Returns

• 0 : Success
• Not 0：Failure

Details

Publish your own audio and video to the channel for others to watch and listen to. After publishing successfully, the local will receive rtcEngine:localVideoStateChangeWithState:error: callback

• If the remote end turns off automatic subscription, it will receive rtcEngine:onUserPublished:type:stream: callback，At this time, if the other party decides to watch this person, it needs to call subscribe， Received after success rtcEngine:remoteVideoStateChangedOfUid:streamId:type:state:reason:streamInfo: callback
• If the remote end does not turn off automatic subscription, it will receive it directly rtcEngine:remoteVideoStateChangedOfUid:streamId:type:state:reason:streamInfo: callback

Note

• This method can only be called after joining the channel successfully

unPublishStream

Stop publishing local audio and video

- (int)unPublishStream;

Returns

• 0 : Success
• Not 0：Failure

Details

Stop publishing local audio and video. When publishing is stopped, the local will receive rtcEngine:localVideoStateChangeWithState:error: callback. If the remote end turns off automatic subscription, it will receive rtcEngine:onUserUnPublished:type:stream: callback. Whether the remote end turns off automatic subscription or not, it will receive rtcEngine:remoteVideoStateChangedOfUid:streamId:type:state:reason:streamInfo: callback

Note

• This method can only be called after joining the channel successfully

Manual subscription management

subscribe

Start subscribing to audio and video

- (int)subscribe:(NSString * _Nonnull)streamId;

Parameter

• 0 : Success
• Not 0：Failure

Details

Please call it after receiving the rtcEngine:onUserPublished:type:stream:

unSubscribe

Unsubscribe from audio and video

- (int)unSubscribe:(NSString * _Nonnull)streamId;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

• After receiving the rtcEngine:onUserPublished:type:stream: callback,You can repeatedly adjust the subscribe / unSubscribe to create / remove subscriptions to this video stream
• After receiving the rtcEngine:onUserUnPublished:type:stream: callback, you do not need to call unSubscribe

Server recording

• When the channel starts to stop / suspend / suspend / resume the server connection, all the channels in the channel will receive thertcEngine:onServerRecordStateChange:startTS:currTS:pauseDuration:recordDuration: callback when the server status changes.
• When the channel is currently in the two states of the recording / recording pause, the new channel channel will also receive the rtcEngine:onServerRecordStateChange:startTS:currTS:pauseDuration:recordDuration: callback

startServerRecord

Start server recording

- (int) startServerRecord;

Returns

• 0 : Success
• Not 0：Failure

stopServerRecord

Stop server recording

- (int) stopServerRecord;

Returns

• 0 : Success
• Not 0：Failure

pauseServerRecord

Pause server recording

- (int) pauseServerRecord;

Returns

• 0 : Success
• Not 0：Failure

resumeServerRecord

Resume server recording

- (int) resumeServerRecord;

Returns

• 0 : Success
• Not 0：Failure

Advanced signaling method

setPropertyOfUid:tell:properties:

Set custom properties for a user in the channel

- (int)setPropertyOfUid:(NSString * _Nonnull)uid 
                   tell:(NSString * _Nullable)whom 
             properties:(NSString * _Nonnull)prop;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

There are two ways to set custom properties:

• When users join the channel, specify properties in joinChannelByToken:channelId:properties:uid:autosubscribeAudio:autoSubscribeVideo:joinSuccess:
• After the user enters the channel, call setPropertyOfUid:tell:properties:, The user will receive rtcEngine:onSetPropertyOfUid:from:properties: callback
• When successful, users notified and users will be notified. In addition, users of the new access channel will get these attributes in the callback of the rtcEngine:didJoinedOfUid:properties:isHistory:fromChannel: callback.

Note

• If multiple attributes of the same user are specified many times, these attributes will be recorded and sent back to the user after the new access channel through the rtcEngine:didJoinedOfUid:properties:isHistory:fromChannel: callback.
• If the same attributes of the same user are specified many times, the later set of properties will override the previous attributes. For example, repeat the setting for user A twice, and pass in{"test": true"} and {"test": false} respectively, Then user B newly entering the channel will get the attribute {"test": false} of user A when receiving the rtcEngine:didJoinedOfUid:properties:isHistory:fromChannel: callback about user A

sendChatMsg:to:withExtraData:

Send chat message

- (int)sendChatMsg:(NSString * _Nonnull)message 
                to:(NSString * _Nullable)whom 
     withExtraData:(NSString * _Nullable)extraData;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

You can usually use extraData to convey some fonts, heads and other information channels, and users will receive rtcEngine:onChatMessageArrival:from:withExtraData: callbacks.

pubMsg:msgId:to:withData:associatedWithUser:associatedWithMsg:save:extraData:

Post a custom message

- (int)     pubMsg:(NSString * _Nonnull)msgName
             msgId:(NSString * _Nonnull)msgId
                to:(NSString * _Nullable)whom
          withData:(NSString * _Nullable)data
associatedWithUser:(NSString * _Nullable)uid
 associatedWithMsg:(NSString * _Nullable)assMsgID
              save:(BOOL)save
         extraData:(NSString * _Nullable)extra;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Details

The pubMsg mechanism is similar to a message board, which is used to save and synchronize the business status in the channel. Whether it is a user already in the channel or a new user who joins later, you can use rtcEngine:onPubMsg:msgId:from:withData:associatedWithUser:associatedWithMsg:ts:withExtraData:isHistory: Call back to receive custom messages that have been published in the current channel

delMsg:msgId:to:

Delete a custom message

-(int)delMsg:(NSString * _Nonnull)msgName
        msgId:(NSString * _Nonnull)msgId
           to:(NSString * _Nullable)whom;

with

-(int)delMsg:(NSString * _Nonnull)msgName
        msgId:(NSString * _Nonnull)msgId
           to:(NSString * _Nullable)whom
     withData:(NSString * _Nullable)data;

Parameter

Returns

• 0: Success
• Not 0: Failure

Details

After the call is successful, users already in the channel will receive the message rtcEngine:onDelMsg:msgId:from:withData:

Note

• Deleting a non-existent message will fail

evictUser:reason:

Kick a user out of the channel

-(int)evictUser:(NSString * _Nonnull)uid
           reason:(NSInteger)reason;

Parameter

Returns

• 0: Success
• Not 0: Failure

Details

After the call is successful, the kicked user will receive the rtcEngine:onLocalUserEvicted: callback, and other users will receive the rtcEngine:didOfflineOfUid:reason: callback

CDN publisher

addPublishStreamUrl:

Publishes the local stream to a specified CDN live streaming URL.

- (int) addPublishStreamUrl:(NSString* _Nonnull)url;

Parameter

Returns

• 0 : Success
• Not 0：Failure

removePublishStreamUrl:

Removes an RTMP or RTMPS stream from the CDN.

- (int) removePublishStreamUrl:(NSString* _Nonnull)url;

Parameter

Returns

• 0 : Success
• Not 0：Failure

setLiveTranscoding:

Sets the transcoding configurations for CDN live streaming.

- (int) setLiveTranscoding:(CloudHubLiveTranscoding* _Nonnull)transcoding;

Parameter

Returns

• 0 : Success
• Not 0：Failure

Other methods

getCallId

Get channel number

-(NSString * _Nullable)getCallId;

Returns

• Current channel number

getSdkVersion

Get the SDK version number

+ (NSString * _Nonnull)getSdkVersion;

Returns

• Current version number

setLogFilter:

Set the log output level

-(int)setLogFilter:(NSUInteger)filter;

Parameter

Returns

• 0: Success
• Not 0: Failure

getNativeHandle

Get Native SDK Engine Handle

-(void *_Nullable)getNativeHandle;

Details

This method obtains the C++ handle of native SDK engine, which is used for special scenes including registering audio and video frame observers