ApsaraVideo Live:AliRtcEngine APIs

Creates an AliRtcEngine instance.

static AliEngine *Create(const char *extras);

When to call

Call this method to create an AliRtcEngine instance before you call any other APIs of the ARTC SDK.

Limits

The SDK supports only one AliRtcEngine instance per application.

Metric descriptions

Return value

Returns a singleton object of the AliEngine class.

Destroys the AliRtcEngine instance.

static void Destroy(AliEngineDestroyCompletionCallback *callback = nullptr);

This method destroys the AliRtcEngine singleton object and releases all its internal resources. After this method is called, you can no longer use other AliRtcEngine methods or any callbacks. To use them again, you must call Create to create a new instance.

When to call

Call this method to release the instance after you finish using Real-Time Communication.

Limits

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

Parameters

Retrieves a feature interface instance.

virtual int QueryInterface(AliEngineInterfaceIdType iid, void** pInterface) = 0;

This method retrieves an instance of a specific feature interface. When you develop applications for Real-Time Communication on the Windows platform, many advanced features are provided through corresponding interface classes, such as audio device management (AliEngineInterfaceAudioDeviceManager), video device management (AliEngineInterfaceVideoDeviceManager), and the media engine (AliEngineInterfaceMediaEngine). Before you call the related methods, you must use the QueryInterface method to obtain instances of these interfaces.

Parameters

Return value

• 0: The call was successful.

• <0: The call failed.

Enables or disables H5 compatibility mode.

static void SetH5CompatibleMode(bool comp);

Parameters

Checks whether H5 compatibility mode is enabled.

static bool GetH5CompatibleMode();

Return value

true: H5 compatibility is enabled. false: H5 compatibility is disabled.

Sets the event listener callbacks.

virtual int SetEngineEventListener(AliEngineEventListener *listener) = 0;

This method sets a callback listener for the SDK. By setting this listener, you can receive various notification events from the engine, such as users joining or leaving a channel, network status changes, and audio and video stream status.

You need to implement the AliEngineEventListener class to customize the event methods that you want to listen for. By default, all methods have empty implementations, so you do not need to implement all of them. You can implement only the event methods that you need.

Related callbacks

If an exception occurs during an operation, the SDK first attempts to recover automatically using its internal retry mechanism. For errors that cannot be resolved automatically, the SDK notifies your application through predefined callback interfaces. The following are key callbacks for issues that the SDK cannot handle and that require your application to listen for and respond to:

Parameters

Return value

• 0: Success.

• A non-zero value: Failure. This may be because the listener parameter is invalid or the SDK is not initialized correctly.

Queries the current SDK version.

static const char *GetSDKVersion();

Return value

The current SDK version number in a string format. Example: "2.5.0.x".

Sets the channel profile.

virtual int SetChannelProfile(const AliEngineChannelProfile channelProfile) = 0;

This method sets the channel profile. It currently provides profiles for video call scenarios and interactive stream scenarios:

• Video call profile: All users have the streamer role and can publish and subscribe to streams.

• Interactive stream mode: You must call the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#c99c2b257dd8o" id="4e50f781a01e1">SetClientRole</a> method to set the user 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 mode is recommended for RTC scenarios.

When to call

You can call this method only before you join a channel. You cannot reset it while in the channel. You can reset it after you leave the channel.

Parameters

Return value

• 0: The method call was successful.

• Other values: The method call failed.

  • -1: The SDK is not initialized or has been destroyed.

Sets the audio profile.

virtual int SetAudioProfile(int audioProfile, int audioScene) = 0;

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

When to call

You can call this method only before you join a channel. You cannot reset it after you join the channel. You can reset it after you leave the channel.

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Checks whether the current mode is audio-only.

virtual bool IsAudioOnlyMode() = 0;

Return value

true: The current mode is audio-only. false: The current mode is audio and video.

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

virtual int SetAudioOnlyMode(bool audioOnly) = 0;

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Joins a channel.

virtual int JoinChannel(const char *token, const char *channelId, const char *userId, const char *userName) = 0;

This method joins a channel. In ARTC, users are organized by 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, as follows:

• This method is for joining a channel with a single parameter. You must pass a token generated for single-parameter joining using Token-based authentication. We recommend that you use this method to join a channel in RTC scenarios.

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

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

When to call

Call this method after you create the engine.

Limits

• After you successfully join a channel, to join another channel, you must first call LeaveChannel to leave the current channel. You can call to join another channel only after you receive the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#b70203f9ea0mz" id="b2522e57e4vom">OnLeaveChannelResult</a> callback.

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

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

• Do not call this method when you retry after a failed attempt to join a channel.

Related callbacks

A successful call to this method triggers the following callbacks:

• The result of the local client joining a channel is returned through the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#7cbf47a35bcel" id="cad6eb9b1bwx7">OnJoinChannelResult</a> callback of AliRtcEngineEventListener.

• After you successfully join the channel, the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#3333f6e9d344q" id="fab4a94264m28">OnRemoteUserOnLineNotify</a> callback is triggered on remote clients.

Parameters

Return value

0: The method call was successful. A non-zero value: The method call failed.

Joins a channel.

virtual int JoinChannel(const AliEngineAuthInfo &authInfo,
                                 const char *userName) = 0;

This method joins a channel. In ARTC, users are organized by 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, as follows:

• JoinChannel[1/3] is for joining a channel with a single parameter. You must pass a token generated for single-parameter joining using Token-based authentication. We recommend that you use this method to join a channel in RTC scenarios.

• This method is for joining a channel with multiple parameters. You need to pass a multi-parameter token generated using Token-based authentication and the user information that was used to generate the token.

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

Limits

• After you successfully join a channel, to join another channel, you must first call LeaveChannel to leave the current channel. You can call to join another channel only after you receive the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#b70203f9ea0mz" id="fcd2fac6abf0y">OnLeaveChannelResult</a> callback.

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

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

Related callbacks

A successful call to this method triggers the following callbacks:

• The local client is notified of the result of joining a channel through the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#7cbf47a35bcel" id="b3db8c610ewua">OnJoinChannelResult</a> callback.

• After you successfully join a channel, the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#3333f6e9d344q" id="a1297d33bcd92">OnRemoteUserOnLineNotify</a> callback is triggered on remote clients.

Parameters

Joins a channel.

virtual int JoinChannel(const char *token, const char *channelId, const char *userId, const AliEngineChannelParam &userParam) = 0;

This method joins a channel. In ARTC, users are organized by 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, as follows:

