Intelligent Media Services:AliRtcEngine API reference

Joins a channel using multiple parameters.

public abstract int joinChannel(AliRtcAuthInfo authInfo, String userName);

Use this method to join a channel. Alibaba Real-Time Communication (ARTC) uses channels to organize users. Users must join a channel to publish or subscribe to audio and video streams. This method, joinChannel[1/3], and joinChannel[3/3] all let you join a channel. They differ in their authentication methods and the user information they pass. The differences are as follows:

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

• This multi-parameter interface for joining a channel requires you 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 used for Real-time Conversational AI scenarios. Pass a single-parameter joining token and set the capabilityProfile user property based on the scenario.

Call limits

• After you successfully join a channel, to join another channel, you must first call <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#fef395c4beqdt" id="e2525ba6a0k3s">leaveChannel</a> to leave the current channel, and ensure that you receive, from AliRtcEngineEventListener, the <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#8c189be470bsp" id="6aefdfedb0op3">onLeaveChannelResult</a> callback before you can join another channel.

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

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

Related callbacks

A successful call to this method triggers the following callbacks:

• The result of the local client joining a channel is returned by the AliRtcEngineEventListener <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#89f5ad2d0bnd1" id="fb41cdcfc6acj">onJoinChannelResult</a> callback.

• After you successfully join a channel, remote clients trigger the <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#7298cad465wnd" id="8e9d69ebe54sr">onRemoteUserOnLineNotify</a> callback.

Parameters

Return value

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

Joins a channel (single-parameter join).

public abstract int joinChannel(String token, AliRTCSdkChannelParam channelParam);

This method joins a channel. Alibaba Real-Time Communication (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] all let you 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. Pass a token generated for a single-parameter join using Token authentication. This method is recommended for joining channels in RTC scenarios.

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

• This method is for Real-time Conversational AI scenarios. Pass a single-parameter token to join a session. Set the user property capabilityProfile based on the scenario. For calls with an AI agent, set this property to AliCapabilityProfileAiHuman.

Calling restrictions

• After you successfully join a channel, to join another channel, you must first call <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#fef395c4beqdt" id="719d580348a95">leaveChannel</a> to leave the current channel and ensure that AliRtcEngineEventListener receives the <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#8c189be470bsp" id="d128acfee2fpd">onLeaveChannelResult</a> callback before you can join a new channel.

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

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

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

Related callbacks

A successful call to this method triggers the following callbacks:

• The result of the local client joining a channel is notified by the AliRtcEngineEventListener <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#89f5ad2d0bnd1" id="879ae2fa04zjd">onJoinChannelResult</a> callback.

• After you successfully join a channel, remote clients trigger the <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#7298cad465wnd" id="9b5662c5a0nvf">onRemoteUserOnLineNotify</a> callback.

Parameters

Return value

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

Leaves the channel. After you call this method, the SDK stops audio and video interaction and leaves the current channel.

public abstract int leaveChannel();

When to call

• Call this method to leave a channel after you have joined it.

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

Related callbacks

• Local user: Calling this method triggers the <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#8c189be470bsp" id="80f5e30245vfn">onLeaveChannelResult</a> callback to provide the result of leaving the channel.

• Remote users: After this API is called successfully, the <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#75c700a2376c1" id="69bf5ff199oda">onRemoteUserOffLineNotify</a> callback is triggered for remote users.

Return value

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

Checks if you are in a channel.

public abstract boolean isInCall();

Return value

Returns true if you are in a channel, and false otherwise.

Sets the user role.

public abstract int setClientRole(AliRTCSdkClientRole clientRole);

This method sets the user role to streamer or viewer.

In interactive mode, before you join a channel:

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

• Set the user role to viewer: The SDK does not publish local audio and video streams, but receives streams from other streamers.

When to call

Call this method either before or after you join a channel. Set the user role before you join, or switch the role after you join.

Limitations

This method works only in interactive mode. To use this method, you must call the setChannelProfile method to set the channel profile to AliRTCSdkInteractiveLive.

In interactive mode, explicitly set the user role before you join the channel.

Parameters

Gets the user role.

public abstract AliRTCSdkClientRole getCurrentClientRole();

Return value

The current user role.

Refreshes the authentication information.

public abstract int refreshAuthInfo(AliRtcAuthInfo authInfo);

This method updates the authentication information. A token expires after a certain period. When the token expires, the software development kit (SDK) cannot connect to the server.

When to call

In the following scenarios:

• When you receive the <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#e9acb46a25uym" id="7e1510bec7s3s">onAuthInfoWillExpire</a> callback reporting that the authentication information is about to expire, regenerate a Token on your server-side and then call this method to pass in the new Token.

• If you do not update the Token in time, the <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#8fa7e60f9f5qq" id="97664f9e46fhp">onAuthInfoExpired</a> callback is triggered to indicate that the authentication has expired. You must then regenerate a Token and call joinChannel to rejoin the channel.

Parameters

Return value

A return value of 0 indicates that the method call succeeded. Other values indicate that the method call failed.

Refreshes the authentication information.

public abstract int refreshAuthInfo(String token);

This method updates the token. Tokens expire after a certain period. After a token expires, the SDK can no longer connect to the server.

When to call

Regenerate a token on your server and then call this method to pass in the new token under the following circumstances:

• When you receive the <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#e9acb46a25uym" id="d708af68eevs9">onAuthInfoWillExpire</a> callback reporting that the authentication information is about to expire.

• If the token is not updated in time, the <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#8fa7e60f9f5qq" id="3fd674e985gl8">onAuthInfoExpired</a> callback is triggered, indicating that the authentication has expired. At this point, you must call joinChannel to rejoin the channel.

Parameters

Return value

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

Stops or resumes publishing the local video stream.

public abstract int publishLocalAudioStream(boolean enable);

This method controls whether to publish the local audio stream. By default, the SDK publishes the audio stream. To disable this default behavior, call publishLocalAudioStream(false) before joining a channel.

When to call

Call this method before or after joining a channel. If you call it before joining a channel, it modifies the default configuration. The new configuration takes effect when you join the channel.

Related callbacks

When the status of the local audio stream ingest changes, the local client triggers the <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#b7e3bb51c2ga9" id="4ced92c3f5hmj">onAudioPublishStateChanged</a> callback to notify you of the new ingest status, while remote clients trigger <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#7078e15087a0z" id="2b5460d448ga9">onRemoteTrackAvailableNotify</a> to notify you of the change in the remote user's stream availability.

