ApsaraVideo Live:AliRtcEngine Interface

Join a channel for a multi-party conference.

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

This method joins a channel. ARTC organizes users into channels. Users must join a channel to publish or subscribe to audio and video streams. This method, joinChannel[1/3], and joinChannel[3/3] all join a channel. They differ in authentication method and user information passed:

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

• This interface is a multi-parameter channel-joining interface. It requires you to provide a multi-parameter channel-joining token generated by Token authentication, and the user information used to generate the token to join the channel.

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

Limitations

• After successfully joining a channel, to join another channel during the session, 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 the <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#8c189be470bsp" id="6aefdfedb0op3">onLeaveChannelResult</a> callback from AliRtcEngineEventListener. Only then can you join a channel again.

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

• Apps using different App IDs cannot interoperate.

Related callbacks

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

• The result of the local client joining a channel is notified through 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, the remote side triggers 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 Description

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

Joins a channel for AI real-time interaction scenarios.

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

This method joins a channel. ARTC organizes users into channels. Users must join a channel to publish or subscribe to audio and video streams. This method, joinChannel[1/3], and joinChannel[2/3] all join a channel. They differ in authentication method and user information passed:

• joinChannel[1/3] is a single-parameter channel-joining interface for RTC scenarios. You can join a channel by passing in a token generated through Token authentication. We recommend using this interface to join a channel in RTC scenarios.

• joinChannel[2/3] is an interface for multi-participant joining. It requires you to pass in the Token generated through Token authentication for multi-participant joining, and also pass in the user information used to generate the Token to join.

• This method is for AI real-time interaction scenarios. Pass a single-parameter token and set the user attribute capabilityProfile. Set it to AliCapabilityProfileAiHuman when communicating with AI agents.

Limitations

• After successfully joining a channel, to join another channel while in a 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 you receive the <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#8c189be470bsp" id="d128acfee2fpd">onLeaveChannelResult</a> callback from AliRtcEngineEventListener. Only then can you join a channel again.

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

• Apps using different App IDs cannot interoperate.

• You do not need to invoke the method again to retry a failed channel join.

Related callbacks

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

• The result of the local client joining a channel is reported through 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 users 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 Description

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

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

public abstract int leaveChannel();

When to call

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

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

Related callbacks

• Local end: After you call this method, it 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 notify you of the result of leaving the channel.

• Remote side: After you successfully call this operation, remote users trigger the <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#75c700a2376c1" id="69bf5ff199oda">onRemoteUserOffLineNotify</a> callback.

Return Description

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

Checks whether you are in a channel.

public abstract boolean isInCall();

Return Description

A value of true indicates that you are in a channel. A value of false indicates that you are not in a channel.

Specifies the user role.

public abstract int setClientRole(AliRTCSdkClientRole clientRole);

This method sets the user role as streamer or viewer.

In interactive mode, before joining a channel:

• Set the user role as streamer: The SDK automatically ingests local audio and video streams and pulls audio and video streams from other streamers.

• Set the user role as viewer: The SDK does not ingest local audio and video streams but pulls audio and video streams from other streamers.

When to call

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

Limitations

This method works only in interactive mode—that is, when setChannelProfile is set to AliRTCSdkInteractiveLive.

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

Parameters

Queries the user role.

public abstract AliRTCSdkClientRole getCurrentClientRole();

Return Description

Returns the current user role.

Refreshes the authentication information.

public abstract int refreshAuthInfo(AliRtcAuthInfo authInfo);

This method updates authentication information. Tokens expire after a period, preventing the SDK from connecting to the server.

When to call

In the following situations:

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

Parameters

Return Description

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

Refreshes the authentication information.

public abstract int refreshAuthInfo(String token);

This method updates the token. Tokens expire after a period, preventing the SDK from connecting to the server.

When to call

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

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

• If you do not update the Token in time, it will trigger <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#8fa7e60f9f5qq" id="3fd674e985gl8">onAuthInfoExpired</a> to notify that authentication has expired. At this point, you need to call joinChannel to rejoin the channel.

Parameters

Return description

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

You can stop or resume publishing the local video stream.

public abstract int publishLocalAudioStream(boolean enable);

This method controls whether to publish the locally captured audio stream. By default, the SDK publishes the audio stream. To disable audio stream publishing, call publishLocalAudioStream(false) before joining the channel.

When to call

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

Related callbacks

When the result of 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 that the local audio stream ingest status has changed, and the remote client triggers the <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#7078e15087a0z" id="2b5460d448ga9">onRemoteTrackAvailableNotify</a> callback to notify you that the remote user's audio and video streams have changed.

Parameters

Return Description

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

Queries whether an audio stream is published.

public abstract boolean isLocalAudioStreamPublished();

Return Instructions

A value of true indicates that the audio stream is published. A value of false indicates that the audio stream is not published.

Specifies whether to subscribe to audio streams of remote users by default.

public abstract int setDefaultSubscribeAllRemoteAudioStreams(boolean sub);

This method configures whether the system subscribes to remote users' audio streams by default. This setting affects the audio stream subscription behavior of new users joining the channel. Unless you have specific requirements, we recommend setting this to true.

