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

CloudHubSDK iOS

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

CloudHubRtcChannelKit

Set delegate

delegate:

Set delegate for CloudHubRtcChannelKit

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

Discussion

See CloudHubRtcChannelDelegate

Channel management

setClientRole

Sets the role of the user in interactive live streaming.

- (int)setClientRole:(CloudHubClientRole)role;

Parameters

Return Value

• 0: Success.
• Not 0：Failure.

Discussion

Before joining the channel, users need to set audience (default) or anchor role through this method. After joining the channel, users can switch user role through this method If you call this method to switch the user role after joining a channel,

• TriggersrtcChannel:onClientRoleChangedFrom:to: on the local client;
• Triggers rtcChannel:didJoinedOfUid:properties:isHistory:fromChannel: or rtcChannel:didOfflineOfUid:reason: on the remote client.

Note

• This method only applies to live broadcast scenarios.
• When calling publishStream ，the user role is automatically switched to the anchor.

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

Joins the channel with a user ID.

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Discussion

In this method, users can join the calling channel. Users in the same channel can talk with each other, and multiple users can join the same channel and chat in groups. Apps with different App ids cannot communicate with each other,If the call is already on, the user must call leaveChannel: to exit the current call before going to the next channel

• After joining the channel,triggers rtcChannel:didJoinChannelwithUid:elapsed: on the local client;
• After users in communication scenarios and anchors in live broadcast scenarios join the channel,triggersrtcChannel:didJoinedOfUid:properties:isHistory:fromChannel: on the remote client.
• The client may lose connection to the server if the network condition is not ideal;The SDK will automatically try to reconnect and send rtcChannel:connectionChangedToState: ，After the reconnection is successful，will triggers rtcChannel:didReJoinChannelwithUid:elapsed: on the local client

Note

• The UID of each user in the channel cannot be repeated,If repeated, a subsequent user with the same UID enters the channel, triggering the previous user to automatically leave the channel，The previous user will receive rtcChannel:onLocalUserEvicted:

joinChannelByToken:properties:uid:autosubscribeAudio:autoSubscribeVideo:publishLocalAudio:publishLocalVideo:joinSuccess:

Joins the channel with a user ID.

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Discussion

In this method, users can join the calling channel. Users in the same channel can talk with each other, and multiple users can join the same channel and chat in groups. Apps with different App ids cannot communicate with each other,If the call is already on, the user must call leaveChannel: to exit the current call before going to the next channel

• After joining the channel,triggers rtcChannel:didJoinChannelwithUid:elapsed: on the local client;
• After users in communication scenarios and anchors in live broadcast scenarios join the channel,triggersrtcChannel:didJoinedOfUid:properties:isHistory:fromChannel: on the remote client.
• The client may lose connection to the server if the network condition is not ideal;The SDK will automatically try to reconnect and send rtcChannel:connectionChangedToState: ，After the reconnection is successful，will triggers rtcChannel:didReJoinChannelwithUid:elapsed: on the local client

Automatic publishing is enabled when automatic publishing audio (publishLocalAudio is true) or automatic publishing video ( publishLocalVideo is true) is set.

When automatic publishing comes on, If the audio stream or video stream is not automatically published (publishLocalAudio is false or publishLocalVideo is false ), its state of muted (equivalent to invoke muteLocalAudioStream/muteLocalVideoStream and passing parameters for true).

When automatic release function use, you can use the muteLocalAudioStream/muteLocalVideoStream method to reset is released within the channel local audio stream.

In single-current mode:

When automatic publish is enabled, the SDK will no longer publish the corresponding method until the unPublish method is called.

In multi-stream mode:

Only one camera will be published (devices whose index is 0 in the device enumeration result)

Note

• The UID of each user in the channel cannot be repeated,If repeated, a subsequent user with the same UID enters the channel, triggering the previous user to automatically leave the channel，The previous user will receive rtcChannel:onLocalUserEvicted:

leaveChannel:

Leaves the current channel.

