ApsaraVideo Live:AliRtcEngine interface

Creates an AliRtcEngine instance (singleton pattern).

+ (instancetype _Nonnull )sharedInstance:(id<AliRtcEngineDelegate>_Nullable)delegate extras:(NSString *_Nullable)extras;

When to call

You must call this method to create an AliRtcEngine instance before you call any other Alibaba Real-Time Communication (ARTC) SDK APIs.

Limits

• This method is a synchronous call and can be invoked only in the main thread.

• The SDK supports the creation of only one AliRtcEngine instance for each application.

Related callbacks

When you create an engine instance, you must implement the callbacks in AliRtcEngineDelegate based on your business scenario. If the SDK encounters an exception during operation, it first attempts to recover automatically using an internal retry mechanism. For errors that cannot be resolved, the SDK notifies your application through predefined callback interfaces. The following are key callbacks that the SDK cannot handle and require the application layer to listen for and respond to:

Parameters

Destroys the AliRtcEngine instance.

+ (void)destroy;

Destroys the AliRtcEngine singleton object. After this method is called, all internal resources are released, and you can no longer use any other methods of AliRtcEngine or any callbacks. To use the engine again, you must call <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#2db21d4f16s77" id="96631a9306wq8">sharedInstance</a> to create a new instance.

Both this method and destroy[2/2] destroy the engine instance. However, destroy[2/2] also accepts a listener object to be notified upon completion.

When to call

When the audio and video communication ends and the AliRtcEngine features are no longer needed, call this method to release the instance and its associated resources.

Limits

To avoid deadlocks, do not call this method within an SDK callback.

Destroys the AliRtcEngine instance.

+ (void)destroy:(id<AliRtcEngineDestroyDelegate>_Nullable)delegate;

This method destroys the AliRtcEngine singleton object and releases all internal resources. After this method is called, you can no longer use other methods of AliRtcEngine or any callbacks. To use the engine again, you must call <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#2db21d4f16s77" id="115fd691743nx">sharedInstance</a> to create a new instance.

When to call

You can call this method to release the instance after an audio and video session is complete.

Limits

To avoid deadlocks, do not call this method in any SDK callback.

Parameters

Configures the H5 compatibility mode.

+ (void)setH5CompatibleMode:(BOOL)comp;

Parameters

Checks if the H5 compatible mode is set.

+ (BOOL)getH5CompatibleMode;

Return value

Returns YES if the H5 compatible mode is set, and NO otherwise.

Retrieves the SDK version number.

+ (NSString *_Nonnull)getSdkVersion;

Return value

The current SDK version number as a string, for example, "2.5.0.x".

Description

This is a static method that you can use to retrieve the version number at any time.

Sets the channel profile.

- (int)setChannelProfile:(AliRtcChannelProfile)profile;

This method sets the channel profile. The available scenarios are video call and interactive live streaming:

• Video call: All users are streamers and can publish and subscribe to streams.

• Interactive live streaming: You must call <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#892915dd4edcy" id="d88dccff391by">setClientRole</a> to set the user role. To publish streams, a user's role must be set to streamer (AliRTCSdkInteractive). To only subscribe to streams without publishing, a user's role must be set to viewer (AliRTCSdkLive). This mode is recommended for RTC scenarios.

When to call

You can only call this method before joining a channel. The channel profile cannot be changed while you are in the channel. You can change it after you leave the channel.

Parameters

Return value

If the method call is successful, 0 is returned. Otherwise, an error code is returned.

Sets the audio profile.

- (int)setAudioProfile:(AliRtcAudioProfile)audio_profile audio_scene:(AliRtcAudioScenario)audio_scene;

This method sets the audio encoding and scenario modes. For more information, see Common audio operations and configurations. By default, the ARTC SDK uses the high-quality audio mode (AliRtcEngineHighQualityMode) and the music scenario mode (AliRtcSceneMusicMode). If the default settings do not meet your requirements, you must call this method to change them.

When to call

You can call this method only before you join a channel. The settings cannot be changed after you join a channel. However, you can change them after you leave the channel.

Parameters

Return description

A return value of 0 indicates that the method was called successfully. Any other value indicates that the call failed.

Checks if the current mode is audio-only.

- (BOOL)isAudioOnly;

Response Description

Returns YES if the current mode is audio-only, or NO if the current mode is audio and video.

Sets the call to audio-only or audio-and-video.

- (int)setAudioOnlyMode:(BOOL)audioOnly;

Parameters

Return value

Returns 0 if the method call is successful, or a non-zero value if the method call fails.

Joins a channel (single-parameter join).

- (int)joinChannel:(NSString *_Nonnull)token channelId:(NSString *_Nullable)channelId userId:(NSString *_Nullable)userId name:(NSString *_Nullable)userName onResultWithUserId:(void(^_Nullable)(NSInteger errCode, NSString * _Nonnull channel, NSString * _Nonnull userId, NSInteger elapsed))onResult;

This method is used to join a channel. In ARTC, users are organized into channels. To publish or subscribe to audio and video streams, users must join a channel. You can use this method, joinChannel[2/3], or joinChannel[3/3] to join a channel. The differences between these methods relate to the authentication method and the user information that is passed:

• This method joins a channel using a single parameter. You must pass a single-parameter token generated by Token authentication to join the channel. This method is recommended for joining a channel in RTC scenarios.

• joinChannel[2/3] is a method for joining a channel with multiple parameters. You must pass a multi-parameter token generated by Token authentication and the user information that was used to generate the token.

• joinChannel[3/3] is used for AI real-time interaction scenarios. You must pass a single-parameter token and set the capabilityProfile user attribute based on the scenario.

When to call

Call this method after you create the engine instance.

Limits

• After you successfully join a channel, if you want to join another channel, you must first call <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#449873b819cz2" id="37299758eavvg">leaveChannel</a> to leave the current channel. You can join a new channel only after you receive the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#3721f1f2a3kpd" id="50039f328fdk7">onLeaveChannelResult</a> callback.

• A user can join only one channel at a time.

• Apps with different App IDs cannot communicate with each other.

• You do not need to call this method to retry joining a channel after an initial failure.

Related callbacks

After you successfully call this method, the following callbacks are triggered:

• The <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#e6d2a213d7sl2" id="903005c54be4d">onJoinChannelResult</a> callback returns the result of the local client joining the channel.

• After you successfully join a channel, remote clients in the channel receive the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#634626babfq9x" id="4b11b846b1f4t">onRemoteUserOnLineNotify</a> callback.

Parameters

Return description

0 indicates that the method call was successful. A non-zero value indicates that the method call failed.

Joins a channel using multiple parameters.

- (int)joinChannel:(AliRtcAuthInfo *_Nonnull)authInfo name:(NSString *_Nullable)userName onResultWithUserId:(void(^_Nullable)(NSInteger errCode, NSString * _Nonnull channel, NSString * _Nonnull userId, NSInteger elapsed))onResult;

This method is used to join a channel. In ARTC, users are organized into channels. Users must join a channel to publish or subscribe to audio and video streams. You can use this method, joinChannel[1/3], or joinChannel[3/3] to join a channel. The main differences between these methods are the authentication method and the user information that is passed, as follows:

• joinChannel[1/3] is a single-parameter method. To use this method, you must pass a single-parameter token generated using Token authentication. This method is recommended for joining a channel in RTC scenarios.

• This method is a multi-parameter method. To use this method, you must pass a multi-parameter token generated using Token authentication and the user information that was used to generate the token.

• joinChannel[3/3] is used in AI real-time interaction scenarios. To use this method, you must pass a single-parameter token and set the capabilityProfile user attribute.

Limits

• After you join a channel, if you want to join another channel, you must first call <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#449873b819cz2" id="4283c6cc013bz">leaveChannel</a> to leave the current channel. You can join the new channel only after you receive the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#3721f1f2a3kpd" id="9e6478b2f0hen">onLeaveChannelResult</a> callback.

• This method allows a user to join only one channel at a time.

• Apps with different App IDs cannot communicate with each other.

Related callbacks

After you successfully call this method, the following callbacks are triggered:

• The <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#e6d2a213d7sl2" id="df00346ea8928">onJoinChannelResult</a> callback returns the result of the local client joining the channel.

• After you join the channel, the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#634626babfq9x" id="c3832e71e8vck">onRemoteUserOnLineNotify</a> callback is triggered on remote clients.

Parameters

Joins a channel.