When to call

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

• Before joining:

  • By default, the SDK subscribes to remote users' audio streams when joining a channel. To change this behavior, call this method before joining.

• After joining:

  • To stop default subscription, call setDefaultSubscribeAllRemoteAudioStreams(false). Then, newly joined users' audio streams are not subscribed to.

  • After you stop the default subscription, you can call the subscribeRemoteAudioStream API to resume subscription to the audio stream of a specified user, and call it multiple times to resume subscription for multiple users.

  • After stopping default subscription, calling setDefaultSubscribeAllRemoteAudioStreams(true) resumes subscription only for users who join after the call. It does not resume subscription for remote users who joined during the stopped period.

Parameters

Return description

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

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

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

This method stops or resumes subscribing to the audio stream of a specific remote user. Unless you have specific requirements, we recommend setting this to true.

Parameters

Return description

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

Specifies whether to receive audio streams of all remote users.

public abstract int subscribeAllRemoteAudioStreams(boolean sub);

This method is the master switch for subscribing to remote audio streams. We recommend setting it to true. If set to false, it causes:

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

• New users who join later are also not subscribed to.

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

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

Parameters

Return description

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

Specifies whether to publish the camera stream.

public abstract int publishLocalVideoStream(boolean enable);

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

When to call

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

Calling it before joining modifies the default configuration and takes effect upon joining.

Related callbacks

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

Parameters

Return Description

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

Queries whether a camera stream is published.

public abstract boolean isLocalVideoStreamPublished();

Return Description

A value of true indicates that the camera stream is published. A value of false indicates that the camera stream is not published.

Specifies whether to subscribe to video streams of remote users by default.

public abstract int setDefaultSubscribeAllRemoteVideoStreams(boolean sub);

This method specifies whether to subscribe to video streams of remote users by default. The SDK subscribes by default.

When to call

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

After you stop receiving video streams, call subscribeRemoteVideoStream and specify the ID of the remote user to resume receiving their video stream. To resume receiving video streams from multiple users, you need to call subscribeRemoteVideoStream multiple times. setDefaultSubscribeAllRemoteVideoStreams(true) only resumes receiving video streams from users who join the channel later.

This method specifies whether to subscribe to video streams of remote users by default.

Parameters

Return Description

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

Stops or resumes subscribing to a specified remote video stream.

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

Subscribes to or unsubscribes from a specified user's video stream.

When to call

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

Parameters

Return description

• 0: the method executed successfully.

• Non-zero: the method 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 set to false, it causes:

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

• New users who join later will not subscribe (even if you have set setDefaultSubscribeAllRemoteVideoStreams(true) to enable default subscription).

• 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 control the video stream of a specified user.

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

Parameters

Return Description

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

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

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

This method combines subscription to remote audio and video streams.

Related methods

Compared to <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 utilizes two Boolean parameters, subVideo and subAudio, to specify whether to subscribe to the remote audio and video streams. The videoTrack parameter controls which video stream to pull.

Parameters

Return description

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

Stops or resumes subscribing to a remote user's audio and video streams in a single call.

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

This interface merges subscribed remote audio and video streams.

Related methods

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

• If you want to subscribe to the camera stream and the microphone stream, set videoTrack and audioTrack to AliRtcVideoTrackCamera and AliRtcAudioTrackMic, respectively, when you invoke.

• To unsubscribe from the camera stream but continue subscribing to the microphone stream, set the videoTrack parameter to AliRtcVideoTrackNo and the audioTrack parameter to AliRtcAudioTrackMic.

• To unsubscribe from both, you can set videoTrack and audioTrack to AliRtcVideoTrackNo and AliRtcAudioTrackNo, respectively.

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

Parameters

Return Description

• 0: Success.

• <0: Failure.

Subscribe to a specific user's stream across channels.

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

Parameters

Return Description

A return value of 0 indicates that the method call succeeded, while any other value indicates that the call failed.

Stops or resumes subscribing to all users' streams across channels.

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

Parameters

Return description

• 0: The method call succeeded.

• Non-zero: The method call failed.

Adjusts the playback volume of the pulled audio stream.

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

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

Parameters

Return Description

• 0: The method call succeeded.

• Non-zero: The method call failed, for example, due to an invalid volume value.

Stops or resumes sending local audio data.

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

When to call

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

Related callbacks

After the call succeeds, the remote user triggers the <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#ea457055e4izi" id="cce3d390a3xud">onUserAudioMuted</a> notification to indicate whether they are muted.

Parameters

Return Description

A return value of 0 indicates success. Any other value indicates failure. Muting sends silent frames, but audio capture and encoding continue to run.

Stops or resumes playback of the remote audio stream.

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

This API controls playback of a specified remote user’s audio stream only. It does not affect stream pulling or decoding of the remote audio. 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 set this before or after joining a channel.

Parameters

Return Description

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

Stops or resumes playing all remote audio streams.

public abstract int muteAllRemoteAudioPlaying(boolean mute);

This method stops or resumes all remote audio streams.

When to call

You can set this before or after you join a channel.

Parameters

Return description