- (int)leaveChannel:(void(^ _Nullable)(NSString * _Nonnull channelID))leaveChannelBlock;

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Discussion

To leave a channel, which means to hang up or quit a call,When calling joinChannelByToken:properties:uid:autosubscribeAudio:autoSubscribeVideo:joinSuccess: method, you must call leaveChannel: to end the call. Otherwise, the next call cannot start. This method can be called regardless of whether a call is currently in progress or not, and has no side effects. This method frees all resources associated with the session. This method is asynchronous and does not actually exit the channel when the call returns

• After successfully calling this method to leave the channel,Local triggersrtcChannel:didLeaveChannel: callback
• Communication scenarios of users and live under the scenario of the host left channel, distal triggersrtcChannel:didOfflineOfUid:reason: callback

renewToken:

Renews the token when the current token expires.

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

Parameters

Return Value

• 0: Success.
• Not 0：Failure.

Discussion

In the following situations, the SDK decides that the current token has expired:

• rtcChannel:tokenPrivilegeWillExpire:
• rtcChannelRequestToken:

You should get a new token from your server and call this method to renew it. Failure to do so results in the SDK disconnecting from the Cloudhub server.

getConnectionState

Gets the connection state of the SDK.

- (CloudHubConnectionStateType)getConnectionState;

Return Value

• 见 CloudHubConnectionStateType

Release management

setPublishStreamInfo:

User-defined data when publishing local audio and video (Json string format)

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

Return Value

• 0: Success
• Not 0：Failure.

Discussion

