ApsaraVideo Live:AliRtcEngine class

Join a channel for a multi-participant meeting.

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

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

• joinChannel[1/3] uses single-parameter authentication. Pass a token generated by token-based authentication. We recommend this for RTC scenarios.

• This is the multi-parameter method. Pass a multi-parameter token generated by token-based authentication, along with the user information used to generate the token.

• joinChannel[3/3] is for Real-time Conversational AI. Pass a single-parameter token and set the capabilityProfile based on the scenario.

Limitations

• After you join a channel, to switch to a different one, 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. You can join a new channel only after 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.

• 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 the channel, the remote end 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 value

0 indicates success. Non-zero values indicate failure.

Joins a channel (single-parameter authentication).

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

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

• joinChannel[1/3] is for RTC scenarios. Pass a token-based authentication single-parameter token. We recommend this for RTC scenarios.

• joinChannel[2/3] uses multi-parameter authentication. Pass a multi-parameter token generated by token-based authentication, along with the user information used to generate the token.

• This method is for Real-time Conversational AI. Pass a single-parameter token and set the capabilityProfile parameter. For AI agent conversations, set it to AliCapabilityProfileAiHuman.

Limitations

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

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

• Apps using different App IDs cannot interoperate.

• Do not call this method when retrying after a failed join.

Related callbacks

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

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

• After a user successfully joins a channel, the remote client triggers 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

0 indicates success. Non-zero values indicate failure.

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

public abstract int leaveChannel();

When to call

• Call this after joining a channel and needing to exit.

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

Related callbacks

• Local client: After you call this method, the <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#8c189be470bsp" id="80f5e30245vfn">onLeaveChannelResult</a> callback is triggered to notify you of the result of leaving the channel.

• Remote side: After you successfully call this operation, remote users receive a notification through 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

0 indicates success. Non-zero values indicate failure.

Checks whether you are currently in a channel.

public abstract boolean isInCall();

Return value

true: in a channel. false: not in a channel.

Sets 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 role to streamer: The SDK publishes local audio or video by default and receives other streamers' audio or video.

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

When to call

You can call this before or after joining a channel. Set the role before joining, or switch roles after joining.

Limitations

This method works only in interactive mode—that is, after calling setChannelProfile with AliRTCSdkInteractiveLive.

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

Parameters

Queries the user role.

public abstract AliRTCSdkClientRole getCurrentClientRole();

Return description

Returns the current user role.

Refreshes authentication information.

public abstract int refreshAuthInfo(AliRtcAuthInfo authInfo);

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

When to call

Under the following conditions:

• 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 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 notify you that authentication has expired. You then need to regenerate a token and call joinChannel to rejoin the channel.

Parameters

Return Description

0 indicates success. Other values indicate failure.

Refreshes authentication information.

public abstract int refreshAuthInfo(String token);

This method updates the token. Tokens expire after a period, preventing connection to the server.

When to call

We recommend regenerating the token on your server and calling this method under the following conditions:

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

• 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="3fd674e985gl8">onAuthInfoExpired</a> notification is triggered, indicating that authentication has expired. At this point, you must call joinChannel to rejoin the channel.

Parameters

Return description

0 indicates success. Other values indicate 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 track. The SDK publishes audio by default. To disable publishing, call publishLocalAudioStream(false) before joining.

When to call

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

Related callbacks

When the local audio stream ingest result 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 latest status of the audio stream ingest, 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

0 indicates success. Other values indicate failure.

Queries whether the audio track is published.

public abstract boolean isLocalAudioStreamPublished();

Return description

true: audio track is published. false: audio track is not published.

Specifies whether to subscribe to remote users' audio tracks by default.

public abstract int setDefaultSubscribeAllRemoteAudioStreams(boolean sub);

This method configures whether the system subscribes to remote users' audio tracks by default. This affects subscription behavior for newly joined users. Unless you have specific requirements, we recommend setting this to true.

When to call

You can call this before or after joining a channel.

• Before joining:

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

• After joining:

  • To stop default subscription, call setDefaultSubscribeAllRemoteAudioStreams(false). New users joining afterward will not be subscribed.

  • To resume subscription for a specific user, call subscribeRemoteAudioStream. For multiple users, call it multiple times.

  • After stopping default subscription, calling setDefaultSubscribeAllRemoteAudioStreams(true) resumes subscription only for users who join afterward—not for users who joined during the pause.

Parameters

Return Description

0 indicates success. Other values indicate failure.

You can stop or resume pulling audio streams from a specific remote user.

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

This API stops or resumes subscribing to audio streams from a specific remote user. Unless your scenario requires otherwise, we recommend setting it to true.

Parameters

Return Description

0 indicates success. Other values indicate failure.

Specifies whether to subscribe to all remote users' audio tracks.