A value of 0 indicates that the call is successful. Any other value indicates failure.

Starts audio capture.

public abstract int startAudioCapture();

This method starts audio capture. You can call this method before joining a channel to enable audio capture in advance. If this method is not called, the SDK automatically controls the audio capture device. You can also call this method to re-enable audio capture after calling stopAudioCapture.

When to call

You can 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="#b71a48f4b84n0" id="4565abdceeq8i">startAudioCapture[2/2]</a> API uses parameters to control whether the audio capture device remains enabled after you leave a meeting.

Related callbacks

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

Return Description

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

Starts audio capture.

public abstract int startAudioCapture(boolean keepAlive);

Disables microphone capture after muting.

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

When to call

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

Related methods

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

Related callbacks

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

Parameters

Return Description

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

Stops audio capture.

public abstract int stopAudioCapture();

The SDK enables audio capture by default. When you start a preview or join a channel, audio capture starts automatically. Call this method to stop audio device capture.

Related callbacks

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

Return Description

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

Sets whether the default audio output device is the speakerphone.

public abstract int setDefaultAudioRoutetoSpeakerphone(boolean defaultToSpeakerphone);

This method configures the default audio routing device before you join a channel. You can set the default output to either the earpiece or the speakerphone. By default, the SDK uses the speakerphone. To change this default, call this method before joining a channel.

The SDK defines an audio routing priority that automatically switches based on the current peripheral connection status, as follows: wired headset > Bluetooth headset > user settings > default settings. Therefore, if no peripheral is connected and enableSpeakerphone is not set, the SDK applies the default settings.

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

Mobile devices typically support two audio output devices: the earpiece and the speakerphone:

• When audio is routed to the earpiece, the sound is quieter and requires holding the phone close to your ear, providing better privacy and making it suitable for phone calls.

• When audio is routed to the speakerphone, the sound is louder and enables hands-free use without holding the phone to your ear.

Related methods

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

When to call

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

Parameters

Response description

• 0: the method call succeeded.

• <0: the method call failed.

Sets the audio output device to either the headset or the speaker.

public abstract int enableSpeakerphone(boolean enable);

This method selects the current audio playback device after joining a channel, switching between the earpiece and the speaker. If you do not call this method, playback uses the device specified by the default audio route.

The SDK defines a predefined priority order for audio routing and performs automatic switchover based on the current peripheral connection status. The priority order is as follows: wired headset > Bluetooth headset > user settings > default settings. Therefore, when a peripheral is connected, this API call has no effect. For more information about audio routing settings, see Audio Routing Settings.

When to call

You can 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> modifies the default audio routing settings and sets the current routing device.

Parameters

Return description

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

Determines whether the current audio output device is the earpiece or the speaker.

public abstract boolean isSpeakerOn();

Return Description

A value of true indicates the speaker. A value of false indicates the earpiece.

Enable the user volume prompt.

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

This method enables the SDK to periodically report the volume of the local user and the remote user with the highest current volume. To use this feature, implement the AliRtcAudioVolumeObserver class and call registerAudioVolumeObserver to register the observer.

When to call

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

Related callbacks

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

• The AliRtcAudioVolumeObserver#onAudioVolume callback reports the audio volume of each speaker. The frequency of this callback is determined by the interval parameter.

• Voice activity detection: When an active speaker is detected, their user ID (UID) is reported through the AliRtcAudioVolumeObserver#onActiveSpeaker callback.

Parameters

Return Description

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

Enables in-ear monitoring.

public abstract int enableEarBack(boolean enable);

This method enables or disables in-ear monitoring. You can obtain better results by enabling in-ear monitoring when wearing wired or Bluetooth headphones.

When to call

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

Parameters

Return description

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

Sets the in-ear monitoring volume.

public abstract int setEarBackVolume(int volume) ;

This method takes effect only after in-ear monitoring is enabled by calling enableEarBack.

When to call

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

Parameters

Return Instructions

• 0: The method call was successful.

• <0: The method call failed.

Starts the audio playback device.

public abstract int startAudioPlayer();

You can use this method to enable audio playback in advance. If you do not call this method, the SDK automatically enables audio playback after you subscribe to an audio stream.

Return Description

• 0: The call succeeded.

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

Stops the audio playback device.

 public abstract int stopAudioPlayer();

This interface stops audio playback and is the counterpart to startAudioPlayer.

Return Information

• 0: The call succeeded.

• Non-zero: The call failed. An error code is returned.

You can set the local playback volume.

public abstract int setPlayoutVolume(int volume);

Parameters

Response description

• 0: The call succeeded.

• A non-zero value: The call failed.

You can set the recording volume.

public abstract int setRecordingVolume(int volume);

Parameters

Return Description

• 0: the method call succeeded.

• A non-zero return code indicates that the call failed.

You can play the audio file.

public abstract int playAudioFileTest(String filePath) ;

You can use this method to play an audio file before joining a channel to test audio playback.

When to call

You can call this method only before joining a channel.

Call Limits

Multiple calls overwrite previous ones. Calling this method stops any currently playing file.

Parameters

Return description

• 0: the method call succeeded.