• JoinChannel[1/3] is a single-parameter method for joining a channel in RTC scenarios. You must pass a token generated for single-parameter joining using Token-based authentication. We recommend that you use this method to join a channel in RTC scenarios.

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

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

Limits

• After you successfully join a channel, to join another channel, you must first call leaveChannel to leave the current channel. You can join a channel again only after you receive the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#b70203f9ea0mz" id="15ec544e3985m">OnLeaveChannelResult</a> callback.

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

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

• Do not call this method when you retry after a failed attempt to join a channel.

Related callbacks

A successful call to this method triggers the following callbacks:

• The result of the local user joining a channel is provided through the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#7cbf47a35bcel" id="5d109191c950l">OnJoinChannelResult</a> callback.

• After you successfully join the channel, the remote client triggers the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#3333f6e9d344q" id="fa6f8d9357glx">OnRemoteUserOnLineNotify</a> callback.

Parameters

Return value

0: The method call was successful. A non-zero value: The method call failed.

You can leave the channel.

virtual int LeaveChannel() = 0;

After you call this method, the SDK terminates the audio and video call and leaves the current channel.

When to call

• Call this method to leave a channel.

• You must call this method to leave the current channel before joining a new one.

Related callbacks

• Calling this method triggers the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#b70203f9ea0mz" id="9626ae24d89ue">OnLeaveChannelResult</a> callback on the local client, which reports whether the client successfully left the channel.

• Remote users: A successful call to this API triggers the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#44ce12a0ecj52" id="0dfcab6a6fylt">OnRemoteUserOffLineNotify</a> callback.

Response Description

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

Checks whether the user is currently in a channel.

virtual bool IsInCall() = 0;

Return value

true: The user is in a channel. false: The user is not in a channel.

Sets the user role.

virtual int SetClientRole(const AliEngineClientRole clientRole) = 0;

This method sets the user role to streamer or viewer.

In interactive stream mode, before you join a channel:

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

• If you set the user role to viewer, the SDK does not publish the local audio and video streams but receives 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 user role, or after you join to switch the user role.

Limits

This method is effective only in interactive stream mode. This means you must call the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#901e748242y3g" id="322c3da902jpt">SetChannelProfile</a> method and set the channel profile to AliEngineInteractiveLive.

In interactive stream mode, we recommend that you explicitly call this method to set the user role before you join a channel.

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Retrieves the current user role type (streamer or viewer).

virtual AliEngineClientRole GetClientRole() = 0;

Return value

If the method call is successful, it returns an AliEngineClientRole object. This is an enumeration type that indicates the role is either streamer (0) or viewer (1).

Refreshes the authentication information.

virtual int RefreshAuthInfo(const AliEngineAuthInfo &authInfo) = 0;

This method updates the authentication information. The token expires after a certain period. When the token expires, the SDK cannot connect to the server.

When to call

In the following situations:

• When you receive the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#9f8ebe177degw" id="f52a19bb78yoi">OnAuthInfoWillExpire</a> callback, which indicates that the authentication information is about to expire, we recommend that you regenerate a token on your server and then call this method with the new token.

• If you do not update the token in time, the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#09c4ec9160eom" id="440c501877fxr">OnAuthInfoExpired</a> callback is triggered to notify you that the authentication has expired. You must then regenerate the token and call JoinChannel to rejoin the channel.

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Refreshes the authentication information.

virtual int RefreshAuthInfo(const char *token) = 0;

This method updates the token. The token expires after a certain period. When the token expires, the SDK cannot connect to the server.

When to call

In the following situations, we recommend that you regenerate the token on your server and then call this method to pass in the new token:

• When you receive the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#9f8ebe177degw" id="b21949148djrc">OnAuthInfoWillExpire</a> callback, which indicates that the authentication information is about to expire.

• If the token is not updated in time, the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#09c4ec9160eom" id="62df9bf63786v">OnAuthInfoExpired</a> callback is triggered to indicate that the authentication has expired. In this case, you need to call JoinChannel to rejoin the channel.

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Enables or disables publishing of the local audio stream.

virtual int PublishLocalAudioStream(bool enabled) = 0;

This method controls whether to publish the locally collected 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

You can call this method before or after you join a channel. Calling it before you join a channel 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 local client triggers the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#eb8fab7f5ak7v" id="c584949653jn5">OnAudioPublishStateChanged</a> callback to report the latest state of the audio stream ingest. The remote client triggers the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#ff1f7c8581r3r" id="75f2096b1efxy">OnRemoteTrackAvailableNotify</a> callback to report changes to the remote user's audio and video streams.

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Queries whether publishing the audio stream is currently allowed.

virtual bool IsLocalAudioStreamPublished() = 0;

Return value

true: Publishing is allowed. false: Publishing is not allowed.

Sets whether to subscribe to remote audio streams by default.

virtual int SetDefaultSubscribeAllRemoteAudioStreams(bool sub) = 0;

This method configures whether to subscribe to remote users' audio streams by default. This setting affects the audio stream subscription behavior for new users who join the channel. We recommend that you set this to true unless you have special requirements.

When to call

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

• Before you join a channel:

  • The SDK subscribes to remote users' audio streams by default when you join a channel. If you want to change this behavior, call this method before you join.

• After you join a channel:

  • If you want to stop the default subscription, call <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#e51a461de2k9t" id="e95a7e2d6fjwt">SetDefaultSubscribeAllRemoteAudioStreams</a>(false). Then, 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="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#957e547813q56" id="1a391bcabc66e">SubscribeRemoteAudioStream</a> to resume subscribing to a specific user's audio stream. If you want to resume subscribing to multiple users, you must call this method multiple times.

  • After you stop the default subscription, calling <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#e51a461de2k9t" id="e79b5ad58awcw">SetDefaultSubscribeAllRemoteAudioStreams</a>(true) resumes the subscription only for the audio streams of users who subsequently join the channel. It does not subscribe to the streams of remote users who joined while the subscription was stopped.

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

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

virtual int SubscribeRemoteAudioStream(const char* uid, bool sub) = 0;

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

Parameters

Response description

0: The method call was successful. Other values: The method call failed.

Stops or resumes receiving all remote audio streams.

virtual int SubscribeAllRemoteAudioStreams(bool sub) = 0;

This method is the master switch for subscribing to remote audio streams. We recommend that you set it to true. If you set it to false, the following occurs:

• Subscription to all remote audio streams in the current channel stops.

• Users who join later will also not be subscribed.

• You cannot use <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#957e547813q56" id="aface4ad3920l">SubscribeRemoteAudioStream</a> to control the audio stream of a specific user.

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

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Publishes or stops publishing the camera stream.