Parameters

Return value

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

Checks whether the local audio stream is published.

public abstract boolean isLocalAudioStreamPublished();

Return value

Returns true if the local audio stream is published, or false otherwise.

Sets whether to subscribe to remote audio streams by default.

public abstract int setDefaultSubscribeAllRemoteAudioStreams(boolean sub);

This method configures the default subscription behavior for remote audio streams. This setting affects users who join the channel after this method is called. For most scenarios, set this to true.

When to call

Call this method before or after joining a channel.

• Before joining a channel:

  • By default, the software development kit (SDK) subscribes to remote audio streams when joining a channel. To change this behavior, call this method before joining the channel.

• After joining a channel:

  • To stop the default subscription, call setDefaultSubscribeAllRemoteAudioStreams(false). The SDK will not subscribe to the audio streams of users who join the channel afterward.

  • After stopping the default subscription, call the subscribeRemoteAudioStream method to resume subscribing to a specific user's audio stream. To resume subscribing to multiple users, call the method for each user.

  • After stopping the default subscription, calling setDefaultSubscribeAllRemoteAudioStreams(true) only resumes the audio streams from users who join the channel afterward. The SDK does not subscribe to the audio streams of remote users who joined while the default subscription was stopped.

Parameters

Returns

0 indicates a successful call. A non-zero value indicates a failed call.

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

public abstract int subscribeRemoteAudioStream(String uid, boolean sub);

Call this method to stop or resume subscribing to the audio stream of a specific remote user. For most scenarios, set the sub parameter to true.

Parameters

Return value

Returns 0 if the method is called successfully. Returns a value other than 0 if the call fails.

Sets whether to subscribe to all remote audio streams.

public abstract int subscribeAllRemoteAudioStreams(boolean sub);

This method is the master switch for subscribing to remote audio streams. Set this parameter to true in most cases. If you set it to false, the following occurs:

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

• The SDK will not subscribe to new users who join the channel.

• You cannot use <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#e09342eeb0z4k" id="a56b5f2a3f56k">subscribeRemoteAudioStream</a> to individually control the audio stream of a specific user.

To re-subscribe, call this API again and set it to true to resume the subscription.

Parameters

Return value

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

Sets whether to publish the camera stream.

public abstract int publishLocalVideoStream(boolean enable);

This method controls whether to publish the video stream captured by the local camera.

When to call

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

Call this method to modify the default configurations before you join a channel. The changes take effect when you join the channel.

Related callbacks

When the local audio stream ingest status changes, the <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#afe6d3c4b1rvg" id="8b70bc353aj68">onVideoPublishStateChanged</a> callback is triggered on the local client to report the latest status of the audio stream ingest. The <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#7078e15087a0z" id="176ee94b46lb7">onRemoteTrackAvailableNotify</a> callback is triggered on the remote client to indicate that the remote user's audio and video streams have changed.

Parameters

Returns

A value of 0 indicates a successful method call. A non-zero value indicates a failed call.

Checks if the camera stream is published.

public abstract boolean isLocalVideoStreamPublished();

Return value

true if the camera stream is published. false otherwise.

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

public abstract int setDefaultSubscribeAllRemoteVideoStreams(boolean sub);

Use this method to set the default video stream subscription behavior. By default, the SDK subscribes to video streams.

When to call

Call this method before or after you join a channel. If you call setDefaultSubscribeAllRemoteVideoStreams(false) after joining a channel, you will not receive video streams from users who subsequently join the channel.

To resume a video stream from a specific remote user, call subscribeRemoteVideoStream and specify the user's ID. To resume video streams from multiple users, call subscribeRemoteVideoStream multiple times. Calling setDefaultSubscribeAllRemoteVideoStreams(true) only resumes video streams from users who join the channel after the method is called.

This method sets the default subscription for remote video streams.

Parameters

Return value

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

Stops or resumes the subscription to a specified remote video stream.

public abstract int subscribeRemoteVideoStream(String uid, AliRtcVideoTrack track, boolean sub);

Subscribes to or unsubscribes from the video stream of a specified user.

When to call

Call this method before or after joining a channel.

Parameters

Return value

• 0: The call succeeded.

• A non-zero value: The call failed.

Stops or resumes receiving all remote video streams.

public abstract int subscribeAllRemoteVideoStreams(boolean sub);

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

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

• New users who join the meeting later will also not be subscribed (even if you have set <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#c90127d90d22o" id="8661e30c89dum">setDefaultSubscribeAllRemoteVideoStreams</a>(true) to subscribe by default).

• You cannot use <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#b738a1b498bc1" id="19b0cea8593i5">subscribeRemoteVideoStream</a> to individually subscribe to the video stream of a specified user.

To resume subscriptions, call this method again and set the parameter to true.

Parameters

Return value

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

Subscribes to or unsubscribes from the media stream of a specific remote user.

public abstract int subscribeRemoteMediaStream(String uid, AliRtcVideoTrack videoTrack, boolean subVideo, boolean subAudio);

This method subscribes to the audio and video streams of a remote user.

Related methods

Unlike <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#4cec275051vr6" id="faff82a053mev">subscribeRemoteMediaStream[2/2]</a>, this API uses two Boolean parameters, subVideo and subAudio, to determine whether to subscribe to the remote audio and video streams, while the videoTrack parameter is used to control which video stream to pull.

Parameters

Return value

Returns 0 if the method is called successfully. A non-zero value indicates a failure.

Subscribes to or unsubscribes from the audio and video streams of a remote user.

public abstract int subscribeRemoteMediaStream(String uid, AliRtcVideoTrack videoTrack, AliRtcAudioTrack audioTrack) ;

This method lets you manage subscriptions for both audio and video streams in a single call.

Related methods

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

• If you want to subscribe to the camera and microphone streams, set videoTrack and audioTrack to AliRtcVideoTrackCamera and AliRtcAudioTrackMic respectively when you make the call.

• If you want to unsubscribe from the camera stream but keep the microphone, set videoTrack and audioTrack to AliRtcVideoTrackNo and AliRtcAudioTrackMic respectively in the next call.

• If you want to cancel both, set videoTrack and audioTrack to AliRtcVideoTrackNo and AliRtcAudioTrackNo respectively when you call again.

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

Parameters

Return values

• 0: The operation was successful.

• <0: The operation failed.

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

public abstract int subscribeRemoteDestChannelStream(String channelId, String uid, AliRtcVideoTrack track, boolean sub_audio, boolean sub);

Parameters

Return value

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

Stops or resumes subscribing to all user streams from another channel.

public abstract int subscribeRemoteDestChannelAllStream(String channelId, AliRtcVideoTrack track, boolean sub_audio, boolean sub);

Parameters

Return value

• 0: The call succeeded.

• Any other value: The call failed.

Adjusts the playback volume of the remote audio stream.

public abstract int setRemoteAudioVolume(String uid, int volume);

Use this method to adjust the playback volume of a specified user's audio stream on the local device.

Parameters

Return value

• 0: The method call was successful.

• A non-zero value: The method call failed. For example, the value of the volume parameter is invalid.

Stops or resumes sending the local audio stream.

public abstract int muteLocalMic(boolean mute, AliRtcMuteLocalAudioMode mode);

When to call

Call this method before or after you join a channel.

Callbacks

After a successful call, remote users receive the <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#ea457055e4izi" id="cce3d390a3xud">onUserAudioMuted</a> callback to indicate whether that user is muted.

Parameters

Return value

0 indicates that the method call is successful. A value other than 0 indicates that the call has failed. Muting only sends silent frames in the audio stream. The audio capture and encoding modules continue to run.

Stops or resumes the playback of a remote audio stream.

public abstract int muteRemoteAudioPlaying(String uid, boolean mute);

This API only stops or resumes a specified remote user's audio playback, but it does not affect pulling and decoding the remote audio stream. To unsubscribe from a user's audio stream, call <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#e09342eeb0z4k" id="66a2ef0919jjg">subscribeRemoteAudioStream</a>.

When to call

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

Parameters

Returns

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

Stops or resumes playing all remote audio.

public abstract int muteAllRemoteAudioPlaying(boolean mute);

This method stops or resumes playing all remote audio.

When to call

Call this method before or after you join a channel.

Parameters

Return value

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

Starts audio capture.

public abstract int startAudioCapture();

You can call this method before joining a meeting to start audio capture in advance. If you do not call this method, the SDK automatically controls the audio capture device. To restart audio capture after stopping it with stopAudioCapture, call this method.

When to call

Call this method before or after joining a meeting.

Related methods

The <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#b71a48f4b84n0" id="4565abdceeq8i">startAudioCapture[2/2]</a> interface uses parameters to control whether the audio capture device maintains its enabling status after you leave a channel.

Related callbacks

After you call this method to change the local audio capture status, the onLocalAudioStateChanged callback reports the status change.

Return value

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

Enables audio capture.

public abstract int startAudioCapture(boolean keepAlive);

Muting disables microphone capture.

Use this method to enable audio capture. Call this method before joining a channel to start capture early. If you do not call this method, the SDK automatically manages the audio capture device.

When to call

Call this method before or after joining a channel.

Related methods

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

Related callbacks

After you call this method to change the local audio capture status, the onLocalAudioStateChanged callback provides the status change.

Parameters

Return value

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

Stops audio capture.

public abstract int stopAudioCapture();

The SDK enables audio capture by default. Actions such as starting a preview or joining a channel automatically start audio capture. Call this method to stop the audio device from capturing audio.

Related callbacks

After you call this method, the onLocalAudioStateChanged callback reports the change in the local audio capture status.

Return value

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

Sets the default audio output to the speakerphone.

public abstract int setDefaultAudioRoutetoSpeakerphone(boolean defaultToSpeakerphone);

This method sets the default audio routing device before you join a channel. You can set the default output to the earpiece or the speakerphone. By default, the software development kit (SDK) uses the speakerphone. To change this default setting, call this method before joining the channel.

The audio routing priority is predefined in the SDK. The audio route 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 route is not set using enableSpeakerphone, the default setting is used.

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

Mobile devices usually have two audio output devices: the earpiece and the speakerphone.

• Earpiece: The sound is quieter. You must hold the device to your ear to hear clearly. This option provides good privacy and is ideal for phone calls.

• Speakerphone: The sound is louder. You can hear without holding the device to your face. This enables a hands-free feature.

Related methods

This method modifies the default audio routing setting. The enableSpeakerphone method sets the current routing device.

When to call

Call this method before or after joining a channel.

Parameters

Return value

• 0: The method call succeeded.

• <0: The method call failed.

Sets the audio output to the earpiece or the speaker.

public abstract int enableSpeakerphone(boolean enable);

Call this method to select the audio playback device, either the earpiece or the speaker, after joining a channel. If you do not call this method, the default audio routing device is used for playback.

The SDK has a predefined audio routing priority. It automatically switches the audio route based on the connection status of peripheral devices. The priority is as follows: Wired headset > Bluetooth headset > User settings > Default settings. Because of this priority, this method call has no effect when a peripheral device is connected. For more information about audio routing settings, see Audio routing settings.

When to call

Call this method before or after joining a channel.

Related methods

<a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#d4dab00b21ebx" id="944fb5797e773">setDefaultAudioRoutetoSpeakerphone</a> is used to modify the default audio routing settings. You can use this API to set the current routing device.

Parameters

Return value

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

Checks whether the speaker or the earpiece is used for audio output.

public abstract boolean isSpeakerOn();

Return value

Returns true if the speaker is on. Returns false if the earpiece is on.

Enables audio volume notifications for users.

public abstract int enableAudioVolumeIndication(int interval, int smooth, int reportVad);

This method enables the SDK to periodically report volume information. This includes the volume of the local user sending a stream and the remote user with the highest instantaneous volume. To use this feature, implement the AliRtcAudioVolumeObserver class and call the registerAudioVolumeObserver method to register the observer object.

When to call

Call this method before or after you join a channel.

Related callbacks

After a successful call to this method, the SDK triggers the following two callbacks at the specified interval if a user in the channel is sending a stream:

• The audio volume of the speaker is reported through the AliRtcAudioVolumeObserver#onAudioVolume callback. The callback frequency is determined by the interval parameter.

• Voice activity detection: The AliRtcAudioVolumeObserver#onActiveSpeaker callback reports the UID of the speaker when an active speaker is detected.

Parameters

Return value

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

Enables in-ear monitoring.

public abstract int enableEarBack(boolean enable);

This method enables or disables the in-ear monitoring feature. For the best experience, use wired or Bluetooth headphones when this feature is enabled.

When to call

Call this method before or after joining a channel.

Parameters

Return value

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

Sets the in-ear monitoring volume.

public abstract int setEarBackVolume(int volume) ;

Use this API to set the in-ear monitoring volume. The setting takes effect only after you enable the in-ear monitoring feature by calling enableEarBack.

When to call

Call this method before or after joining a channel.

Parameters

Return value

• 0: The method call was successful.

• <0: The method call failed.

Starts the audio playback device.

public abstract int startAudioPlayer();

Call this method to start audio playback in advance. If you do not call this method, the SDK automatically starts playback after it subscribes to an audio stream.

Returns

• 0: The call succeeded.

• A non-zero value: The call failed. The value is an error code.

Stops the audio playback device.

 public abstract int stopAudioPlayer();

This method lets you stop audio playback and is the counterpart to startAudioPlayer.

Return value

• 0: The call is successful.

• A non-zero value: The call failed. An error code is returned.

Sets the local playback volume.

public abstract int setPlayoutVolume(int volume);

Parameters

Return value

• 0: The call was successful.

• A non-zero value: The call failed.

Sets the recording volume.

public abstract int setRecordingVolume(int volume);

Parameters

Return value

• 0: The call succeeded.

• A non-zero value: The call failed.

Plays an audio file.

public abstract int playAudioFileTest(String filePath) ;

Use this method to play an audio file to test audio playback before you join a meeting.

When to call

Call this method only before joining a meeting.

Limitations

Each call to this method overwrites the previous one. A new call also stops any audio file that is currently playing.

Parameters

Return value

• 0: The call is successful.

• A non-zero value: The call failed.

Stops the audio file playback.

public abstract int stopAudioFileTest();

This method is the counterpart to playAudioFileTest. It stops the audio file playback.

Limitations

Call this method only before joining a channel.

Return value

• 0: The call succeeded.

• A non-zero value: The call failed.

Starts the audio capture device test before a call.

public abstract int startAudioCaptureTest();

This method starts a test to check if the local audio capture device works correctly before a call. After this method is called, the SDK reports the volume of the capture device to the developer through the AliRtcAudioVolumeObserver::OnTestAudioVolume callback.

When to call

Call this method before joining a channel. After the test is complete, call stopAudioCaptureTest to stop the device test and prevent the device from being occupied.

Return value

• 0: The call is successful.

• A non-zero value: The call failed. The value is an error code.

Stops the audio capture device test.

public abstract int stopAudioCaptureTest();

You must call this method to stop the audio capture test after you call startAudioCaptureTest.

When to call

Call this method before joining a channel.

Return value

• 0: The call was successful.

• A non-zero value: The call failed. An error code is returned.

Sets the voice changer mode.

public abstract int setAudioEffectVoiceChangerMode(AliRtcAudioEffectVoiceChangerMode mode);

Parameters

Return value

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

Sets the pitch parameter.

public abstract int setAudioEffectPitchValue(double value);

Parameters

Return value

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

Sets the reverb sound effect mode.

public abstract int setAudioEffectReverbMode(AliRtcAudioEffectReverbMode mode);

Parameters

Returns

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

Sets the type and parameters for the reverb sound effect.

public abstract int setAudioEffectReverbParamType(AliRtcAudioEffectReverbParamType type, float value);

Parameters

Return value

A return value of 0 indicates a successful call. Any other value indicates a failed call.

Adds an external audio stream.

public abstract int addExternalAudioStream(AliRtcExternalAudioStreamConfig config);

Use this method to add an external audio stream. The steps are as follows:

1. Call <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#42b363024fich" id="20c33a9acb0ui">addExternalAudioStream</a> to add an external audio stream and obtain the external audio stream ID.

2. Call <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#930f22d3dcdco" id="d3deb62b2fl0f">pushExternalAudioStreamRawData</a> to push audio data to the created audio stream.

3. When the call ends, call <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#0333f86114078" id="16d826dedcli6">removeExternalAudioStream</a> to remove the external audio stream.

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

Parameters

Return value

A return value greater than 0 indicates a successful call and is the ID of the external audio stream. Any other value indicates that the call failed.

Pushes raw data to an external audio stream.

public abstract int pushExternalAudioStreamRawData(int streamId, AliRtcAudioFrame rawData);

Use this method to push data to a specified audio stream. The steps are as follows:

1. Call <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#42b363024fich" id="8822f2932e9ep">addExternalAudioStream</a> to add an external audio stream and obtain the external audio stream ID.

2. Call <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#930f22d3dcdco" id="880fe8cd02j10">pushExternalAudioStreamRawData</a> to push audio data to the created audio stream.

3. When the call ends, you need to call <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#0333f86114078" id="106c7aefa27c0">removeExternalAudioStream</a> to remove the external audio stream.

For more information, see Custom audio capture.

When to call

Call this method after you join a channel.

Parameters

Return value

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

Sets the publish volume for an external audio stream.

public abstract int setExternalAudioStreamPublishVolume(int streamId, int publishVolume);

Parameters

Return value

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

Gets the stream ingest volume for an external audio stream.

public abstract int getExternalAudioStreamPublishVolume(int streamId);

Parameters

Return value

The stream ingest volume, which ranges from 0 to 100. A value of < 0 indicates that the call failed.

Sets the playback volume of an external audio stream.

public abstract int setExternalAudioStreamPlayoutVolume(int streamId, int playoutVolume);

Parameters

Return value

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

Gets the playback volume of an external audio stream.

public abstract int getExternalAudioStreamPlayoutVolume(int streamId);

Parameters

Return value

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

Removes an external audio stream.

public abstract int removeExternalAudioStream(int streamId);

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

When to call

To use the custom audio input feature, call the addExternalAudioStream method to add an audio stream and get its ID. Then, call the pushExternalAudioStreamRawData method to push audio data to the SDK. To stop the custom audio input, call this method to remove the corresponding external audio stream and release resources.

Parameters

Return values

• 0: The call was successful.

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

Gets audio file information.

public abstract int getAudioFileInfo(String fileName);

You can call this method to obtain the duration of an audio file asynchronously. The information is returned through the onAudioFileInfo callback.

Parameters

Return value

• 0: The call was successful.

• A non-zero value: An error code.

Starts audio accompaniment mixing.

public abstract int startAudioAccompany(String fileName, AliRtcAudioAccompanyConfig config) ;

This method plays local or online accompaniment files. This is an asynchronous call. After calling this method, listen for the accompaniment playback status through the AliRtcEngineNotify#onAudioAccompanyStateChanged callback.

When to call

Call this method after joining a channel.

Limitations

Unlike sound effects, only one accompaniment can be played at a time. Calling this method again overwrites the previous accompaniment.

Parameters

Return value

• 0: The call was successful.

• A non-zero value: The call failed. An error code is returned.

Stops the audio accompaniment.

public abstract int stopAudioAccompany() ;

This method is the counterpart to startAudioAccompany and stops accompaniment playback.

When to call

Call this method before or after you join a channel.

Return values

• 0: The call succeeded.

• A non-zero value: The call failed. The return value is the error code.

Sets the volume of the audio accompaniment, including the local playback volume and the stream ingest volume.

public abstract int setAudioAccompanyVolume( int volume) ;

Call this method to set the volume of the audio accompaniment. This method sets both the local playback volume and the stream ingest volume. In contrast, setAudioAccompanyPlayoutVolume sets only the local playback volume, and setAudioAccompanyPublishVolume sets only the stream ingest volume.

Parameters

Return value

• 0: The call succeeded.

• A non-zero value: The call failed and an error code is returned.

Sets the volume of the audio accompaniment for stream ingest.

public abstract int setAudioAccompanyPublishVolume(int volume) ;

Parameters

Return value

• 0: The call is successful.

• A non-zero value: The call failed. An error code is returned.

Gets the stream ingest volume of the audio accompaniment.

public abstract int getAudioAccompanyPublishVolume() ;

Return value

The stream ingest volume of the accompaniment music.

• [0-100]: Success.

• Other: An error code.

Sets the local playback volume for the audio accompaniment.

public abstract int setAudioAccompanyPlayoutVolume(int volume) ;

Parameters

Return value

• 0: The call succeeded.

• A non-zero value: The call failed and an error code is returned.

Gets the local playback volume of the audio accompaniment.

public abstract int getAudioAccompanyPlayoutVolume() ;

Return value

The local playback volume of the audio accompaniment.

• A value from 0 to 100 indicates a successful call.

• Other values indicate an error code.

Pauses the audio accompaniment mixing.

public abstract int pauseAudioAccompany();

Return value

• 0: The call was successful.

• A non-zero value: The call failed. The value is the error code.

Resumes audio accompaniment mixing.

public abstract int resumeAudioAccompany();

Return value

• 0: The call is successful.

• A non-zero value: The call failed. An error code is returned.

Gets the duration of the accompaniment file in milliseconds.

public abstract int getAudioAccompanyDuration();

This method gets the duration of the current accompaniment file.

Return value

• >=0: The duration of the accompaniment file.

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

Gets the playback progress of the audio accompaniment file in milliseconds.

public abstract int getAudioAccompanyCurrentPosition();

This method gets the playback progress of the current audio accompaniment file in milliseconds.

Returns

• >= 0: The playback progress of the audio accompaniment file.

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

Sets the playback position of the accompaniment file.

public abstract int setAudioAccompanyPosition(int posMs);

This method sets the playback progress of the accompaniment. Use this method to implement features such as dragging a progress bar. After a successful call, the accompaniment file starts playback from the position that is specified by posMs.

Parameters

Return value

• 0: Success.

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

Preloads a sound effect file.

public abstract int preloadAudioEffect(int soundId, String filePath);

Parameters

Return value

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

Unloads a preloaded sound effect file.

public abstract int unloadAudioEffect(int soundId);

Parameters

Return value

Returns 0 if the method is called successfully. Returns a non-zero value if the call fails.

Starts playing a sound effect.

public abstract int playAudioEffect(int soundId, String filePath, int cycles, boolean publish);

Parameters

Return value

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

Stops playing a sound effect.

public abstract int stopAudioEffect(int soundId);

Parameters

Return value

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

Stops playing all sound effects.

public abstract int stopAllAudioEffects();

Return value

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

Sets the stream ingest volume for a sound effect.

public abstract int setAudioEffectPublishVolume(int soundId, int volume);

Parameters

Return value

A value of 0 means the method call succeeded. Any other value means it failed.

Gets the volume of a sound effect for stream ingest.

public abstract int getAudioEffectPublishVolume(int soundId);

Parameters

Return values

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

Sets the local playback volume for a sound effect.

public abstract int setAudioEffectPlayoutVolume(int soundId, int volume);

Parameters

Return value

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

Gets the local playback volume of a sound effect on Android and iOS.

public abstract int getAudioEffectPlayoutVolume(int soundId);

Parameters

Return value

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

Sets the publish mixing volume for all sound effects.

public abstract int setAllAudioEffectsPublishVolume(int volume);

Parameters

Return value

Returns 0 if the method call succeeds. Returns another value if the call fails.

Sets the local playback volume for all sound effects on Android and iOS.

public abstract int setAllAudioEffectsPlayoutVolume(int volume);

Parameters

Return value

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

Starts recording a media file.

public abstract boolean startRecord(AliRtcRecordType recordType, AliRtcRecordFormat recordFormat, String filePath, AliRtcRecordAudioConfig audioConfig, AliRtcRecordVideoConfig videoConfig, long maxSize, long maxDuration);

Parameters

Return value

Returns true if the operation is successful, or false otherwise.

Stops recording the media file.

  public abstract void stopRecord();

Parameters

None.

Pauses a sound effect.

public abstract int pauseAudioEffect(int soundId);

Parameters

Return value

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

Pauses all sound effects.

public abstract int pauseAllAudioEffects();

Return value

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

Resumes the playback of a sound effect.

public abstract int resumeAudioEffect(int soundId);

Parameters

Return value

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

Resumes playing all sound effects.

public abstract int resumeAllAudioEffects();

Return value

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

Creates a SurfaceView for rendering.

public abstract SophonSurfaceView createRenderSurfaceView(Context context);

To display a video view, call this method instead of creating a SurfaceView directly. Call it as follows:

• Assign the return value to AliRtcVideoCanvas#view.

• Call setLocalViewConfig to set the local preview view or call setRemoteViewConfig to set the remote preview view.

When to call

Call this method before or after joining a channel.

Limitations

Call this method on the main thread.

Parameters

Sets the rendering window and parameters for the local preview.

public abstract int setLocalViewConfig(AliRtcVideoCanvas viewConfig, AliRtcVideoTrack track);

This method sets the local preview view. It attaches a display window (view) to the local video stream and sets the rendering mode, mirror mode, and rotation angle for the local user's view. These settings affect only the local preview and not the published video stream. To set the view for a remote user, call setRemoteViewConfig.

When to call

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

Parameters

Returns

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

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

public abstract int setRemoteViewConfig(AliVideoCanvas canvas, String uid,AliRtcVideoTrack track);

This method attaches a display view to a specified video stream from a remote user. It also sets parameters for the remote view's local display, such as the rendering mode, mirror mode, and rotation angle. These settings only affect the video image that the local user sees. To set the local preview view, call setLocalViewConfig.

• If the view parameter in AliRtcVideoCanvas is null, rendering stops.

• To reset the renderMode parameter of AliRtcVideoCanvas during playback, modify only the renderMode value. Keep all other parameters unchanged.

• To reset the mirrorMode parameter of AliRtcVideoCanvas during playback, modify only the mirrorMode value. Keep all other parameters unchanged.

When to call

Call this method when you receive the onRemoteTrackAvailableNotify callback. This callback is triggered when a video stream from a remote user becomes available.

Parameters

Return value

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

Sets the camera capture preferences.

public abstract int setCameraCapturerConfiguration(AliEngineCameraCapturerConfiguration cameraCapturerConfiguration);

Use this method to configure camera capture preferences, such as the camera direction and capture frame rate.

When to call

Call this method before opening the camera, for example, before calling the following methods:

• startPreview

• joinChannel

Parameters

Return value

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

Disables or enables local video capture.

public abstract int enableLocalVideo(boolean enable);

This method controls local video capture. When local video capture is disabled, video data is unavailable for local preview and stream ingest. This does not affect receiving remote video. If you call this method to disable the local camera, the local preview and stream ingest freeze on the last captured frame.

When to call

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

Related callbacks

A successful call to this method triggers the onUserVideoEnabled callback to notify remote users.

Parameters

Returns

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

Stops or resumes sending local video data.

public abstract int muteLocalCamera(boolean mute, AliRtcVideoTrack track);

Call this method during stream ingest to send black video frames. The local preview remains normal. The capture, encoding, and sending modules continue to work, but the video content consists of black frames.

Parameters

Return value

0 is returned if the method call is successful.

Checks if the camera is on.

public abstract boolean isCameraOn();

Return value

Returns true if the camera is on, or false if the camera is off.

Sets the video encoding properties.

public abstract void setVideoEncoderConfiguration(AliRtcVideoEncoderConfiguration config);

This method sets the video parameters for video stream encoding, such as resolution, frame rate, bitrate, and video orientation. Call this method in all video scenarios.

When to call

This method can be called before or after joining a channel. To set the camera stream encoding properties only once for each session, call this method before joining the channel.

Limitations

Both the mirrorMode parameter of this method and the setVideoMirrorMode method can set the mirror mode for stream ingest. Use only one of these methods. Using both at the same time can cause the mirror effects to overlap, which may lead to configuration failure or errors.

Parameters

Sets the video decoding properties.

    public abstract void setVideoDecoderConfiguration(AliRtcVideoDecoderConfiguration config);

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

When to call

Call this method before joining a channel.

Parameters

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

public abstract int switchCamera();

This method lets you dynamically switch cameras while the app is running based on their availability. You do not need to restart the video stream or reconfigure the video source.

When to call

Call this method after the camera is successfully started.

Call restrictions

Available only on Android and iOS platforms.

Return value

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

Gets the current camera direction.

public abstract AliRTCCameraDirection getCurrentCameraDirection();

Return value

• Returns CAMERA_REAR(0) for the rear camera.

• Returns CAMERA_FRONT(1) for the front camera.

• Returns CAMERA_INVALID(-1) for an invalid state.

Starts the local video preview.

public abstract int startPreview();

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 calling this method, set a view for the local preview by calling setLocalViewConfig. Otherwise, the preview cannot be displayed. This does not affect stream ingest.

• If needed, call this method to start the preview before you join a channel by calling joinChannel. The camera turns on automatically.

Return value

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

Stops the local preview.

public abstract int stopPreview();

This method stops the local video preview and shuts down the camera. After the preview stops, the local display remains on the last frame. This does not affect stream ingest.

When to call

Call this method to stop the preview after it starts.

Return value

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

Sets the camera zoom factor.

public abstract int setCameraZoom(float zoom);

This method sets the zoom factor of the camera.

Restrictions

This method is available only on iOS and Android.

When to call

This method takes effect only after the camera is turned on. The zoom factor is reset each time the camera is restarted.

Parameters

Return value

• 0: The call succeeded.

• A non-zero value: The call failed.

Gets the maximum zoom factor supported by the camera.

public abstract float GetCameraMaxZoomFactor();

Returns

The maximum zoom factor supported by the camera.

Gets the current zoom setting of the camera.

public abstract float GetCurrentZoom();

Return value

The current zoom ratio of the camera.

Sets the camera exposure.

public abstract int SetExposure(float exposure);

Ambient light that is too dim or too bright affects the quality of captured video. To get better video results, use this method to adjust the exposure of the camera in use. You can call GetMinExposure and GetMaxExposure to get the exposure range that the device supports.

Parameters

Returns

• 0: The method call was successful.

• A non-zero value: The method call failed.

Gets the camera exposure.

public abstract float GetCurrentExposure();

Gets the exposure setting of the camera that is currently in use.

Return value

The current camera exposure.

Gets the minimum exposure of the camera.

public abstract float GetMinExposure();

Return value

The minimum exposure of the camera.

Gets the maximum exposure that the camera supports.

public abstract float GetMaxExposure();

Return value

The maximum exposure of the camera.

Turns the camera flash on or off.

public abstract int setCameraFlash(boolean flash);

Turn the flash on or off.

Limitations

This interface is available only on iOS and Android.

Parameters

Return value

• 0: The operation is successful.

• A non-zero value: The operation failed.

Checks whether the current device supports manual focus.

public abstract boolean isCameraFocusPointSupported();

Call this method to check whether a focus point can be set on the current camera to support the manual focus feature.

Limitations

This API is available only on iOS and Android.

Return value

• true: The device supports the manual focus feature.

• false: The device does not support the manual focus feature.

Checks whether the device supports setting a camera exposure point.

public abstract boolean isCameraExposurePointSupported();

Call this method to check if the current device supports setting an exposure point.

Limitations

This method is available only on iOS and Android.

Return value

• true: The device supports setting a camera exposure point.

• false: The device does not support setting a camera exposure point.

Sets the manual focus point for the camera.

public abstract int setCameraFocusPoint(float x, float y);

Sets the focus point for the current camera. When you call this method, the camera adjusts the exposure for the specified point once and then maintains that focus value. Before you call this method, call isCameraFocusPointSupported to check whether the device supports the manual focus feature.

Limitations

This method is available only on iOS and Android.

Parameters

Return value

• 0: The method call was successful.

• A non-zero value: The method call failed.

Sets the camera exposure point.

public abstract int setCameraExposurePoint(float x, float y);

Calling this method triggers a one-time exposure adjustment for the specified point. The camera then maintains this exposure value. Before you call this method, call isCameraExposurePointSupported to check if the device supports manually setting the exposure point.

Limitations

This method is available only on iOS and Android.

Parameters

Return value

• 0: The call was successful.

• A non-zero value: The call failed.

Checks whether the camera supports automatic facial focus.

public abstract boolean isCameraAutoFocusFaceModeSupported();

Checks whether the camera supports automatic facial focus.

When to call

Call this method after the camera is on. This method returns false by default if the camera is off. It returns true if the camera is on and supports both facial recognition and focus features.

Restrictions

This method is available only on iOS and Android.

Return values

• true: Automatic facial focus is supported.

• false: Automatic facial focus is not supported.

Sets the face-based autofocus for the camera.

public abstract boolean setCameraAutoFocusFaceModeEnabled(boolean enable);

This method sets the camera to focus on faces in real time. Before calling this method, call isCameraAutoFocusFaceModeSupported to check if the device supports this feature.

Limitations

This method is available only on iOS and Android.

Parameters

Return value

• true: The call was successful.

• false: The call failed.

Configures video mirroring.

public abstract int setVideoMirrorMode(AliRtcVideoPipelineMirrorMode mirrorMode);

Sets whether to enable mirror mode for the local preview video and the ingested video stream.

When to call

Call this method before or after joining a channel. The SDK records the setting and applies it to the video when preview and encoding for stream ingest are available.

Limitations

The functionality of this method overlaps with the mirrorMode parameter in setLocalViewConfig&setVideoEncoderConfiguration. Use only one of these methods.

Parameters

Return values

• 0: The operation is successful.

• <0: The operation failed.

  • AliRtcErrInner: An internal SDK status error occurred. Check whether the SDK instance was created.

Sets the timing for video capture scaling.

public abstract void setCapturePipelineScaleMode(AliRtcCapturePipelineScaleMode mode);

Sets whether to scale the video data immediately upon capture or during encoding. For example, if the capture resolution differs from the encoding resolution, setting the scaling timing determines whether the preview data is consistent with the published stream data.

When to call

Call this method before you open the camera, such as before you call startPreview or joinChannel.

Parameters

Return value

None.

Enables an external video input source.

public abstract void setExternalVideoSource(boolean enable,boolean useTexture,
 AliRtcVideoTrack streamType,AliRtcRenderMode renderMode);

Parameters

Inputs video data.

public abstract int pushExternalVideoFrame(AliRtcRawDataFrame aliRawDataFrame,AliRtcVideoTrack streameType);

Parameters

Returns

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

Starts a bypass live stream.

public abstract int startPublishLiveStream(String streamUrl,AliRtcLiveTranscodingParam transcodingParam);

Parameters

Return value

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

Updates the parameters for bypass live streaming.

public abstract int updatePublishLiveStream(String streamUrl,AliRtcLiveTranscodingParam transcodingParam);

Parameters

Return value

Returns 0 if the method is called successfully. Returns a non-zero value if the method call fails.

Stops bypass live streaming.

public abstract int stopPublishLiveStream(String streamUrl);

Parameters

Return value

Returns 0 if the method is called successfully. Returns a non-zero value if the call fails.

Gets the status of the bypass live stream.

public abstract AliRtcEngine.AliRtcLiveTranscodingState getPublishLiveStreamState(String streamUrl);

Parameters

Return value

The status of the bypass live stream.

Starts a network quality probe test.

public abstract int startNetworkQualityProbeTest(AlirtcNetworkQualityProbeConfig config);

Parameters

Return value

0 indicates success. Other values indicate failure.

Stops the network quality probe test.

public abstract int stopNetworkQualityProbeTest();

Return value

A return value of 0 indicates success. Any other value indicates that the operation failed.

Sends media extension messages.

public abstract int sendMediaExtensionMsg(byte[]message, int repeatCount, int delay, boolean isKeyFrame);

The SDK lets you send and receive media extension messages. This method sends the messages using the Supplemental Enhancement Information (SEI) extension protocol. The receiver receives the messages by listening for the onMediaExtensionMsgReceived callback.

Common scenarios include the following:

• Use media extension messages to send timestamps. This helps calculate end-to-end network latency or synchronize data with other services.

• Use media extension messages to send descriptive information. You can send up to 4 KB of data. This is useful for small amounts of data. Use JSON or plain strings for the data format.

When to call

Call this method after you start stream ingest.

Limits

Media extension messages reuse the audio and video data tunnel. Because of this, 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 information is transmitted within the H.264/H.265 stream and can be attached only when video frames are encoded.

• The size of a custom message body is limited to 4 KB to prevent any impact on media data transmission quality. Custom messages are designed for transmitting small amounts of information.

• In the sendMediaExtensionMsg function, the repeatCount parameter specifies the degree of redundancy for the custom message. If its value is greater than 1, the message is sent multiple times,

• This repetition helps prevent message loss from network packets. However, other users in the channel will receive the same message multiple times. Remove these duplicate messages.

• Subscribers in the channel also receive custom messages during a bypass live stream.

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

Related callbacks

When the stream ingest client sends a media extension message, the stream pulling client receives the message by listening for the onMediaExtensionMsgReceived callback.

Parameters

Return values

• 0: The call is successful.

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

  • ERR_INNER(-1): An internal SDK error occurred. This can happen if the SDK is not initialized or if the method is called after the SDK is destroyed.

Sends media extension messages.

public abstract int sendMediaExtensionMsgEx(byte[]message, int repeatCount, int delay, boolean isKeyFrame, int payloadType);

The SDK lets you send and receive media extension messages. This method sends media extension messages using the Supplemental Enhancement Information (SEI) extension protocol. The receiver can get the message by listening for the onMediaExtensionMsgReceived callback. If you set payloadType to 5, this method works the same as the sendMediaExtensionMsg method.

Common scenarios include the following:

• Use media extension messages to pass timestamps, calculate end-to-end network latency, or synchronize data with other services.

• Use media extension messages to pass descriptive information. You can pass up to 4 KB of data, which is useful for transmitting small amounts of information. Use JSON or plain strings for the data.

When to call

Call this method after you start stream ingest.

Limits

Media extension messages reuse the audio and video data tunnel. Therefore, control the frequency and length of custom messages. The limits are as follows:

• A maximum of `fps` messages are sent per second, as set in the profile. This is because SEI messages are transmitted in the H.264/H.265 stream, and extension information can be attached only when video frames are encoded.

• A maximum of `fps` messages are sent per second, as set in the profile. This is because SEI messages are transmitted in the H.264/H.265 stream, and extension information can be attached only when video frames are encoded.

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

• The `repeatCount` parameter sets the message redundancy. If this value is greater than 1, the message is sent multiple times to prevent loss from network packet loss. Other subscribers in the channel will receive the same message multiple times, so you must remove the duplicates.

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

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

Parameters

Returns

• 0: The call is successful.

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

  • ERR_INNER(-1): An internal SDK error occurred. Possible causes include calling the method before the SDK is initialized or after it is destroyed.

A callback for the network connection status. You must handle this callback.

public void onConnectionStatusChange(AliRtcEngine.AliRtcConnectionStatus status,
 AliRtcEngine.AliRtcConnectionStatusChangeReason reason);

Parameters

This is the callback for a local device exception. You must handle this callback.

public void OnLocalDeviceException(AliRtcEngine.AliRtcEngineLocalDeviceType deviceType, AliRtcEngine.AliRtcEngineLocalDeviceExceptionType exceptionType, String msg)

Parameters

This callback notifies you that the user authentication information will expire in 30 seconds. You must handle this callback.

public void onAuthInfoWillExpire();

When you receive this callback, the authentication expires in 30 seconds. Obtain a new token, and then update the authentication information in one of the following ways:

• Call the <a baseurl="t2309760_v6_4_1.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#975b9af9ecq1a" id="8099ac5a509hn">refreshAuthInfo</a> method to update the authentication information.

• Call <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#fef395c4beqdt" id="fe88be037dy4g">leaveChannel</a> 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 authentication information expires. After you receive this callback, update the authentication information promptly.

When a user calls an API that requires authentication, the server returns a message indicating that the authentication information has expired.

public void onAuthInfoExpired();

This callback indicates that the authentication information has expired. To remain in the channel, generate a new token on the server and then update the authentication information by leaving and rejoining the channel:

• Call <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#fef395c4beqdt" id="c3b0cf2f19dgm">leaveChannel</a> 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.

The callback for the result of joining a channel.

public void onJoinChannelResult(int result, String channel, String userId, int elapsed);

Parameters

Reports the result of leaving a channel.

public void onLeaveChannelResult(int result, AliRtcEngine.AliRtcStats stats);

Triggering conditions

When an application successfully calls <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#fef395c4beqdt" id="7f3d2133c81tx">leaveChannel</a> to leave the channel, this callback is triggered and returns the result of leaving the channel and the statistics for the current channel session.

Parameters

A callback for when a remote user goes offline.

public void onRemoteUserOffLineNotify(String uid, AliRtcUserOfflineReason reason);

This callback notifies the local user that a remote user has left the channel for any reason.

Triggers

• A remote user actively leaves the channel.

• When a remote streamer calls <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#84f350f904s98" id="4c0adbe948tif">setClientRole</a> to switch to the viewer role (by calling AliRtcEngine#setClientRole to set the role to AliRTCSdkLive), this callback is triggered.

• No data is received from a remote streamer for an extended period, and the streamer is considered offline.

Parameters

Callback for when a remote user goes online.

public void onRemoteUserOnLineNotify(String uid, int elapsed);

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

Triggers

• A remote user successfully joins the channel.

• After the local user joins a channel, this callback is triggered for each user who is already in the channel. This helps you identify users who have already joined.

Parameters

Callback for when a remote user's audio or video stream changes.

public void onRemoteTrackAvailableNotify(String uid, AliRtcAudioTrack audioTrack,
 AliRtcVideoTrack videoTrack);

This callback is triggered when the stream ingest status of a remote user changes, informing you in real time whether the remote user is pushing audio and video streams so you can show or hide the user's audio and video information on the interface.

Trigger conditions

This callback is triggered in the following scenarios:

• A remote user starts ingesting an audio or video stream.

• A remote user stops ingesting all audio and video streams.

• This callback is triggered in interactive mode when a remote user calls setClientRole to switch from a viewer to a streamer and starts stream ingest.

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

• If a remote user starts pushing the camera stream (stream ingest status: no video stream -> only camera stream), the local callback returns AliRtcVideoTrackCamera to indicate that the remote user's camera stream is active.

• The remote user then pushes a screen sharing stream. The stream ingest status changes from only the camera stream to both the camera and screen sharing streams. The callback returns AliRtcVideoTrackBoth to indicate that both streams are active.

• The remote user stops pushing the camera stream but keeps only the screen sharing stream. The stream ingest status changes from pushing both the camera and screen sharing streams to pushing only the screen sharing stream. The callback returns AliRtcVideoTrackScreen to indicate that only the screen sharing stream is available.

• The remote user then stops pushing the screen sharing stream. The stream ingest status changes from only the screen sharing stream to no video stream. The callback returns AliRtcVideoTrackNo to indicate that no video stream is active.

Parameter descriptions

Triggered when a user is removed from a channel by the server or when the channel is shut down.

public void onBye(int code);

This callback is triggered when a user is disconnected for any reason or when a session ends. You can check the callback parameter code to determine the reason for the disconnection and handle it accordingly.

Triggers

• The user is removed from the channel by the server.

• The session ends because the server shuts down the channel.

• The user is involuntarily disconnected. The client must then try to resume the session or reconnect.

Parameters

Callback for changes in the audio stream ingest status.

public void onAudioPublishStateChanged(AliRtcEngine.AliRtcPublishState oldState , 
 AliRtcEngine.AliRtcPublishState newState,
 int elapseSinceLastState, String channel);

The SDK triggers this callback when the ingest status of the local user's audio stream changes.

When triggered

The ingest status changes in scenarios such as the following:

• The stream ingest stops.

• Call <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#84f350f904s98" id="e6c8edfc45xbw">setClientRole</a> to switch to a viewer.

Parameters