• A non-zero value indicates that the call failed.

Stop the playback of the audio file.

public abstract int stopAudioFileTest();

This interface corresponds to the playAudioFileTest interface and stops audio file playback.

Limitations

You can call this method only before you join a channel.

Return description

• 0: call succeeded.

• Non-zero: call failed.

Starts an audio capture device test before a call.

public abstract int startAudioCaptureTest();

You can call this method to test whether the local audio capture device is working correctly before a call. After you call this method, the SDK reports the volume of the audio capture device through the AliRtcAudioVolumeObserver::OnTestAudioVolume callback.

When to call

You must call this method before joining a channel. After the test is complete, call stopAudioCaptureTest to stop the test and release the audio device.

Return Description

• 0: The call is successful.

• Non-zero: The call failed. An error code is returned.

Disable audio capture detection.

public abstract int stopAudioCaptureTest();

This method stops the audio capture device test. After you call startAudioCaptureTest, you must call this method to stop the test.

When to call

You can call this method before joining a channel.

Return Description

• 0: The call succeeded.

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

Sets the voice change mode.

public abstract int setAudioEffectVoiceChangerMode(AliRtcAudioEffectVoiceChangerMode mode);

Parameters

Return Description

A value of 0 indicates that the call is successful. Any other value indicates failure.

You can set pitch adjustment parameters.

public abstract int setAudioEffectPitchValue(double value);

Parameters

Return description

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

Sets the reverberation mode.

public abstract int setAudioEffectReverbMode(AliRtcAudioEffectReverbMode mode);

Parameters

Return description

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

You can set the type and parameters for the reverberation sound effect.

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

Parameters

Return Description

A value of 0 indicates that the call is successful. Any other value indicates failure.

Sets a predefined voice beautification mode.

public abstract int setAudioEffectBeautifyMode(AliRtcAudioEffectBeautifyMode mode);

This method sets a predefined voice beautification mode provided by the SDK. It is suitable for scenarios that require enhanced vocal quality, such as voice live streaming, karaoke, and voice social networking. By selecting a voice beautification mode, you can alter the sound of the human voice, such as making it more resonant or improving its clarity. This enhances the listening experience for remote users.

When to call

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

Parameters

Return value

• 0: The operation was successful.

• A non-zero value: The operation failed.

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

public abstract int setAudioEffectEqualizationParam(AliRtcAudioEffectEqualizationBandFrequency bandIndex, float gain);

This method adjusts the graphic equalizer for locally captured voice and audio signals. By adjusting the gain (in dB) of a specific frequency band, you can customize the sound for purposes such as optimizing voice clarity, highlighting vocals, and improving noise reduction.

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

Limitations

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

Parameters

Return Description

0: The method call succeeded.

A non-zero value: The method call failed.

You can add an external audio stream.

public abstract int addExternalAudioStream(AliRtcExternalAudioStreamConfig config);

This method adds an external audio stream. Follow these steps:

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

2. You can 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 into the external audio stream.

3. When ending a call, you must 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.

If you want to publish custom audio capture in a channel, see Custom Audio Capture.

When to call

Return description

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

You can input external audio stream data.

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

Use this interface to send 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. After the call ends, invoke <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 about publishing audio from a custom source in a channel, see Custom Audio Capture.

When to call

Call this method after joining a channel.

Parameters

Return Description

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

Sets the publishing volume of an external audio stream.

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

Parameters

Return description

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

Retrieve the stream ingest volume of the external audio stream

public abstract int getExternalAudioStreamPublishVolume(int streamId);

Parameters

Return Description

Stream ingest volume: The valid values are 0 to 100. A value less than 0 indicates a failure.

Sets the playback volume of an external audio stream.

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

Parameters

Return description

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

Retrieve the playback volume of the external audio stream

public abstract int getExternalAudioStreamPlayoutVolume(int streamId);

Parameters

Response description

The playback volume has valid values ranging from 0 to 100. A value less than 0 indicates failure.

Removes an external audio stream.

public abstract int removeExternalAudioStream(int streamId);

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

When to call

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

Parameters

Return Description

• 0: The call is successful.

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

Retrieves audio file information.

public abstract int getAudioFileInfo(String fileName);

You can call this interface asynchronously to retrieve the duration of a file. This is an asynchronous interface, and you can obtain audio file information using onAudioFileInfo.

Parameters

Back to Introduction

• 0: The call succeeded.

• Non-zero: An error code is returned.

Starts audio accompaniment mixing.

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

This interface plays local or online accompaniment files. It is an asynchronous interface. After you call this interface, you can monitor the accompaniment playback status using AliRtcEngineNotify#onAudioAccompanyStateChanged.

When to call

You can call this method only after joining a channel.

Limitations

Unlike sound effects, only one accompaniment can play at a time. Repeated calls overwrite the previous accompaniment playback.

Parameters

Return Description

• 0: The call succeeded.

• Non-zero: The call failed and returns an error code.

Sets the headset or speaker as the audio output device.

public abstract int stopAudioAccompany() ;

This interface is the counterpart to startAudioAccompany and stops the playback of the audio accompaniment.