virtual int PublishLocalVideoStream(bool enabled) = 0;

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

When to call

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

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

Related callbacks

When the local audio stream ingest state changes, the local client triggers the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#6bf4efbd1cadl" id="d37709b09147d">OnVideoPublishStateChanged</a> callback to report the new audio stream ingest status, and the remote client triggers the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#ff1f7c8581r3r" id="f16e4b51bchqb">OnRemoteTrackAvailableNotify</a> callback to report changes to the remote user's audio and video stream.

Parameters

Return value

• 0: The method call was successful.

• <0: The method call failed.

Enables or disables sending the video stream.

virtual int PublishLocalVideoStream(bool enabled, AliEngineVideoTrack track) = 0;

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

When to call

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

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

Related callbacks

When the state of the local video stream ingest changes, the local client triggers the <a baseurl="t2713962_v5_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#6bf4efbd1cadl" id="18a9d4b47ezcc">OnVideoPublishStateChanged</a> callback to report the latest state of the video stream ingest. The remote client triggers the <a baseurl="t2713962_v5_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#ff1f7c8581r3r" id="d01e7a574f92o">OnRemoteTrackAvailableNotify</a> callback to notify that the remote user's audio and video streams have changed.

Parameters

Returns

• 0: The method call was successful.

• <0: The method call failed.

Queries whether publishing the video stream is currently allowed.

virtual bool IsLocalVideoStreamPublished() = 0;

Return value

true: The camera stream is published. false: The camera stream is not published.

Sets whether to receive video streams by default.

virtual int SetDefaultSubscribeAllRemoteVideoStreams(bool sub) = 0;

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

When to call

You can call this method 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 a channel:

  • To stop the default subscription, call SetDefaultSubscribeAllRemoteVideoStreams(false). This will prevent subscription to the video streams of users who join the channel subsequently.

  • After you stop the default subscription, if you want to resume subscribing to a specific user's video stream, call the SubscribeRemoteVideoStream method. To resume subscribing to multiple users, you must call it multiple times.

  • After the default subscription is stopped, a call to SetDefaultSubscribeAllRemoteVideoStreams(false) only resumes the audio streams of users who join the channel later.

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

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

virtual int SubscribeRemoteVideoStream(const char* uid, AliEngineVideoTrack track, bool sub) = 0;

This method subscribes to or unsubscribes from a specific user's video stream.

When to call

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

Parameters

Return value

• true: The setting was successful.

• false: The setting failed.

Stops or resumes receiving all remote video streams.

virtual int SubscribeAllRemoteVideoStreams(bool sub) = 0;

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

• Subscription to all remote video streams in the current channel stops.

• Video streams from new users who join the channel later will also not be subscribed to, even if you have called <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#2cbc54790brn3" id="b7b0080f3cnoq">SetDefaultSubscribeAllRemoteVideoStreams</a>(true) to subscribe by default.

• You cannot use <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#jyGTp" id="0e2edf97aa1g6">SubscribeRemoteVideoStream</a> to independently control the audio stream of a specified user.

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

Parameters

Response description

0: The method call was successful. Other values: The method call failed.

Stops or resumes a specific remote user's media stream.

virtual int SubscribeRemoteMediaStream(const char* uid, AliEngineVideoTrack videoTrack, bool subVideo,  bool subAudio) = 0;

This method subscribes to remote audio and video streams together.

Related methods

Compared with SubscribeRemoteMediaStream[2/2], this method uses two Boolean parameters, subVideo and subAudio, to determine whether to subscribe to the remote audio and video streams. The videoTrack parameter controls which video stream to pull.

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Stops or resumes a specific remote user's media stream.

virtual int SubscribeRemoteMediaStream(const char* uid, AliEngineVideoTrack videoTrack, AliEngineAudioTrack audioTrack) = 0;

This method subscribes to remote audio and video streams together.

Related methods

Compared with 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 when you call the method.

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

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

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

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Subscribes to a specified user's stream across channels.

virtual int SubscribeRemoteDestChannelStream(const char* channelId, const char* uid, AliEngineVideoTrack track, bool sub_audio, bool sub) = 0;

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Adjusts the playback volume of a specified remote user.

virtual int SetRemoteAudioVolume(const char *uid, int volume) = 0;

Parameters

Return value

• 0: Success.

• A non-zero value: Failure.

Stops or resumes sending local audio data.

virtual int MuteLocalMic(bool mute, AliEngineMuteLocalAudioMode mode = AliEngineMuteLocalAudioModeDefault) = 0;

When to call

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

Related callbacks

After the call succeeds, the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#a15f0a6cf6id7" id="f4ae88f094vqy">OnUserAudioMuted</a> callback is triggered on remote clients to indicate whether the user is muted.

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Stops or resumes playback of remote audio.

virtual int MuteRemoteAudio(const char *uid,
                                    bool mute) = 0;

This API is used only to stop or resume audio playback for a specified remote user. It does not affect stream pulling or decoding of the remote audio. To unsubscribe from a user's audio stream, call <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#957e547813q56" id="89841a0989t7y">SubscribeRemoteAudioStream</a>.

When to call

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

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Stops or resumes the playback of the audio tracks of all remote users.

virtual int MuteAllRemoteAudio(bool mute) = 0;

Use this method to stop or resume all remote audio playback.

When to call

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

Parameters

Return value

0: The method call was successful. A non-zero value: The method call failed.

Starts audio collection.

virtual int StartAudioCapture() = 0;

This method starts audio collection. You can also call it before you join a channel to start audio collection in advance. If it is not set, the SDK automatically controls the audio collection device. To start audio collection after it has been stopped by calling stopAudioCapture, call this method.

When to call

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

Related methods

• The StartAudioCapture[2/2] method can control whether the audio collection device remains on after you leave the channel using a parameter.

Related callbacks

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

Return value

0: The method call was successful. Other values: The method call failed.

Starts audio collection.

virtual int StartAudioCapture(bool keepAlive) = 0;

Stops microphone audio capture after muting.

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

When to call

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

Related methods

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

Related callbacks

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

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Stops audio collection.

virtual int StopAudioCapture() = 0;

After you start audio device collection with StartAudioCapture, you can call this method to stop it.

Related callbacks

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

Return value

0: The method call was successful. Other values: The method call failed.

Sets the volume callback frequency and smoothing coefficient.

virtual int EnableAudioVolumeIndication(int interval, int smooth, int reportVad) = 0;

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

When to call

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