This method must be in the [rtcChannel:didJoinChannelwithUid:elapsed: callback after a successful publishStream before the call. The successful if the remote subscription streaming video, will receive in rtcChannel:remoteVideoStateChangedOfUid:streamId:type:state:reason: callback, and distal via the streamInfo parameters.

publishStream

Start publish local audio and video

- (int)publishStream;

Return Value

• 0: Success
• Not 0：Failure.

Discussion

Post your audio and video to a channel for others to watch and listen to

• Distal if shut down automatically subscribe to, can get rtcChannel:onUserPublished:type:stream: callback, at this time the other party if you decide to watch the man, you need to call subscribe , After a successful received rtcChannel:remoteVideoStateChangedOfUid:streamId:type:state:reason: callback
• Distal if not closed automatically subscribe to, can directly receive rtcChannel:remoteVideoStateChangedOfUid:streamId:type:state:reason: callback.

Note

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

unPublishStream

Stop publish local audio and video

- (int)unPublishStream;

Return Value

• 0: Success
• Not 0：Failure.

Discussion

Stop their audio and video, when to stop after the release, the distal if shut down automatically subscribe, will receive rtcChannel:onUserUnPublished:type:stream: callback, in addition whether remote shut down automatically subscribe, Will receive rtcChannel:remoteVideoStateChangedOfUid:streamId:type:state:reason: callback

Note

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

Manual Subscription Management

subscribe

Start subscribing to audio and video

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Discussion

Please in receive rtcChannel:onUserPublished:type:stream: the callback after the call

unSubscribe

Unsubscribe all the way audio and video

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Discussion

• After receiving rtcChannel:onUserPublished:type:stream: after the callback can be called repeatedly subscribe / unSubscribe method to establish/removing of audio and video stream to subscribe to the road
• After receiving the rtcChannel:onUserUnPublished:type:stream: , no manual call unSubscribe method

Audio management

muteRemoteAudioStream:mute:

Receives or stops receiving the specified audio stream

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Note

• If you have called muteAllRemoteAudioStreams:YES to mute all remote audio before calling this API, please ensure that you have called muteAllRemoteAudioStreams:NO
• muteAllRemoteAudioStreams: is global control and muteRemoteAudioStream:mute: is fine control

muteAllRemoteAudioStreams

Receive or stop receiving the specified audio stream

- (int)muteAllRemoteAudioStreams:(BOOL)mute;

Parameters

Return Value

• 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

Video management

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;

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Discussion

After initializing the video view of a remote user, you can call this method to update its rendering and mirror modes. This method affects only the video view that the local user sees.

Note

• 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.

muteRemoteVideoStreamWithUid:mute:

Stops or resumes receiving to the video stream of a specified user.

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Discussion

Called after joining a channel

Note

• After a successful call this method, the local triggers rtcChannel:remoteVideoStateChangedOfUid:streamId:type:state:reason: ,reason to CloudHubVideoRemoteStateReasonLocalMuted

muteRemoteVideoByStreamId:mute:

Unsubscribe or resume receiving to the specified remote video stream

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Discussion

Called after joining a channel

muteAllRemoteVideoStreams

Stops or resumes receiving to the video streams of all remote users.

- (int)muteAllRemoteVideoStreams:(BOOL)mute;

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Music File Playing

startPlayingMovie:cycle:

Start playing a music file

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

startPlayingMovie:cycle:view:paused:

Start playing a music file

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

stopPlayingMovie:

Stop playing a music file

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

pausePlayingMovie:

Pause playing a music file

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

resumePlayingMovie:

Continue playing a music file

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

getMovieInfo:

Get music file playback data

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

Parameters

Return Value

• See CloudHubLocalMovieInfo

getMovieCurrentPosition:

Get the playback progress of a music file

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

Parameters

Return Value

• Playback progress (in milliseconds)

setMoviePosition:withFile:

Sets the progress for the playing music file

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Sound file playback

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

Start playing a sound 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;

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Discussion

This method can play specified local or online sound files to add sound effects to the application, such as the sound effects of specific actions in the game

In this method you can set the frequency and gain of playback of the sound file and whether the remote user can hear the sound. You can call this method many times and play multiple sound files simultaneously by passing in soundID and filePath of different sound files to achieve the best user experience. We recommend that no more than 3 sound files be played simultaneously

This method is invoked after the broadcast sound, will trigger rtcChannel:onAudioEffectFinish: callback

stopEffect:

Stops playing a sound file

- (int) stopEffect:(int)soundId;

Parameters

Return Value

• 0: Success
• Not 0：Failure.

stopAllEffects

Stops playing a sound file

- (int) stopAllEffects;

Return Value

• 0: Success
• Not 0：Failure.

preloadEffect:filePath:

Preloads the specified sound file into memory

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

unloadEffect:

Releases a preloaded sound file from memory

- (int) unloadEffect:(int)soundId;

Parameters

Return Value

• 0: Success
• Not 0：Failure.

pauseEffect:

Pause playing a sound file

- (int) pauseEffect:(int)soundId;

Parameters

Return Value

• 0: Success
• Not 0：Failure.

pauseAllEffects

Pause all sound files

- (int) pauseAllEffects;

Return Value

• 0: Success
• Not 0：Failure.

resumeEffect:

Continue playing a sound file

- (int) resumeEffect:(int)soundId;

Parameters

Return Value

• 0: Success
• Not 0：Failure.

resumeAllEffects

Pause playing a sound file

- (int) resumeAllEffects;

Return Value

• 0: Success
• Not 0：Failure.

getEffectsVolume

Gets the sound file playback volume

- (int) getEffectsVolume;

Return Value

• The method returns the volume effect to the volume value in the range of [0, 100] if the method is successful.
• <0：Failure.

setEffectsVolume:

Setting the Volume of Sound Effect File Playback

- (int) setEffectsVolume:(int)volume;

Parameters

Return Value

• 0: Success
• Not 0：Failure.

setVolumeOfEffect:volume:

Real-time adjustment of sound effect file playback volume in the range of [0, 100]

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

CDN Push Streaming

addPublishStreamUrl:

Adding a push stream address

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

removePublishStreamUrl:

Delete push stream address

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

setLiveTranscoding:

Set transcoding parameters

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Cross-channel media circulation

startChannelMediaRelay:

Start cross-channel media circulation

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Discussion

After successfully calling the method, the SDK will trigger the rtcChannel:MediaRelayStateChanged:error: callback and report the current cross channel media stream forwarding status and events in the callback

• If the rtcChannel:MediaRelayStateChanged:error: callback reports CloudHub_RELAY_STATE_RUNNING and CloudHub_RELAY_OK, the SDK has started forwarding the media between the source channel and the target channel
• If the rtcChannel:MediaRelayStateChanged:error: callback reports CloudHub_RELAY_STATE_FAILURE，it indicates that the cross-channel media flow is abnormal

Note

• This method is only applicable to anchors in live broadcast scenarios
• Contact technical support to enable the cross-channel media transmission function
• Call this method after successfully joining the channel
• After successfully calling this method, if you want to call it again, you must call stopChannelMediaRelay to exit the current forwarding state

updateChannelMediaRelay:

Update channels for media circulation

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Discussion

Call this method if you want to send the stream to multiple target channels or exit the current channel after you have successfully started forwarding media streams across channels

Note

• Call this method after the startChannelMediaRelay: method to update the channel of the media flow
• Cross-channel media circulation supports up to 4 target channels

stopChannelMediaRelay

Stop cross-channel media circulation

- (int) stopChannelMediaRelay;

Return Value

• 0: Success
• Not 0：Failure.

Discussion

Once stopped, the anchor will exit all target channels After this method is successfully invoked, the SDK triggers the [rtcChannel:MediaRelayStateChanged:error: callback. If CloudHub_RELAY_STATE_IDLE and CloudHub_RELAY_OK are reported, forwarding media streams has stopped.

Note

• If the method call fails, the SDK will trigger rtcChannel:MediaRelayStateChanged:error: callback, and report status code CloudHub_RELAY_ERROR_SERVER_NO_RESPONSE or CloudHub_RELAY_ERROR_SERVER_CONNECTION_LOST
• You can call the leaveChannel: method to leave the channel, and cross-channel media streaming will stop automatically

Advanced signaling method

setPropertyOfUid:tell:properties:

Sets custom properties for a user in a channel

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Discussion

There are two ways to set custom properties:

• When a user joins a channel:Specify properties in joinChannelByToken:properties:uid:autosubscribeAudio:autoSubscribeVideo:joinSuccess:
  • When the user joins the channel and calls setPropertyOfUid:tell:properties:,the user will receive the rtcChannel:onSetPropertyOfUid:from:properties: callback
• After the Settings are successful, both the notified user and the set user are notified.In addition, new users who enter the channel also get these attributes for that user in the rtcChannel:didJoinedOfUid:properties:isHistory:fromChannel: callback

Note

• If you specify different attributes for the same user more than once, these attributes are logged and sent via the rtcChannel:didJoinedOfUid:properties:isHistory:fromChannel: callback to subsequent users who enter the channel
• If you specify the same attribute for the same user more than once, the last attribute overrides the previous one,For example, if the setting is repeated twice for user A, passing in{"test": true"} and {"test": false},then user B, new to the channel, will get user A’s property{"test": false}when receiving the rtcChannel:didJoinedOfUid:properties:isHistory:fromChannel: callback about user A

sendChatMsg:to:withExtraData:

Sending a Chat Message

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Discussion

You can usually use extraData to pass information about fonts, avatars, and so on
Within the channel users will receivertcChannel:onChatMessageArrival:from:withExtraData: callback

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

Publish 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;

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Discussion

PubMsg mechanism is similar to a message board, which is used to save and synchronize the business status within the channel,Whether you’re already in the channel, or if you’re new to it, Can pass rtcChannel:onPubMsg:msgId:from:withData:associatedWithUser:associatedWithMsg:ts:withExtraData:isHistory: callback received within the current channel has been released Custom message

delMsg:msgId:to:

Delete a custom message

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

and

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Discussion

After the call is successful, users who are already in the channel will receive a rtcChannel:onDelMsg:msgId:from:withData: message

Note

• Deleting a message that does not exist fails

evictUser:reason:

Kick a user out of the channel

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

Parameters

Return Value

• 0: Success
• Not 0：Failure.

Discussion

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