public abstract int subscribeAllRemoteAudioStreams(boolean sub);

This method acts as the master switch for subscribing to remote audio tracks. We recommend setting it to true. Setting it to false causes:

• Immediate unsubscription from all remote audio tracks in the current session.

• Subsequent new users will not be subscribed either.

• It is not possible to individually control the audio stream of a specified user through <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#e09342eeb0z4k" id="a56b5f2a3f56k">subscribeRemoteAudioStream</a>.

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

Parameters

Return description

0 indicates success. Other values indicate failure.

Specifies whether to publish the camera track.

public abstract int publishLocalVideoStream(boolean enable);

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

When to call

You can call this before or after joining a channel.

Calling before joining modifies the default configuration and takes effect at join time.

Related callbacks

When the local audio stream ingest result changes, the local client 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 you of the latest audio stream ingest status, 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="176ee94b46lb7">onRemoteTrackAvailableNotify</a> callback to notify you that the remote users' audio and video streams have changed.

Parameters

Return description

0 indicates success. Other values indicate failure.

Queries whether the camera track is published.

public abstract boolean isLocalVideoStreamPublished();

Return value

true: camera track is published. false: camera track is not published.

Specifies whether to subscribe to remote users' video tracks by default.

public abstract int setDefaultSubscribeAllRemoteVideoStreams(boolean sub);

This method specifies whether to subscribe to remote users' video tracks by default. The SDK subscribes by default.

When to call

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

After stopping video subscription, to resume, call subscribeRemoteVideoStream and specify the remote user ID you want to receive. To resume for multiple users, call subscribeRemoteVideoStream multiple times. setDefaultSubscribeAllRemoteVideoStreams(true) only resumes subscription for users who join afterward.

This method specifies whether to subscribe to remote users' video tracks by default.

Parameters

Return value

0 indicates success. Other values indicate failure.

Subscribes to or stops subscribing to a specified remote video track.

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

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

When to call

You can call this before or after joining a channel.

Parameters

Return Description

• 0: successful.

• Non-zero: failed.

Subscribes to or stops subscribing to all remote video streams.

public abstract int subscribeAllRemoteVideoStreams(boolean sub);

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

• Immediate unsubscription from all remote video streams in the current session.