Related callbacks

After a successful call to this method, if there are publishing users in the channel, the SDK triggers the following two callbacks at the set time interval:

• The speaker's audio volume is reported through the OnAudioVolumeCallback callback. The callback frequency is determined by the `interval` parameter.

• Voice activity detection. When an active user is detected, the speaker's UID is reported through the OnActiveSpeaker callback.

When to call

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

Parameters

Response Description

0: The method call was successful. Other values: The method call failed.

Starts the audio playback device.

virtual int StartAudioPlayer() = 0;

This method can start audio playback in advance. If it is not set, the SDK automatically starts audio playback after subscribing to an audio stream.

Return value

• 0: Success.

• A non-zero value: Failure. An error code is returned.

Stops audio playback.

virtual int StopAudioPlayer() = 0;

This method can stop audio playback. It corresponds to AliEngine::StartAudioPlayer.

Parameters

None.

Return value

• 0: Success.

• A non-zero value: Failure. An error code is returned.

Sets the playback volume.

virtual int SetPlayoutVolume(int volume) = 0;

Parameters

Return value

• 0: Success.

• A non-zero value: Failure. An error code is returned.

virtual int SetRecordingVolume(int volume) = 0;

Parameters

Response description

• 0: Success.

• A non-zero value: Failure. An error code is returned.

Plays an audio file.

virtual int PlayAudioFileTest(const char* filePath) = 0;

Parameters

Return value

• 0: Success.

• <0: Failure.

Stops playing the audio file.

virtual int StopAudioFileTest() = 0;

Return value

• 0: Success.

• <0: Failure.

Starts an audio collection test before a call.

virtual int StartAudioCaptureTest() = 0;

This method can start an audio collection test. You can use the result of the AliEngineEventListener::OnTestAudioVolumeCallback callback to determine if audio collection is normal.

Return value

• 0: Success.

• <0: Failure.

Stops the audio collection test.

virtual int StopAudioCaptureTest() = 0;

Return value

• 0: Success.

• <0: Failure.

Enables or disables system audio collection and publishing.

virtual int EnableSystemAudioRecording(bool enable, const char *path = nullptr, const char *device_id = nullptr) = 0;

This method enables or disables system audio collection, such as sounds played by browsers and applications.

Parameters

Return value

• 0: The method call was successful.

• <0: The method call failed.

Checks if system audio collection and publishing is currently enabled.

virtual bool IsSystemAudioRecording() = 0;

Return value

• true: Enabled.

• false: Disabled.

Sets the system audio collection and publishing volume.

virtual int SetSystemAudioRecordingVolume(int volume) = 0;

This method is valid only on Windows and macOS platforms.

This method can be set only after system audio collection and publishing is enabled. Otherwise, the setting is invalid.

Parameters

Return value

• 0: Success.

• <0: Failure.

Retrieves the current system audio collection and publishing volume.

virtual int GetSystemAudioRecordingVolume() = 0;

This method is valid only on Windows and macOS platforms.

Return value

The system collection publishing volume.

Sets the system audio playback volume.

virtual int SetSystemAudioPlayoutVolume(int volume) = 0;

This method is valid only on Windows and macOS platforms.

This method can be set only after system audio collection and publishing is enabled. Otherwise, the setting is invalid.

Parameters

Return value

• 0: Success.

• <0: Failure.

Retrieves the current system audio playback volume.

virtual int GetSystemAudioPlayoutVolume() = 0;

This method is valid only on Windows and macOS platforms.

Return value

The system tracks the playback volume.

Retrieves the list of recording devices in the system.

virtual AliEngineDeviceInfoList* GetAudioCaptureList() = 0;

Return value

A pointer to the list of recording devices, AliEngineDeviceInfoList *.

Retrieves the name of the recording device in use.

virtual String GetCurrentAudioCaptureName() = 0;

Return value

The name of the current audio collection device.

Retrieves the ID of the recording device in use.

virtual String GetCurrentAudioCaptureID() = 0;

Return value

The ID of the recording device currently in use.

Selects a recording device by name.

virtual int SetCurrentAudioCaptureName(const char* captureName) = 0;

Parameters

Return value

0 for success, other values for failure.

Selects a recording device by ID.

virtual int SetCurrentAudioCaptureID(const char* captureID) = 0;

Parameters

Return value

0 for success, other values for failure.

Retrieves the list of speakers in the system.

virtual AliEngineDeviceInfoList* GetAudioPlayerList() = 0;

Return value

A pointer to the list of speakers in the system, AliEngineDeviceInfoList *.

Retrieves the list of recordable speakers in the system (for in-system recording).

virtual AliEngineDeviceInfoList* GetSystemRecordAudioPlayerList() = 0;

Return value

The audio playback device list is mainly used as the last parameter for EnableSystemAudioRecording to collect system playback audio.

Retrieves the name of the speaker currently in use.

virtual String GetCurrentAudioPlayerName() = 0;

Return value

The name of the current audio playback device.

Retrieves the ID of the speaker currently in use.

virtual String GetCurrentAudioPlayerID() = 0;

Return value

The ID of the current audio playback device.

Selects a speaker by name.

virtual int SetCurrentAudioPlayerName(const char* playerName) = 0;

Return value

The audio playback device name.

Selects a speaker by ID.

virtual int SetCurrentAudioPlayerID(const char* playerID) = 0;

Parameters

Return value

0 for success, other values for failure.

Sets the audio collection device volume. The volume range is [0, 100].

virtual int SetRecordingDeviceVolume(int volume) = 0;

Parameter list

Return value

0 for success, other values for failure.

Retrieves the audio collection device volume.

virtual int GetRecordingDeviceVolume() = 0;

Return value

>=0 returns the volume. Other values indicate failure.

Sets the audio playback device volume. The volume range is [0, 100].

virtual int SetPlaybackDeviceVolume(int volume) = 0;

Parameters

Return value

0 for success, other values for failure.

Retrieves the audio playback device volume.

virtual int GetPlaybackDeviceVolume() = 0;

Return value

>=0 for system volume. Other values for failure.

Mutes the audio collection device.

virtual int SetRecordingDeviceMute(bool mute) = 0;

Parameters

Return value

0 for success, other values for failure.

Retrieves the mute status of the audio collection device.

virtual bool GetRecordingDeviceMute() = 0;

Return value

Whether recording is muted.

Mutes the audio playback device.

virtual int SetPlaybackDeviceMute(bool mute) = 0;

Parameters

Return value

0 for success, other values for failure.

Retrieves the mute status of the audio playback device.

