RTCEngine is the core entry point of the Android SRTC SDK. It handles the SDK lifecycle, joining and leaving channels, event listeners, media capture/publishing/subscription, and info queries. For the complete minimal integration flow, see Quickstart.
Static methods
version()
Parameters: None.
Returns:
String, the SDK version.
buildTime()
Parameters: None.
Returns:
String, the build time string.
create(app, enableLocalLog, engineEvent, localLogPath, version)
RTCEngine instance.Parameters:
app:Application, the application context.enableLocalLog:Boolean, whether to enable local log storage.engineEvent:RTCEngineEvent, an error listener that shares the Engine lifecycle; see RTCEngineEvent.localLogPath:String?, the log directory; the default path is used whennull.version:String, the version identifier of your app (useful for logs/troubleshooting).
RTCEngine, the engine instance.
Lifecycle
initSDK()
Parameters: None.
Returns: None (
Unit).
releaseSDK()
Parameters: None.
Returns: None (
Unit).
IM
enableIm(token, resultListener)
Parameters:
token:String, the IM/channel authentication token.resultListener:RTCResultListener?, the enable result callback; can benull.
Unit).
disableIm()
Parameters: None.
Returns: None (
Unit).
Transcription
startAsr()
Parameters: None.
Returns: None (
Unit).
stopAsr()
Parameters: None.
Returns: None (
Unit).
isStartAsr()
Parameters: None.
Returns:
Boolean, true if it’s on.
Channels
join(activity, token, clientEvent, options)
RTCEngine delegate to it; subsequent channels use their own returned RTCChannel.
Parameters:
activity:Activity, the current screen context.token:String, the token containing the information required to join.clientEvent:RTCClientEvent, the initial channel control listener for this channel; the join result is returned throughonJoinSucceed/onJoinFailed.options:JoinOptions?, auto-subscribe configuration; you can setautoSubscribeAudioandautoSubscribeVideo.
RTCChannel?. A non-null value only means the SDK accepted the request and created a session, not that the join succeeded; if the request is rejected before creation, it returns null, and the failure reason is still returned through this call’s clientEvent.onJoinFailed(...). If the SDK isn’t initialized or has been released, it synchronously throws SdkNotInitializedException.
Joining the same channel twice returnsnulland calls back a failure withRtcChannelErrorCode.CHANNEL_ALREADY_EXISTS(102208); the existing channel and listener stay unchanged. For the full multi-channel flow, see Multi-channel.
leave()
RTCChannel.leave().
Parameters: None.Returns: None (
Unit).
resume()
Parameters: None.
Returns: None (
Unit).
isAudience()
is_audience in your own user info cached by the SDK; it returns false when you haven’t joined.Parameters: None.
Returns:
Boolean, true if you’re currently an audience user.
Read the initial role after joining with this method; when the role changes during the call, you’re notified by RTCClientEvent.onMeMembershipChanged.
Listener setup
setRtcImEvent(e)
Parameters:
e:RTCImEvent, the IM callback implementation. See RTCImEvent.
Unit).
setRtcMediaEvent(e)
RTCChannel.setRtcMediaEvent(...).
Parameters:
e:RTCMediaEvent, the media callback implementation. See RTCMediaEvent.
Unit).
setRtcCameraDeviceEvent(e)
null to unbind. Camera capture is shared by all channels, so events don’t carry a channel ID and aren’t duplicated across multiple channels. See RTCCameraDeviceEvent.
setRtcLocalVideoFrameEvent(e)
null to remove the callback.Parameters:
e:RTCLocalVideoFrameEvent?, the local video frame callback implementation;nullremoves it.
Unit).
RTCLocalVideoFrameEvent interface methods:
onLocalVideoFrame: called back with one local video frame.yuvis data the SDK copies separately for your app, so you can cache or process it yourself;stampis the frame timestamp;formatis the frame format;facingis the camera facing.onLocalVideoFrameSizeChanged: called back when the local video frame size or camera direction changes.
setRtcLocalScreenFrameEvent(e)
null to remove the callback.
Parameters:
e:RTCLocalScreenFrameEvent?, the local screen frame callback implementation;nullremoves it.
Unit).
RTCLocalScreenFrameEvent interface methods:
yuv: tightly packed I420 data in Y, U, V order. The SDK has already created an independent copy, so your app can still cache it or process it asynchronously after the callback returns.width/height: the width and height of the frame actually dispatched.stamp: a nanosecond timestamp based on a monotonic clock.format: the video format, currently alwayscn.seastart.rtc.media.format.YuvFormat.I420.rotation: clockwise rotation angle:0,90,180, or270.
setRtcLocalAudioFrameEvent(e)
null to unbind. Registering the listener doesn’t open the microphone automatically; you must call LocalMicTrack.startCapture(...). See RTCLocalAudioFrameEvent.
setRtcMicDeviceEvent(e)
null to unbind. See RTCMicDeviceEvent.
Media quality
getMetric()
qualityReport). Returns a thread-safe copy and doesn’t trigger the underlying getStats; the sampling period is about 5 seconds, so it may be null right after media starts. For additional channels, use RTCChannel.getMetric(); for poor-network level changes, prefer listening to RTCMediaEvent.onNetworkQualityChanged.
Parameters: None.Returns:
MediaMetric.Metric?, the most recent quality snapshot; null when there’s no data yet. For fields, see Media quality; for how to get it and handle poor networks, see Network quality.
Audio routing
getAudioRouterManager()
Parameters: None.
Returns:
AudioRouterManager, the routing manager instance. See AudioRouterManager and Audio routing.
releaseAudioRouterManager()
release(true), restoring the system audio mode and switching back to the speaker).Parameters: None.
Returns: None (
Unit).
Device capabilities
getCameraDevices()
cameraId in the returned list can be used with LocalCameraTrack.switchCameraDevice to switch cameras exactly.Parameters: None.
Returns:
List<CameraDeviceCapability>; an empty list when no device is available. For the type definition, see Types.
Dynamic changes to camera devices are notified through RTCCameraDeviceEvent.
getMicDevices()
switchMicDevice(deviceId)
deviceId comes from getMicDevices() and is valid only while that device stays connected; switching during capture rebuilds the recording pipeline. You can also use the method of the same name on LocalMicTrack.
Virtual background
Performs local person segmentation on camera capture, supporting background blur and background image replacement. The local preview matches what remote users see. Call order:installVirtualBackground → setVirtualBackgroundBlur or setVirtualBackgroundImage → enabledVirtualBackground(true); call uninstallVirtualBackground when no longer needed.
installVirtualBackground(modelData)
Parameters:
modelData is the content of the selfie_segmenter onnx model, read from assets by your app and passed in.Returns: An error code;
0 means success. If the model is empty or invalid, it returns VIRTUAL_BACKGROUND_MODEL_INVALID; see Error codes.
uninstallVirtualBackground()
enabledVirtualBackground(enabled)
Parameters:
enabled is true to turn it on, false to turn it off.Returns: An error code;
0 means success. If the module isn’t installed, it returns VIRTUAL_BACKGROUND_NOT_INSTALL.
setVirtualBackgroundBlur(level)
setVirtualBackgroundImage; whichever is called last takes effect.Parameters:
level is in the range 1–10; default 5.
setVirtualBackgroundImage(image)
setVirtualBackgroundBlur; whichever is called last takes effect.Parameters:
image is the background image; pass null to cancel the replacement.
setVirtualBackgroundInferenceInterval(interval)
interval frames; default 1. Used to reduce overhead on low-end devices. We recommend that your app set it per device model rather than exposing it to end users.Parameters:
interval is at least 1.
setVirtualBackgroundMaskSync(on)
false. Used to eliminate misaligned trailing artifacts when waving quickly; it only makes a difference when the inference interval is greater than 1.
isVirtualBackgroundEnabled()
Getting tracks
getLocalCameraTrack(preOpt)
Parameters:
preOpt:PreOptionCamera, the camera capture/publishing preset; default_480P. See Camera preset. The track copiespreOpt.capture, so changingcaptureon the original object after getting the track has no effect—reassigntrack.preOptinstead; changes topreOpt.publishstill take effect. SeeLocalCameraTrack.
LocalCameraTrack, the local camera track instance.
getLocalScreenTrack(activity, preOpt)
Parameters:
activity:Activity, used to request the screen recording permission.preOpt:PreOptionScreen, the screen capture/publishing preset. See Screen sharing preset.
LocalScreenTrack, the local screen track instance.
getLocalMicTrack(preOpt)
Parameters:
preOpt:PreOptionMic, the microphone capture/publishing preset. See Microphone preset.
LocalMicTrack, the local microphone track instance. Getting the track doesn’t open the microphone automatically; you must call LocalMicTrack.startCapture(...) before publishing.
getLocalCustomVideoTrack(preOpt)
preOpt passed in.Parameters:
preOpt:PreOptionCustomVideo, the custom video capture/publishing preset; defaultPreOptionCustomVideo.def(track descriptioncustom). To publish with the screen sharing description, usePreOptionCustomVideo.screen. See Custom video preset.
LocalCustomVideoTrack, the local custom video track instance. See LocalCustomVideoTrack.
For the full integration flow, see Custom tracks.
getRemoteVideoTrack(uid, trackDesc)
Parameters:
uid:String, the remote user ID.trackDesc:String, the track description (such ascamera_big/screen).
RemoteVideoTrack?; null if not found.
getRemoteMixtureTrack()
Parameters: None.
Returns:
RemoteVideoTrack?; null if not found.
getRemoteAudioMixTrack()
Parameters: None.
Returns:
RemoteAudioMixTrack?; null if not found. See RemoteAudioMixTrack.
Publishing and subscription
publishLocalVideo(track, publishCustomOpt, listener)
Parameters:
track:LocalVideoTrack, the local video track (cameraLocalCameraTrack/ screen recordingLocalScreenTrack/ local customLocalCustomVideoTrack). Passing any other type returnsRtcChannelErrorCode.TRACK_TYPE_INVALID(102002; see Error codes) throughlistener.onFail.publishCustomOpt:PublishCustomOptions?, custom publishing parameters; can benull. See Camera preset.listener:RTCResultListener?, the publishing result callback; can benull.
Unit).
Note: camera publishing uses declarative reconciliation. When youpublish/unpublishin rapid succession, intermediate calls merged into later operations may not call back; rely on the callback of the last call or the final state, and don’t assume “every call gets exactly one callback”.
publishLocalAudio(track, publishCustomOpt, listener)
LocalMicTrack.startCapture(...) first.
Parameters:
track:LocalAudioTrack, the local audio track.publishCustomOpt:PublishCustomOptions?, custom publishing parameters; can benull.listener:RTCResultListener?, the publishing result callback; can benull.
Unit).
unPublishLocalVideo(track, listener)
Parameters:
track:LocalVideoTrack, the target video track.listener:RTCResultListener?, the unpublish result callback; can benull.
Unit).
Note: as with publishLocalVideo, intermediate calls merged during rapid successive operations may not call back; rely on the last one.
unPublishLocalAudio(track, listener)
LocalMicTrack.stopCapture().
Parameters:
track:LocalAudioTrack, the target audio track.listener:RTCResultListener?, the unpublish result callback; can benull.
Unit).
subscribeRemoteTrack(uid, trackId, preferTrackIds, result)
Parameters:
uid:String, the remote user ID.trackId:String, the target (default) remote track ID.preferTrackIds:MutableList<String>?, the candidate layer list, used in simulcast scenarios to declare the priority of acceptable tracks. Whennull, onlytrackIdis subscribed; if the list doesn’t containtrackId, the SDK automatically inserts it at the front.result:RTCResultListener?, the subscription result callback; can benull.
Unit).
unSubscribeRemoteTrack(uid, trackId)
Parameters:
uid:String, the remote user ID.trackId:String, the remote track ID.
Unit).
subscribeRemoteMixture()
Parameters: None.
Returns: None (
Unit).
unSubscribeRemoteMixture()
Parameters: None.
Returns: None (
Unit).
Wangsu generic streams (advanced / engine-specific)
⚠️ Wangsu engine only: the following APIs work only with the Wangsu media streaming engine. They subscribe to a “generic stream” by a stream name your app provides directly, an advanced capability for specific integration scenarios. With a non-Wangsu engine:getRemoteStreamTrackreturnsnull,subscribeRemoteStreamreturns a not-supported error throughresult.onFail, andunSubscribeRemoteStreamis ignored. Most integrations don’t need these APIs.
getRemoteStreamTrack(uid, trackDesc)
addPlayView). It doesn’t depend on channel users and is obtained by the (uid, trackDesc) passed when subscribing. You can call it before subscribeRemoteStream—get the controller and call addPlayView first, then subscribe, and the video renders as soon as it arrives.Parameters:
uid:String, the render routing identifier (defined by your app; can be the same as the stream name).trackDesc:String, the special stream identifier, used for render binding and to distinguish multiple generic streams.
RemoteVideoTrack?; null for a non-Wangsu engine or when the channel hasn’t started.
subscribeRemoteStream(streamName, uid, trackDesc, kind, result)
"rtc_v_lesson_fknqb").Parameters:
streamName:String, the full stream name, used directly in Wangsu HTTP requests.uid:String, the render routing identifier (defined by your app; can be the same asstreamName).trackDesc:String, the special stream identifier, used for render binding and to distinguish multiple generic streams.kind:String?, optional,"video"/"audio"; when empty, inferred from the stream name prefix (rtc_v→ video,rtc_a→ audio).result:RTCResultListener?, the subscription result callback; can benull.
Unit).
unSubscribeRemoteStream(streamName, uid, trackDesc, kind)
Parameters:
streamName:String, the full stream name passed when subscribing.uid:String, the render routing identifier passed when subscribing.trackDesc:String, the special stream identifier passed when subscribing.kind:String?, optional,"video"/"audio"; when empty, inferred from the stream name prefix.
Unit).
Info queries
getChannelInfo()
Parameters: None.
Returns:
ChannelInfo?; may be null when not joined or there’s no data. See Types.
getMeInfo()
Parameters: None.
Returns:
UserInfo?; may be null when not joined or there’s no data.
getUserInfos()
Parameters: None.
Returns:
MutableList<UserInfo>, the user list.
getUserInfo(uid)
Parameters:
uid:String, the target user ID.
UserInfo?; null if not found.
getTrackInfos(uid)
Parameters:
uid:String, the target user ID.
List<TrackInfo>, the track info list.
getTrackInfoByTrackDesc(uid, trackDesc)
Parameters:
uid:String, the target user ID.trackDesc:String, the track description.
TrackInfo?; null if not found.
getTrackInfoByTrackId(uid, trackId)
Parameters:
uid:String, the target user ID.trackId:String, the track ID.
TrackInfo?; null if not found.
Common result callback types
Most asynchronous APIs return their results throughRTCResultListener.
RTCResultListener
onSuccess(): the call succeeded.onFail(int code): the call failed;codeis the error code. See Error codes.
RTCValueResultListener<T>
onSuccess(t): the call succeeded and returned the result objectt.onFail(code): the call failed;codeis the error code.
RTCResultListener2<T> has been renamed to RTCValueResultListener<T>; apart from the type name, the method signatures are unchanged.