- (int)joinChannel:(NSString *_Nonnull)token channelParam:(AliRtcChannelParam *_Nonnull)channelParam onResultWithUserId:(void(^_Nullable)(NSInteger errCode, NSString * _Nonnull channel, NSString * _Nonnull userId, NSInteger elapsed))onResult;

This method is used to join a channel. In ARTC, users are organized into channels and must join one to publish or subscribe to audio and video streams. You can use this method, joinChannel[1/3], or joinChannel[2/3] to join a channel. The methods differ in their authentication process and the user information they require:

• joinChannel[1/3] is a single-parameter method for RTC scenarios. To join a channel, you must pass a single-parameter token generated by Token authentication. This is the recommended method for joining a channel in RTC scenarios.

• joinChannel[2/3] is a multi-parameter method. To join a channel, you must pass a multi-parameter token generated by Token authentication and the user information that was used to generate the token.

• This method is used for AI real-time interaction scenarios. To join a channel, you must pass a single-parameter token and set the capabilityProfile user attribute. To interact with an AI agent, set this attribute to AliRtcCapabilityProfileAiHuman.

Limits

• To join a new channel, you must first call <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#449873b819cz2" id="923190466431o">leaveChannel</a> to leave the current channel. You can join the new channel only after you receive the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#3721f1f2a3kpd" id="dfd794c32covq">onLeaveChannelResult</a> callback.

• This method allows a user to join only one channel at a time.

• Apps with different App IDs cannot communicate with each other.

• You do not need to call this method again when retrying to join a channel after a failure.

Related callbacks

A successful call to this interface triggers the following callbacks:

• The <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#e6d2a213d7sl2" id="f83d0aff9btwh">onJoinChannelResult</a> callback returns the result of a local user joining a channel.

• After you successfully join a channel, the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#634626babfq9x" id="aeef817be3a0b">onRemoteUserOnLineNotify</a> callback is triggered on the remote side.

Parameters

Leaves the current channel.

- (int)leaveChannel;

Calling this method terminates all audio and video interactions and causes the user to leave the current channel.

When to call

• You can call this method to leave a channel that you have joined.

• If you are in a channel and want to join another channel, you must call this method to leave the current channel first.

Related callbacks

• Local client: The SDK triggers the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#3721f1f2a3kpd" id="ea2e36a41csu0">onLeaveChannelResult</a> callback to report the result of leaving the channel.

• A successful call to this API triggers the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#34876c27d7zv7" id="a50f534f21mew">onRemoteUserOffLineNotify</a> callback for the remote user.

Return value

A return value of 0 indicates that the method call was successful. Any other value indicates that the method call failed.

Checks if the user is in a channel.

- (BOOL)isInCall;

Return value

Returns YES if the user is in a channel, or NO otherwise.

Sets the user role.

- (int)setClientRole:(AliRtcClientRole)role;

This method sets the user role to either streamer or viewer.

In interactive mode, if you set the role before joining a channel:

• Streamer: The SDK will automatically publish local audio and video streams and receive audio and video streams from other streamers.

• Viewer: The SDK will not publish local audio and video streams but will receive audio and video streams from other streamers.

When to call

You can call this method before joining a channel to set the user role, or after joining to switch the user role.

Limits

This method is effective only in interactive mode. To use this method, you must call the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#fc9626a99f5kj" id="cd8138c77fv4r">setChannelProfile</a> method and set the channel profile to AliRtcInteractivelive.

In interactive mode, we recommend making an explicit call to set the user role before joining.

Parameters

Returns

A return value of 0 indicates that the method call was successful. Any other value indicates that the call failed.

Retrieves the user role (iOS only).

- (AliRtcClientRole)getCurrentClientRole;

Return value

Returns the current user role.

Refreshes the authentication information.

- (int)refreshAuthInfo:(AliRtcAuthInfo *_Nonnull)authInfo;

This method updates the authentication information. A token expires after a specific period. When the token expires, the SDK cannot establish a connection with the server.

When to call

Consider the following scenarios:

• When you receive the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#6766cdfb40z1a" id="c1cc6cbddb22o">onAuthInfoWillExpire</a> callback indicating that the authentication information is about to expire, we recommend that you regenerate a token on your server and call this method to pass the new token.

• If you do not update the token in time, the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#b04cd67880ptu" id="13c9ccb2b6ghh">onAuthInfoExpired</a> callback is triggered, indicating that the authentication has expired. In this case, you must regenerate a token and call joinChannel to rejoin the channel.

Parameters

Return value

0 indicates that the method call was successful. Any other value indicates that the call failed.

Refreshes the authentication information.

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

This method is used to update the token. The token expires after a certain period, at which point the SDK cannot establish a connection with the server.

When to call

You should regenerate a token on your server and then call this method to pass the new token in the following situation:

When the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#6766cdfb40z1a" id="b1dbfcb71d5ys">onAuthInfoWillExpire</a> callback indicates that the authentication information is about to expire.

Parameters

Return value

0 indicates that the method call was successful. Otherwise, the call failed.

Sets whether to publish the local audio stream.

- (int)publishLocalAudioStream:(BOOL)enable;

This method controls whether to publish the local audio stream. By default, the SDK publishes the audio stream. To disable publishing, you can call publishLocalAudioStream(false) before you join a channel.

When to call

You can call this method before or after joining a channel. If you call this method before joining a channel, the setting modifies the default configuration and takes effect when you join the channel.

Related callbacks

When the publishing state of the local audio stream changes, the local client triggers the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#86b2d8735bm71" id="e5ef180ba6e2i">onAudioPublishStateChanged</a> callback to report the latest publishing state. Remote clients trigger the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#6da9cf330aoer" id="299ef35806ttb">onRemoteTrackAvailableNotify</a> callback to report changes to the audio and video streams of a remote user.

Parameters

Returns

0 indicates that the method call was successful. A non-zero value indicates that the call failed.

Checks if the local audio stream is allowed to be published.

- (BOOL)isLocalAudioStreamPublished;

Returns

YES: Publishing is allowed. NO: Publishing is not allowed.

Sets whether to subscribe to remote audio streams by default.

- (int)setDefaultSubscribeAllRemoteAudioStreams:(BOOL)sub;

You can use this method to configure whether to subscribe to the audio streams of remote users by default. This setting affects the subscription behavior for the audio streams of users who subsequently join the channel. We recommend setting this parameter to true for most scenarios.

When to call

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

• Before joining a channel:

  • By default, the SDK subscribes to the audio streams of all remote users after you join a channel. To change this default behavior, you can call this method before joining the channel.

• After joining a channel:

  • To stop the default subscription, call <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#8b515d9855osk" id="a467e60e4eyhk">setDefaultSubscribeAllRemoteAudioStreams</a>(false) to prevent subscribing to the audio streams of users who subsequently join the channel.

  • To resume subscribing to a specific user's audio stream after stopping the default subscription, call the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#c8249fb568gms" id="9806dd9a750pf">subscribeRemoteAudioStream</a> method. To resume subscribing to multiple users, call this method multiple times.

  • After you stop the default subscription, calling <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#8b515d9855osk" id="9507d6d3121uh">setDefaultSubscribeAllRemoteAudioStreams</a>(true) resumes the subscription to audio streams only from users who join the channel after this method is called. This call does not subscribe to the audio streams of users who are already in the channel.

Parameters

Return value

A value of 0 indicates that the method call was successful. Otherwise, the call failed.

Stops or resumes subscribing to the audio stream of a specific remote user.

- (int)subscribeRemoteAudioStream:(NSString *_Nonnull)uid sub:(BOOL)sub;

You can call this method to stop or resume subscribing to the audio stream of a specific remote user. In most scenarios, we recommend subscribing to the audio stream.

Parameters

Return value

A value of 0 indicates that the method call was successful. Otherwise, the call failed.

Stops or resumes receiving all remote audio streams.

- (int)subscribeAllRemoteAudioStreams:(BOOL)sub;

This method is a master switch for subscribing to remote audio streams. If you set the parameter to NO, the following occurs:

• The SDK stops subscribing to all remote audio streams in the current meeting.

• New users who join later will no longer be subscribed.

• You cannot use <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#c8249fb568gms" id="846b0dd501epf">subscribeRemoteAudioStream</a> to individually control the audio stream of a specific user.

To resume subscribing, call this method again and set the parameter to YES.

Parameters

Return value

0 indicates that the method call was successful. A non-zero value indicates that the method call failed.