virtual bool GetPlaybackDeviceMute() = 0;

Return value

Whether the playback device is muted.

Sets the voice changer effect mode.

virtual int SetAudioEffectVoiceChangerMode(const AliEngineAudioEffectVoiceChangerMode &mode) = 0;

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Sets the pitch parameter.

virtual int SetAudioEffectPitchValue(double value) = 0;

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Sets the reverb effect mode.

virtual int SetAudioEffectReverbMode(const AliEngineAudioEffectReverbMode& mode) = 0;

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Sets the reverb effect type and specific parameters.

virtual int SetAudioEffectReverbParamType(const AliEngineAudioEffectReverbParamType& type,
                                                  float value) = 0;

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Sets the preset beautification sound effect mode.

virtual int SetAudioEffectBeautifyMode(const AliEngineAudioEffectBeautifyMode& mode) = 0;

This method sets preset beautification modes within the SDK. It is suitable for scenarios that require beautification of human voice quality, 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 magnetism or improving clarity. This improves the listening experience for remote users.

When to call

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

Parameters

Return value

• 0: The setting was successful.

• A non-zero value: The setting failed.

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

virtual int SetAudioEffectEqualizationParam(const AliEngineAudioEffectEqualizationBandFrequency &bandIndex, float gain) = 0;

This method adjusts the locally collected 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 voice clarity optimization, human voice enhancement, and noise reduction assistance.

The equalizer supports adjustment of the full audio spectrum from 31 Hz to 16 kHz, with a total of 10 standard frequency bands. The gain value for each band can be set independently, ranging from [-15, 15] dB, with a default of 0 dB (no enhancement or attenuation).

Limits

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

Parameters

Response description

0: The setting was successful.

A non-zero value: The setting failed.

Adds an external audio stream.

virtual int AddExternalAudioStream(const AliEngineExternalAudioStreamConfig& config) = 0;

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

1. Call <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#991b862eb353w" id="08ee3d1ed35jj">AddExternalAudioStream</a> to add an external audio stream and obtain the external audio stream ID.

2. Call <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#e6cf3f7cef0g6" id="fae817d0f00p3">PushExternalAudioStreamRawData</a> to push audio data to the created audio stream.

3. When the call ends, you need to call <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#u27oe" id="3b9a3eb119umh">RemoveExternalAudioStream</a> to remove the external audio stream.

For more information about how to publish custom collected audio in a channel, see Custom audio collection.

Parameters

Return value

A value greater than 0 indicates a successful method call and returns the external audio stream ID. Other values indicate a failed method call.

Inputs external audio stream data.

virtual int PushExternalAudioStreamRawData(int streamId, AliEngineAudioRawData& data) = 0;

This method passes data into the specified audio stream. The steps are as follows:

1. Call the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#991b862eb353w" id="3836ac109732c">AddExternalAudioStream</a> API to add an external audio stream and obtain the external audio stream ID.

2. Call PushExternalAudioStreamRawData to pass audio data into the created audio stream.

3. When the call ends, you need to call <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#u27oe" id="398ea88d61fn0">RemoveExternalAudioStream</a> to remove the external audio stream.

For more information about how to publish custom collected audio in a channel, see Custom audio collection.

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Sets the publishing volume of the external audio stream.

virtual int SetExternalAudioStreamPublishVolume(int streamId, int vol) = 0;

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Sets the publishing volume of the external audio stream.

virtual int SetExternalAudioStreamPlayoutVolume(int streamId, int vol) = 0;

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Retrieves the publishing volume of the external audio stream.

virtual int GetExternalAudioStreamPublishVolume(int streamId) = 0;

Parameters

Returns

[0, 100]: The publishing volume. A value less than 0 indicates failure.

Retrieves the playback volume of the external audio stream.

virtual int GetExternalAudioStreamPlayoutVolume(int streamId) = 0;

Parameters

Return value

[0, 100]: The playback volume. A value less than 0 indicates failure.

Removes an external audio stream.

virtual int RemoveExternalAudioStream(int streamId) = 0;

This method removes the corresponding external audio stream based on the passed streamId. It corresponds to the AddExternalAudioStream method.

When to call

If you want to use the custom audio input feature, you need to call the AddExternalAudioStream method to add an audio stream and obtain the external audio stream ID. You can then call the <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#e6cf3f7cef0g6" id="bdab74f108i1p">PushExternalAudioStreamRawData</a> interface to input your audio data to the SDK. When you want to stop the custom audio input, call this interface to remove the corresponding external audio stream and clean up resources.

Parameters

Return value

0 for success, other values for failure.

Retrieves audio file information.

virtual int GetAudioFileInfo(const char *filePath) = 0;

This is an asynchronous method. You can retrieve the audio file information through AliEngineEventListener::OnAudioFileInfo.

Parameters

Return value

• 0: Success.

• A non-zero value: Failure. An error code is returned.

Starts audio mixing for accompaniment.

virtual int StartAudioAccompany(const char *filePath, const AliEngineAudioAccompanyConfig& config) = 0;

This is an asynchronous method. You can listen to the audio accompaniment player status through AliEngineEventListener::OnAudioAccompanyStateChanged.

Parameters

Return value

• 0: Success.

• A non-zero value: Failure. An error code is returned.

Stops audio mixing for accompaniment.

virtual int StopAudioAccompany() = 0;

Return value

• 0: Success.

• A non-zero value: Failure. An error code is returned.

Sets the accompaniment volume.

 virtual int SetAudioAccompanyVolume(int volume) = 0;

Parameters

Return value

• 0: Success.

• A non-zero value: Failure. An error code is returned.

Sets the accompaniment publishing volume.

virtual int SetAudioAccompanyPublishVolume(int volume) = 0;

Parameters

Return value

• 0: Success.

• A non-zero value: Failure. An error code is returned.

Retrieves the accompaniment publishing volume.

virtual int GetAudioAccompanyPublishVolume() = 0;

Return value

The accompaniment publishing volume. The range is [0-100].

Sets the local playback volume for accompaniment.

virtual int SetAudioAccompanyPlayoutVolume(int volume) = 0;

Parameters

Return value

• 0: Success.

• A non-zero value: Failure. An error code is returned.

Retrieves the local playback volume for accompaniment.

virtual int GetAudioAccompanyPlayoutVolume() = 0;

Return value

The local playback volume for accompaniment. The range is [0-100].

Pauses audio mixing for accompaniment.

virtual int PauseAudioAccompany() = 0;

Response description

• 0: Success.

• A non-zero value: Failure. An error code is returned.

