ApsaraVideo Live:AliRtcEngine Interface

Creates an AliRtcEngine instance using the singleton pattern.

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

When to call

Call this method before calling any other ARTC SDK APIs to create an AliRtcEngine instance.

Limitations

• This method is synchronous and must be called on the main thread.

• The SDK supports only one AliRtcEngine instance per app.

Related callbacks

Implement the callbacks in AliRtcEngineDelegate based on your use case when creating the engine instance. If the SDK encounters an exception during operation, it first attempts internal retries to recover automatically. For errors that cannot be resolved internally, the SDK notifies your application through predefined callbacks. The following are key callbacks that require application-level handling:

Parameters

Destroys the AliRtcEngine instance.

+ (void)destroy;

Destroys the AliRtcEngine singleton object. After you invoke this method, all internally used resources are released. You cannot use any other AliRtcEngine methods or callbacks. To use AliRtcEngine again, you must invoke <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.

This method and destroy[2/2] both destroy engine instances, but the difference is that destroy[2/2] lets you pass in a monitor object for completion of destruction.

When to call

Call this method to release the instance after real-time communication ends (that is, when you no longer need AliRtcEngine functionality). This reduces unnecessary resource usage.

Limitations

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

Destroys the AliRtcEngine instance.

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

Destroys the AliRtcEngine singleton object. After you invoke this method, all resources that the object uses internally are released. You can no longer use any other AliRtcEngine methods or any callbacks. To use AliRtcEngine again, you must invoke <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

We recommend calling this method to release the instance after completing real-time communication.

Limitations

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

Parameters

Specify whether to enable the HTML5 compatibility mode.

+ (void)setH5CompatibleMode:(BOOL)comp;

Parameters

Queries whether the HTML5 compatibility mode is enabled.

+ (BOOL)getH5CompatibleMode;

Return Description

A value of YES indicates that the HTML5 compatibility mode is enabled. A value of NO indicates that the HTML5 compatibility mode is disabled.

Retrieves the SDK version number.

+ (NSString *_Nonnull)getSdkVersion;

Return value

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

Notes

This is a static method. You can call it at any time to retrieve the version number.

Sets the channel mode.

- (int)setChannelProfile:(AliRtcChannelProfile)profile;

This method sets the channel profile. Two primary profiles are available:

• Communication profile: All users act as streamers and can both publish and subscribe streams.

• Interactive live streaming profile: 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 client role. Set the role of users who ingest streams in the channel to streamer (AliRTCSdkInteractive). If a user only needs to pull streams and does not ingest streams, set their role to viewer (AliRTCSdkLive). This profile is recommended for RTC scenarios.

When to call

You can call this method only before joining a channel. You cannot change the profile while in a channel. You can change it after leaving the channel.

Parameters

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Sets the audio profile.

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

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

When to call

You can call this method only before joining a channel. You cannot change it after joining. You can change it after leaving the channel.

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Queries whether the audio-only mode is enabled.

- (BOOL)isAudioOnly;

Return description

A value of YES indicates that the audio-only mode is enabled. A value of NO indicates that the audio-video mode is enabled.

Enables the audio-only mode or the audio-video mode.

- (int)setAudioOnlyMode:(BOOL)audioOnly;

Parameters

Return instructions

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Join a channel (that is, join the meeting).