Enables or disables publishing the video stream from the camera.

- (int)publishLocalVideoStream:(BOOL)enable;

This method controls whether to publish the local video stream.

When to call

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

If you call this method before joining a channel, the setting takes effect when you join the channel.

Related callbacks

When the local audio stream ingest status changes, the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#bd67711e63tnk" id="f966292202q3d">onVideoPublishStateChanged</a> callback is triggered on the local client to report the latest audio stream ingest status. The <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#6da9cf330aoer" id="2fdc208ccczr1">onRemoteTrackAvailableNotify</a> callback is triggered on the remote client to report changes in the audio and video streams of a remote user.

Parameters

Checks whether the local video stream is published.

- (BOOL)isLocalVideoStreamPublished;

Return value

Returns YES if the local video stream is published, or NO otherwise.

Sets whether to subscribe to all remote video streams by default.

- (int)setDefaultSubscribeAllRemoteVideoStreams:(BOOL)sub;

This interface sets the default subscription behavior for video streams. By default, the SDK subscribes to all remote video streams.

When to call

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

• Before joining a channel:

  • You can call this interface to cancel the default subscription behavior.

• After joining a channel:

  • If you want to stop the default subscription, you can call setDefaultSubscribeAllRemoteVideoStreams(false). This prevents the SDK from automatically subscribing to the video streams of users who subsequently join the channel.

  • After stopping the default subscription, if you want to resume subscribing to a specific user's video stream, call the subscribeRemoteVideoStream interface. To resume subscribing to multiple users, call the interface for each user.

  • After you stop the default subscription, a call to setDefaultSubscribeAllRemoteVideoStreams(false) resumes only the audio streams of users who join the channel afterward.

Parameters

Return value

A return value of 0 indicates that the method call was successful. Any other value indicates that the call failed.

Stops or resumes subscribing to a remote user's video stream.

- (int)subscribeRemoteVideoStream:(NSString *_Nonnull)uid track:(AliRtcVideoTrack)track sub:(BOOL)sub;

This method subscribes to or unsubscribes from the video stream of a specified remote user.

When to call

You can call this method before or after you join a meeting.

Parameters

Stops or resumes receiving all remote video streams.

- (int)subscribeAllRemoteVideoStreams:(BOOL)sub;

This method is a master switch for subscribing to remote video streams. If this parameter is set to false, the following occurs:

• You stop subscribing to all remote video streams in the current meeting.