When to call

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

Response description

• 0: The call succeeded.

• Non-zero: The call failed and returns an error code.

Sets the volume of the audio accompaniment for both local playback and stream ingest.

public abstract int setAudioAccompanyVolume( int volume) ;

This API sets the audio accompaniment volume for local playback and for publishing. To set only the local playback volume, use setAudioAccompanyPlayoutVolume. To set only the publish volume, use setAudioAccompanyPublishVolume.

Parameters

Response description

• 0: The call succeeded.

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

Sets the volume of the audio accompaniment for stream ingest.

public abstract int setAudioAccompanyPublishVolume(int volume) ;

Parameters

Return description

• 0: The call succeeded.

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

Retrieves the ingest volume for the accompaniment stream.

public abstract int getAudioAccompanyPublishVolume() ;

Response description

The ingest volume for the accompaniment music stream.

• 0 to 100: success.

• Other values: error code.

Sets the local playback volume of the accompaniment.

public abstract int setAudioAccompanyPlayoutVolume(int volume) ;

Parameters

Return Description

• 0: The call succeeded.

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

Queries the local playback volume of the accompaniment.

public abstract int getAudioAccompanyPlayoutVolume() ;

Return Description

The local playback volume of the accompaniment.

• [0-100]: Success.

• Other values: Error code.

Pause the accompaniment mixing.

public abstract int pauseAudioAccompany();

Return Description

• 0: The call succeeded.

• Non-zero: The call failed and returned an error code.

You can restart the accompaniment mixing.

public abstract int resumeAudioAccompany();

Return description

• A value of 0 indicates that the call succeeded.

• A non-zero value indicates that the call failed and returns an error code.

Retrieves the duration of the accompaniment file, in milliseconds.

public abstract int getAudioAccompanyDuration();

This method retrieves the duration of the current accompaniment file.

Return description

• >= 0: duration of the accompaniment file.

• < 0: the call failed and returns an error code.

Obtains the playback progress of the accompaniment file, in milliseconds.

public abstract int getAudioAccompanyCurrentPosition();

This method obtains the playback progress of the current accompaniment file, in milliseconds.

Response description

• A value greater than or equal to 0: The playback progress of the accompaniment file.

• A value less than 0: The call failed. An error code is returned.

Sets the playback position of the accompaniment.

public abstract int setAudioAccompanyPosition(int posMs);

This method sets the playback progress of the accompaniment. It is useful for features such as dragging a progress bar. After this method is successfully called, the accompaniment plays from the specified position.

Parameters

Return Description

• 0: The call succeeded.

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

Preloads a sound effect.

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

Parameters

Return description

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

Deletes a preloaded sound effect file.

public abstract int unloadAudioEffect(int soundId);

Parameters

Return description

A value of 0 indicates that the call is successful. Any other value indicates failure.

Starts playing a sound effect.

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

Parameters

Return description

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

Stops playing a sound effect.

public abstract int stopAudioEffect(int soundId);

Parameters

Return description

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

Stops playing all sound effects.

public abstract int stopAllAudioEffects();

Return Description

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

Sets the volume for the sound effect stream ingest.

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

Parameters

Return Description

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

Queries the sound effect stream ingest volume.

public abstract int getAudioEffectPublishVolume(int soundId);

Parameters

Response description

A value of 0 indicates that the call is successful. Any other value indicates failure.

Sets the local playback volume of the sound effect.

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

Parameters

Return description

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

Retrieves the local playback volume for the sound effect on Android and iOS devices.

public abstract int getAudioEffectPlayoutVolume(int soundId);

Parameters

Return description

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

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

public abstract int setAllAudioEffectsPublishVolume(int volume);

Parameters

Return description

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

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

public abstract int setAllAudioEffectsPlayoutVolume(int volume);

Parameters

Return description

A value of 0 indicates that the call is successful. Any other value indicates failure.

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

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

Stops recording media files.

  public abstract void stopRecord();

Parameters

None.

Pauses a sound effect.

public abstract int pauseAudioEffect(int soundId);

Parameters

Return Description

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

Pauses all sound effects.

public abstract int pauseAllAudioEffects();

Return Description

A value of 0 indicates that the call is successful. Any other value indicates failure.

Resumes playback of a sound effect.

public abstract int resumeAudioEffect(int soundId);

Parameters

Return description

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

You can resume playing all sound effects.

public abstract int resumeAllAudioEffects();

Return Description

A value of 0 indicates that the call is successful. Any other value indicates failure.

Creates a SurfaceView rendering view.

public abstract SophonSurfaceView createRenderSurfaceView(Context context);

You must call this method to display video views instead of creating a SurfaceView directly. To use this method:

• Assign the return value to AliRtcVideoCanvas#view.

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

When to call

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

Limitations

You must call this method on the main thread.

Parameters

You can set the rendering window and drawing parameters for local preview.

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

This method sets the local preview view by binding the local video stream to a view and configuring the local user's view rendering mode, mirroring mode, and rotation angle. It affects only the local user's preview and not the ingested video. To set the remote user interface view, call setRemoteViewConfig.