- (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 joins a channel. ARTC organizes users into channels. Users must join a channel to publish or subscribe to audio and video streams. This method, along with joinChannel[2/3] and joinChannel[3/3], can be used to join a channel. The differences lie in authentication method and user information passed:

• This is a single-parameter join method. Pass a token generated using Token authentication. We recommend this method for RTC scenarios.

• joinChannel[2/3] is a multi-parameter join method. Pass a token generated using Token authentication, and also pass the user information used to generate the token.

• joinChannel[3/3] is for AI real-time interaction scenarios. Pass a single-parameter token and set the user property capabilityProfile according to the scenario.

When to call

Call this method after creating the engine instance.

Limitations

• After you successfully join a channel, to join another channel mid-session, 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 and ensure that 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 before you join a channel again.

• This method supports joining only one channel at a time.

• Apps with different App IDs cannot interoperate.

• No need to call this method when retrying after a failed join.

Related callbacks

After successfully calling this method, the following callbacks are triggered:

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

• After you successfully join the channel, the remote side triggers 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

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Join a channel, which is a multi-participant session.

- (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 joins a channel. ARTC organizes users into channels. Users must join a channel to publish or subscribe to audio and video streams. This method, along with joinChannel[1/3] and joinChannel[3/3], can be used to join a channel. The differences lie in authentication method and user information passed:

• joinChannel[1/3] is a single-parameter join method. Pass a token generated using Token authentication. We recommend this method for RTC scenarios.

• This is a multi-parameter join method. Pass a token generated using Token authentication, and also pass the user information used to generate the token.

• joinChannel[3/3] is for AI real-time interaction scenarios. Pass a single-parameter token and set the user property capabilityProfile.

Limitations

• To switch channels after joining one, 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 your 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="9e6478b2f0hen">onLeaveChannelResult</a> callback.

• This method supports joining only one channel at a time.

• Apps with different App IDs cannot interoperate.

Related callbacks

After successfully calling 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 user joining the channel.

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

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 joins a channel. ARTC organizes users into channels. Users must join a channel to publish or subscribe to audio and video streams. This method, along with joinChannel[1/3] and joinChannel[2/3], can be used to join a channel. The differences lie in authentication method and user information passed:

• joinChannel[1/3] is the RTC scenario single-parameter join method. Pass a token generated using Token authentication. We recommend this method for RTC scenarios.

• joinChannel[2/3] is a multi-parameter join method. Pass a token generated using Token authentication, and also pass the user information used to generate the token.

• This method is for AI real-time interaction scenarios. Pass a single-parameter token and set the user property capabilityProfile. When communicating with AI agents, set this to AliRtcCapabilityProfileAiHuman.

Limitations

• After you successfully join a channel, to join another one, 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 and ensure that 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 before you can join another channel.

• This method supports joining only one channel at a time.

• Apps with different App IDs cannot interoperate.

• No need to call this method when retrying after a failed join.

Related callbacks

After successfully calling this method, the following callbacks are triggered:

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

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

Parameters

Leaves a channel.

- (int)leaveChannel;

After calling this method, the SDK terminates real-time communication and leaves the current channel.

When to call

• Call this method when you need to leave a channel after joining.

• If you have joined a channel and need to join another channel, call this method first.

Related callbacks

• Local user: After this method is called, the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#3721f1f2a3kpd" id="ea2e36a41csu0">onLeaveChannelResult</a> callback is triggered to report the result of leaving the channel.

• Remote side: After you successfully call this operation, remote users trigger the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#34876c27d7zv7" id="a50f534f21mew">onRemoteUserOffLineNotify</a> callback.

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Checks whether you are in a channel.

- (BOOL)isInCall;

Return description

A value of YES indicates that you are in the channel. A value of NO indicates that you are not in the channel.

Specifies the user role.

- (int)setClientRole:(AliRtcClientRole)role;

This method sets the user role as streamer or viewer.

In interactive mode, before joining a channel:

• Set the user role to streamer: The SDK automatically publishes local audio and video streams and subscribes to other streamers' streams.

• Set the user role to viewer: The SDK does not publish local audio or video streams, but subscribes to other streamers' streams.

When to call

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

Limitations

This method is effective only in interactive mode, that is, when you 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.

We recommend explicitly setting the user role before joining in interactive mode.

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Queries the role of a user. This method applies only to iOS.

- (AliRtcClientRole)getCurrentClientRole;

Return Value

The user role is returned.

Refreshes the authentication information.

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

This method updates authentication information. Tokens expire after a period, and the SDK will fail to connect to the server once expired.

When to call

In the following cases:

• 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 your authentication information is about to expire, we recommend that you regenerate the token server-side and then call this method to pass in 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 to indicate that authentication has expired. At this point, you must regenerate the token and then call joinChannel to rejoin the channel.

Parameters

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Refreshes the authentication information.

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

This method updates the token. Tokens expire after a period, and the SDK will fail to connect to the server once expired.

When to call

We recommend regenerating the token on your server and calling this method with the new token in the following case:

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

Parameters

Return description

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

Specifies whether to publish an audio track.

- (int)publishLocalAudioStream:(BOOL)enable;

This method controls whether to publish locally captured audio. By default, the SDK publishes audio. If you do not want to publish audio by default, call publishLocalAudioStream(false) before joining the channel.

When to call

You can call this method before or after joining a channel. Calling it before joining modifies the default configuration and takes effect at join time.

Related callbacks

When the state of local audio stream ingest 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 ingest state, and the remote client triggers 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 a remote user's audio and video streams.

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Queries whether an audio track is published.

- (BOOL)isLocalAudioStreamPublished;

Return Description

YES indicates that push is allowed. NO indicates that push is not allowed.

Set the default behavior for accepting audio streams.

- (int)setDefaultSubscribeAllRemoteAudioStreams:(BOOL)sub;

This method configures whether the system subscribes to remote users' audio tracks by default. This setting affects subscription behavior for users who join the channel later. Unless you have specific requirements, set this to true.

When to call

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

• Before joining:

  • The SDK subscribes to remote users' audio tracks by default when joining a channel. To change this behavior, call this method before joining.

• After joining:

  • If you want to stop the default subscription, you can call <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#8b515d9855osk" id="a467e60e4eyhk">setDefaultSubscribeAllRemoteAudioStreams</a>(false). The system will not subscribe to audio streams from users who join the channel later.

  • After you stop the default subscription, if you want to resume subscribing to the audio stream of a specified user, call the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#c8249fb568gms" id="9806dd9a750pf">subscribeRemoteAudioStream</a> API. If you want to resume subscribing for multiple users, call it 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) only resumes the audio streams of users who join the channel afterward, and does not subscribe to the audio streams of remote users who joined while the subscription was stopped.

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Subscribes to or stops subscribing to the audio track of a specific remote user.

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

Use this interface to stop or resume the audio stream from a specific remote user. For most scenarios, set this parameter to true.

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Subscribes to or stops subscribing to the audio tracks of all remote users.

- (int)subscribeAllRemoteAudioStreams:(BOOL)sub;

This method is the master switch for subscribing to remote audio tracks. We recommend setting it to YES. Setting it to NO causes the following:

• Remote audio tracks in the current session are no longer subscribed.

• New users who join later are not 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 specified user.

To resume the subscription, call this method again with the sub parameter set to YES.

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Specifies whether to publish a video track.

- (int)publishLocalVideoStream:(BOOL)enable;

This method controls the publishing of the video that is captured locally.

When to call

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

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

Related callbacks

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

Parameters

Queries whether a video track is published.

- (BOOL)isLocalVideoStreamPublished;

Return description

A value of YES indicates that the video track is published. A value of NO indicates that the video track is not published.

You can set whether to accept video streams by default.

- (int)setDefaultSubscribeAllRemoteVideoStreams:(BOOL)sub;

By default, the SDK subscribes to remote users’ video tracks. Use this method to change that behavior.

When to call

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

• Before joining:

  • You can use this method to disable the default subscription.

• After joining:

  • To disable the default subscription, call setDefaultSubscribeAllRemoteVideoStreams(false). You will also no longer automatically subscribe to the audio streams of users who join the channel later.

  • After you stop the default subscription, you can call the subscribeRemoteVideoStream interface to resume subscribing to the audio stream of a specific user. To resume subscribing to multiple users, call this interface once for each user.

  • After you stop the default subscription, calling setDefaultSubscribeAllRemoteVideoStreams(false) restores only the audio streams for users who join the channel afterward.

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Stop or resume subscribing to video streams from remote users.

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

You can subscribe to or unsubscribe from the video stream of a specified user.

When to call

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

Description

Subscribes to or stops subscribing to the video tracks of all remote users.

- (int)subscribeAllRemoteVideoStreams:(BOOL)sub;

This method serves as the master switch for subscribing to remote video streams. Setting sub to false causes:

• All remote video streams in the current session to stop being subscribed to.

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

• 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 individually control the audio stream for a specific user.

To resume subscription, call this method again with sub set to true.

Parameters

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Stop or resume the media stream from a specific remote user.

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

This interface merges subscribed remote audio and video streams.

Related API operations

Unlike subscribeRemoteMediaStream[2/2], this interface uses two Boolean parameters—subVideo and subAudio—to control whether to subscribe to remote video and audio streams, and the videoTrack parameter specifies which video stream to pull.

Note: In this API, the AliRtcVideoTrackNo of AliRtcVideoTrack is invalid, and setting it has no effect.

Parameters

Response description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

You can stop or resume the media stream from a specific remote user.

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

This interface merges subscribed remote audio and video streams.

Related APIs

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

• To subscribe to camera and microphone streams, set videoTrack to AliRtcVideoTrackCamera and audioTrack to AliRtcAudioTrackMic when you invoke the method.

• If you want to unsubscribe from the camera stream but keep the microphone, set AliRtcVideoTrackNo and AliRtcAudioTrackMic to the videoTrack and audioTrack parameters, respectively, when you invoke the method again.

• If you want to cancel all tracks, set videoTrack and audioTrack to AliRtcVideoTrackNo and AliRtcAudioTrackNo, respectively, when you invoke it again.

• To subscribe to both camera and screen sharing streams, set videoTrack to AliRtcVideoTrackBoth. Audio works similarly.

Parameters

Return description

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

Subscribes to or stops subscribing to the media stream of a specific remote user across channels.

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

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Subscribes to all user streams in the target channel.

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

Parameters

Return value

0 indicates success. Any other value indicates failure.

You can set the volume of remote audio.

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

Parameters

Return value

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

Stop or resume the transmission of local audio data.

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

When to call

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

Related callbacks

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

Parameters

Return values

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

You can stop or resume 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 API stops or resumes playback of audio from a specified remote user but does not affect stream pulling or decoding of the remote audio. 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 Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

You can stop or resume all remote audio playback.

- (int)muteAllRemoteAudioPlaying:(BOOL)mute;

This API stops or resumes playback of all remote audio.

When to call

You can configure this setting before or after you join a channel.

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Starts audio collection.

- (void)startAudioCapture;

This method starts audio capture. 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 manages the audio capture device. After you call stopAudioCapture to stop audio capture, you can call this method again to restart it.

When to call

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

Related methods

startAudioCapture[2/2] API controls whether the audio capture device remains enabled after you leave the meeting, based on the specified parameters.

Related callbacks

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

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Starts audio collection.

- (void)startAudioCapture:(BOOL)keepAlive;

Disables microphone capture after muting.

This method starts audio capture. You can call it before joining a channel to begin audio capture early. If you do not call this method, the SDK automatically manages the audio capture device.

When to call

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

Related methods

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

Related callbacks

After calling this method to change the local audio capture status, you can obtain status updates through the onLocalAudioStateChanged callback.

Parameters

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Stops audio collection.

- (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> to enable audio capture from an audio device, you can call this method to stop audio capture.

Related callbacks

After calling this method to modify the local audio capture status, you can retrieve status changes via the onLocalAudioStateChanged callback.

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Sets the headset or speaker as the audio output device. This method applies only to iOS.

- (int)enableSpeakerphone:(BOOL)enable;

This method sets the audio playback device to either the speaker or headset after you join a channel. If you do not call this method, the SDK uses the default audio route.

The SDK defines an internal priority order for audio routing and automatically switches based on connected peripherals: Wired headset > Bluetooth headset > User setting > Default setting. Therefore, this method has no effect when peripherals are connected. For more information, see Audio routing settings.

When to call

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

Related methods

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 routing settings and sets the current audio output device.

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Queries whether the current audio output device is the headset or the speaker. This method applies only to iOS.

- (BOOL)isEnableSpeakerphone;

Return Description

A value of YES indicates that the current audio output device is the speaker. A value of NO indicates that the current audio output device is the headset.

Set the volume callback interval and smoothing factor.

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

This method enables the SDK to periodically report volume information for local publishing users and the remote user with the highest instantaneous volume.

When to call

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

Related callbacks

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

• The SDK reports the volume for speaking users through the onAudioVolumeCallback callback. The callback frequency depends on the interval parameter.

• For voice activity detection, when an active speaker is detected, the SDK reports their UID through the onActiveSpeaker callback.

Parameters

Return value

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

You can enable in-ear monitoring.

- (int)enableEarBack:(BOOL)enable;

This method enables or disables in-ear monitoring. For optimal results, we recommend enabling in-ear monitoring when using wired or Bluetooth headphones.

When to call

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

Parameter description

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Sets the in-ear monitoring volume.

- (int)setEarBackVolume:(NSInteger)volume;

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

When to call

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

Parameters

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

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, while any other value indicates failure.

Sets the recording volume.

- (int)setRecordingVolume:(NSInteger)volume;

Parameters

Return value

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

Plays an audio file.

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

Parameters

Return value

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

Stops playback of an audio file.

- (int)stopAudioFileTest;

Return value

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

Enable audio capture device detection before a call.

- (void)startAudioCaptureTest;

Detect the audio collection device before terminating the call.

- (void)stopAudioCaptureTest;

Sets the default audio output to the speaker. By default, audio plays through the speaker.

- (int)setDefaultAudioRouteToSpeakerphone:(BOOL)defaultToSpeakerphone;

This method configures the default audio route device before you join a channel. You can route audio to either the headset or the speaker. The SDK uses the speaker by default. To change this behavior, call this method before joining the channel.

The SDK defines a fixed priority order for audio routing and performs automatic switchover based on the current peripheral connection status. The priority order is as follows: wired headset > Bluetooth headset > user settings > default settings. Therefore, if no peripherals are connected and you have not configured audio routing through <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#f7d0d8b64fzkz" id="30798b686b5qk">enableSpeakerphone</a>, the SDK applies the default settings.

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

Mobile devices typically support two audio routes: headset and speaker:

• When using the headset, sound is quieter and requires holding the phone close to your ear. This provides better privacy and is suitable for phone calls.

• When using the speaker, sound is louder and audible without holding the phone to your ear. This enables hands-free operation.

Related methods

This API modifies the default audio routing settings. 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 audio routing device.

When to call

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

Parameters

Return value

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

Sets the voice change mode.

- (int)setAudioEffectVoiceChangerMode:(AliRtcAudioEffectVoiceChangerMode)mode;

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Sets the audio pitch.

- (int)setAudioEffectPitchValue:(double)value;

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Sets the reverberation mode.

- (int)setAudioEffectReverbMode:(AliRtcAudioEffectReverbMode)mode;

Parameters

Response description

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

You can set the reverb effect type and specific parameters.

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

Parameters

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Sets a predefined voice beautification effect mode.

- (int)setAudioEffectBeautifyMode:(AliRtcAudioEffectBeautifyMode)mode;

This method configures built-in voice beautification modes in the SDK. It is suitable for scenarios such as voice live streaming, karaoke, and voice-based social apps where voice quality enhancement is required. Selecting different beautification modes alters the perceived vocal characteristics—for example, enhancing richness or clarity—to improve the listening experience for remote users.

When to call

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

Parameters

Return Description

• 0: Success.

• Non-zero: Failure.

Sets audio equalizer (EQ) parameters to adjust the gain for specified frequency bands.

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

This method applies graphic equalizer adjustments to locally captured voice or audio signals. You can adjust the gain in decibels (dB) for ten fixed frequency bands to customize the tonal quality. This method is suitable for optimizing speech clarity, enhancing voice quality, and reducing noise.

The equalizer supports full-spectrum adjustments from 31 Hz to 16 kHz across ten standard frequency bands. The gain for each band can be adjusted independently from -15 dB to 15 dB. The default gain is 0 dB, which indicates no boost or attenuation.

Limitations

• You must enable voice beautification by calling setAudioEffectBeautifyMode before using the equalizer.

Parameters

Return description

0: Success.

Non-zero: Failure.

Adds an external audio track.

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

To add an external 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="c310321e9eu35">addExternalAudioStream</a> interface to add the external audio stream and retrieve its ID.

2. Call pushExternalAudioStream to feed audio data into the 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 capture.

Parameters

Return description

A value greater than 0 indicates that the call is successful and is the ID of the external audio track. A value less than or equal to 0 indicates that the call fails.

Imports external audio data.

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

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

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

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

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

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

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Set the volume for external audio stream ingest.

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

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Queries the volume of external audio for stream ingest.

- (int)getExternalAudioStreamPublishVolume:(int)streamId;

Parameters

Return Description

The valid values of the volume range from 0 to 100. A value less than 0 indicates that the call fails.

Sets the playback volume of external audio.

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

Parameters

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Queries the playback volume of external audio.

- (int)getExternalAudioStreamPlayoutVolume:(int)streamId;

Parameters

Response description

The valid values of the volume range from 0 to 100. A value less than 0 indicates that the call fails.

Delete the external (audio stream).

- (int)removeExternalAudioStream:(int)streamId;

This method removes the external audio stream for the specified streamId and is the counterpart to the addExternalAudioStream method.

When to call

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

Parameters

Return value

0 indicates success. Any other value indicates failure.

Retrieves audio file information.

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

Parameters

You can start accompaniment mixing.

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

Parameters

Return value

0 indicates success. Other values indicate failure.

Stops audio accompaniment mixing.

- (int)stopAudioAccompany;

Return value

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

Set the accompaniment volume.

- (int)setAudioAccompanyVolume:(NSInteger)volume;

Parameters

Return value

0 succeeded; the rest failed.

Sets the publishing volume of the audio accompaniment.

- (int)setAudioAccompanyPublishVolume:(NSInteger)volume;

Parameters

Return value

Returns 0 on success. An error code is returned on failure.

You can retrieve the volume level for publishing the audio accompaniment.

- (int)getAudioAccompanyPublishVolume;

Return value

A value in the range [0, 100] indicates success. Any other value indicates failure.

Sets the local playback volume for the accompaniment.

- (int)setAudioAccompanyPlayoutVolume:(NSInteger)volume;

Parameters

Return value

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

You can retrieve the local playback volume of the accompaniment.

- (int)getAudioAccompanyPlayoutVolume;

Return value

A value in the range of 0 to 100 indicates success, while any other value indicates failure.

Pauses audio accompaniment mixing.

- (int)pauseAudioAccompany;

Return value

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

Resumes audio accompaniment mixing.

- (int)resumeAudioAccompany;

Return value

0 indicates success. Other values indicate failure.

Retrieves the duration of the accompaniment file in milliseconds.

- (int)getAudioAccompanyDuration;

Return value

Returns the accompaniment file duration in milliseconds if successful (>= 0). Returns a value less than 0 if the operation fails.

Retrieve the playback progress of the accompaniment file in milliseconds.

- (int)getAudioAccompanyCurrentPosition;

Return value

A value of 0 or greater indicates the current playback position in milliseconds. A negative value indicates a failure.

Sets the playback position of the accompaniment file.

- (int)setAudioAccompanyPosition:(int)pos;

Parameters

Return value

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

Preloads a sound effect.

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

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Deletes a preloaded sound effect.

- (int)unloadAudioEffectWithSoundId:(NSInteger)soundId;

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Starts the playback of a sound effect.

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

Parameters

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Stops the playback of a sound effect.

- (int)stopAudioEffectWithSoundId:(NSInteger)soundId;

Parameters

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Stops the playback of all sound effects.

- (int)stopAllAudioEffects;

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Pauses the playback of a sound effect.

- (int)pauseAudioEffectWithSoundId:(NSInteger)soundId;

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Pauses the playback of all sound effects.

- (int)pauseAllAudioEffects;

Response description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Resumes the playback of a sound effect.

- (int)resumeAudioEffectWithSoundId:(NSInteger)soundId;

Parameters

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Resumes the playback of all sound effects.

- (int)resumeAllAudioEffects;

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Sets the volume of a sound effect for stream ingest.

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

Parameters

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Queries the volume of a sound effect for stream ingest.

- (int)getAudioEffectPublishVolumeWithSoundId:(NSInteger)soundId;

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

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

- (int)setAllAudioEffectsPublishVolume:(NSInteger)volume;

Parameters

Response description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Sets the volume of a sound effect for local playback.

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

Parameters

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Queries the volume of a sound effect for local playback.

- (int)getAudioEffectPlayoutVolumeWithSoundId:(NSInteger)soundId;

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

You can set the local playback volume of all sound effects.

- (int)setAllAudioEffectsPlayoutVolume:(NSInteger)volume;

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Starts recording media files.

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

Parameters

Return description

A value of TRUE indicates success. Any other value indicates failure.

Stops the recording of media files.

- (void)stopRecord 

Parameters

None.

Sets the rendering view and drawing parameters for local preview.

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

This method sets the local preview view. When you call it, the local video stream is bound to the display view and the rendering mode, mirroring mode, and rotation angle for the local user’s view are configured. It affects only the local preview—not stream ingest. To configure remote users’ views, call setRemoteViewConfig.

When to call

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

Parameter description

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Sets the collection preferences of the camera.

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

This method configures camera capture preferences, such as camera direction and frame rate.

When to call

You must set this before turning on the camera. For example, before:

• startPreview

• joinChannel (Join Channel)

Parameters

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Disables or re-enables local video collection.

- (int)enableLocalVideo:(BOOL)enable;

This method enables or disables local video capture. When disabled, local preview and stream ingest display no video. However, receiving remote video remains unaffected. If you disable local camera capture, local preview and stream ingest freeze on the last frame.

When to call

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

Related callbacks

• After you successfully call this method, the onUserVideoEnabled callback notifies remote users.

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Stop or resume transmitting local video data.

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

Call this method to send black frames while publishing. The local preview continues to display normally. The capture, encoding, and transmission modules remain active, sending only black frames.

Parameter Description

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Sets the rendering view and drawing parameters for the video track of a remote user.

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

This method attaches the display view for a specified remote user's video stream and sets properties for its local display, such as the rendering mode, mirror mode, and rotation angle. This affects only the video image seen by the local user. 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 of AliVideoCanvas: rendering canvas is null, rendering stops.

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

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

When to call

We recommend calling this method when you receive the onRemoteTrackAvailableNotify callback, which is triggered when a remote user's video becomes available.

Parameters

Response description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Queries whether the camera is turned on.

- (BOOL)isCameraOn;

Response description

A value of YES indicates that the camera is turned on. A value of NO indicates that the camera is turned off.

Sets video encoding properties.

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

This method sets video stream encoding parameters, such as resolution, frame rate, bitrate, and orientation. We recommend calling this method for all video scenarios.

When to call

You can call this method before or after joining a channel. To set camera stream encoding properties once per session, we recommend calling it before joining.

Limitations

Both this method and setVideoMirrorMode control video stream mirroring. We recommend using only one. Using both may cause overlapping mirror effects, leading to incorrect behavior.

Parameters

Sets video decoding properties.

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

This method sets the video decoding parameters for the camera stream.

When to call

You can call this method before joining the meeting.

Parameters

Switches between the front and rear cameras. By default, the front camera is used. This method applies only to iOS.

- (int)switchCamera;

This method controls whether the front or rear camera is used. You can dynamically switch cameras during app runtime based on available hardware without restarting the video stream or reconfiguring the video source.

When to call

You can call this method only after the camera has been successfully turned on.

Limitations

This method is supported only on iOS and Android platforms.

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Queries the current camera type. By default, the front camera is used. This method applies only to iOS.

- (AliRtcCameraDirection)getCurrentCameraDirection;

Return description

Returns a camera direction enumeration.

Starts a local preview. The camera is automatically turned on.

- (int)startPreview;

This API enables local video preview and automatically opens the camera. To stop the local preview, call the `stopPreview` API.

When to call

• Before calling this method, you can set the preview view using setLocalViewConfig. Otherwise, the preview fails—but stream ingest remains unaffected.

• You can call this method before joinChannel to start the preview early. The camera starts automatically.

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Stops a local preview.

- (int)stopPreview;

This method stops the local video preview and disables the camera. After stopping, the local preview freezes on the last frame. Stream ingestion is unaffected.

When to call

You can call this method to stop the preview.

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Sets the camera zoom.

 - (int)setCameraZoom:(float)zoom;

Parameters

Return value

Returns 0 on success. Other values indicate failure.

Retrieves the maximum camera zoom factor.

 - (float)GetCameraMaxZoomFactor;

Return value

The maximum camera zoom factor.

Obtains the current camera zoom level.

- (float)GetCurrentZoom;

Return value

The current camera zoom level.

You can set the camera exposure level.

- (int)SetExposure:(float)exposure;

Parameters

Return value

0 indicates success. Any other value indicates failure.

You can obtain camera exposure.

- (float)GetCurrentExposure;

Return value

The exposure level of the camera.

Obtain the minimum camera exposure

- (float)GetMinExposure;

return value

The minimum exposure level for the camera.

Retrieves the maximum camera exposure level.

- (float)GetMaxExposure;

Return value

The maximum camera exposure level.

You can set the camera flash toggle.

- (int)setCameraFlash:(BOOL)flash;

Parameters

Return value

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

Checks whether manual focus is supported.

- (BOOL)isCameraFocusPointSupported;

Return value

Returns TRUE if manual focus is supported, and FALSE otherwise.

Does the camera support setting an exposure point?

- (BOOL)isCameraExposurePointSupported;

Return value

TRUE indicates that setting an exposure point is supported. FALSE indicates that it is not supported.

Sets the manual focus point for the camera.

- (int)setCameraFocusPoint:(CGPoint)point;

Parameters

Return value

Returns 0 on success. Any other value indicates a failure.

Set the exposure value at the specified point.

- (int)setCameraExposurePoint:(CGPoint)point;

Parameters

Return value

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

Does the camera support face focus?

- (BOOL)isCameraAutoFocusFaceModeSupported;

Return value

A value of TRUE indicates that face autofocus is supported, and a value of FALSE indicates that it is not.

You can enable or disable face autofocus.

- (BOOL)setCameraAutoFocusFaceModeEnabled:(BOOL)enable;

Parameters

Return value

A return value of TRUE indicates success. A return value of FALSE indicates failure.

Set the video mirroring mode.

- (int)setVideoMirrorMode:(AliRtcVideoPipelineMirrorMode)mirrorMode;

Sets whether to apply mirroring to the local preview and published video streams.

When to call

You can call this method dynamically before or after joining a channel. The SDK stores the state and applies mirroring during preview or encoding (stream ingest).

Limitations

This method overlaps with setLocalViewConfig and setVideoEncoderConfiguration, both of which support the mirrorMode parameter. We recommend using only this method.

Parameters

You can set the scaling mode for the video link.

-(void)setCapturePipelineScaleMode:(AliRtcCapturePipelineScaleMode)mode;

Specifies whether video data is scaled during capture or during encoding. For example, if the capture resolution differs from the encoding resolution, this setting determines whether the preview data matches the stream ingest data.

When to Call

You must set this method before starting the camera—for example, before calling startPreview or joinChannel.

Parameters

Return value

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

Registers a video data output observer.

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

You can use this method to register an object that exports video data. To unregister, call unregisterVideoSampleWithObserver.

When to call

To obtain raw video data (such as YUV or RGBA format) at various stages, you can call this interface to register a video data monitor.

Related callbacks

After you successfully register a video data output observer, the SDK triggers your implemented callbacks when it captures each video frame. Implement the following callbacks as needed:

• onCaptureVideoSample: Callback for locally captured video data.

• onRemoteVideoSample: Callback for remote video data.

• onPreEncodeVideoSample: Callback for local video data before encoding.

Parameters

You can cancel the video data output object.

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

This interface corresponds 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 data output object.

Parameters

Registers an OpenGL texture observer for local camera video.

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

To retrieve raw video data, call registerVideoSampleObserver. To retrieve internal texture data, call this method. To unregister the observer, call unRegisterLocalVideoTextureObserver.

Related callbacks

After you successfully register an OpenGL texture observer for local camera video, the SDK triggers the callbacks that you implemented in AliRtcTextureObserver each time a video frame is captured. You can implement the following callbacks 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. When an external texture observer is registered, you can process the texture and return the updated texture ID. The return value must be a valid texture ID. If no processing is performed, return the input textureId.

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

Parameters

Unregisters the OpenGL texture observer for the local camera video.

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

This method corresponds to registerLocalVideoTextureObserver and handles its unregistration.

Parameters

Takes a snapshot of the video.

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

Parameters

Return value

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

Specifies whether to enable an external video source.

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

Parameters

Imports external video data.

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

Parameters

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Starts relayed live streaming.

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

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Updates the parameters for relayed live streaming.

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

Parameters

Return Value

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Stop the live streaming bypass.

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

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Queries the status of relayed live streaming.

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

Parameters

Return description

The status of relayed live streaming is returned.

Starts network quality testing.

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

Parameters

Return Description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Stops network quality testing.

- (int)stopLastmileDetect;

Return description

A value of 0 indicates that the call is successful. A value other than 0 indicates that the call fails.

Sets the parameters of the reverberation mode.

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

The SDK supports sending and receiving media extension messages. It sends messages using the Supplemental Enhancement Information (SEI) protocol. Receivers can obtain messages by listening to the onMediaExtensionMsgReceived callback.

Common use cases include the following:

• You can use media extension messages to transmit timestamps for calculating end-to-end network latency or for synchronizing with other business logic.

• You can use media extension messages to transmit descriptive information, with a payload of up to 4 KB. For small payloads, use JSON or plain strings.

When to call

Call this method after stream ingest begins.

Limitations

Media extension messages reuse the audio-video data channel. Therefore, you must control message frequency and size. The following limitations apply:

• The maximum number of messages per second equals the frames per second (FPS) setting in the profile. Because SEI messages are embedded in H.264 or H.265 streams, video frame encoding is required to attach extension data.

• To avoid affecting media transmission quality, the message body size is limited to 4 KB. This limit is suitable for small payloads.

• You can use the sendMediaExtensionMsg function. The repeatCount parameter specifies custom message redundancy. If this parameter is greater than 1, the message is sent multiple times.

• To prevent packet loss from causing message loss, other users in the channel also receive duplicate messages. You must deduplicate them.

• Subscribers in relayed live streaming sessions also receive custom messages.

• Only one MediaExtensionMsg can be transmitted at a time. Multiple calls to sendMediaExtensionMsg cause the data from a new call to overwrite the data from the previous call.

Related callbacks

When the publisher sends media extension messages, subscribers receive them through the onMediaExtensionMsgReceived callback.

Parameter Description

Return value

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

Media extension information is transmitted and implemented at the underlying layer using SEI.

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

The SDK supports sending and receiving media extension messages. This method sends messages using the Supplemental Enhancement Information (SEI) protocol. Receivers can obtain messages by listening to the onMediaExtensionMsgReceived callback. If payloadType is 5, this method functions identically to sendMediaExtensionMsg.

Common use cases include the following:

• You can use media extension messages to transmit timestamps for end-to-end network latency calculation or to synchronize with other business logic.

• You can use media extension messages to transmit descriptive information. Up to 4 KB of data can be sent. For small payloads, use JSON or plain strings.

When to call

You can call after starting stream ingest.

Call Limits

Media extension messages reuse the audio-video data channel. Therefore, you must control the frequency and size of these messages. The limitations are:

• The maximum number of messages per second equals the frames per second (FPS) setting in the profile. Because SEI messages are embedded in H.264 or H.265 streams, video frame encoding is required to attach extension data.

• To avoid affecting media transmission quality, the message body size is limited to 4 KB. This limit is suitable for small payloads.

• The repeatCount parameter of the sendMediaExtensionMsg function defines message redundancy. Values greater than 1 trigger multiple transmissions.

• To prevent packet loss from causing message loss, other users in the channel also receive duplicate messages. You must deduplicate them.

• Subscribers in relayed live streaming sessions also receive custom messages.

• Only one MediaExtensionMsg can be transmitted at a time. Multiple calls to sendMediaExtensionMsg overwrite previous data.

Parameters

Return Description

• 0: Success.

• < 0: Failure. Returns an error code.

  • ERR_INNER (-1): Internal SDK error. Possible causes: The SDK was not initialized or was destroyed before the call.

The callback that is invoked when the network connection status changes.

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

Parameters

The callback that is invoked when a local device exception occurs. Pay attention to this callback.

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

Parameters

The callback that is invoked when user authentication is about to expire. The authentication expires 30 seconds after you receive this callback. Pay attention to this callback.

- (void)onAuthInfoWillExpire;

This callback indicates that user authentication will soon expire. Upon receiving it, authentication expires in 30 seconds. You must generate a new token and update authentication using one of the following methods:

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

The SDK triggers this callback 30 seconds before authentication expires. After you receive it, update authentication promptly.

A user calls an authenticated API, and the server returns a response that has expired.

- (void)onAuthInfoExpired;

This callback indicates that user authentication has expired. To continue the session, generate a new token on your server and update authentication using one of the following methods:

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

When triggered

This callback is triggered when user authentication expires.

This callback reports the result of joining a channel. It is functionally equivalent to the joinChannel method’s blocking operation. You can use either approach to handle the event that occurs after joining the channel.

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

Trigger condition

This callback is triggered when your app calls the joinChannel method. It reports whether the operation succeeded or failed and returns related information, including join latency.

Parameters

This callback is invoked after you call leaveChannel. If you call destroy immediately after leaveChannel, this callback is not triggered.

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

Parameters

The callback that is invoked when a remote user goes offline.

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

This callback notifies local users when a remote user leaves the channel for any reason. It is triggered when a remote user goes offline.

Trigger condition

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

• A remote streamer invokes <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#892915dd4edcy" id="78b1952ad5lwp">setClientRole</a> to switch to the viewer role (AliRtcClientRoleLive), and the callback is triggered.

• The system detects that no data has been received from a remote streamer for an extended period and considers them offline.

Parameters

The callback that is invoked when a remote user goes online.

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

This method is triggered when a remote user joins the channel.

Trigger conditions

• A remote user successfully joins the channel.

• After the local user joins the channel, they receive join callbacks for users who were already in the channel to display previously joined users.

Parameters

The callback that is invoked when the stream of a remote user changes.

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

This callback is triggered when a remote user’s publishing status changes. You can use it to monitor whether remote users are publishing audio and video streams and update the UI accordingly by showing or hiding their media.

Trigger conditions

This callback is triggered in the following cases:

• A remote user transitions from not publishing to publishing audio and/or video.

• A remote user transitions from publishing to not publishing audio and/or video.

• In interactive mode, a remote user calls setClientRole to switch from viewer to streamer while publishing streams.

For example, this callback is not triggered if a remote user disables video stream ingest:

• If a remote user starts publishing camera video (publishing status: no video → camera only), this callback returns AliRtcVideoTrackCamera, indicating that the remote user’s camera stream is available.

• If the same user later publishes screen sharing as well (publishing status: camera only → camera + screen sharing), this callback returns AliRtcVideoTrackBoth, indicating that both camera and screen sharing streams are available.

• If the user stops publishing camera video but continues screen sharing (publishing status: camera + screen sharing → screen sharing only), this callback returns AliRtcVideoTrackScreen, indicating that only the screen sharing stream is available.

• If the user stops publishing screen sharing (publishing status: screen sharing only → no video), this callback returns AliRtcVideoTrackNo, indicating that no video stream is available.

Parameters

The callback that is invoked when a user is forced to leave a channel.

- (void)onBye:(int)code;

This callback is triggered when a user disconnects or the session ends. Developers can use the code parameter to identify the cause and handle it appropriately.

Trigger Conditions

• The user is disconnected by the server.

• The session ends (the server terminates the channel).

• The user is passively disconnected. Clients should attempt session recovery or reconnection.

Parameters

The callback that is invoked when the status of stream ingest for an audio track changes.

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

This callback monitors changes in the local user's audio publishing status.

Trigger conditions

This callback is triggered when the user's audio publishing status changes—for example:

• Stop stream ingest.

• You can invoke <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#892915dd4edcy" id="81771ef0798we">setClientRole</a> to switch to a viewer.

Parameters

The callback that is invoked when the status of subscription to an audio track changes.

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

This callback notifies local users when the subscription status for a remote user's audio stream changes. You can use it to track subscription status changes for a specific remote user's camera stream and the time interval between states.

Parameters

The callback that is invoked when a user mutes the audio track.

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

Parameters

The callback that is invoked when the audio track of a user is interrupted. For example, the audio track may be preempted when the user makes a phone call.

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

Parameters

The callback that is invoked when the audio track interruption for a user ends. This callback is paired with the onUserAudioInterruptedBegin callback.

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

Parameters

The callback that is invoked when the status of the stream ingest for a video track changes.

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

This callback monitors changes to the local user’s video publishing status.

Parameters

The callback that is invoked when the status of subscription to a video track 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 of changes in the subscription status of a remote user's camera stream. It provides the new subscription status and the time elapsed between state changes.

Related callbacks

Video streams include camera streams and screen sharing streams. This callback is triggered by subscription changes to camera streams. Subscription changes to screen sharing streams trigger the onScreenShareSubscribeStateChanged callback.

Parameters

User video mute notification.

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

Parameters

A notification is sent when local video capture is disabled or re-enabled.

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

Parameters

The callback that is invoked when a remote user switches the application to the background.

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

Parameters