• New users who join the meeting later will not be subscribed either (even if you have used <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#a975297480yoj" id="0464849a17dks">setDefaultSubscribeAllRemoteVideoStreams</a> to set a default subscription).

• You cannot use <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#1cc7ef76fdawz" id="498e782f414zz">subscribeRemoteVideoStream</a> to independently control a specific user's audio stream.

Call this interface again and set the parameter to true to resume the subscription.

Parameters

Return value

A value of 0 indicates that the method call was successful. Any other value indicates that the call failed.

Stops or resumes a subscription to the media stream of a specific remote user.

- (int)subscribeRemoteMediaStream:(NSString *_Nonnull)uid videoTrack:(AliRtcVideoTrack)videoTrack subVideo:(BOOL)subVideo subAudio:(BOOL)subAudio;

This interface is used to subscribe to remote audio and video streams simultaneously.

Related interfaces

Compared to subscribeRemoteMediaStream[2/2], this interface uses two boolean parameters, subVideo and subAudio, to determine whether to subscribe to remote audio and video streams. The videoTrack parameter controls which video stream to pull.

Note: In this interface, the AliRtcVideoTrackNo value of AliRtcVideoTrack is not supported, and setting it has no effect.

Parameters

Return value

A return value of 0 indicates that the method call was successful. Any other value indicates that the call failed.

Stops or resumes the subscription to a media stream from a specific remote user.

- (int)subscribeRemoteMediaStream:(NSString *_Nonnull)uid videoTrack:(AliRtcVideoTrack)videoTrack audioTrack:(AliRtcAudioTrack)audioTrack;

This interface is used to merge subscriptions for remote audio and video streams.

Related interfaces

Unlike subscribeRemoteMediaStream[1/2], this interface sets the desired subscription state in a single call using the videoTrack and audioTrack parameters. For example:

• To subscribe to the camera and microphone streams, set videoTrack to AliRtcVideoTrackCamera and audioTrack to AliRtcAudioTrackMic in the method call.

• To unsubscribe from the camera stream but maintain the microphone subscription, call the method again with videoTrack set to AliRtcVideoTrackNo and audioTrack set to AliRtcAudioTrackMic.

• To cancel both subscriptions, call the method again with videoTrack set to AliRtcVideoTrackNo and audioTrack set to AliRtcAudioTrackNo.

• To subscribe to both the camera and screen sharing streams, set videoTrack to AliRtcVideoTrackBoth. The same principle applies to audio.

Parameters

Return description

A return value of 0 indicates that the method call was successful. Otherwise, the call failed.

Subscribes to a specific user's stream across channels.

- (int)subscribeRemoteDestChannelStream:(NSString *_Nonnull)channelId uid:(NSString *_Nonnull)uid track:(AliRtcVideoTrack)track subAudio:(BOOL)subAudio sub:(BOOL)sub;

Parameters

Response Description

0 is returned when the method call is successful. A non-zero value is returned when the method call fails.

Subscribes to the streams of all users in the destination channel.

- (int)subscribeRemoteDestChannelAllStream:(NSString *_Nonnull)channelId track:(AliRtcVideoTrack)track subAudio:(BOOL)subAudio sub:(BOOL)sub;

Parameters

Return value

Returns 0 on success. A non-zero value indicates failure.

Sets the volume of the remote audio.

- (int)setRemoteAudioVolume:(NSString *_Nonnull)uid volume:(NSInteger)volume;

Parameters

Return value

0 indicates success. A non-zero value indicates failure.

Stops or resumes sending the local audio stream.

- (int)muteLocalMic:(BOOL)mute mode:(AliRtcMuteLocalAudioMode)mode;

When to call

You can call this method before or after you join a room.

Related callbacks

After the call is successful, the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#3189c59d9fipb" id="1579c3523779c">onUserAudioMuted</a> callback is triggered to notify you whether the remote user is muted.

Parameters

Return value

A return value of 0 indicates that the method call was successful. A non-zero value indicates that the call failed.

Stops or resumes remote audio playback.

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

This method only stops or resumes a specified remote user's audio playback and does not affect the pulling and decoding of the remote audio stream. To unsubscribe from a user's audio stream, call <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#c8249fb568gms" id="dd9dbbad0bkni">subscribeRemoteAudioStream</a>.

When to call

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

Parameters

Return value

A return value of 0 indicates that the method call was successful. Any other value indicates that the method call failed.

Stops or resumes all remote audio playback.

- (int)muteAllRemoteAudioPlaying:(BOOL)mute;

This interface stops or resumes all remote audio playback.

When to call

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

Parameters

Return value

0 indicates that the method call was successful. A value other than 0 indicates that the method call failed.

Starts audio capture.

- (void)startAudioCapture;

This method starts audio capture. You can call this method before joining a channel to enable audio capture in advance. If this method is not called, the SDK automatically manages the audio capture device. To restart audio capture after calling stopAudioCapture, you must call this method.

When to call

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

Related interfaces

You can use the parameters of the startAudioCapture[2/2] method to control whether the audio capture device remains active after you leave the channel.

Related callbacks

After you call this method, the SDK triggers the onLocalAudioStateChanged callback to report the change in the local audio capture state.

Returns

0 indicates that the method call was successful. Any other value indicates that the method call failed.

Starts audio capture.

- (void)startAudioCapture:(BOOL)keepAlive;

Audio capture stops when the microphone is muted.

You can call this method before joining a channel to start audio capture in advance. If you do not call this method, the SDK automatically controls the audio capture device.

When to call

Call this method before or after joining a channel.

Related methods

Compared to startAudioCapture[1/2], this method lets you control whether the capture device remains on after you leave the channel using the keepAlive parameter.

Related callbacks

After you call this method to modify the local audio capture status, you will receive the status change in the onLocalAudioStateChanged callback.

Parameters

Return value

0 indicates that the method call was successful. Other values indicate that the method call failed.

Stops audio capture.

- (void)stopAudioCapture;

After you call <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#3103c368bexf8" id="ddef64f9b93zq">startAudioCapture</a>, you can call this method to stop audio capture.

Related callbacks

After calling this interface to modify the local audio collection status, you will receive the status change through the onLocalAudioStateChanged callback.

Return value

A return value of 0 indicates that the method call was successful. Any other value indicates that the call failed.

Sets the audio output to the earpiece or speaker (iOS only).

- (int)enableSpeakerphone:(BOOL)enable;

This interface sets the audio playback device to either the earpiece or the speaker after you join a channel. If you do not call this interface, the default audio routing device is used for playback.

The SDK defines the audio routing priority and automatically switches the audio route based on the peripheral connection status. The priority is as follows: Wired headset > Bluetooth headset > User settings > Default settings. Therefore, this interface call has no effect when a peripheral is connected. For more information about audio route settings, see Audio route settings.

When to call

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

Related interfaces

The <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#83be8cc066qqq" id="f8de149ef8so0">setDefaultAudioRoutetoSpeakerphone</a> method modifies the default audio route settings. In contrast, this method sets the current routing device.

Parameters

Return value

A return value of 0 indicates that the method call was successful. A non-zero value indicates that the method call failed.

Checks whether the current audio output is the earpiece or the speaker (iOS only).

- (BOOL)isEnableSpeakerphone;

Return value

YES indicates that speaker mode is enabled. NO indicates that earpiece mode is enabled.

Sets the frequency of the volume callback and the smoothing coefficient.

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

This method allows the SDK to periodically report volume information about the local publishing user and the remote user with the highest instantaneous volume to the app.

When to call

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

Related callbacks

After you successfully call this method, if users are publishing in the channel, the SDK triggers the following two callbacks at the set time interval:

• The onAudioVolumeCallback callback reports the audio volume of each speaker at the specified interval.

• For voice activity detection, the onActiveSpeaker callback reports the UID of the active speaker.

Parameters

Return value

0 indicates that the method call was successful. A value other than 0 indicates that the method call failed.

Enables in-ear monitoring.

- (int)enableEarBack:(BOOL)enable;

This method enables or disables the in-ear monitoring feature. We recommend enabling in-ear monitoring when you use headphones (wired or Bluetooth) for a better experience.

When to call

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

Parameters

Returns

0 indicates that the method call was successful. A negative value indicates that the method call failed.

Sets the in-ear monitoring volume.

- (int)setEarBackVolume:(NSInteger)volume;

This method sets the volume for in-ear monitoring. This setting takes effect only after you enable the in-ear monitoring feature by calling <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#bd665d0f894ux" id="b0fa86c9bcuq">enableEarBack</a>.

When to call

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

Parameters

Return value

0 indicates that the method call was successful. A non-zero value indicates that the call failed.

Starts audio playback.

- (void)startAudioPlayer;

Stops audio playback.

- (void)stopAudioPlayer;

Sets the playback volume.

- (int)setPlayoutVolume:(NSInteger)volume;

Parameters

Return value

A return value of 0 indicates success. Any other value indicates failure.

Sets the recording volume.

- (int)setRecordingVolume:(NSInteger)volume;

Parameters

Return value

Returns 0 if the call is successful, or a non-zero value if it fails.

Plays an audio file.

- (int)playAudioFileTest:(NSString *_Nonnull)filePath;

Parameters

Return value

0 indicates success. A non-zero value indicates failure.

Stops the playback of the audio file.

- (int)stopAudioFileTest;

Return value

A return value of 0 indicates success. Any other value indicates failure.

Starts a test of the audio capture device before you join a channel.

- (void)startAudioCaptureTest;

Stops the pre-call test of the audio capture device.

- (void)stopAudioCaptureTest;

Sets whether to route the default audio output to the speaker. By default, audio is routed to the speaker.

- (int)setDefaultAudioRouteToSpeakerphone:(BOOL)defaultToSpeakerphone;

You can use this interface to set the default audio routing device before you join a meeting. You can choose to route the audio output to either the earpiece or the speaker. By default, the SDK routes audio to the speaker. To change this default configuration, you can call this interface before you join the meeting.

The audio routing priority is predefined in the SDK. The SDK automatically switches the audio route based on the connection status of peripheral devices. The priority is as follows: Wired headset > Bluetooth headset > User settings > Default settings. Therefore, if no peripheral device is connected and you do not call the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#f7d0d8b64fzkz" id="30798b686b5qk">enableSpeakerphone</a> method, the default settings are applied.

For more information about audio route settings, see Audio route settings.

Mobile devices typically have two audio output devices: the earpiece and the speaker.

• When audio is routed to the earpiece, the sound is quieter and provides better privacy. This is suitable for phone calls because the audio can only be heard clearly when the device is held close to your ear.

• When audio is routed to the speaker, the sound is louder and enables a hands-free function. The audio can be heard clearly without holding the device to your ear.

Related interfaces

This API modifies the default audio routing settings, whereas the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#f7d0d8b64fzkz" id="6001aa98ebapw">enableSpeakerphone</a> API sets the current routing device.

When to call

You can call this method before or after you join a meeting.

Parameters

Return value

Returns 0 on success. A non-zero value indicates failure.

Sets the voice changer effect mode.

- (int)setAudioEffectVoiceChangerMode:(AliRtcAudioEffectVoiceChangerMode)mode;

Parameters

Return value

A return value of 0 indicates that the method call was successful. Otherwise, the call failed.

Sets the pitch shifting parameter.

- (int)setAudioEffectPitchValue:(double)value;

Parameters

Return value

A value of 0 indicates that the method call is successful. A non-zero value indicates that the method call failed.

Sets the reverberation effect mode.

- (int)setAudioEffectReverbMode:(AliRtcAudioEffectReverbMode)mode;

Parameters

Response description

Returns 0 if the method call is successful, or a non-zero value if the call fails.

Sets the type and parameters for the reverberation effect.

- (int)setAudioEffectReverbParamType:(AliRtcAudioEffectReverbParamType)type value:(float)value;

Parameters

Return value

0 indicates that the method call was successful. A value other than 0 indicates that the method call failed.

Sets the preset voice beautification effect mode.

- (int)setAudioEffectBeautifyMode:(AliRtcAudioEffectBeautifyMode)mode;

You can call this interface to set preset voice beautification modes for scenarios that require voice beautification, such as voice live streaming, karaoke, and voice-based social networking. By selecting a mode, you can change the auditory effect of the human voice, for example, by enhancing its magnetic quality or improving its clarity, to create a better listening experience for remote users.

When to call

You can call this interface before or after joining a channel.

Parameters

Return values

• 0: The mode was set successfully.

• A non-zero value: Failed to set the mode.

Sets the audio equalizer (EQ) parameter to adjust the gain of a specified frequency band.

- (int)setAudioEffectEqualizationParam:(AliRtcAudioEffectEqualizationBandFrequency)bandIndex gain:(float)gain;

You can use this interface to adjust the graphic equalizer for locally captured voice or audio signals. By adjusting the gain in decibels (dB) for one of the 10 fixed frequency bands, you can achieve customized sound processing. This feature is suitable for scenarios such as voice clarity optimization, human voice highlighting, and assisted noise reduction.

The equalizer supports adjustments across the full audio spectrum from 31 Hz to 16 kHz, which is divided into 10 standard frequency bands. The gain for each band can be set independently from -15 dB to 15 dB. The default value is 0 dB, which indicates no enhancement or attenuation.

Limits

• You must enable the voice beautification mode by calling setAudioEffectBeautifyMode before you call this interface.

Parameters

Response Description

0: The parameter was set successfully.

A non-zero value: The parameter failed to be set.

Adds an external audio stream.

- (int)addExternalAudioStream:(AliRtcExternalAudioStreamConfig *_Nonnull)config;

This method adds a new external audio stream. The steps are as follows:

1. Call the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#d71bbfd2f242b" id="c310321e9eu35">addExternalAudioStream</a> method to add an external audio stream and obtain the external audio stream ID.

2. Call pushExternalAudioStream to push audio data to the created audio stream.

3. When the call ends, call <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#282d70095duaw" id="16f621608d94x">removeExternalAudioStream</a> to remove the external audio stream.

To publish custom captured audio in a channel, see Custom audio collection.

Parameters

Returns

If the method call is successful, it returns the ID of the external audio stream, which is a value greater than 0. Other values indicate failure.

Inputs external audio stream data.

- (int)pushExternalAudioStream:(int)streamId rawData:(AliRtcAudioFrame * _Nonnull)audioFrame;

This method inputs data into a specified audio stream. Follow these steps:

1. Call the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#d71bbfd2f242b" id="0a353f7272shu">addExternalAudioStream</a> method to add an external audio stream and obtain the external audio stream ID.

2. Call this method to input audio data into the created audio stream.

3. When the call ends, call the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#282d70095duaw" id="a9ebc8d599dz4">removeExternalAudioStream</a> method to remove the external audio stream.

For more information about publishing custom collected audio in a channel, see Custom audio collection.

Parameters

Return value

A return value of 0 indicates that the method call was successful. Any other value indicates that it failed.

Sets the publishing volume of the external audio stream.

- (int)setExternalAudioStream:(int)streamId
                publishVolume:(int)publishVolume;

Parameters

Return value

Returns 0 if the method call is successful, or a non-zero value if the call failed.

Retrieves the publishing volume of the external audio stream.

- (int)getExternalAudioStreamPublishVolume:(int)streamId;

Parameters

Response Description

The stream ingest volume. The value ranges from 0 to 100. A value less than 0 indicates that the call failed.

Sets the playback volume of the external audio stream.

- (int)setExternalAudioStream:(int)streamId
                playoutVolume:(int)playoutVolume;

Parameters

Returns

The method returns 0 if the call is successful, or a non-zero value if the call fails.

Retrieves the playback volume of the external audio stream.

- (int)getExternalAudioStreamPlayoutVolume:(int)streamId;

Parameters

Return value

The playback volume. The value ranges from 0 to 100. A value less than 0 indicates that the method call failed.

Deletes an external audio stream.

- (int)removeExternalAudioStream:(int)streamId;

This method removes the external audio stream that corresponds to the specified streamId. It is the counterpart to the addExternalAudioStream method.

When to call

To use the custom audio input feature, you must first call the addExternalAudioStream method to add an audio stream and obtain its stream ID. Then, you can call the pushExternalAudioStream interface to push your audio data to the SDK. When you want to stop using the custom audio input, call this method to remove the corresponding external audio stream and release its resources.

Parameters

Return value

0 indicates success. A non-zero value indicates failure.

Retrieves information about an audio file.

- (int)getAudioFileInfo:(NSString *_Nonnull)filePath;

Parameters

Starts audio mixing.

- (int)startAudioAccompanyWithFile:(NSString *_Nonnull)filePath config:(AliRtcAudioAccompanyConfig *_Nonnull)config;

Parameters

Return value

Returns 0 on success, or a non-zero value on failure.

Stops audio mixing.

- (int)stopAudioAccompany;

Return value

Returns 0 on success, and a non-zero value on failure.

Sets the audio mixing volume.

- (int)setAudioAccompanyVolume:(NSInteger)volume;

Parameters

Return value

Returns 0 on success, or an error code on failure.

Sets the publishing volume for the audio mixing stream.

- (int)setAudioAccompanyPublishVolume:(NSInteger)volume;

Parameters

Return value

Returns 0 on success. A non-zero value indicates failure.

Retrieves the volume of the audio mixing stream ingest.

- (int)getAudioAccompanyPublishVolume;

Return value

A value in the range of 0 to 100 is returned on success. Other values indicate a failure.

Sets the local playback volume for audio mixing.

- (int)setAudioAccompanyPlayoutVolume:(NSInteger)volume;

Parameters

Return value

Returns 0 on success. A non-zero value indicates failure.

Retrieves the local playback volume for audio mixing.

- (int)getAudioAccompanyPlayoutVolume;

Return value

A value from 0 to 100 indicates success. Any other value indicates failure.

Pauses audio mixing.

- (int)pauseAudioAccompany;

Return value

0 indicates success. Other values indicate failure.

Resumes audio mixing.

- (int)resumeAudioAccompany;

Return value

0 indicates success, and any other value indicates failure.

Returns the duration of the audio mixing file in milliseconds.

- (int)getAudioAccompanyDuration;

Return value

A return value of 0 or greater indicates the duration of the audio mixing file in milliseconds. A return value of less than 0 indicates a failure.

Retrieves the playback progress of the audio mixing file in milliseconds.

- (int)getAudioAccompanyCurrentPosition;

Return value

A value greater than or equal to 0 indicates the playback progress. A value less than 0 indicates that the call failed.

Sets the playback position of the accompanying audio file.

- (int)setAudioAccompanyPosition:(int)pos;

Parameters

Return value

Returns 0 on success and a non-zero value on failure.

Preloads a sound effect file.

- (int)preloadAudioEffectWithSoundId:(NSInteger)soundId filePath:(NSString *_Nonnull)filePath;

Parameters

Returns

0 indicates a successful method call, and a non-zero value indicates a failed method call.

Unloads a preloaded sound effect file.

- (int)unloadAudioEffectWithSoundId:(NSInteger)soundId;

Parameters

Returns

A return value of 0 indicates that the method call was successful. A non-zero value indicates that the method call failed.

Starts playing a sound effect.

- (int)playAudioEffectWithSoundId:(NSInteger)soundId filePath:(NSString *_Nonnull)filePath cycles:(NSInteger)cycles publish:(BOOL)publish;

Parameters

Return value

A return value of 0 indicates that the method was called successfully. A non-zero value indicates that the method call failed.

Stops playing a sound effect.

- (int)stopAudioEffectWithSoundId:(NSInteger)soundId;

Parameters

Return value

0 indicates that the method call was successful. A non-zero value indicates that the method call failed.

Stops playing all sound effects.

- (int)stopAllAudioEffects;

Return value

0 indicates that the method call was successful. A non-zero value indicates that the call failed.

Pauses a sound effect.

- (int)pauseAudioEffectWithSoundId:(NSInteger)soundId;

Parameters

Returns

0 indicates that the method call was successful. Otherwise, the method call failed.

Pauses all sound effects.

- (int)pauseAllAudioEffects;

Returns

A value of 0 indicates that the method call was successful. A value other than 0 indicates that the method call failed.

Resumes playing a specified sound effect.

- (int)resumeAudioEffectWithSoundId:(NSInteger)soundId;

Parameters

Return value

Returns 0 if the method call is successful, or a non-zero value if the method call failed.

Resumes playing all sound effects.

- (int)resumeAllAudioEffects;

Return value

Returns 0 if the call is successful, or a non-zero value if the call fails.

Sets the sound effect stream ingest volume.

- (int)setAudioEffectPublishVolumeWithSoundId:(NSInteger)soundId volume:(NSInteger)volume;

Parameters

Return Value

Returns 0 if the method call is successful, or a non-zero value if the method call fails.

Retrieves the volume of the published sound effect for stream ingest.

- (int)getAudioEffectPublishVolumeWithSoundId:(NSInteger)soundId;

Parameters

Return value

A value of 0 indicates that the method call was successful. A non-zero value indicates that the method call failed.

Sets the mixing volume of all sound effects for stream ingest.

- (int)setAllAudioEffectsPublishVolume:(NSInteger)volume;

Parameters

Returns

A return value of 0 indicates that the method call was successful. A non-zero value indicates that the call failed.

Sets the local playback volume for a sound effect.

- (int)setAaudioEffectPlayoutVolumeWithSoundId:(NSInteger)soundId volume:(NSInteger)volume;

Parameters

Returns

A return value of 0 indicates that the method call was successful. Any other value indicates that the call failed.

Retrieves the local playback volume for a sound effect.

- (int)getAudioEffectPlayoutVolumeWithSoundId:(NSInteger)soundId;

Parameters

Return value

Returns 0 if the method call is successful. Returns a non-zero value if the method call failed.

Sets the local playback volume for all sound effects.

- (int)setAllAudioEffectsPlayoutVolume:(NSInteger)volume;

Parameters

Return value

0 indicates that the method call was successful. Otherwise, the call failed.

Starts recording a media file.

- (BOOL)startRecord:(AliRtcRecordType)recordType recordFormat:(AliRtcRecordFormat)recordFormat filePath:(NSString*)filePath audioConfig:(AliRtcRecordAudioConfig*)audioConfig videoConfig:(AliRtcRecordVideoConfig*)videoConfig;

Parameters

Return value

A return value of true indicates success. Any other value indicates failure.

Stops recording the media file.

- (void)stopRecord 

Parameters

None.

Sets the rendering window and drawing parameters for the local video preview.

- (int)setLocalViewConfig:(AliVideoCanvas *_Nullable)viewConfig forTrack:(AliRtcVideoTrack)track;

You can call this method to bind the display view to the local video stream and set the rendering mode, image mode, and rotation angle for the local user's view. These settings only affect the local preview and do not apply to the published video stream. To set the view for a remote user, call setRemoteViewConfig.

When to call

This method can be called before or after joining a channel.

Parameters

Return value

A return value of 0 indicates that the method call was successful. A non-zero value indicates that the call failed.

Sets the camera capture preferences.

- (int)setCameraCapturerConfiguration:(AliRtcCameraCapturerConfiguration* _Nonnull)config;

This method is used to configure camera capture preferences, such as the camera direction and capture frame rate.

When to call

You must call this method before you open the camera, for example, before you call the following methods:

• startPreview

• joinChannel

Parameters

Return value

A return value of 0 indicates that the method call was successful. A non-zero value indicates that the call failed.

Enables or disables local video capture.

- (int)enableLocalVideo:(BOOL)enable;

This method enables or disables local video capture. When local video capture is disabled, the SDK stops sending video data for the local preview and stream ingest, which causes them to freeze on the last captured frame. This action does not affect receiving remote video.

When to call

You can call this method before or after you join a channel.

Related callbacks

• After you successfully call this method, remote users in the channel receive the onUserVideoEnabled callback.

Parameters

Return description

0 indicates that the method call was successful. A value other than 0 indicates that the method call failed.

Stops or resumes sending local video data.

- (int)muteLocalCamera:(BOOL)mute forTrack:(AliRtcVideoTrack)track;

When you publish a stream, you can call this interface to send black video frames. The local preview is not affected. The collection, encoding, and sending modules continue to work, but the sent video consists of black frames.

Parameters

Return description

A return value of 0 indicates that the method call was successful. Otherwise, the method call failed.

Sets the rendering window and rendering parameters for a remote video stream.

- (int)setRemoteViewConfig:(AliVideoCanvas *_Nullable)canvas uid:(NSString *_Nonnull)uid forTrack:(AliRtcVideoTrack)track;

This method attaches a display view to a specified video stream from a remote user and sets rendering properties for the view on the local display, such as the rendering mode, mirror mode, and rotation angle. This affects only the video image that the local user sees. To set the local preview view, you can call <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#fea843803078q" id="b6f22fe87a2es">setLocalViewConfig</a>.

• If the view parameter in AliVideoCanvas: Rendering Canvas is null, rendering stops.

• To reset the renderMode parameter of AliVideoCanvas: Rendering Canvas during playback, keep the other parameters unchanged and modify only the renderMode parameter.

• To reset the mirrorMode parameter of AliVideoCanvas: Rendering Canvas during playback, keep the other parameters unchanged and modify only the mirrorMode parameter.

When to call

We recommend that you call this method when the onRemoteTrackAvailableNotify callback is received. This callback indicates that the remote user's video is available.

Parameters

Returns

0 indicates that the method call was successful. Any other value indicates that the method call failed.

Checks if the camera is on.

- (BOOL)isCameraOn;

Return value

Returns YES if the camera is on, or NO if it is off.

Sets video encoding properties.

- (void)setVideoEncoderConfiguration:(AliRtcVideoEncoderConfiguration* _Nonnull)config;

This method sets video encoding properties, such as resolution, frame rate, bitrate, and video orientation. We recommend that you call this interface in all video scenarios.

When to call

You can call this method before or after joining a meeting. If you only need to set the video encoding properties for the camera stream once per meeting, we recommend that you call this method before joining.

Limits

The mirrorMode parameter of this method and setVideoMirrorMode both control the mirroring of the video stream ingest image. We recommend that you use only one. Using both at the same time causes the image effects to stack, which may result in setting failures or unexpected behavior.

Parameters

Sets video decoding properties.

- (void)setVideoDecoderConfiguration:(AliRtcVideoDecoderConfiguration* _Nonnull)config;

This method sets the video decoding properties for a camera stream.

When to call

We recommend calling this method before joining a meeting.

Parameters

Switches between the front and rear cameras. The front camera is used by default.

- (int)switchCamera;

You can call this method to dynamically switch cameras during runtime without restarting the video stream or reconfiguring the video source.

When to call

You must call this method after the camera is successfully opened.

Limits

This method is available only on Android and iOS platforms.

Return description

A return value of 0 indicates that the method call was successful. Otherwise, the call failed.

Retrieves the current camera direction. The default is the front camera (iOS only).

- (AliRtcCameraDirection)getCurrentCameraDirection;

Return value

The camera direction enumeration value.

Starts the local video preview and automatically opens the camera.

- (int)startPreview;

This interface starts the local video preview and automatically opens the camera. To stop the local preview, you can call the stopPreview interface.

When to call

• Before you call this interface, you must call setLocalViewConfig to set the view for the local preview. Otherwise, the preview cannot be started. This does not affect stream ingest.

• You can call this interface before you call joinChannel to start the preview. This automatically opens the camera.

Return value

0 indicates that the method call was successful. Any other value indicates that it failed.

Stops the local preview.

- (int)stopPreview;

This method stops the local video preview and turns off the camera. After the preview is stopped, the local view remains on the last captured frame, which does not affect stream ingest.

When to call

You can call this method to stop the preview after you have started it.

Return value

0 indicates that the method call was successful. Otherwise, the call failed.

Sets the zoom level of the camera.

 - (int)setCameraZoom:(float)zoom;

Parameters

Return value

Returns 0 on success. A non-zero value indicates failure.

Retrieves the maximum camera zoom factor.

 - (float)GetCameraMaxZoomFactor;

Return value

The maximum camera zoom factor.

Returns the current zoom factor of the camera.

- (float)GetCurrentZoom;

Return value

The current camera zoom factor.

Sets the camera exposure.

- (int)SetExposure:(float)exposure;

Parameters

Return value

Returns 0 on success. Other values indicate a failure.

Returns the current camera exposure.

- (float)GetCurrentExposure;

Return value

The current camera exposure.

Retrieves the minimum camera exposure.

- (float)GetMinExposure;

Return value

The minimum camera exposure.

Retrieves the maximum camera exposure.

- (float)GetMaxExposure;

Return value

The maximum camera exposure.

Turns the camera flash on or off.

- (int)setCameraFlash:(BOOL)flash;

Parameters

Return value

0 indicates success. Other values indicate failure.

Checks if the camera supports manual focus.

- (BOOL)isCameraFocusPointSupported;

Return value

TRUE: Manual focus is supported. FALSE: Manual focus is not supported.

Checks whether the camera supports setting an exposure point.

- (BOOL)isCameraExposurePointSupported;

Return value

Returns TRUE if the camera supports setting an exposure point, or FALSE otherwise.

Sets the manual focus point for the camera.

- (int)setCameraFocusPoint:(CGPoint)point;

Parameters

Return value

Returns 0 if the operation is successful. Otherwise, an error code is returned.

Sets the exposure point and exposure value.

- (int)setCameraExposurePoint:(CGPoint)point;

Parameters

Return value

Returns 0 on success. Other values indicate failure.

Checks whether the camera supports face-based autofocus.

- (BOOL)isCameraAutoFocusFaceModeSupported;

Return value

Returns TRUE if face-based autofocus is supported, or FALSE otherwise.

Enables or disables face-based autofocus for the camera.

- (BOOL)setCameraAutoFocusFaceModeEnabled:(BOOL)enable;

Parameters

Return value

Returns TRUE if the method call is successful, or FALSE otherwise.

Sets the video mirror mode.

- (int)setVideoMirrorMode:(AliRtcVideoPipelineMirrorMode)mirrorMode;

Sets the mirror mode for the local video preview and the published video stream.

When to call

You can call this interface before or after joining a meeting. The SDK internally records the setting and applies it when the video preview and encoding (stream ingest) are available.

Limits

This interface's functionality overlaps with the mirrorMode setting in setLocalViewConfig and setVideoEncoderConfiguration. We recommend that you use only this interface.

Parameters

Sets the scaling mode of the video capture pipeline.

-(void)setCapturePipelineScaleMode:(AliRtcCapturePipelineScaleMode)mode;

This method sets whether video data is scaled immediately upon capture or only during encoding. For example, if the capture resolution differs from the encoding resolution, you can use this setting to determine whether the preview data is consistent with the stream ingest data.

When to call

You must call this method before you open the camera, for example, before you call startPreview or joinChannel.

Parameters

Return value

0 indicates success. Other values indicate failure.

Registers a video data output object.

- (void)registerVideoFrameWithObserver:(id<AliRtcVideoFrameDelegate> _Nullable)observer;

You can use this interface to register a video data output object. To unregister the object, call the unregisterVideoSampleWithObserver interface.

When to call

To obtain raw video data (such as data in YUV or RGBA format), you can call this interface to register a video data observer to retrieve video data at each stage.

Related callbacks

After you successfully register a video data observer, the SDK triggers your implemented callbacks for each video frame. You can implement the following callbacks as needed:

• onCaptureVideoSample: Callback for locally captured video data.

• onRemoteVideoSample: Callback for remote video data.

• onPreEncodeVideoSample: Callback for pre-encoded local video data.

Parameters

Unregisters the observer object that is used to export video data.

- (void)unregisterVideoSampleWithObserver:(id<AliRtcVideoFrameDelegate> _Nullable)observer;

This interface is the counterpart to the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#9a3437ab16j1w" id="f524bad30a6ys">registerVideoSampleObserver</a> interface and unregisters the video sample observer.

Parameters

Registers an observer for OpenGL texture data from the local camera video stream.

- (void)registerLocalVideoTextureObserver:(id<AliRtcTextureDelegate> _Nullable)observer;

To obtain raw video data, call the registerVideoSampleObserver method to register the corresponding callback. To obtain internal texture data, call this method. To unregister the observer, call the unRegisterLocalVideoTextureObserver method.

Related callbacks

After you successfully register the observer, the SDK triggers the callbacks that you implemented in the AliRtcTextureObserver interface each time a video frame is captured. Implement the callbacks that you need as needed:

• onTextureCreate: This callback is triggered when the SDK creates its internal OpenGL context.

• onTextureUpdate: This callback is triggered after each video frame is uploaded to the OpenGL texture. If an external OpenGL texture data observer is registered, you can process the texture in this callback and return the ID of the processed texture. The return value of this callback must be a valid texture ID. If you do not process the texture, you must return the value of the textureId parameter.

• onTextureDestroy: This callback is triggered when the SDK destroys its internal OpenGL context.

Parameters

Unregisters the observer for OpenGL video texture data from the local camera stream.

- (void)unregisterLocalVideoTextureObserver:(id<AliRtcTextureDelegate> _Nullable)observer;

This method is the counterpart of registerLocalVideoTextureObserver.

Parameters

Captures a snapshot of the current video stream.

- (int)snapshotVideo:(NSString*_Nullable)userId type:(AliRtcVideoTrack)type;

Parameters

Return value

Returns 0 on success and an error code on failure.

Enables an external video source.

- (int)setExternalVideoSource:(BOOL)enable sourceType:(AliRtcVideoSource)type renderMode:(AliRtcRenderMode)renderMode;

Parameters

Enter the video data.

- (int)pushExternalVideoFrame:(AliRtcVideoDataSample *_Nonnull)frame sourceType:(AliRtcVideoSource)type;

Parameters

Return value

0 indicates that the method call was successful. A value other than 0 indicates that the call failed.

Starts a bypass live stream.

- (int)startPublishLiveStreamWithURL:(NSString *_Nonnull)streamURL liveTranscoding:(AliRtcLiveTranscodingParam *_Nonnull)trancoding;

Parameters

Return Value

A return value of 0 indicates that the method call was successful. Otherwise, the call failed.

Updates the parameters of a bypass live stream.

- (int)updatePublishLiveStreamWithURL:(NSString *_Nonnull)streamURL liveTranscoding:(AliRtcLiveTranscodingParam *_Nonnull)trancoding;

Parameters

Return value

A return value of 0 indicates that the method call was successful, and a non-zero value indicates that the call failed.

Stops a bypass live stream.

- (int)stopPublishLiveStreamWithURL:(NSString *_Nonnull)streamURL;

Parameters

Returns

0 indicates that the method call was successful. A value other than 0 indicates that the method call failed.

Retrieves the status of the bypass live stream.

- (AliRtcLiveTranscodingState)GetPublishLiveStreamStateWithURL:(NSString *_Nonnull)streamURL;

Parameters

Return Value

Returns the status of the bypass live stream.

Starts a last-mile network quality probe.

- (int)startLastmileDetect:(AliRtcNetworkQualityProbeConfig *_Nonnull)config;

Parameters

Returns

0 indicates success. A value other than 0 indicates failure.

Stops network quality probing.

- (int)stopLastmileDetect;

Response Description

0 indicates success. Any other value indicates failure.

Sends Supplemental Enhancement Information (SEI).

- (int)sendMediaExtensionMsg:(NSData *_Nonnull)data repeatCount:(int)repeatCount delay:(int)delay isKeyFrame:(bool)isKeyFrame;

The SDK lets you send and receive media extension information. This method sends media extension information using the SEI protocol. Subscribers can obtain the information by listening for the onMediaExtensionMsgReceived callback.

Common use cases include the following:

• Transmitting timestamps to calculate end-to-end network latency or synchronize data with other business operations.

• Transmitting descriptive information. You can send up to 4 KB of data, which is suitable for transferring small amounts of data. We recommend using the JSON or plain string format.

When to call

Call this method after you start to publish the stream.

Limits

Media extension information reuses the audio and video data channel. Therefore, you must control the sending frequency and the length of the message data. The usage limits are as follows:

• The maximum number of messages that you can send per second is equal to the frames per second (fps) set in the profile. This is because SEI is transmitted within the H.264/H.265 stream, and the extension information can only be attached during video frame encoding.

• To avoid affecting media transmission quality, the message body is limited to 4 KB.

• The repeatCount parameter in the sendMediaExtensionMsg function specifies the redundancy for the message. If you set this parameter to a value greater than 1, the message is sent multiple times.

• Sending a message multiple times helps prevent message loss from network packet loss. However, subscribers in the channel will also receive multiple identical messages and must perform deduplication.

• If you send media extension messages during a bypass live stream, subscribers in the channel will also receive the messages.

• Only one media extension message can be transmitted at a time. If you call sendMediaExtensionMsg multiple times, the new data overwrites the previous data.

Related callbacks

After the publisher sends media extension information, subscribers can obtain the information by listening for the onMediaExtensionMsgReceived callback.

Parameters

Return value

0 indicates success, and other values indicate failure.

Sends media extension information using Supplemental Enhancement Information (SEI) at the underlying layer.

- (int)sendMediaExtensionMsgEx:(NSData *_Nonnull)data repeatCount:(int)repeatCount delay:(int)delay isKeyFrame:(bool)isKeyFrame payloadType:(int)payloadType;

The SDK lets you send and receive media extension information. This method sends the information, and receivers can obtain it by listening for the onMediaExtensionMsgReceived callback. If the payloadType parameter is set to 5, this method is equivalent to the sendMediaExtensionMsg interface.

Common use cases include the following:

• Transmitting timestamps to calculate end-to-end network latency or synchronize data with other business operations.

• Transmitting descriptive information. You can send up to 4 KB of data, which is ideal for transferring small amounts of information in JSON or plain string format.

When to call

You can call this method after you publish a stream.

Limits

Media extension information reuses the audio and video data channel. Therefore, you must control the sending frequency and message data length. The limits are as follows:

• The maximum number of messages that you can send per second is limited by the frames per second (fps) that is set in the profile. This is because SEI information is transmitted in the H.264 or H.265 stream, and video frame encoding is required to attach the extension information.

• To avoid affecting media transmission quality, the message body is limited to 4 KB. This size is suitable for transmitting small amounts of information.

• The repeatCount parameter specifies the number of redundant transmissions for the message. If this parameter is set to a value greater than 1, the message is sent multiple times.

• This redundancy helps prevent message loss that is caused by network packet loss. However, subscribers in the channel receive multiple identical messages and must perform deduplication.

• If you send custom messages during a bypass live stream, subscribers in the channel also receive the messages.

• Only one MediaExtensionMsg can be transmitted at a time. If you call sendMediaExtensionMsg multiple times, the new data overwrites the previous data.

Parameters

Return values

• 0: The call was successful.

• <0: The call failed. An error code is returned.

  • ERR_INNER(-1): Internal SDK error. Possible causes include that the SDK is not initialized or the method is called after the SDK is destroyed.

This callback is triggered when the network connection status changes.

- (void)onConnectionStatusChange:(AliRtcConnectionStatus)status reason:(AliRtcConnectionStatusChangeReason)reason;

Parameters

A callback for exceptions that occur on the local device. You must handle the exceptions that are reported in this callback.

- (void)onLocalDeviceException:(AliRtcLocalDeviceType)deviceType exceptionType:(AliRtcLocalDeviceExceptionType)exceptionType message:(NSString *_Nullable)msg;

Parameters

This callback is triggered when the user authentication information is about to expire. The authentication expires 30 seconds after this callback is received.

- (void)onAuthInfoWillExpire;

After you receive this callback, you must obtain a new token and update the authentication information in one of the following ways:

• Call the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#e6a4495191bmd" id="918ba91977wi6">refreshAuthInfo</a> API to update the authentication information.

• Call <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#449873b819cz2" id="ad8235d30dprb">leaveChannel</a> to leave the current channel, and then call joinChannel to rejoin the channel.

Trigger time

The SDK triggers this callback 30 seconds before the user's authentication information expires. You must update the authentication information promptly after you receive this callback.

This callback is triggered when a user calls an interface that requires authentication, but the authentication information has expired.

- (void)onAuthInfoExpired;

This callback indicates that the user's authentication information has expired. To continue in the meeting, you need to generate a new token on the server and then update the authentication information using the following method:

• Call <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#449873b819cz2" id="21390e77a1307">leaveChannel</a> to leave the current channel, and then call joinChannel to rejoin the channel.

Trigger time

This callback is triggered when the user's authentication information expires.

This callback reports the result of joining a channel. It is the asynchronous result of the joinChannel method call and is used to handle events after the user joins the channel.

- (void)onJoinChannelResult:(int)result channel:(NSString *_Nonnull)channel elapsed:(int) elapsed;

Trigger condition

When the application calls the joinChannel method, this callback reports whether the user successfully joined the channel and provides the time elapsed for the operation.

Parameters

This callback is returned after the leaveChannel interface is called, providing the result of leaving the channel. It is not triggered if destroy is called immediately after leaveChannel.

- (void)onLeaveChannelResult:(int)result stats:(AliRtcStats)stats;

Parameters

A callback that is triggered when a remote user goes offline.

- (void)onRemoteUserOffLineNotify:(NSString *_Nonnull)uid offlineReason:(AliRtcUserOfflineReason)reason;

This callback notifies the local user that a remote user has left the channel for various reasons. This callback is triggered when a remote user goes offline.

Trigger conditions

• The callback is triggered when a remote user actively leaves the channel.

• This callback is triggered when a remote streamer calls <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#892915dd4edcy" id="78b1952ad5lwp">setClientRole</a> to switch their role to viewer (`AliRtcClientRolelive`).

• The callback is triggered when the remote streamer is considered dropped because no data has been received for an extended period.

Parameters

A callback that is triggered when a remote user goes online.

- (void)onRemoteUserOnLineNotify:(NSString *_Nonnull)uid elapsed:(int)elapsed;

This callback notifies the local client that a remote user has joined the channel.

Trigger conditions

• A remote user successfully joins the channel.

• After the local user joins the channel, this callback is triggered for each remote user who is already in the channel. This provides the local user with a list of existing users.

Parameters

A callback that is triggered when a remote user's stream changes.

- (void)onRemoteTrackAvailableNotify:(NSString *_Nonnull)uid audioTrack:(AliRtcAudioTrack)audioTrack videoTrack:(AliRtcVideoTrack)videoTrack;

This callback is triggered when a remote user's stream ingest status changes. Developers can use this callback to determine in real time whether a remote user is publishing audio and video streams and then display or hide the remote user's audio and video information on the interface accordingly.

Trigger conditions

This callback is triggered in the following scenarios:

• When a remote user starts publishing a stream (audio and/or video).

• When a remote user stops publishing a stream (audio and/or video).

• In interactive mode, when a remote user calls setClientRole to switch from a viewer to a streamer and starts publishing a stream.

For example, if a remote user disables video stream ingest, this callback does not trigger:

• When the remote user starts publishing the camera stream (stream ingest status changes from no video stream to only camera stream), the callback returns AliRtcVideoTrackCamera. This indicates that the remote user's camera stream is available.

• When the remote user also publishes the screen sharing stream (stream ingest status changes from only camera stream to camera stream and screen sharing stream), the callback returns AliRtcVideoTrackBoth. This indicates that both the remote user's camera stream and screen sharing stream are available.

• When the remote user stops publishing the camera stream but continues to publish the screen sharing stream (stream ingest status changes from camera stream and screen sharing stream to only screen sharing stream), the callback returns AliRtcVideoTrackScreen. This indicates that only the screen sharing stream is available.

• When the remote user also stops publishing the screen sharing stream (stream ingest status changes from only screen sharing stream to no video stream), the callback returns AliRtcVideoTrackNo. This indicates that no video stream is available.

Parameters

A callback that is triggered when you are removed from the server or the channel is closed.

- (void)onBye:(int)code;

This callback is triggered when a user is disconnected or the meeting ends. You can use the code parameter to determine the reason for the disconnection and take appropriate action.

Trigger conditions

• The current user is removed from the server.

• The meeting ends because the server closes the channel.

• An unexpected disconnection occurs, which requires the client to attempt to restore the session or reconnect.

Parameters

Callback for changes in the audio stream ingest state.

- (void)onAudioPublishStateChanged:(AliRtcPublishState)oldState newState:(AliRtcPublishState)newState elapseSinceLastState:(NSInteger)elapseSinceLastState channel:(NSString *_Nonnull)channel;

This callback is triggered when the audio stream ingest state of the local user changes.

Triggers

This callback is triggered when the user's audio stream ingest state changes. For example:

• Stream ingest stops.

• The user calls <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#892915dd4edcy" id="81771ef0798we">setClientRole</a> to switch their role to viewer.

Parameters

Callback for audio subscription state changes.

- (void)onAudioSubscribeStateChanged:(NSString *_Nonnull)uid oldState:(AliRtcSubscribeState)oldState newState:(AliRtcSubscribeState)newState elapseSinceLastState:(NSInteger)elapseSinceLastState channel:(NSString *_Nonnull)channel;

This callback notifies the local user that the subscription state of a remote user's audio stream has changed. The callback provides the new subscription state and the time elapsed since the previous state.

Parameters

Occurs when a user mutes their audio.

- (void)onUserAudioMuted:(NSString *_Nonnull)uid audioMuted:(BOOL)isMute;

Parameters

This notification is triggered when a user's audio is interrupted, for example, when it is preempted by an incoming phone call.

- (void)onUserAudioInterruptedBegin:(NSString *_Nonnull)uid;

Parameters

Occurs when a user's audio interruption ends. This callback corresponds to onUserAudioInterruptedBegin.

- (void)onUserAudioInterruptedEnded:(NSString *_Nonnull)uid;

Parameters

Callback for changes in the video stream ingest state.

- (void)onVideoPublishStateChanged:(AliRtcPublishState)oldState newState:(AliRtcPublishState)newState elapseSinceLastState:(NSInteger)elapseSinceLastState channel:(NSString *_Nonnull)channel;

This callback is triggered when the ingest state of the local user's video stream changes.

Parameters

Callback for camera stream subscription state changes.

- (void)onVideoSubscribeStateChanged:(NSString *_Nonnull)uid oldState:(AliRtcSubscribeState)oldState newState:(AliRtcSubscribeState)newState elapseSinceLastState:(NSInteger)elapseSinceLastState channel:(NSString *_Nonnull)channel;

This callback notifies the local user that the subscription state of a remote user's camera stream has changed. This callback provides the new subscription state and the time elapsed since the previous state.

Related callbacks

A video stream primarily consists of a camera stream and a screen sharing stream. This interface reports changes in the subscription state of a camera stream. The corresponding callback interface for a screen sharing stream is onScreenShareSubscribeStateChanged.

Parameters

A notification that a user has muted their video.

- (void)onUserVideoMuted:(NSString *_Nonnull)uid videoMuted:(BOOL)isMute;

Parameters

Occurs when local video capture is disabled or re-enabled.

- (void)onUserVideoEnabled:(NSString *_Nullable)uid videoEnabled:(BOOL)isEnable;

Parameters

Occurs when a remote user's application moves to the background.

- (void)onUserWillResignActive:(NSString *_Nonnull)uid;

Parameters

Occurs when a remote user's application returns to the foreground.

- (void)onUserWillBecomeActive:(NSString *_Nonnull)uid;

Parameters