When to call

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

Parameters

Return Instructions

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

You can set the rendering window and drawing parameters for the remote video.

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

This method binds the display view for a specified remote user’s video stream and configures the rendering mode, mirroring mode, and rotation angle for that user’s video when displayed locally. It affects only the video shown to the local user. To configure the local preview view, call setLocalViewConfig.

• If the view parameter of AliRtcVideoCanvas is empty, rendering stops.

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

• To change the `mirrorMode` parameter of AliRtcVideoCanvas during playback, modify the `mirrorMode` value while keeping the other parameters unchanged.

When to call

We recommend that you call this function when you receive the onRemoteTrackAvailableNotify callback. You can set it when a remote user’s video becomes available.

Parameters

Return Description

A value of 0 indicates that the call is successful, while any other value indicates failure.

Sets the camera capture preferences, such as the camera direction and capture frame rate.

public abstract int setCameraCapturerConfiguration(AliEngineCameraCapturerConfiguration cameraCapturerConfiguration);

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

When to call

You must call this method before turning on the camera, for example, before performing the following operations:

• startPreview (starts the video preview)

• joinChannel (joins a channel)

Parameters

Return Description

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

Disables or re-enables local video capture.

public abstract int enableLocalVideo(boolean enable);

This method controls enabling and disabling local video capture. When local video capture is disabled, there is no video data for local preview or stream ingest, but it does not affect receiving remote video. If you call this method to disable local camera capture, both local preview and remote stream ingest remain on the last frame.

When to call

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

Related callbacks

A successful call to this API notifies the remote user through the onUserVideoEnabled callback.

Parameters

Return Description

A value of 0 indicates that the call is successful. Any other value indicates failure.

Stops or resumes sending local video data.

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

When ingesting streams, you can call this method to send entirely black video frames. Local preview remains normal, and capture, encoding, and sending modules continue to operate, but the video content consists of black frames.

Parameters

Return Description

A value of 0 indicates that the call is successful.

Checks if the camera is on.

public abstract boolean isCameraOn();

Return Description

A value of true indicates the camera is on. A value of false indicates the camera is off.

Sets video encoding properties.

public abstract void setVideoEncoderConfiguration(AliRtcVideoEncoderConfiguration config);

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

When to call

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

Limitations

The mirrorMode parameter of this method and the setVideoMirrorMode method both set the mirroring for video stream ingest. We recommend that you use only one of these methods. Using both methods can cause mirroring effects to overlap, which can lead to mirroring failures or inconsistencies.

Parameters

Sets video decoding properties.

    public abstract void setVideoDecoderConfiguration(AliRtcVideoDecoderConfiguration config);

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

When to call

We recommend calling this method before joining a channel.

Parameters

You can switch between the front and rear cameras. The front camera is used by default.

public abstract int switchCamera();

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

When to call

You can call this method only after the camera is successfully enabled.

Limitations

This method is only supported on Android and iOS.

Return description

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

Retrieves the current camera direction.

public abstract AliRTCCameraDirection getCurrentCameraDirection();

Return Instructions

• A value of CAMERA_REAR (0) indicates the rear camera.

• A value of CAMERA_FRONT (1) indicates the front camera.

• A value of CAMERA_INVALID (-1) indicates an invalid value.

Start the local preview.

public abstract int startPreview();

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

Invocation timing

• You must set a view for the local preview by calling setLocalViewConfig before the call. Otherwise, the preview will not be displayed, but stream ingest is not affected.

• If needed, you can call this method to start preview before calling joinChannel. The camera automatically turns on.

Return description

A value of 0 indicates a successful call, while any other value indicates failure.

Stops the local preview.

public abstract int stopPreview();

This method stops the local video preview and turns off the camera. After the preview is stopped, the local view displays the last captured frame, and stream ingest is not affected.

When to call

You can call this method after starting the local preview.

Return Description

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

You can set the camera zoom ratio.

public abstract int setCameraZoom(float zoom);

You can set the zoom factor of the camera.

Limitations

This method is available only on iOS and Android devices.

When to call

This setting takes effect only after you enable the camera. The zoom resets each time the camera restarts.

Parameters

Return Description

• 0: call succeeded.

• Non-zero: the method call failed.

Retrieves the maximum zoom factor (optical zoom) supported by the camera.

public abstract float GetCameraMaxZoomFactor();

Return Description

The maximum zoom factor supported by the device camera.

You can retrieve the current camera zoom factor setting.

public abstract float GetCurrentZoom();

Return Description

The current camera zoom factor of the device.

You can set the camera exposure.

public abstract int SetExposure(float exposure);

When the shooting environment is too dark or too bright, video capture quality is affected. To improve video quality, you can use this method to adjust your camera's exposure level. You can retrieve the supported exposure level range using GetMinExposure and GetMaxExposure.

Parameters

Response description

• 0: call succeeded.

• A non-zero value indicates that the method call failed.

Retrieves the exposure level of the camera.

public abstract float GetCurrentExposure();

Retrieves the exposure level setting of the camera currently in use.

Return description

The current exposure level of the camera.

You can obtain the minimum exposure supported by the camera.

public abstract float GetMinExposure();

Return description

The minimum camera exposure level.

Retrieves the maximum supported camera exposure level.

public abstract float GetMaxExposure();

Return Description

The maximum camera exposure level.

Enables or disables the camera flash.

public abstract int setCameraFlash(boolean flash);

Enables or disables the flash.

Limitations

This method is supported only on iOS and Android.

Parameters

Return Description

• 0: The setting succeeded.

• A non-zero value: The setting failed.

Queries whether manual focus is supported on the current device.

public abstract boolean isCameraFocusPointSupported();

Checks whether the current camera supports setting a focus point for manual focus.

Limitations

This method is available only on iOS and Android.

Response description

• true: The device supports manual focus.

• false: The device does not support manual focus.

Checks if setting the camera exposure point is supported.

public abstract boolean isCameraExposurePointSupported();

Determines if an exposure point can be set on the current device.

Limitations

This method is available only on iOS and Android.

Return Description

• true: The camera exposure point can be set.

• false: The camera exposure point cannot be set.

You can set the camera's manual focus point.

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

Sets the focus point for the current camera. After you call this operation, the camera adjusts the exposure for the specified point and then maintains this focus value. Before you call this operation, we recommend that you call isCameraFocusPointSupported to check whether the device supports manual focus.

Limitations

This method is available only on iOS and Android.

Call this method only before joining a channel.

Return Description

• 0: call succeeded.

• Non-zero: call failed.

You can set the camera exposure point.

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

This operation sets the camera exposure point. After you call it, the camera adjusts the exposure once for the specified point and maintains that exposure value. Before calling this operation, we recommend that you call isCameraExposurePointSupported to check whether the device supports manual exposure point setting.

Limitations

This method is available only on iOS and Android devices.

Parameters

Return Description

• 0: The method call succeeded.

• Non-zero: The method call failed.

Checks if the camera supports automatic face focus.

public abstract boolean isCameraAutoFocusFaceModeSupported();

Determines whether the camera supports automatic face focus.

When to call

You can call this method only after the camera is enabled. It returns true if the camera is enabled and supports both face detection and auto focus. Otherwise, it returns false.

Limitations

This method is available only on iOS and Android.

Return description

• true: Automatic face focus is supported.

• false: Automatic face focus is not supported.

You can set the camera's face focus.

public abstract boolean setCameraAutoFocusFaceModeEnabled(boolean enable);

This interface enables real-time autofocus on human faces. Before calling this method, you must call isCameraAutoFocusFaceModeSupported to verify device support for this feature.

Limitations

This method is available only on iOS and Android.

Parameters

Return description

• true: The call succeeded.

• false: The call failed.

Configure video mirroring for preview and stream ingest.

public abstract int setVideoMirrorMode(AliRtcVideoPipelineMirrorMode mirrorMode);

Specifies whether to enable mirroring mode for local preview video and ingested video streams.

When to call

You can dynamically set this method before or after joining a channel. The SDK records the state internally and applies video operations when preview and encoding (stream ingest) are available.

Call Limits

This method overlaps with mirrorMode in setLocalViewConfig and setVideoEncoderConfiguration. We recommend using only one of these methods.

Call this method before joining a channel.

Response description

• 0: The setting was applied successfully.

• <0: Settings failed.

  • AliRtcErrInner: SDK internal state error. You can check if the SDK instance was created successfully.

Sets the timing of video capture scaling.

public abstract void setCapturePipelineScaleMode(AliRtcCapturePipelineScaleMode mode);

Sets whether video data capture scaling occurs immediately upon capture or during encoding. For example, when capture resolution differs from encoding resolution, you can set the scaling timing to determine if preview data and stream ingest data are consistent.

When to call

Set this method before enabling the camera. For example, set it before starting preview with startPreview or joining a channel with joinChannel.

Parameters

Return Description

None.

Enables an external video input source.

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

Parameters

Imports video data.

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

Parameters

Response description

A value of 0 indicates that the call is successful. Any other value indicates failure.

Starts relayed live streaming.

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

Parameters

Response description

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

You can update the bypass live streaming parameters.

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

Parameters

Return instructions

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

Stop the bypass live stream.

public abstract int stopPublishLiveStream(String streamUrl);

Parameters

Return description

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

Retrieve the bypass live streaming status.

public abstract AliRtcEngine.AliRtcLiveTranscodingState getPublishLiveStreamState(String streamUrl);

Parameters

Return Instructions

Returns the status of bypass live streaming.

You can enable network quality probing.

public abstract int startNetworkQualityProbeTest(AlirtcNetworkQualityProbeConfig config);

Parameters

Return description

A value of 0 indicates success, while a non-zero value indicates failure.

Stops network quality testing.

public abstract int stopNetworkQualityProbeTest();

Return Description

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

You can send media extension information.

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

The SDK lets you send and receive media extension messages. The sending method uses the SEI extension protocol. Receivers can obtain the messages by listening for the onMediaExtensionMsgReceived event.

Common use cases include the following:

• Use media extension information to transmit timestamps, calculate end-to-end network latency, or synchronize data with other business operations.