• New users who join later will not subscribe either, even if you set setDefaultSubscribeAllRemoteVideoStreams(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 control the video stream of a specified user.

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

Parameters

Return Description

0 indicates success. Other values indicate failure.

You can stop or resume the media stream from 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 with <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 interface uses two Boolean parameters—subVideo and subAudio—to determine whether to subscribe to remote audio and video streams, and videoTrack controls which video stream to pull.

Parameters

Return description

0 indicates success. Other values indicate failure.

Subscribes to or stops subscribing to audio and video streams of a remote user.

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

This method combines subscription to remote audio and video streams.

Related methods

Compared with subscribeRemoteMediaStream[1/2], this interface uses the videoTrack and audioTrack parameters to specify the media streams you want to subscribe to in a single interface call, for example:

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

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

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

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

Parameters

Return description

• 0: successful.

• <0: failed.

Subscribes to or stops subscribing 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

0 indicates success. Other values indicate failure.

Subscribes to or stops subscribing to all users' streams across channels.

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

Parameters

Return description

• 0: successful.

• Non-zero: failed.

Adjusts playback volume for ingested audio streams.

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

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

Parameters

Return Description

• 0: The method executed successfully.

• Non-zero: failed—for example, 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 before or after joining a channel.

Related callbacks

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

Parameters

Return description

0 indicates success. Other values indicate failure. Muting sends silent frames, but capture and encoding remain active.

Stops or resumes playing the audio track of a specific remote user.

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

This operation is used only to stop or resume playback of audio from a specified remote user, but does not affect stream pulling or decoding of audio from remote users. To unsubscribe from the audio stream of a specific user, 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 configure this before or after joining a channel.

Parameters

Return description

0 indicates success. Other values indicate failure.

Stops or resumes playing all remote users' audio.

public abstract int muteAllRemoteAudioPlaying(boolean mute);

This method stops or resumes playback of all remote users' audio.

When to call

You can configure this before or after joining a channel.

Parameters

Return Description

0 indicates success. Other values indicate failure.

Starts audio capture.

public abstract int startAudioCapture();

This method starts audio capture. You can also call it before joining to pre-start audio capture. If you do not set it, the SDK manages the audio capture device automatically. After calling stopAudioCapture to stop audio capture, call this method to restart.

When to call

You can call this 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> interface lets you control whether the audio capture device remains in the enabling status after you leave the meeting using parameters.

Related callbacks

After calling this method to modify local audio capture status, use the onLocalAudioStateChanged callback to monitor changes.

Return description

0 indicates success. Other values indicate failure.

Starts audio capture.

public abstract int startAudioCapture(boolean keepAlive);

Stops microphone capture after muting.

This method starts audio capture. You can also call it before joining to pre-start audio capture. If you do not set it, the SDK manages the audio capture device automatically.

When to call

You can call this before or after joining a channel.

Related methods

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

Related callbacks

After calling this method to modify local audio capture status, use the onLocalAudioStateChanged callback to monitor changes.

Parameters

Return Description

0 indicates success. Other values indicate failure.

Stops audio capture.

public abstract int stopAudioCapture();

The SDK enables audio capture by default. Without special configuration, actions like preview start and channel join automatically start audio capture. To stop audio capture, call this method.

Related callbacks

After calling this method to modify local audio capture status, use the onLocalAudioStateChanged callback to monitor changes.

Return description

0 indicates success. Other values indicate failure.

Sets whether the default audio output is the speaker.

public abstract int setDefaultAudioRoutetoSpeakerphone(boolean defaultToSpeakerphone);

This method sets the default audio routing device before joining a channel. You can choose earpiece or speaker output. The SDK defaults to speaker. To change this, call the method before joining.

The SDK defines internal audio routing priority and switches automatically based on connected peripherals. Priority order: Wired headset > Bluetooth headset > User setting > Default setting. So if no peripheral is connected and you have not used enableSpeakerphone, the default setting applies.

For more details about audio routing, see Audio Routing Settings.

Mobile devices usually support two audio routing options: earpiece and speaker:

• Earpiece: Lower volume. Requires holding the phone near your ear for clear sound. Offers better privacy—ideal for calls.

• Speaker: Higher volume. No need to hold the phone to your ear. Enables hands-free operation.

Related methods

This method modifies the default audio routing setting. Use enableSpeakerphone to set the current routing device.

When to call

You can call this before or after joining a channel.

Parameters

Return Description

• 0: successful.

• <0: failed.

Sets the audio output device to earpiece or speaker.

public abstract int enableSpeakerphone(boolean enable);

This method sets the current audio playback device after joining a channel—choosing between earpiece and speaker. If you do not set this, playback uses the default audio routing device.

The SDK defines internal audio routing priority and switches automatically based on connected peripherals. Priority order: Wired headset > Bluetooth headset > User setting > Default setting. So if a peripheral is connected, this method has no effect. For more details, see Audio Routing Settings.

When to call

You can call this 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 default audio routing settings. This interface sets the current routing device.

Parameters

Return Information

0 indicates success. Other values indicate failure.

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

public abstract boolean isSpeakerOn();

Return description

true: speaker. false: earpiece.

Enables user volume indication.

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

This method lets the SDK periodically report volume information for the local user and the remote user with the highest instantaneous volume. To use it, implement the AliRtcAudioVolumeObserver class and register it using registerAudioVolumeObserver.

When to call

You can call this before or after joining a channel.

Related callbacks

After calling successfully, if users are publishing streams, the SDK triggers these callbacks at the configured interval:

• Speaker volume is reported via AliRtcAudioVolumeObserver#onAudioVolume.

• Voice activity detection triggers AliRtcAudioVolumeObserver#onActiveSpeaker to report the speaking user's UID.

Parameters

Return Description

0 indicates success. Other values indicate failure.

Enables in-ear monitoring.

public abstract int enableEarBack(boolean enable);

This method enables or disables in-ear monitoring. We recommend enabling it when using wired or Bluetooth headphones for best results.

When to call

You can call this before or after joining a channel.

Parameters

Return description

0 indicates success. Other values indicate failure.

Sets the in-ear monitoring volume.

public abstract int setEarBackVolume(int volume) ;

This method sets the in-ear monitoring volume. It takes effect only after enableEarBack is called.

When to call

You can call this before or after joining a channel.

Parameters

Return value

• 0: successful.

• <0: Method call failed.

Starts the audio playback device.

public abstract int startAudioPlayer();

This method pre-starts audio playback. If you do not set it, the SDK starts playback automatically after subscribing to an audio stream.

Return description

• 0: successful.

• Non-zero: failed. Returns error code.

Stops the audio playback device.

 public abstract int stopAudioPlayer();

This method stops audio playback. It corresponds to startAudioPlayer.

Return description

• 0: successful.

• Non-zero: failed. Returns error code.

Sets the local playback volume.

public abstract int setPlayoutVolume(int volume);

Parameters

Return description

• 0: successful.

• Non-zero: failed.

Sets the recording volume.

public abstract int setRecordingVolume(int volume);

Parameters

Return Description

• 0: successful.

• Non-zero: failed.

Plays an audio file.

public abstract int playAudioFileTest(String filePath) ;

This method plays an audio file before joining a channel to test audio playback.

When to call

Call this only before joining a channel.

Limitations

Multiple calls overwrite each other. Calling this stops any currently playing file (if present).

Parameters

Return value

• 0: successful.

• Non-zero: failed.

Stops audio file playback.

public abstract int stopAudioFileTest();

This method corresponds to playAudioFileTest and stops audio file playback.

Limitations

Call this only before joining a channel.

Return description

• 0: successful.

• Non-zero: failed.

Starts audio capture device testing before a session begins.

public abstract int startAudioCaptureTest();

This method starts audio capture testing to verify that the local audio capture device works properly before a session. After calling it, the SDK reports volume information via the AliRtcAudioVolumeObserver::onTestAudioVolume callback.

When to call

Call this before joining a channel. After testing completes, ensure you call stopAudioCaptureTest to stop testing and prevent device conflicts.

Return Description

• 0: successful.

• Non-zero: failed. Returns error code.

Stops audio capture testing.

public abstract int stopAudioCaptureTest();

This method stops audio capture testing. Call it after startAudioCaptureTest.

When to call

Call this before joining a channel.

Return value

• 0: successful.

• Non-zero: failed. Returns error code.

Sets the voice change effect mode.

public abstract int setAudioEffectVoiceChangerMode(AliRtcAudioEffectVoiceChangerMode mode);

Parameters

Return description

0 indicates success. Other values indicate failure.

Sets the pitch adjustment value.

public abstract int setAudioEffectPitchValue(double value);

Parameters

Return Description

0 indicates success. Other values indicate failure.

Sets the reverberation effect mode.

public abstract int setAudioEffectReverbMode(AliRtcAudioEffectReverbMode mode);

Parameters

Return description

0 indicates success. Other values indicate failure.

Sets the reverberation effect type and specific parameters.

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

Parameters

Return Description

0 indicates success. Other values indicate failure.

Sets a predefined voice beautification effect mode.

public abstract int setAudioEffectBeautifyMode(AliRtcAudioEffectBeautifyMode mode);

This method configures built-in voice beautification modes in the SDK. It is ideal for scenarios requiring enhanced vocal quality—such as voice live streaming, karaoke, and voice social apps. Selecting different modes alters vocal perception—for example, boosting richness or clarity—to improve the listening experience for remote users.

When to call

You can call this before or after joining a channel.

Parameters

Return description

• 0: successful.

• Non-zero: failed.

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

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

This method applies graphic equalization to locally captured voice or audio signals. By adjusting gain (in dB) for one of ten fixed frequency bands, you can customize tonal characteristics. It is useful for speech clarity enhancement, vocal emphasis, and noise reduction assistance.

The equalizer supports full audio spectrum tuning—from 31 Hz to 16 kHz—with ten standard bands. Each band supports independent gain settings ranging from [-15, 15] dB. Default gain is 0 dB (no boost or attenuation).

Limitations

• You cannot use the equalizer without first enabling a beautification mode. Call setAudioEffectBeautifyMode before calling this method.

Parameters

Return Description

0: successful.

Non-zero: failed.

Adds an external audio stream.

public abstract int addExternalAudioStream(AliRtcExternalAudioStreamConfig config);

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

1. 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 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 send 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="16d826dedcli6">removeExternalAudioStream</a> to remove the external audio stream.

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

Parameters

Return description

Values >0 indicate success and return the external audio stream ID. Other values indicate failure.

Imports external audio stream data.

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

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

1. You can 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 retrieve the external audio stream ID.

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

3. When you end the call, you must 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 on publishing custom-captured audio in a channel, see Custom Audio Capture.

When to call

You can call this after you join a channel.

Parameters

Return description

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

Sets the volume of an external audio stream for stream ingest.

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

Parameters

Return value

A return value of 0 indicates success. Other values indicate failure.

Retrieves the volume of the external audio stream ingest.

public abstract int getExternalAudioStreamPublishVolume(int streamId);

Parameters

Return Description

The volume ranges from 0 to 100. A value less than 0 indicates failure.

Sets the playback volume for external audio streams.

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

Parameters

Return Description

0 indicates success. Other values indicate failure.

Retrieves the playback volume of external audio streams.

public abstract int getExternalAudioStreamPlayoutVolume(int streamId);

Parameters

Return description

The playback volume, ranging from 0 to 100. A negative value indicates a failure.

Removes an external audio stream.

public abstract int removeExternalAudioStream(int streamId);

This method removes the external audio stream associated with the specified streamId. It complements the addExternalAudioStream method.

When to call

If you want to use custom audio input, call addExternalAudioStream to add an audio stream and obtain its ID. Then call pushExternalAudioStreamRawData to feed your audio data to the SDK. When you no longer need the custom audio input, call this method to remove the stream and release associated resources.

Parameters

Return description

• 0: Success.

• <0: Failure. Returns an error code.

Retrieves information about an audio file.

public abstract int getAudioFileInfo(String fileName);

You can call this method asynchronously to retrieve the file duration. The method returns audio file information through the onAudioFileInfo callback.

Parameters

Back to Introduction

• 0: The operation succeeded.

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

Starts music accompaniment mixing.

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

This method plays local or online accompaniment files. It is asynchronous. After calling this method, 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 replace the previous accompaniment.

Parameters

Return Description

• 0: The operation was successful.

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

Stops music accompaniment mixing.

public abstract int stopAudioAccompany() ;

This method corresponds to startAudioAccompany and stops accompaniment playback.

When to call

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

Return Description

• 0: Success.

• Non-zero: Failure. Returns an error code.

You can use this method to set the volume of the audio accompaniment for both local playback and stream ingest.

public abstract int setAudioAccompanyVolume( int volume) ;

This operation sets the audio accompaniment volume for both local playback and stream ingest. To set these volumes individually, use setAudioAccompanyPlayoutVolume for local playback and setAudioAccompanyPublishVolume for stream ingest.

Parameters

Return Description

• 0: The method call was successful.

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

Sets the volume of the accompaniment stream ingest.

public abstract int setAudioAccompanyPublishVolume(int volume) ;

Parameters

Return value

• 0: Success.

• Non-zero: Failure. Returns an error code.

Queries the accompaniment stream ingest volume.

public abstract int getAudioAccompanyPublishVolume() ;

Return Description

The stream ingest volume for accompaniment music.

• [0–100]: successful.

• Other values: error codes.

Sets the local playback volume for accompaniment.

public abstract int setAudioAccompanyPlayoutVolume(int volume) ;

Parameters

Return description

• 0: successful.

• Non-zero: failed. Returns error code.

Retrieves the local playback volume for accompaniment music.

public abstract int getAudioAccompanyPlayoutVolume() ;

Return Description

The local playback volume for accompaniment music.

• [0-100]: Success.

• Other values indicate error codes.

Pauses music accompaniment mixing.

public abstract int pauseAudioAccompany();

Return description

• 0: successful.

• Non-zero: failed. Returns error code.

Resumes mixing of the music accompaniment.

public abstract int resumeAudioAccompany();

Return Description

• 0: successful.

• A non-zero value: failed. Returns an error code.

Queries the accompaniment file duration in milliseconds.

public abstract int getAudioAccompanyDuration();

This method queries the duration of the current accompaniment file.

Return value

• >= 0: A value greater than or equal to 0 indicates the accompaniment file duration.

• < 0: The operation failed. Returns an error code.

Retrieves the accompaniment file's playback progress.

public abstract int getAudioAccompanyCurrentPosition();

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

Return Description

• >=0: The accompaniment file's playback progress.

• <0: The operation 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 file, which is useful for features such as seek bars. After a successful call, playback starts from the specified position.

Parameters

Return Description

• 0: The call was successful.

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

Preloads a sound effect.

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

Parameters

Return Description

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

Unloads a preloaded sound effect.

public abstract int unloadAudioEffect(int soundId);

Parameters

Return description

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

Plays a sound effect.

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

Parameters

Return Description

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

Stops the playback of a sound effect.

public abstract int stopAudioEffect(int soundId);

Parameters

Return value

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

Stops the playback of all sound effects.

public abstract int stopAllAudioEffects();

Return Description

0 is returned on success. Other values indicate failure.

Sets the volume for mixing sound effects into stream ingest.

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

Parameters

Return Description

0 indicates success. Other values indicate failure.

Retrieves the volume level used to mix sound effects into the stream ingest.

public abstract int getAudioEffectPublishVolume(int soundId);

Parameters

Return value

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

Sets the local playback volume for a sound effect.

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

Parameters

Return Description

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

Retrieves the local playback volume of a sound effect.

public abstract int getAudioEffectPlayoutVolume(int soundId);

Parameters

Return description

Returns 0 on success. Other values indicate failure.

Set the audio mixing volume for all sound effects during stream ingest.

public abstract int setAllAudioEffectsPublishVolume(int volume);

Parameters

Return Description

0 indicates success. Other values indicate failure.

Sets the local playback volume for all sound effects.

public abstract int setAllAudioEffectsPlayoutVolume(int volume);

Parameters

Return Description

A return value of 0 indicates success. 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

TRUE indicates success. Other values indicate failure.

Stops the media file recording.

  public abstract void stopRecord();

Parameters

None.

You can pause the sound effect.

public abstract int pauseAudioEffect(int soundId);

Parameters

Return Description

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

This method pauses all sound effects.

public abstract int pauseAllAudioEffects();

Return Description

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

You can restart the sound effect playback.

public abstract int resumeAudioEffect(int soundId);

Parameters

Return Instructions

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

Resumes playback of all sound effects.

public abstract int resumeAllAudioEffects();

Return description

0 indicates success. Other values indicate failure.

Creates a SurfaceView rendering view.

public abstract SophonSurfaceView createRenderSurfaceView(Context context);

To display a video view, call this method instead of directly creating a SurfaceView. Follow these steps:

• Assign the return value to AliRtcVideoCanvas#view.

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

When to call

You can call this before or after joining a channel.

Limitations

You can call this method in 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 display window (view) for the local video stream and configuring the rendering mode, mirroring mode, and rotation angle. This setting affects only the local user’s preview and does not affect the published video stream. To set the remote user interface view, you can call setRemoteViewConfig.

When to call

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

Parameters

Return Description

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

Configures the rendering window and drawing parameters for a remote user's video stream.

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

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

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

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

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

When to call

You can call this method after you receive the onRemoteTrackAvailableNotify callback—that is, when the remote user's video stream becomes available.

Parameters

Return description

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

You can use this method to configure camera capture preferences, such as camera direction and frame rate.

public abstract int setCameraCapturerConfiguration(AliEngineCameraCapturerConfiguration cameraCapturerConfiguration);

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

When to call

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

• startPreview (Start preview)

• joinChannel (to join a channel)

Parameters

Return description

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

Disables or enables local video capture.

public abstract int enableLocalVideo(boolean enable);

This method controls local video capture. When disabled, the local preview and stream ingest will not have video data, but receiving remote video is not affected. If you use this method to disable local camera capture, the video freezes on the last captured frame for both the local preview and for remote viewers.

When to call

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

Related callbacks

After a successful call to this method, the onUserVideoEnabled callback is triggered for remote users.

Parameters

Return value

0 indicates success. Any other value indicates failure.

You can stop or resume sending local video data.

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

When ingesting a stream, you can call this method to send black video frames without affecting the local preview or interrupting the capture, encoding, and sending modules.

Parameters

Return description

A value of 0 indicates success.

Determines whether the camera is enabled.

public abstract boolean isCameraOn();

Return value

true: The camera is enabled. false: The camera is disabled.

Sets the video encoding properties.

public abstract void setVideoEncoderConfiguration(AliRtcVideoEncoderConfiguration config);

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

When to call

You can call this method before or after you join 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 you join the channel.

Limitations

Both the mirrorMode parameter in this method and the setVideoMirrorMode method set video stream mirroring. We recommend that you use only one of these methods. Using both can cause the mirroring effects to overlap, which may result in failed or incorrect mirroring.

Parameters

Sets the video decoding properties.

    public abstract void setVideoDecoderConfiguration(AliRtcVideoDecoderConfiguration config);

This method configures video parameters for decoding a video stream.

When to call

You can call this method before joining a channel.

Parameters

Switches between the front and rear cameras. By default, the front camera is used.

public abstract int switchCamera();

You can call this method to dynamically switch cameras during runtime without restarting the video stream or reconfiguring the video source.

When to call

Call this method only after the camera is successfully enabled.

Limitations

This method is available only on Android and iOS platforms.

Return Description

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

Retrieves the current camera direction.

public abstract AliRTCCameraDirection getCurrentCameraDirection();

Return value

• CAMERA_REAR (0) indicates the rear camera.

• CAMERA_FRONT (1) indicates the front camera.

• CAMERA_INVALID (-1) indicates an invalid state.

Start the local preview.

public abstract int startPreview();

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

When to Call

• You must call `setLocalViewConfig` to set the view for the local preview before you start a call. Otherwise, the preview will fail, but stream ingest will be unaffected.

• You can call this method to start the preview before you call `joinChannel`. The camera turns on automatically.

Return description

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

Stops the local video preview and turns off the camera.

public abstract int stopPreview();

After you stop the preview, the local display remains on the last frame. Stream ingest is unaffected.

When to call

You can call this method to stop the preview after it has started.

Return value

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

Sets the camera’s zoom factor.

public abstract int setCameraZoom(float zoom);

This method sets the camera’s zoom factor.

Limitations

This method is supported only on iOS and Android.

When to call

You can set the zoom factor only after enabling the camera. The zoom factor resets each time the camera restarts.

Parameters

Returns

• 0: The call succeeded.

• A non-zero value: The call failed.

Queries the maximum supported camera zoom (digital zoom) factor.

public abstract float GetCameraMaxZoomFactor();

Return Instructions

The maximum zoom factor supported by the device camera.

Retrieves the current camera zoom factor.

public abstract float GetCurrentZoom();

Return description

The current camera zoom factor.

Set the exposure level of the camera.

public abstract int SetExposure(float exposure);

An excessively dark or bright shooting environment can affect the quality of the captured video. To achieve better video effects, you can use this method to adjust the camera's exposure level. You can query the supported exposure range using getMinExposure and getMaxExposure.

Parameters

Return value

• 0: Success.

• Non-zero: Failure.

Queries the exposure level of the currently active camera.

public abstract float GetCurrentExposure();

Queries the exposure level of the currently active (camera).

Return description

The current camera exposure level.

Retrieves the minimum supported camera exposure level.

public abstract float GetMinExposure();

Return Description

The minimum camera exposure level.

Returns the maximum supported camera exposure level.

public abstract float GetMaxExposure();

Return Description

The maximum camera exposure level.

Turns the camera flash on or off.

public abstract int setCameraFlash(boolean flash);

You can turn the flash on or off.

Limitations

This method is available only on iOS and Android.

Parameters

Return description

• 0: successful.

• Non-zero: failed.

Determines whether the current device supports manual focus.

public abstract boolean isCameraFocusPointSupported();

Determines whether the current camera can set a focus point to support manual focus.

Limitations

This method is supported only on iOS and Android.

Return Description

• true: The device supports manual focus.

• false: The device does not support manual focus.

Determines whether the device supports setting a camera exposure point.

public abstract boolean isCameraExposurePointSupported();

This method determines whether the current device supports setting a camera exposure point.

Limitations

This method is supported only on iOS and Android.

Return description

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

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

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 method, the camera performs a single exposure adjustment to the specified point and maintains that focus value. Before you call this method, check whether the device supports manual focus using isCameraFocusPointSupported.

Limitations

This method is only available on iOS and Android.

Parameters

Return description

• 0: Success.

• Non-zero: Failure.

Sets the camera exposure point.

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

After you call this method, the camera performs a single exposure adjustment to the specified point and maintains that exposure value. Before you call this method, we recommend that you use isCameraExposurePointSupported to check if the device supports setting the exposure point.

Limitations

This method is available only on iOS and Android.

Parameters

Return Description

• 0: The call was successful.

• Non-zero: The call failed.

Checks whether 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. If this method is called before the camera is enabled, it returns false by default. The method returns true if the camera is enabled and supports automatic face focus.

Limitations

This method is available only on iOS and Android.

Return Description

• true: The camera supports automatic face focus.

• false: The camera does not support automatic face focus.

Set the face focus for the camera.

public abstract boolean setCameraAutoFocusFaceModeEnabled(boolean enable);

This method enables or disables real-time face detection for camera focus. Before you call this method, verify device support using isCameraAutoFocusFaceModeSupported.

Limitations

This method is available only on iOS and Android.

Parameters

Return Description

• true: The call succeeds.

• false: The call failed.

You can configure the preview and stream ingest video mirroring capability.

public abstract int setVideoMirrorMode(AliRtcVideoPipelineMirrorMode mirrorMode);

Enables or disables mirroring for the local video preview and published video streams.

When to call

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

Limitations

This method overlaps with the mirrorMode settings in setLocalViewConfig and setVideoEncoderConfiguration. You can use only one of these methods.

Parameter description

Return Description

• 0 indicates success.

• <0: setting failed.

  • ERR_INNER (–1): An internal SDK state error occurred. Verify that the SDK instance was created successfully.

Sets the timing for video capture scaling.

public abstract void setCapturePipelineScaleMode(AliRtcCapturePipelineScaleMode mode);

Determines whether video capture scaling occurs during capture or during encoding. For example, when the capture resolution differs from the encoding resolution, you can set the scaling timing to ensure that preview data matches published data.

When to call

You can set this before opening the camera—for example, before calling startPreview or joinChannel.

Parameters

Return description

None.

You can enable an external video input source.

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

Parameters

Enter the video data.

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

Parameters

Return value

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

Starts relayed live streaming.

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

Parameters

Return Instructions

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

Updates the parameters for a relayed live stream.

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

Parameters

Return description

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

Stops the relayed live stream.

public abstract int stopPublishLiveStream(String streamUrl);

Parameters

Return description

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

You can use this method to query the status of relayed live streaming.

public abstract AliRtcEngine.AliRtcLiveTranscodingState getPublishLiveStreamState(String streamUrl);

Parameters

Return Description

This method returns the status of relayed live streaming.

Starts network quality testing.

public abstract int startNetworkQualityProbeTest(AlirtcNetworkQualityProbeConfig config);

Parameters

Return description

0 indicates success. Other values indicate failure.

Stops the network quality test.

public abstract int stopNetworkQualityProbeTest();

Return description

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

Send media extension information.

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

The SDK enables you to send and receive media extension messages. This method sends media extension messages using the SEI extension protocol. Receivers can retrieve messages by listening to onMediaExtensionMsgReceived.

Common use cases include the following:

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

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

When to call

You can call this after starting stream ingest.

Limitations

Media extension messages share the audio and video data channel. Therefore, you must control the sending frequency and data length of custom messages. The limitations are as follows:

• You can send a maximum of fps messages per second, as configured in the profile. This is because SEI information is transmitted within H.264/H.265 streams, and extension information can only be attached when video frames are encoded.

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

• The repeatCount parameter in sendMediaExtensionMsg specifies message redundancy. If its value is greater than 1, the message is sent multiple times.

• This prevents message loss due to packet loss. Other participants in the room will receive duplicate messages, which require deduplication.

• Subscribers in relayed live streaming also receive custom messages.

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

Related callbacks

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

Parameters

Return description

• 0: Success.

• <0: The call failed, returning an error code.

  • ERR_INNER(-1): SDK internal error. Possible causes: The SDK was not initialized, or it was called after it was destroyed.

Send media extension information.

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

The SDK provides functions for sending and receiving media extension messages. This method sends media extension messages using the SEI extension protocol. Receivers can obtain messages by listening to onMediaExtensionMsgReceived. If the payloadType is 5, it is equivalent to using the sendMediaExtensionMsg method.

Common use cases include the following:

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

• You can use media extension messages to transmit descriptive information. The data size is limited to 4 KB, which is suitable for small payloads. We recommend using JSON or plain strings.

When to call

You can call this after starting stream ingest.

Limitations

Because media extension messages use the audio/video data channel, you must control the sending frequency and data length of custom messages. The limitations are as follows:

• You can send a maximum of fps messages per second, as specified in the profile, because SEI information is transmitted within H.264 or H.265 streams and extension information can be attached only when video frames are encoded.

• To avoid affecting media data transmission quality, the custom message body length is limited to 4 KB, which is suitable for transmitting small amounts of information.

• The repeatCount parameter in sendMediaExtensionMsg specifies message redundancy. If this parameter is greater than 1, the message is sent multiple times.

• This prevents message loss due to packet loss. Other participants in the room receive duplicate messages and must perform deduplication.

• Subscribers in relayed live streaming also receive custom messages.

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

Return value

Return description

• 0: The operation was successful.

• <0: The call failed, returning an error code.

  • ERR_INNER(-1): An internal SDK error. This error occurs when the SDK is called before initialization or after destruction.

This callback is invoked when the network connection status changes.

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

Parameters

An abnormal callback is received from an on-premises device. You need to handle this callback.

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

Parameter description

This callback is triggered when user authentication is about to expire. Authentication expires 30 seconds after you receive this callback. Monitor this callback closely.

public void onAuthInfoWillExpire();

This callback indicates that user authentication information is about to expire. Authentication expires 30 seconds after you receive this callback. You can obtain a new token and update the authentication information using one of the following methods:

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

The SDK triggers this callback 30 seconds before user authentication information expires. You must update the authentication information promptly after receiving this callback.

When a user calls an API that requires authentication, the server-side returns an "information expired" message.

public void onAuthInfoExpired();

To continue the session, generate a new token on the server and update the authentication information using the following method:

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

Trigger timing

This callback is triggered when user authentication information expires.

This callback returns the result of joining a channel.

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

Parameters

This callback is invoked to return the result of leaving a channel.

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

Trigger conditions

This callback is triggered when the application successfully invokes <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, providing the result and the performance statistics for the current channel session.

Parameters

Callback for remote user offline events.

public void onRemoteUserOffLineNotify(String uid, AliRtcUserOfflineReason reason);

This callback is triggered when a remote user goes offline, indicating that the user has left the channel.

Trigger Conditions

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

• The callback is triggered when a remote streamer switches to the viewer role by calling <a baseurl="t2309760_v6_0_0.xdita" data-node="4086566" data-root="16090" data-tag="xref" href="#84f350f904s98" id="4c0adbe948tif">setClientRole</a> with the role set to AliRTCSdkLive.

• If the remote streamer sends no data for an extended period and is considered offline, the callback is triggered.

Parameters

Triggered when a remote user goes online.

public void onRemoteUserOnLineNotify(String uid, int elapsed);

This interface notifies the local client when a remote user joins the channel.

Trigger Conditions

• The remote user joined the channel successfully.

• When the current user joins a channel, they receive join callbacks for users who are already in the channel. You can use these callbacks to display the users who joined previously.

Parameters

A callback is triggered when a remote user’s audio or video stream changes.

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

This callback is triggered when a remote user’s stream ingest status changes. It enables developers to determine in real time whether a remote user is publishing audio or video streams and to display or hide the remote user’s audio or video information accordingly.

Trigger Condition

This callback is triggered in the following scenarios: