AliRtcEngine API reference

Creates a singleton AliRtcEngine instance.

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

When to call

Call this method to create an AliRtcEngine instance before you call any other ApsaraVideo Real-time Communication (ARTC) SDK APIs.

Limits

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

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

Related callbacks

When you create an engine instance, you can 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 its internal retry mechanism. For errors that it cannot resolve on its own, the SDK notifies your application through predefined callback interfaces. The following are key callbacks that the application layer must listen for and respond to because the SDK cannot handle them:

Parameters

Destroys the AliRtcEngine instance.

+ (void)destroy;

This method destroys the AliRtcEngine singleton object. After you call this method, all internal resources are released, and you can no longer use other AliRtcEngine methods 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] can destroy the engine instance. The difference is that `destroy[2/2]` lets you pass a listener object to monitor the completion of the destruction.

When to call

After a real-time communication session ends and you no longer need to use AliRtcEngine features, you can call this method to release the instance and reduce resource usage.

Limits

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

Destroys the AliRtcEngine instance.

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

This method destroys the AliRtcEngine singleton object and releases all internal resources. After you call this method, you can no longer use any other AliRtcEngine methods 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 a real-time communication session ends.

Limits

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

Parameters

Sets whether to enable HTML5 (H5) compatibility.

+ (void)setH5CompatibleMode:(BOOL)comp;

Parameters

Checks whether H5 compatibility mode is enabled.

+ (BOOL)getH5CompatibleMode;

Return value

YES indicates that H5 compatibility is enabled. NO indicates that H5 compatibility is not enabled.

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. You can retrieve the version number at any time.

Configure the channel mode.

- (int)setChannelProfile:(AliRtcChannelProfile)profile;

This method sets the channel profile. The SDK provides profiles for video calls and interactive streaming:

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

• Interactive stream mode: 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. Users who ingest streams in the channel must be set to the streamer role (AliRTCSdkInteractive), while users who only pull streams must be set to the viewer role (AliRTCSdkLive). This mode is recommended for Real-Time Communication (RTC) scenarios.

When to call

This method can only be called before you join a channel. It cannot be reset during a session. You can set it again after you leave the channel.

Parameters

Returns

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

Sets the audio profile.

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

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

When to call

This method can only be called before you join a channel. It cannot be reset after you join. You can set it again after you leave the channel.

Parameters

Return value

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

Checks whether the current mode is audio-only.

- (BOOL)isAudioOnly;

Response Description

YES indicates audio-only mode. NO indicates audio and video mode.

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

- (int)setAudioOnlyMode:(BOOL)audioOnly;

Parameters

Returns

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

Joins a channel (single-parameter authentication).

- (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 allows a user to join a channel. ARTC organizes users into channels. Users must join a channel to publish or subscribe to audio and video streams. This method, joinChannel[2/3], and joinChannel[3/3] can all be used to join a channel. They differ in their authentication methods and the user information they pass.

• This method uses single-parameter authentication. You must pass a token that is generated for single-parameter authentication to join a channel. For more information, see Token-based authentication. This method is recommended for RTC scenarios.

• joinChannel[2/3] uses multi-parameter authentication. You must pass a token that is generated for multi-parameter authentication and the corresponding user information that is used to generate the token. For more information, see Token-based authentication.

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

When to call

You can call this method after you create the engine instance.

Limits

• After you join a channel, to switch to 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 call the join method again 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.

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

• Applications with different App IDs cannot interoperate.

• Do not call this method to retry joining a channel if the initial attempt fails.

Related callbacks

Calling this method successfully triggers the following callbacks:

• 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 user joining the 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="4b11b846b1f4t">onRemoteUserOnLineNotify</a> callback is triggered on the remote client.

Parameters

Return value

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

Join a channel for a multi-party call.

- (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 allows a user to join a channel. ARTC organizes users into channels. Users must join a channel to publish or subscribe to audio and video streams. This method, joinChannel[1/3], and joinChannel[3/3] can all be used to join a channel. They differ in their authentication methods and the user information they pass.

• joinChannel[1/3] uses single-parameter authentication. You must pass a token that is generated for single-parameter authentication to join a channel. For more information, see Token-based authentication. This method is recommended for RTC scenarios.

• This method uses multi-parameter authentication. You must pass a token that is generated for multi-parameter authentication and the corresponding user information that is used to generate the token. For more information, see Token-based authentication.

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

Limits

• After you successfully join a channel, to switch to 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 one. 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 supports joining only one channel at a time.

• Applications with different App IDs cannot interoperate.

Related callbacks

Calling this method successfully triggers the following callbacks:

• The <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#e6d2a213d7sl2" id="df00346ea8928">onJoinChannelResult</a> callback notifies you of the result of the 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="c3832e71e8vck">onRemoteUserOnLineNotify</a> callback is triggered on the remote client.

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 allows a user to join a channel. ARTC organizes users into channels. Users must join a channel to publish or subscribe to audio and video streams. This method, joinChannel[1/3], and joinChannel[2/3] can all be used to join a channel. They differ in their authentication methods and the user information they pass.

• joinChannel[1/3] is a single-parameter authentication method for RTC scenarios. You must pass a token that is generated for single-parameter authentication to join a channel. For more information, see Token-based authentication. This method is recommended for RTC scenarios.

• joinChannel[2/3] uses multi-parameter authentication. You must pass a token that is generated for multi-parameter authentication and the corresponding user information that is used to generate the token. For more information, see Token-based authentication.

• This method is used for AI real-time interaction scenarios. You must pass a single-parameter authentication token and set the user property capabilityProfile. To communicate with an AI agent, set it to AliRtcCapabilityProfileAiHuman.

Limits

• After you successfully join a channel, 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="923190466431o">leaveChannel</a> to leave the current channel and 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 a new channel.

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

• Applications with different App IDs cannot interoperate.

• Do not call this method to retry joining a channel if the initial attempt fails.

Related callbacks

Calling this method successfully 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 notifies you of the result of joining a channel.

• After you successfully join the 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 for remote users.

Parameters

Leaves the current channel.

- (int)leaveChannel;

When you call this method, the SDK terminates the real-time communication session and leaves the current channel.

When to call

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

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

Related callbacks

• Local client: Calling this method 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 notify you of the result of leaving the channel.

• Remote users: 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.

Response Description

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

Checks whether the user is in a channel.

- (BOOL)isInCall;

Return value

YES indicates that the user is in a channel. NO indicates that the user is not in a channel.

Sets the user role.

- (int)setClientRole:(AliRtcClientRole)role;

This method sets the user role to streamer or viewer.

In interactive mode, before you join a channel:

• If you set the user role to streamer, the SDK automatically publishes local audio and video streams and subscribes to the audio and video streams of other streamers by default.

• If you set the user role to viewer, the SDK does not publish local audio and video streams but subscribes to the audio and video streams of other streamers.

When to call

This method can be called before or after you join a channel. You can call it before you join to set the initial user role, or after you join to switch roles.

Limits

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

In interactive mode, you must explicitly call this method to set the user role before you join a channel.

Parameters

Return value

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

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. The token expires after a specific period. After the token expires, the SDK can no longer connect to the server.

When to call

In the following situations:

• 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, which indicates that your authentication information is about to expire, you must regenerate a token on your server and then 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, which indicates that authentication has expired. You must then regenerate a token and call joinChannel to rejoin the channel.

Parameters

Returns

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

Refreshes the authentication information.

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

This method updates the token. The token expires after a specific period. After the token expires, the SDK can no longer connect to the server.

When to call

In the following situation, you must regenerate the token on your server and then call this method to pass in the new token:

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 when the authentication information is about to expire.

Parameters

Return value

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

Sets whether to publish the local audio stream.

- (int)publishLocalAudioStream:(BOOL)enable;

This method controls whether to publish the locally captured audio stream. The SDK publishes the audio stream by default. If you do not want to publish the audio stream by default, you can call publishLocalAudioStream(false) before you join the channel to disable audio stream publishing.

When to call

This method can be called before or after you join a channel. Calling it before you join modifies the default configuration, which takes effect when you join the channel.

Related callbacks

When the state of the local audio stream ingest changes, the <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#86b2d8735bm71" id="e5ef180ba6e2i">onAudioPublishStateChanged</a> callback is triggered on the local client to report the latest status of the stream ingest. The <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#6da9cf330aoer" id="299ef35806ttb">onRemoteTrackAvailableNotify</a> callback is triggered on the remote client to notify of changes to the remote user's audio and video streams.

Parameters

Return value

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

Checks whether the local audio stream is being published.

- (BOOL)isLocalAudioStreamPublished;

Return value

YES allows pushing, and NO denies pushing.

Sets whether to subscribe to remote audio streams by default.

- (int)setDefaultSubscribeAllRemoteAudioStreams:(BOOL)sub;

This method configures whether the system subscribes to the audio streams of remote users by default. This setting affects the audio stream subscription behavior of new users who join the channel. We recommend that you set this to true unless you have specific scenario requirements.

When to call

This method can be called before or after you join a channel.

• Before you join a channel:

  • By default, the SDK subscribes to the audio streams of remote users when you join a channel. If you want to change this behavior, you can call this method before you join.

• After you join a channel:

  • 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). You will not subscribe to the audio streams of users who join the channel later.

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

Parameters

Response Description

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

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

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

This method stops or resumes subscribing to the audio stream of a specific remote user. We recommend that you set this to true unless you have specific scenario requirements.

Parameters

Return value

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

Stops or resumes subscribing to all remote audio streams.

- (int)subscribeAllRemoteAudioStreams:(BOOL)sub;

This method is a master switch for subscribing to remote audio streams. We recommend that you set it to YES. If it is set to NO, it causes the following:

• Subscription to all remote audio streams in the current session is stopped.

• New users who join the session are not subscribed to.

• 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 resubscribe, you can call this method again and set it to YES to resume subscription.

Parameters

Return value

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

Sets whether to publish the local camera stream.

- (int)publishLocalVideoStream:(BOOL)enable;

This method controls whether to publish the locally captured video stream.

When to call

This method can be called before or after you join a channel.

Calling it before you join modifies the default configuration, which takes effect when you join the channel.

Related callbacks

When the state of the local audio stream ingest 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 provide 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 notify that the remote user's audio and video stream has changed.

Parameters

Checks whether publishing a video stream is allowed.

- (BOOL)isLocalVideoStreamPublished;

Return value

YES indicates that the camera stream is published. NO indicates that the camera stream is not published.

Sets whether to subscribe to remote video streams by default.

- (int)setDefaultSubscribeAllRemoteVideoStreams:(BOOL)sub;

This method sets whether to subscribe to video streams by default. The SDK subscribes by default.

When to call

This method can be called before or after you join a channel.

• Before you join a channel:

  • You can use this method to cancel the default subscription setting.

• After you join the meeting:

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

  • After you stop the default subscription, to resume subscribing to a specific user's audio stream, you can call the subscribeRemoteVideoStream method. To resume subscribing to the audio streams of multiple users, you must call it multiple times.

  • After you stop the default subscription, calling setDefaultSubscribeAllRemoteVideoStreams(false) resumes subscribing only to the audio streams of users who join subsequently.

Parameters

Return value

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

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 a specific user's video stream.

When to call

This method can be called before or after you join a channel.

Parameters

Stops or resumes subscribing to all remote video streams.

- (int)subscribeAllRemoteVideoStreams:(BOOL)sub;

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

• Subscription to all remote video streams in the current session is stopped.

• New users who join later are also not subscribed to, even if you have called <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#a975297480yoj" id="0464849a17dks">setDefaultSubscribeAllRemoteVideoStreams</a>, which sets the 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 individually control the audio stream of a specific user.

To resubscribe, you can call this method again and set it to true to resume subscription.

Parameters

Return value

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

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

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

This method merges the subscription to remote audio and video streams.

Related APIs

Compared to subscribeRemoteMediaStream[2/2], this method 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 method, AliRtcVideoTrackNo for AliRtcVideoTrack is invalid and has no effect.

Parameters

Return value

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

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

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

This method merges the subscription to remote audio and video streams.

Related APIs

Compared to subscribeRemoteMediaStream[1/2], this method uses the videoTrack and audioTrack parameters to inform the SDK of the desired subscription state in a single call. For example:

• To subscribe to the camera stream and microphone stream, set videoTrack and audioTrack to AliRtcVideoTrackCamera and AliRtcAudioTrackMic respectively.

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

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

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

Parameters

Return value

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

Subscribes to the stream of a specific user in another channel.

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

Parameters

Return value

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

Subscribes to the streams of all users in a target channel.

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

Parameters

Return value

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

Sets the volume of a remote audio stream.

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

Parameters

Return value

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

Stops or resumes sending local audio data.

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

When to call

This method can be called before or after you join a channel.

Related callbacks

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

Parameters

Return value

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

Stops or resumes playing remote audio.

- (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 only stops or resumes audio playback for a specified remote user, but does not affect stream pulling and decoding of the remote audio. If you want to unsubscribe from a user's audio stream, you can 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

This method can be called before or after you join a channel.

Parameters

Returns

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

Stops or resumes playing all remote audio.

- (int)muteAllRemoteAudioPlaying:(BOOL)mute;

This method stops or resumes playing all remote audio.

When to call

This can be set before or after you join a channel.

Parameters

Return value

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

Starts audio capture.

- (void)startAudioCapture;

This method starts audio capture. You can also call it before you join a channel to start audio capture in advance. If you do not call it, the SDK automatically controls the audio capture device. If you want to start audio capture after you stop it with stopAudioCapture, you can call this method.

When to call

This method can be called before or after you join a channel.

Related APIs

The startAudioCapture[2/2] method lets you control whether the audio capture device remains on after you leave the channel.

Related callbacks

After you call this method to change the local audio capture state, you can retrieve the state change through the onLocalAudioStateChanged callback.

Return value

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

Starts audio capture.

- (void)startAudioCapture:(BOOL)keepAlive;

Stops microphone capture after muting.

This method starts audio capture. You can also call it before you join a channel to start audio capture in advance. If you do not call it, the SDK automatically controls the audio capture device.

When to call

This method can be called before or after you join a channel.

Related APIs

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

Related callbacks

After you call this method to change the local audio capture state, you can retrieve the state change through the onLocalAudioStateChanged callback.

Parameters

Return value

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

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> to start audio device capture, you can call this method to stop the capture.

Related callbacks

After you call this method to change the local audio capture state, you can retrieve the state change through the onLocalAudioStateChanged callback.

Return value

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

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

- (int)enableSpeakerphone:(BOOL)enable;

This method sets the current audio playback device to either the earpiece or the speaker after you join a channel. If this feature is not set, the device that is specified in the default audio route settings is used for playback.

The priority of audio routing is predefined in the SDK and automatically switches based on the current peripheral connection status. The priority is as follows: Wired headset > Bluetooth headset > User settings > Default settings. Therefore, when a peripheral is connected, calls to this API have no effect. For more information about audio routing settings, see Audio Routing Settings.

When to call

This method can be called before or after you join a channel.

Related APIs

<a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#83be8cc066qqq" id="f8de149ef8so0">setDefaultAudioRoutetoSpeakerphone</a> is used to modify the default audio routing settings by setting the current routing device.

Parameters

Return value

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

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

- (BOOL)isEnableSpeakerphone;

Return value

YES indicates speaker mode. NO indicates earpiece mode.

Sets the volume callback frequency and smoothing coefficient.

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

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

When to call

This method can be called before or after you join a channel.

Related callbacks

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

• The onAudioVolumeCallback callback notifies the speaker's audio volume. The callback frequency is determined by the interval.

• For voice activity detection, when an active user is detected, the onActiveSpeaker callback reports the speaker's UID.

Parameters

Returns

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

Enables in-ear monitoring.

- (int)enableEarBack:(BOOL)enable;

This method enables or disables the in-ear monitoring feature. For better results, enable in-ear monitoring when you wear headphones (wired or Bluetooth).

When to call

This method can be called before or after you join a channel.

Parameters

Return value

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

Sets the in-ear monitoring volume.

- (int)setEarBackVolume:(NSInteger)volume;

This API is used to set 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="b0fa866c9bcuq">enableEarBack</a>.

When to call

This method can be called before or after you join a channel.

Parameters

Return value

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

Starts audio playback.

- (void)startAudioPlayer;

Stops audio playback.

- (void)stopAudioPlayer;

Sets the playback volume.

- (int)setPlayoutVolume:(NSInteger)volume;

Parameters

Return value

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

Sets the recording volume.

- (int)setRecordingVolume:(NSInteger)volume;

Parameters

Return value

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

Plays an audio file.

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

Parameters

Return value

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

Stops playing the audio file.

- (int)stopAudioFileTest;

Return value

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

Starts audio capture device detection before a call.

- (void)startAudioCaptureTest;

Stops the pre-call device detection of audio capture devices.

- (void)stopAudioCaptureTest;

Sets whether the default audio output is the speaker. The default is the speaker.

- (int)setDefaultAudioRouteToSpeakerphone:(BOOL)defaultToSpeakerphone;

This method sets the default audio route device before you join a channel. You can choose to output to the earpiece or speaker by default. The SDK defaults to the speaker. If you want to change this default configuration, you can call this method before you join.

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

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

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

• When the audio route is the earpiece, the sound is quieter and can be heard clearly only by bringing the ear close. This provides better privacy and is suitable for answering calls.

• When the audio route is the speaker, the sound is louder and can be heard without holding the phone to your face, which enables a "hands-free" feature.

Related APIs

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

This method can be called before or after you join a channel.

Parameters

Return value

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

Sets the voice changer effect mode.

- (int)setAudioEffectVoiceChangerMode:(AliRtcAudioEffectVoiceChangerMode)mode;

Parameters

Return value

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

Sets the pitch parameter.

- (int)setAudioEffectPitchValue:(double)value;

Parameters

Return value

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

Sets the reverberation effect mode.

- (int)setAudioEffectReverbMode:(AliRtcAudioEffectReverbMode)mode;

Parameters

Return value

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

Sets the reverberation effect type and specific parameters.

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

Parameters

Return value

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

Sets the preset voice beautification effect mode.

- (int)setAudioEffectBeautifyMode:(AliRtcAudioEffectBeautifyMode)mode;

This method sets some of the SDK's preset voice beautification modes. It is suitable for scenarios that require voice enhancement, such as voice live streaming, karaoke, and voice social networking. By selecting different beautification modes, you can change the auditory effect of the human voice, such as enhancing its magnetic quality or improving clarity, which improves the listening experience for remote users.

When to call

This method can be called before or after you join a channel.

Parameters

Return value

• 0: Success.

• Non-zero: Failure.

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

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

This method adjusts the locally captured human voice or audio signal using a Graphic Equalizer. By adjusting the gain in dB of one of the 10 fixed frequency bands, you can customize the timbre. It is suitable for scenarios such as optimizing voice clarity, emphasizing vocals, and assisting with noise reduction.

The equalizer supports adjusting the full audio spectrum from 31 Hz to 16 kHz, with 10 standard frequency bands. The gain for each band can be set independently within the range of [-15, 15] dB. The default is 0 dB, which means no enhancement or attenuation.

Limits

• The equalizer cannot be used alone before the voice beautification mode is enabled. You must call this method after you call setAudioEffectBeautifyMode.

Parameters

Return value

0: Success.

Non-zero: Failure.

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 <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#d71bbfd2f242b" id="c310321e9eu35">addExternalAudioStream</a> to add an external audio stream and retrieve the external audio stream ID.

2. Call pushExternalAudioStream to input audio data into the created audio stream.

3. When the call ends, you must 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.

For more information about how to publish custom-captured audio in a channel, see Custom audio capture.

Parameters

Returns

A value greater than 0 indicates success and is the external audio stream ID. Any other value indicates failure.

Inputs external audio stream data.

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

This method inputs data into a specified 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="0a353f7272shu">addExternalAudioStream</a> method to add an external audio stream and retrieve the external audio stream ID.

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

3. When the call ends, you must 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.

For more information about how to publish custom-captured audio in a channel, see Custom audio capture.

Parameters

Return value

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

Sets the publishing volume of the external audio stream.

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

Parameters

Returns

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

Retrieves the publishing volume of the external audio stream.

- (int)getExternalAudioStreamPublishVolume:(int)streamId;

Parameters

Return value

[0, 100]: The publishing volume. < 0: Failure.

Sets the playback volume of the external audio stream.

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

Parameters

Return value

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

Retrieves the playback volume of the external audio stream.

- (int)getExternalAudioStreamPlayoutVolume:(int)streamId;

Parameters

Return value

[0, 100]: The playback volume. < 0: Failure.

Deletes an external audio stream.

- (int)removeExternalAudioStream:(int)streamId;

This method removes the corresponding external audio stream based on the provided streamId. It corresponds to the addExternalAudioStream method.

When to call

If you want to use the custom audio input feature, you must call the addExternalAudioStream method to add an audio stream and retrieve the external audio stream ID. Then, you can call the pushExternalAudioStream method to input your audio data into the SDK. When you want to stop custom audio input, you can call this method to remove the corresponding external audio stream and clean up resources.

Parameters

Return value

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

Retrieves audio file information.

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

Parameters

Starts audio mixing.

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

Parameters

Return value

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

Stops audio mixing.

- (int)stopAudioAccompany;

Return value

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

Adjust the accompaniment volume

- (int)setAudioAccompanyVolume:(NSInteger)volume;

Parameters

Return value

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

Sets the publishing volume for audio mixing.

- (int)setAudioAccompanyPublishVolume:(NSInteger)volume;

Parameters

Return value

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

Retrieves the publishing volume for audio mixing.

- (int)getAudioAccompanyPublishVolume;

Return value

[0, 100] indicates success. Any other value indicates failure.

Sets the local playback volume for audio mixing.

- (int)setAudioAccompanyPlayoutVolume:(NSInteger)volume;

Parameters

Return value

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

Retrieves the local playback volume for audio mixing.

- (int)getAudioAccompanyPlayoutVolume;

Return value

[0, 100]: Success. Any other value indicates failure.

Pauses audio mixing.

- (int)pauseAudioAccompany;

Return value

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

Resumes audio mixing.

- (int)resumeAudioAccompany;

Return value

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

Retrieves the duration of the audio mixing file in milliseconds.

- (int)getAudioAccompanyDuration;

Return value

>=0: The duration of the audio mixing file in milliseconds. <0: Failure.

Retrieves the current playback position of the audio mixing file in milliseconds.

- (int)getAudioAccompanyCurrentPosition;

Return value

>=0: The playback position of the audio mixing file. <0: Failure.

Sets the playback position of the audio mixing file.

- (int)setAudioAccompanyPosition:(int)pos;

Parameters

Return value

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

Preloads a sound effect file.

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

Parameters

Return value

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

Deletes a preloaded sound effect file.

- (int)unloadAudioEffectWithSoundId:(NSInteger)soundId;

Parameters

Return value

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

Starts playing a sound effect.

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

Parameters

Returns

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

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

Stops playing all sound effects.

- (int)stopAllAudioEffects;

Return value

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

Pauses a sound effect.

- (int)pauseAudioEffectWithSoundId:(NSInteger)soundId;

Parameters

Returns

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

Pauses all sound effects.

- (int)pauseAllAudioEffects;

Return value

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

Resumes playing a sound effect.

- (int)resumeAudioEffectWithSoundId:(NSInteger)soundId;

Parameters

Return value

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

Resumes playing all sound effects.

- (int)resumeAllAudioEffects;

Return value

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

Sets the publishing volume of a sound effect.

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

Parameters

Returns

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

Retrieves the publishing volume of a sound effect.

- (int)getAudioEffectPublishVolumeWithSoundId:(NSInteger)soundId;

Parameters

Return value

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

Sets the publishing mix volume for all sound effects.

- (int)setAllAudioEffectsPublishVolume:(NSInteger)volume;

Parameters

Return value

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

Sets the local playback volume of a sound effect.

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

Parameters

Return value

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

Retrieves the local playback volume of a sound effect.

- (int)getAudioEffectPlayoutVolumeWithSoundId:(NSInteger)soundId;

Parameters

Return value

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

Sets the local playback volume for all sound effects.

- (int)setAllAudioEffectsPlayoutVolume:(NSInteger)volume;

Parameters

Return value

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

Starts recording a media file.

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

Parameters

Response description

TRUE indicates success. Any other value indicates failure.

Stops recording a media file.

- (void)stopRecord 

Parameters

None.

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

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

This method sets the local preview view. It binds the display view for the local video stream and sets the rendering mode, mirror mode, and rotation angle for the local user's view. It affects only the local user's preview and not the published video. To set the remote user's view, you can call setRemoteViewConfig.

When to call

This method can be called before or after you join a channel.

Parameters

Return value

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

Sets camera capture preferences.

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

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

When to call

This must be set before the camera is turned on, for example, before the following operations:

• startPreview (starts preview)

• joinChannel (joins a channel)

Parameters

Return value

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

Disables or re-enables local video capture.

- (int)enableLocalVideo:(BOOL)enable;

This method controls whether local video capture is enabled or disabled. When local video capture is disabled, both the local preview and the published stream have no video data, but this does not affect receiving remote video. If you call this method to disable local camera capture, both the local preview and the remote stream freeze on the last frame.

When to call

This method can be called before or after you join a channel.

Related callbacks

• After this method is called successfully, remote users are notified through the onUserVideoEnabled callback.

Parameters

Return value

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

Stops or resumes sending local video data.

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

When you publish a stream, you can call this method to send all-black video frames. The local preview remains normal, and the capture, encoding, and sending modules continue to work, but the video content is black frames.

Parameters

Return value

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

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

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

This method attaches the display view for a specified video stream from a remote user and sets its rendering mode, mirror mode, and rotation angle for local display. 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 renderMode.

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

When to call

You can call this method when you receive the onRemoteTrackAvailableNotify callback, which is when the remote user's video is available.

Parameters

Return value

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

Checks whether the camera is on.

- (BOOL)isCameraOn;

Return value

YES indicates that the camera is on. NO indicates that the camera is off.

Sets the video encoding properties.

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

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

When to call

This method can be called before or after you join a channel. To set the camera stream video encoding properties only once per session, we recommend that you call it before you join.

Limits

Both the `mirrorMode` of this method and setVideoMirrorMode can set the video publishing mirror mode. We recommend that you use only one method. If you use both, the mirror effects may stack, which can lead to setting failures or incorrect mirroring.

Parameters

Sets the video decoding properties.

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

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

When to call

You must call this method before you join a channel.

Parameters

Switches between the front and rear cameras. The front camera is used by default (iOS only).

- (int)switchCamera;

This method controls the use of the front or rear camera. The front camera is used by default. You can dynamically switch cameras during the application's runtime based on the available cameras, without restarting the video stream or reconfiguring the video source.

When to call

This method must be called after the camera has been successfully turned on.

Limits

This is available only on Android and iOS.

Return value

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

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

- (AliRtcCameraDirection)getCurrentCameraDirection;

Returns

Returns the camera direction enumeration value.

Starts the local preview (automatically turns on the camera).

- (int)startPreview;

This method starts the local video preview and automatically turns on the camera. To stop the local preview, you can call the stopPreview method.

When to call

• Before you call this method, you must set the view for the local preview using setLocalViewConfig. Otherwise, the preview is not available, but this does not affect publishing.

• If needed, you can call this method to start the preview before you join a channel with joinChannel. This automatically turns on the camera.

Return value

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

Stops the local preview.

- (int)stopPreview;

This method stops the local video preview and turns off the camera. After you stop the preview, the local display remains on the last frame, which does not affect publishing.

When to call

To stop the preview after you start it, you can call this method.

Return value

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

Sets the camera zoom.

 - (int)setCameraZoom:(float)zoom;

Parameters

Return value

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

Retrieves the maximum camera zoom factor.

 - (float)GetCameraMaxZoomFactor;

Return value

The maximum camera zoom factor.

Retrieves the current camera zoom factor.

- (float)GetCurrentZoom;

Return value

Retrieves the current scaling ratio of the camera.

Sets the camera exposure.

- (int)SetExposure:(float)exposure;

Parameters

Return value

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

Retrieves the camera exposure.

- (float)GetCurrentExposure;

Return value

The camera exposure value.

Retrieves the minimum camera exposure.

- (float)GetMinExposure;

Return value

The minimum camera exposure value.

Retrieves the maximum camera exposure.

- (float)GetMaxExposure;

Return value

The maximum camera exposure value.

Turns the camera flash on or off.

- (int)setCameraFlash:(BOOL)flash;

Parameters

Return value

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

Checks whether the camera supports manual focus.

- (BOOL)isCameraFocusPointSupported;

Return value

TRUE indicates that manual focus is supported. FALSE indicates that manual focus is not supported.

Checks whether the camera supports setting an exposure point.

- (BOOL)isCameraExposurePointSupported;

Return value

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

Sets the manual focus point for the camera.

- (int)setCameraFocusPoint:(CGPoint)point;

Parameters

Return value

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

Sets the exposure value for the exposure point.

- (int)setCameraExposurePoint:(CGPoint)point;

Parameters

Return value

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

Checks whether the camera supports face-based autofocus.

- (BOOL)isCameraAutoFocusFaceModeSupported;

Return value

TRUE indicates that face-based autofocus is supported. FALSE indicates that face-based autofocus is not supported.

Sets face-based autofocus for the camera.

- (BOOL)setCameraAutoFocusFaceModeEnabled:(BOOL)enable;

Parameters

Return value

TRUE indicates success. FALSE indicates failure.

Sets the video mirror mode.

- (int)setVideoMirrorMode:(AliRtcVideoPipelineMirrorMode)mirrorMode;

This method sets whether to enable mirror mode for the local preview video and the published video stream.

When to call

This method can be dynamically set before and after you join a channel. The SDK records the state and applies the video operation when the preview and encoding (publishing) can be operated.

Limits

This method overlaps with the mirrorMode in setLocalViewConfig and setVideoEncoderConfiguration. We recommend that you use only this method.

Parameters

Sets the video pipeline scaling mode.

-(void)setCapturePipelineScaleMode:(AliRtcCapturePipelineScaleMode)mode;

This method sets whether video data is scaled immediately upon capture or during encoding. For example, when the capture resolution and encoding resolution are different, you can set the scaling timing to determine whether the preview data and the published data are consistent.

When to call

This method needs to be set before the camera is turned on, for example, before you start the preview with startPreview or join a channel with joinChannel.

Parameters

Return value

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

Registers a video data output object.

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

This method registers a video data output object. To unregister, you can call the unregisterVideoSampleWithObserver method.

When to call

You can call this API to register a video data observer to obtain raw video data, such as data in YUV or RGBA format, at various stages.

Related callbacks

After you successfully register a video data output listener, the SDK triggers the callbacks you implement whenever a video frame is captured. You can implement the corresponding callbacks as needed:

• onCaptureVideoSample: Callback for local captured video data.

• onRemoteVideoSample: Callback for remote video data.

• onPreEncodeVideoSample: Callback for local video data before encoding.

Parameters

Unregisters a video data output object.

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

This API is the counterpart of <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#9a3437ab16j1w" id="f524bad30a6ys">registerVideoSampleObserver</a> and unregisters the object for video data output.

Metric descriptions

Registers a listener for local camera stream video OpenGL texture data.

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

If you want to retrieve raw video data, you can call the registerVideoSampleObserver method to register the relevant callbacks. If you want to retrieve internal texture data, you can call this method. To unregister, you can call the unRegisterLocalVideoTextureObserver method.

Related callbacks

After you successfully register a listener for local camera stream video OpenGL texture data, the SDK triggers the callbacks you implement in the AliRtcTextureObserver interface whenever a video frame is captured. You can implement the corresponding callbacks as needed:

• onTextureCreate: This callback is triggered when the SDK's internal OpenGL context is created.

• onTextureUpdate: This callback is triggered after each video frame is uploaded to an OpenGL texture. When an external OpenGL texture data listener is registered, you can process the texture in this callback and return the processed texture ID. This callback must return a valid texture ID. If no processing is done, it must return the textureId parameter.

• onTextureDestroy: This callback is triggered when the SDK's internal OpenGL context is destroyed.

Parameters

Unregisters the listener for local camera stream video OpenGL texture data.

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

This method corresponds to registerLocalVideoTextureObserver and is responsible for unregistering.

Parameters

Video snapshot feature.

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

Parameters

Return value

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

Enables an external video input source.

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

Parameters

Inputs video data.

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

Parameters

Return value

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

Starts bypass live streaming.

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

Parameters

Return value

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

Updates bypass live streaming parameters.

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

Parameters

Return value

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

Stops bypass live streaming.

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

Parameters

Return value

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

Retrieves the bypass live streaming status.

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

Parameters

Return value

Returns the bypass live streaming status.

Starts network quality probing.

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

Parameters

Response Description

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

Stops network quality probing.

- (int)stopLastmileDetect;

Return value

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

Sends Supplemental Enhancement Information (SEI).

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

The SDK provides the functionality to send and receive media extension information. This method sends media extension information using the SEI extension protocol. The receiver can retrieve the information by listening to the onMediaExtensionMsgReceived callback.

Common use cases include the following:

• You can transmit timestamps using media extension information to calculate end-to-end network latency or to synchronize data with other business services.

• You can transmit descriptive information using media extension information. Currently, up to 4 KB of data can be transmitted, which can be used for small amounts of data, preferably in JSON or plain string format.

When to call

You can call this method after you start to publish the stream.

Limits

When you use media extension information, the audio and video data channel is reused. Therefore, you must control the frequency and length of custom messages. The limits are as follows:

• You can send a maximum of fps messages per second, as set in the profile. This is because SEI is transmitted in the H.264/H.265 stream, and extension information can be attached only when a video frame is available to encode.

• To avoid affecting the quality of media data transmission, the custom message body is limited to 4 KB. This can be used for small amounts of information.

• The repeatCount parameter in the sendMediaExtensionMsg function is for message redundancy. If it is greater than 1, the message is sent multiple times.

• To prevent message loss due to network packet loss, other users in the channel also receive the same message multiple times and need to deduplicate them.

• Subscribers in the channel also receive custom messages that are sent during bypass live streaming.

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

Related callbacks

After the publishing party sends media extension information, the subscribing party can retrieve the information by listening to the onMediaExtensionMsgReceived callback.

Parameters

Return value

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

Sends media extension information, which is implemented using SEI at the underlying layer.

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

The SDK provides the functionality to send and receive media extension information. This method sends media extension information using the SEI extension protocol. The receiver can retrieve the information by listening to the onMediaExtensionMsgReceived callback. When payloadType is 5, it is equivalent to using the sendMediaExtensionMsg method.

Common use cases include the following:

• You can transmit timestamps using media extension information to calculate end-to-end network latency or to synchronize data with other business services.

• You can transmit descriptive information using media extension information. Currently, up to 4 KB of data can be transmitted, which can be used for small amounts of data, preferably in JSON or plain string format.

When to call

You can call this method after you start to publish the stream.

Limits

When you use media extension information, the audio and video data channel is reused. Therefore, you must control the frequency and length of custom messages. The limits are as follows:

• You can send a maximum of fps messages per second, as set in the profile. This is because SEI is transmitted in the H.264/H.265 stream, and extension information can be attached only when a video frame is available to encode.

• To avoid affecting the quality of media data transmission, the custom message body is limited to 4 KB. This can be used for small amounts of information.

• The repeatCount parameter in the sendMediaExtensionMsg function is for message redundancy. If it is greater than 1, the message is sent multiple times.

• To prevent message loss due to network packet loss, other users in the channel also receive the same message multiple times and need to deduplicate them.

• Subscribers in the channel also receive custom messages that are sent during bypass live streaming.

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

Parameters

Returns

• 0: Success.

• <0: Failure. An error code is returned.

  • ERR_INNER(-1): Internal SDK error. This may occur if the SDK is not initialized or is called after it is destroyed.

Callback for network connection status changes.

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

Parameters

Callback for local device exceptions. Customers need to handle this callback.

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

Parameters

Notification that user authentication information is about to expire. Authentication expires 30 seconds after this notification is received. Customers need to handle this callback.

- (void)onAuthInfoWillExpire;

This callback indicates that the user's authentication information is about to expire. Authentication expires 30 seconds after this callback is received. You need to retrieve a new token and then 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.

When this is triggered

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

The server returns that the authentication information has expired when a user calls an API that requires authentication.

- (void)onAuthInfoExpired;

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

• You can 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 it.

When this is triggered

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

Callback for the result of joining a channel. This callback is equivalent to the block operation of the joinChannel method. It handles events after you join a channel. You can use either one.

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

Trigger conditions

When the application calls the joinChannel method, this callback indicates whether joining the channel was successful or failed. It also returns information about joining the channel and the time it took.

Parameters

Callback for the result of leaving a channel. This is returned after you call the leaveChannel method. If you call destroy immediately after leaveChannel, you do not receive this callback.

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

Parameters

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

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

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

Trigger conditions

• Triggered when a remote user leaves the channel.

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

• Triggered when a remote streamer is considered disconnected because no data is received from them for an extended period.

Parameters

Callback for when a remote user comes online.

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

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

Trigger conditions

• A remote user successfully joins the channel.

• After the current user joins the channel, they receive join callbacks for users who are already in the channel. This can be used to display previously joined users.

Parameters

Callback for when a remote user's stream changes.

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

This callback is triggered when the publishing state of a remote user changes. Through this callback, developers can know in real time whether a remote user is publishing audio and video streams and can show 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 changes from not publishing to publishing, including audio and video.

• When a remote user changes from publishing to not publishing, including audio and video.

• In interactive mode, when a remote user calls setClientRole to switch from a viewer to a streamer and also sets up publishing, this callback is triggered.

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

• The remote user starts publishing the camera stream (publishing state: no video stream -> camera stream only). The local client's callback returns AliRtcVideoTrackCamera, which indicates that the remote user's camera stream is available.

• The remote user also publishes the screen sharing stream (publishing state: camera stream only -> camera and screen sharing streams). The local client's callback returns AliRtcVideoTrackBoth, which indicates that both the camera and screen sharing streams are available.

• The remote user stops publishing the camera stream but keeps the screen sharing stream (publishing state: camera and screen sharing streams -> screen sharing stream only). The local client's callback returns AliRtcVideoTrackScreen, which indicates that only the screen sharing stream is available.

• The remote user then stops publishing the screen sharing stream (publishing state: screen sharing stream only -> no video stream). The local client's callback returns AliRtcVideoTrackNo, which indicates that no video stream is available.

Parameters

Callback for when the user is kicked from the server or the channel is closed.

- (void)onBye:(int)code;

When a user is disconnected for some reason or the session ends, this callback is triggered. Developers can learn the reason for the disconnection from the code parameter and handle it accordingly.

Trigger conditions

• The current user is kicked from the server.

• The session ends because the server actively removes the channel.

• The user is passively disconnected, and the client needs to try to restore the session or reconnect.

Parameters

Callback for audio publishing state changes.

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

This callback listens for changes in the local user's audio publishing state.

Trigger conditions

When the user's audio publishing state changes, for example:

• Publishing is stopped.

• You call <a baseurl="t2309850_v9_0_0.xdita" data-node="4087266" data-root="16090" data-tag="xref" href="#892915dd4edcy" id="81771ef0798we">setClientRole</a> to switch your 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 is triggered when the subscription status of a remote user's audio stream changes. It provides details about the status change for a specific remote user and the time elapsed since the previous state.

Parameters

Notification that a user has muted their audio.

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

Parameters

Notification that a user's audio has been interrupted, typically when the audio is preempted by a phone call.

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

Parameters

Notification that a user's audio interruption has ended. This corresponds to onUserAudioInterruptedBegin.

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

Parameters

Callback for video publishing state changes.

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

This callback listens for changes in the local user's video publishing state.

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 of changes in the subscription state of a remote user's camera stream. Through this callback, you can learn about the subscription state changes of a specific remote user's camera stream and the time interval from the previous state to the current state.

Related callbacks

Video streams mainly include camera streams and screen sharing streams. This method is for camera stream subscription state changes. The related callback method for screen sharing streams is onScreenShareSubscribeStateChanged.

Parameters

Notification that a user has muted their video.

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

Parameters

Notification that local video capture has been disabled or re-enabled.

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

Parameters