Resumes audio mixing for accompaniment.

virtual int ResumeAudioAccompany() = 0;

Response description

• 0: Success.

• A non-zero value: Failure. An error code is returned.

Retrieves the duration of the accompaniment file in milliseconds.

virtual int GetAudioAccompanyDuration() = 0;

Response description

The duration of the audio accompaniment file in milliseconds.

Retrieves the playback progress of the accompaniment file in milliseconds.

virtual int GetAudioAccompanyCurrentPosition() = 0;

Return value

The current playback position of the audio accompaniment file in milliseconds.

Sets the playback position of the accompaniment file.

virtual int SetAudioAccompanyPosition(int pos) = 0;

Response Description

• 0: Success.

• A non-zero value: Failure. An error code is returned.

Preloads a sound effect file.

virtual int PreloadAudioEffect(unsigned int soundId,
                                       const char *filePath) = 0;

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Deletes a preloaded sound effect file.

virtual int UnloadAudioEffect(unsigned int soundId) = 0;

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Starts playing a sound effect.

virtual int PlayAudioEffect(unsigned int soundId, const char *filePath, const AliEngineAudioEffectConfig& config) = 0;

Parameters

Returns

0: The method call was successful. Other values: The method call failed.

Stops playing a sound effect.

virtual int StopAudioEffect(unsigned int soundId) = 0;

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Stops playing all sound effects.

- (int)StopAllAudioEffects;

Return value

0: The method call was successful. Other values: The method call failed.

Pauses a sound effect.

virtual int PauseAudioEffect(unsigned int soundId) = 0;

Parameters

Response Description

0: The method call was successful. Other values: The method call failed.

Pauses all sound effects.

virtual int PauseAllAudioEffects() = 0;

Response description

0: The method call was successful. Other values: The method call failed.

Resumes playing a sound effect.

virtual int ResumeAudioEffect(unsigned int soundId) = 0;

Parameters

Response description

0: The method call was successful. Other values: The method call failed.

Resumes playing all sound effects.

virtual int ResumeAllAudioEffects() = 0;

Return value

0: The method call was successful. Other values: The method call failed.

Sets the publishing volume for a sound effect.

virtual int SetAudioEffectPublishVolume(unsigned int soundId, int volume) = 0;

Parameters

Returns

0: The method call was successful. Other values: The method call failed.

Retrieves the publishing volume of a sound effect.

virtual int GetAudioEffectPublishVolume(unsigned int soundId) = 0;

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Sets the local playback volume for all sound effects.

virtual int SetAllAudioEffectsPublishVolume(int volume) = 0;

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Sets the local playback volume for a sound effect.

virtual int SetAudioEffectPlayoutVolume(unsigned int soundId, int volume) = 0;

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Retrieves the local playback volume of a sound effect.

virtual int GetAudioEffectPlayoutVolume(unsigned int soundId) = 0;

Parameters

Response description

0: The method call was successful. Other values: The method call failed.

Sets the playback volume for all sound effects.

virtual int SetAllAudioEffectsPlayoutVolume(int volume) = 0;

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Sets the publishing volume for all sound effects.

virtual int SetAllAudioEffectsPublishVolume(int volume) = 0;

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

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

virtual int SetLocalViewConfig(AliEngineVideoCanvas renderConfig,
                                         AliEngineVideoTrack track) = 0;

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

When to call

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

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Sets the camera collection preferences.

virtual int SetCameraCapturerConfiguration(const AliEngineCameraCapturerConfiguration& config) = 0;

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

When to call

You must set this before you open the camera. For example, call it before the following operations:

• StartPreview (starts preview)

• JoinChannel (joins a channel)

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Disables or re-enables local video collection.

virtual int EnableLocalVideo(bool enabled) = 0;

This method controls the enabling and disabling of local video collection. When local video collection 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 collection, both the local preview and the remote published stream will remain on the last frame.

When to call

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

Related callbacks

After a successful call to this method, the OnUserVideoEnabled callback notifies remote users.

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Stops or resumes sending local video data.

virtual int MuteLocalCamera(bool mute, AliEngineVideoTrack track) = 0;

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

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

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

virtual int SetRemoteViewConfig(AliEngineVideoCanvas renderConfig,
                                          const char *uid,
                                          AliEngineVideoTrack track) = 0;

This method attaches the display view for a specified video stream from a remote user and sets properties for the local display of the remote view, such as the rendering mode, mirror mode, and rotation angle. This action affects only the video image that the local user sees. To set the local preview view, call <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#fbc8ab10f5e03" id="c0f59b8c26y7o">SetLocalViewConfig</a>.

• If the view parameter in AliEngineVideoCanvas is empty, rendering stops.

• To reset the renderMode parameter of AliEngineVideoCanvas during playback, keep the other parameters unchanged and only modify renderMode.

• To reset the mirrorMode parameter of AliEngineVideoCanvas during playback, keep the other parameters unchanged and only modify mirrorMode.

When to call

We recommend that you call this when you receive the OnRemoteTrackAvailableNotify callback, which is when the remote user's video is available.

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Checks whether the camera is on.

virtual bool IsCameraOn() = 0;

Return value

true: The camera is on. false: The camera is not on.

Sets the video encoding properties.

virtual void SetVideoEncoderConfiguration(const AliEngineVideoEncoderConfiguration& config) = 0;

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. If you only need to set the camera stream video encoding properties once per session, we recommend that you call it before you join the channel.

Limits

The `mirrorMode` of this method and setVideoMirrorMode can both set the video publishing mirror. We recommend that you use only one of them. Using multiple methods at the same time can cause the mirror effects to stack, which leads to failed or incorrect mirror settings.

Parameters

Sets the video decoding properties. This method sets the camera stream video decoding properties, including software and hardware decoding settings and whether to enable B-frames.

virtual void SetVideoDecoderConfiguration(const AliEngineVideoDecoderConfiguration& config) = 0;

When to call

We recommend that you call this before you join a channel and pull a stream.

Parameters

Starts the local preview and automatically turns on the camera.

virtual int StartPreview(int width = 0, int height = 0) = 0;

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

When to call

• Before you call this method, you need to set a view for the local preview through SetLocalViewConfig. Otherwise, you cannot preview the video, but this does not affect publishing.

• If needed, you can call this method before you join a channel with JoinChannel to start the preview, which will automatically turn on the camera.

Response description

0: The method call was successful. Other values: The method call failed.

Stops the local preview.

virtual int StopPreview() = 0;