• Use media extension information to transmit descriptive information. You can transmit up to 4 KB of data, which is suitable for small amounts of data. We recommend using JSON or plain strings.

When to call

You can call this method after starting stream ingest.

Limitations

Using media extension information requires reusing the audio and video data channel. Therefore, you must control how frequently you send custom messages and the length of the message data. The limitations are as follows:

• You can send up to fps messages per second, as specified in the profile, because SEI information is embedded in H.264 or H.265 streams and requires video frame encoding to attach extension information.

• To avoid impacting media data transmission quality, the custom message body is limited to 4 KB, making it suitable for small amounts of information.

• The repeatCount parameter in the sendMediaExtensionMsg function specifies the redundancy level for custom messages. If this value is greater than 1, the message is sent multiple times.

• This redundancy helps prevent message loss caused by network packet loss. In such cases, other participants in the room receive multiple identical messages and must deduplicate them.

• Subscribers in the room also receive custom messages during relayed live streaming.

• Only one MediaExtensionMsg is transmitted at a time. Multiple calls to sendMediaExtensionMsg overwrite previously queued data.

Related callbacks

The stream puller can retrieve media extension information sent by the stream ingestor by listening for the onMediaExtensionMsgReceived callback.

Parameters

Return Instructions

• 0: The call succeeded.

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

  • ERR_INNER(-1): Internal SDK error. Possible causes: The SDK is not initialized, or it is called after it has been destroyed.

Sends media extension information.

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

The SDK provides a feature to send and receive media extension information. This method sends media extension information using the SEI extension protocol. You can obtain the information by listening to onMediaExtensionMsgReceived. When payloadType is 5, this is equivalent to using the sendMediaExtensionMsg interface.

Common use cases include the following:

• Use media extension information to transmit timestamps, calculate end-to-end network latency, or synchronize data with other business operations.

• Use media extension information to transmit descriptive information. You can transmit up to 4 KB of data, which is suitable for small amounts of data. We recommend using JSON or plain strings.

When to call

You can call this method after you start stream ingest.

Limitations

Using media extension information requires reusing the audio and video data channel. Therefore, you must control how frequently you send custom messages and the length of the message data. The limitations are as follows:

• You can send up to fps messages per second, as specified in the profile, because SEI information is embedded in H.264 or H.265 streams and requires video frame encoding to attach extension information.

• To avoid degrading media data transmission quality, the custom message body is limited to 4 KB, making it suitable for small amounts of information.

• The repeatCount parameter in the sendMediaExtensionMsg function specifies the redundancy level for custom messages. If this value is greater than 1, the message is sent multiple times.

• This redundancy helps prevent message loss caused by network packet loss. In such cases, other participants in the room receive multiple identical messages and must deduplicate them.

• Subscribers in the room also receive custom messages during relayed live streaming.

• Only one MediaExtensionMsg is transmitted at a time. Multiple calls to sendMediaExtensionMsg overwrite previously queued data.

Parameter description

Return description

• 0: The call succeeded.

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

  • ERR_INNER(-1): An SDK internal error occurred. Possible causes include SDK initialization failure or calling the SDK after it has been destroyed.

This callback is invoked when the network connection status changes. It is important to monitor this callback.

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

Parameters

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

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

Parameters

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

public void onAuthInfoWillExpire();

This callback indicates that the user's authentication information will expire in 30 seconds. You must obtain a new token and update the authentication information using one of the following methods:

• Call <a baseurl="t2309760_v6_4_1.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#975b9af9ecq1a" id="8099ac5a509hn">refreshAuthInfo</a> 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.

Trigger Time

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

The user invokes an interface that requires authentication, and the server returns expired information.

public void onAuthInfoExpired();

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

• You can call <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#fef395c4beqdt" id="c3b0cf2f19dgm">leaveChannel</a> to exit the current channel. Then, call joinChannel to re-enter it.

Trigger time

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

This callback returns the result of joining a channel.

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

Parameters

The callback that returns the result of leaving a channel.

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

Triggering conditions

This callback is triggered when the 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> and the system returns the result of leaving the channel along with the session statistics information.

Parameters

Offline callback for a remote user.

public void onRemoteUserOffLineNotify(String uid, AliRtcUserOfflineReason reason);

This callback notifies the local user that a remote user has left the channel because they went offline.

Trigger conditions

• When a remote user actively leaves the channel, the callback is triggered.

• 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 and setting the role to AliRTCSdkLive), the callback is triggered.

• When a remote streamer is considered offline because no data is received from them for an extended period, the callback is triggered.

Parameters

This callback is invoked when a remote user comes online.

public void onRemoteUserOnLineNotify(String uid, int elapsed);

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

Triggering conditions

• A remote user joins the channel.

• After the local user joins the channel, this callback is invoked for each user who is already in the channel. This allows the local user to identify the existing users.

Parameters

This callback is invoked when a remote user's audio and video streams change.

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

This callback is triggered when a remote user's stream ingest status changes. Through this callback, developers can obtain real-time information about whether remote users are ingesting audio and video streams, and accordingly display or hide the remote users' audio and video information.