This method closes the local video preview and turns off the camera. After you stop the preview, the local end will remain on the last frame, which does not affect publishing.

When to call

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

Return value

0: The method call was successful. Other values: The method call failed.

Sets the preview and publishing mirror capabilities.

virtual int setVideoMirrorMode(AliEngineVideoPipelineMirrorMode mirrorMode) = 0;

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 operates on the video when the preview and encoding (publishing) can be operated.

Limits

This method overlaps with the mirrorMode parameter in SetLocalViewConfig and SetVideoEncoderConfiguration. We recommend that you use only this method.

Parameters

Return value

• 0: The setting was successful.

• <0: The setting failed.

  • AliRtcErrInner: An internal SDK state error. Check if the SDK instance was created successfully.

Sets the collection scaling timing. Video data is scaled either immediately upon collection or during encoding.

virtual void SetCapturePipelineScaleMode(const AliEngineCapturePipelineScaleMode mode) = 0;

This method sets whether video data collection scaling occurs immediately upon collection or during encoding. For example, when the collection resolution is inconsistent with the encoding resolution, 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 you open the camera, for example, before you start the preview with StartPreview or join a channel with JoinChannel.

Parameters

Retrieves the camera list.

virtual AliEngineDeviceInfoList* GetCameraList() = 0;

Return value

A pointer to the camera list object, AliEngineDeviceInfoList*.

Retrieves the name of the camera currently in use.

virtual String GetCurrentCameraName() = 0;

Return value

The name of the camera device currently in use.

Retrieves the ID of the camera currently in use.

virtual String GetCurrentCameraID() = 0;

Return value

The ID of the camera currently in use.

Selects a camera by name.

virtual int SetCurrentCameraName(const char* cameraName) = 0;

Parameters

Return value

0 for success, other values for failure.

Selects a camera by ID.

virtual int SetCurrentCameraID(const char* cameraID) = 0;

Parameters

Return value

0 for success, other values for failure.

Retrieves the supported resolutions.

virtual AliEngineVideoResolutionList * GetCurrentCameraSupportedResolutionList(int source) = 0 ;

Parameters

Return value

If the value is not NULL, it retrieves the list of supported resolutions. NULL indicates failure.

Enables an external video input source.

virtual int SetExternalVideoSource(bool enable,
        AliEngineVideoTrack type,
        AliEngineRenderMode renderMode) = 0;

Parameters

Inputs video data.

virtual int PushExternalVideoFrame(const AliEngineVideoRawData &frame,
        AliEngineVideoTrack type) = 0;

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Starts a bypass live stream.

virtual int StartPublishLiveStream(const String& streamURL, const AliEngineLiveTranscodingParam &transcoding) = 0;

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Updates bypass live stream parameters.

virtual int UpdatePublishLiveStream(const String& streamURL, const AliEngineLiveTranscodingParam &transcoding) = 0;

Parameters

Return value

0: The method call was successful. Other values: The method call failed.

Stops the bypass live stream.

virtual int StopPublishLiveStream(const String& streamURL) = 0;

Parameters

Response description

0: The method call was successful. Other values: The method call failed.

Retrieves the bypass live stream status.

virtual AliEngineLiveTranscodingState GetPublishLiveStreamState(const String& streamURL) = 0;

Parameters

Response description

Returns the bypass live stream status.

Starts network quality detection. Some on-premises network problems may cause audio and video calls to fail. By calling this method, you can obtain information such as upstream and downstream network bandwidth, packet loss rate, jitter, and link RTT to help locate and solve related network problems.

 virtual int StartLastmileDetect(bool uplink, bool downlink, int uplinkBandWidth, int downlinkBandWidth) = 0;

When to call

This method needs to be called before JoinChannel. The detection results will be provided through a callback. A network detection may take a long time. You can call StopLastmileDetect to stop the network detection as needed.

Limits

The SDK can perform only one network detection at a time. Repeated calls before the previous detection is complete will be invalid.

Related callbacks

After a successful call to this method, two callbacks will be triggered:

• OnLastmileDetectResultWithQuality: This callback is triggered in about 3s to roughly determine the network quality level.

• OnLastmileDetectResultWithBandWidth: This callback is triggered in about 30s to provide detailed detection results.

Parameters

Return value

• 0: The method call was successful.

• <0: The method call failed. For example, this can occur if you have already joined a channel.

Stops network quality detection. Call this method to stop network quality detection.

virtual int StopLastmileDetect() = 0;

When to call

You can call this method after you create the engine and before you join a channel.

Return value

• 0: This method was called successfully.

• <0: This method call failed.

Sends media extension information, which is implemented internally using SEI.

virtual int SendMediaExtensionMsg(const int8_t * message, uint32_t length, int32_t repeatCount, uint32_t delay, bool isKeyFrame) = 0;

The SDK provides the function of sending and receiving media extension information. The receiving end refers to AliEngineEventListener::OnMediaExtensionMsgReceived. When you use media extension information, it is necessary to reuse the audio and video data channel, so the sending frequency and data length of custom messages must be controlled. The usage limits are as follows:

• Send a maximum of fps messages per second as set by the profile.

• To avoid affecting the transmission quality of media data, the custom message body length is limited to 4 KB, which can be used to transmit a small amount of data.

• The repeatCount parameter in the sendMediaExtensionMsg function is the redundancy of the custom message. If it is greater than 1, it will be sent multiple times to prevent message loss due to network packet loss. In this case, other people in the room will also receive the same message multiple times, and duplicates need to be removed.

• When the custom message is sent, subscribers in the room will also receive it during bypass live streaming. Setting it to -1 means sending the data permanently, unless sendMediaExtensionMsg is called again.

• Only one sendMediaExtensionMsg will be sent at a time. This means that calling sendMediaExtensionMsg will overwrite the previous call to sendMediaExtensionMsg if the previous call was not sent or not completed.

Parameters

Return value

• 0: Success.

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

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

Sends media extension information, which is implemented internally using SEI.

virtual int SendMediaExtensionMsgEx(const int8_t * message, uint32_t length, int32_t repeatCount, uint32_t delay, bool isKeyFrame, int32_t payloadType) = 0;

The SDK provides the function of sending and receiving media extension information. The receiving end refers to AliEngineEventListener::OnMediaExtensionMsgReceived. When you use media extension information, it is necessary to reuse the audio and video data channel, so the sending frequency and data length of custom messages must be controlled. The usage limits are as follows:

• Send a maximum of fps messages per second as set by the profile.

• To avoid affecting the transmission quality of media data, the custom message body length is limited to 4 KB, which can be used to transmit a small amount of data.

• The repeatCount parameter in the sendMediaExtensionMsg function is the redundancy of the custom message. If it is greater than 1, it will be sent multiple times to prevent message loss due to network packet loss. In this case, other people in the room will also receive the same message multiple times, and duplicates need to be removed.

• When the custom message is sent, subscribers in the room will also receive it during bypass live streaming. Setting it to -1 means sending the data permanently, unless sendMediaExtensionMsg is called again.

• Only one sendMediaExtensionMsg will be sent at a time. This means that calling sendMediaExtensionMsg will overwrite the previous call to sendMediaExtensionMsg if the previous call was not sent or not completed.

Parameters

Return value

• 0: Success.

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

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

Callback for network connection status changes.

virtual void OnConnectionStatusChange(int status, int reason) {};

Parameters

Callback for on-premises device exceptions. Customers need to pay attention to this callback.

virtual void OnLocalDeviceException(AliEngineLocalDeviceType deviceType, AliEngineLocalDeviceExceptionType exceptionType, const char* msg){};

Parameters

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

virtual void OnAuthInfoWillExpire() {};

This callback indicates that the user's authentication information is about to expire. Authentication will expire 30 seconds after this callback is received. You need to obtain a new token and then update the authentication information in one of the following ways:

• Call the RefreshAuthInfo method to update the authentication information.

• Call LeaveChannel to leave the current channel, and then call JoinChannel to rejoin the channel.

When 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 user calls an interface that requires authentication, and the server returns that the information has expired.

virtual void OnAuthInfoExpired() {};

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

• Call LeaveChannel to leave the current channel, and then call JoinChannel to rejoin the channel.

When 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 calling the JoinChannel method, which handles events after joining the channel. Choose one of them.

virtual void OnJoinChannelResult(int result, const char *channel, const char *userId, int elapsed) {}

Trigger conditions

When the application calls the JoinChannel method, this callback indicates whether the channel was successfully joined and returns information about the channel joining and the time it took to join.

Parameters

Callback for the result of leaving a channel. This is returned after you call the LeaveChannel method. If you call Destroy immediately after you call this, you will not receive this callback.

virtual void OnLeaveChannelResult(int result, AliEngineStats stats) {}

Trigger conditions

When the application successfully calls LeaveChannel to leave the channel, this callback is triggered to return the result of leaving and the statistics of this channel session.

Parameters

Callback for when a remote user goes offline.

virtual void OnRemoteUserOffLineNotify(const char *uid, AliEngineUserOfflineReason reason) {}

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

Trigger conditions

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

• A callback is triggered when a remote streamer calls <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#c99c2b257dd8o" id="03e45f655fcxx">SetClientRole</a> to switch their role to a viewer (set to AliEngineClientRoleLive).

• The callback is triggered when no data is received from the remote streamer for a long time and they are considered to have dropped.

Parameters

Callback for when a remote user comes online.

virtual void OnRemoteUserOnLineNotify(const char *uid, 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 will receive a join callback for users already in the channel. This is used to display previously joined users.

Parameters

Callback for when a remote user's stream changes.

virtual void OnRemoteTrackAvailableNotify(const char *uid,
                                                  AliEngineAudioTrack audioTrack,
                                                  AliEngineVideoTrack videoTrack) {}

This callback is triggered when a remote user's publishing state changes. Through this callback, you can know in real time whether a remote user is publishing audio and video streams. You can then display or hide the remote user's audio and video information on the UI 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 stream mode, when a remote user calls SetClientRole to switch from viewer to streamer and also sets publishing, this callback is triggered.

Taking video as an example, suppose a remote user is set not to publish. This callback will not be triggered in that case.

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

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

• When the remote user stops publishing the camera stream and only keeps the screen sharing stream (publishing state: camera stream and screen sharing stream -> only screen sharing stream), the local callback returns AliEngineVideoTrackScreen, which indicates that only the screen sharing stream is currently available.

• When the remote user stops publishing the screen sharing stream (publishing state: only screen sharing stream -> no video stream), the local callback returns AliEngineVideoTrackNo, which indicates that no video stream is currently available.

Parameters

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

virtual void OnBye(int code) {}

When a user is disconnected for some reason or the channel is closed, this callback is triggered. You can use the callback parameter code to identify the reason for the disconnection and handle it accordingly.

Trigger conditions

• The current user is kicked out by the server.

• The channel is closed (the server actively removes the channel).

• Passive leaving, which requires the client to try to restore the session or reconnect.

Parameters

Callback for audio publishing changes.

virtual void OnAudioPublishStateChanged(AliEnginePublishState oldState, AliEnginePublishState newState, int elapseSinceLastState, const char *channel) {};

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

Trigger conditions

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

• Stops publishing.

• Calls <a baseurl="t2713962_v4_0_0.xdita" data-node="4904760" data-root="16090" data-tag="xref" href="#c99c2b257dd8o" id="904fc4e83a35n">SetClientRole</a> to switch to a viewer.

Parameters

Callback for audio subscription changes.

virtual void OnAudioSubscribeStateChanged(const char *uid,
                                                  AliEngineSubscribeState oldState, 
                                                  AliEngineSubscribeState newState,
                                                  int elapseSinceLastState,
                                                  const char *channel) {};

This callback notifies the local user of changes in the remote user's audio stream subscription state. Through this callback, you can know the subscription state change of a remote user's camera stream and the time interval from the previous state to the current state.

Parameters

Notification that a user has muted their audio.

virtual void OnUserAudioMuted(const char* uid, bool isMute) {}

Parameters

Notification that a user's audio has been interrupted. This usually occurs in scenarios where audio is preempted, such as by a phone call.

virtual void OnUserAudioInterruptedBegin(const char* uid) {}

Parameters

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

virtual void OnUserAudioInterruptedEnded(const char* uid) {}

Parameters

Callback for video publishing changes.

virtual void OnVideoPublishStateChanged(AliEnginePublishState oldState, AliEnginePublishState newState, int elapseSinceLastState, const char *channel) {};

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

Parameters

Callback for camera stream subscription changes.

virtual void OnVideoSubscribeStateChanged(const char *uid, 
                                                  AliEngineSubscribeState oldState, 
                                                  AliEngineSubscribeState newState,
                                                  int elapseSinceLastState,
                                                  const char *channel) {};

This callback notifies the local user of changes in the remote user's camera stream subscription state. Through this callback, you can know the subscription state change of a 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.

virtual void OnUserVideoMuted(const char* uid, bool isMute) {}

Parameters