Skip to main content
SDK Introduction

Android SDK

AOQ Android SDK API reference

Complete Java API reference for the AOQ Client SDK on Android, covering engine lifecycle, audio/video capture and playback, codec configuration, real-time messaging, and frame callbacks.

API index

Engine lifecycle

APIDescription
createEngineCreate the engine instance (singleton)
destroyDestroy the engine instance
getVersionGet the SDK version string
connectConnect to the Relay server
disconnectDisconnect from the server

Audio device management

APIDescription
startAudioCaptureOpen the audio capture device (microphone)
stopAudioCaptureClose the audio capture device
muteAudioCaptureMute or unmute audio capture
startAudioPlayerStart audio playback (play remote audio)
stopAudioPlayerStop audio playback
pauseAudioPlayerPause audio playback with optional fade-out
resumeAudioPlayerResume audio playback with optional fade-in
interruptAudioPlayerInterrupt the current audio call turn
enableSpeakerphoneSwitch audio output between speaker and earpiece
isSpeakerphoneEnabledQuery whether the speaker is currently active
enableLocalAudioVolumeIndicationConfigure local capture volume indication

Audio codec configuration

APIDescription
setAudioEncoderConfigSet audio encoding parameters
setAudioDecoderConfigSet audio decoding parameters

Video device management

APIDescription
startVideoCaptureOpen the video capture device (camera)
stopVideoCaptureClose the video capture device
switchCameraSwitch between front and rear cameras
setLocalViewSet or remove the local video rendering view
setRemoteViewSet or remove the remote video rendering view
startScreenCaptureStart screen capture
stopScreenCaptureStop screen capture

Video encoding and external input

APIDescription
setVideoEncoderConfigSet video encoding parameters
pushExternalVideoCapturedFramePush an externally captured raw video frame
pushExternalVideoEncodedFramePush an externally encoded video frame
setVideoDecoderConfigSet video decoding parameters

Media stream control / real-time messaging

APIDescription
enableSendMediaStreamEnable or disable local media stream sending
sendDataMsgSend a real-time data message

Audio file playback

APIDescription
startAudioFileStart streaming a local audio file
stopAudioFileStop audio file playback
pauseAudioFilePause audio file playback
resumeAudioFileResume audio file playback
getAudioFileDurationGet the total duration of the audio file
getAudioFileCurrentPositionGet the current playback position
setAudioFilePositionMillisSeek to a position in the audio file
setAudioFileVolumeSet the audio file volume
getAudioFileVolumeGet the current audio file volume

External audio streams

APIDescription
addAudioExternalStreamAdd an external audio stream
removeAudioExternalStreamRemove an external audio stream
pushAudioExternalStreamDataPush external PCM audio data
setAudioExternalStreamVolumeSet the volume for an external audio stream
getAudioExternalStreamVolumeGet the volume for an external audio stream
clearAudioExternalStreamBufferClear the buffer for an external audio stream

Audio/video frame callbacks

APIDescription
setAudioFrameObserverSet the audio frame data callback listener
enableAudioFrameObserverEnable or disable audio frame callbacks at a specified point
setVideoFrameObserverSet the video frame data callback listener
enableVideoFrameObserverEnable or disable video frame callbacks at a specified point

AoqClientListener callbacks

CallbackDescription
onErrorEngine error callback
onWarningEngine warning callback
onConnectionStatusChangeConnection state change callback
onStatsEngine statistics callback
onAudioDeviceStateChangedAudio device state change callback
onAudioDeviceRouteChangedAudio output route change callback
onAudioDeviceInterruptedAudio device interruption callback
onVideoDeviceStateChangedVideo device state change callback
onAudioDeviceFocusChangedAudio focus change callback
onAudioFileStateAudio file playback state callback
onDataMsgReal-time data message received callback
onLocalAudioVolumeIndicationLocal capture volume callback
onScreenCaptureStateChangedScreen capture state callback

API details

External video input requirements

pushExternalVideoCapturedFrame supports Video and Screen. Enable external capture on the corresponding track first; otherwise, it returns AoqECVideoExternalCaptureNotEnabled (211).

Screen capture

public abstract int startScreenCapture(@NonNull AoqScreenCaptureConfig config)
public abstract int stopScreenCapture()
trackType supports AoqTrackTypeAudio, AoqTrackTypeVideo, and AoqTrackTypeScreen. config specifies screen capture settings. Screen content is sent on the AoqTrackTypeScreen track. For start, 0 means that the request is accepted; onScreenCaptureStateChanged reports the result asynchronously. A nonzero return rejects the request synchronously. Stop returns 0 on success or a nonzero value on failure, and reports the stopped state through this callback. With isExternal=false, the SDK captures through MediaProjection. Starting capture again while it is active returns AoqECStateInvalid; stopping is idempotent. For external raw frames, set isExternal=true and supply raw Screen frames through pushExternalVideoCapturedFrame for SDK encoding. For external encoded frames, configure the Screen track for external encoding with setVideoEncoderConfig, then call pushExternalVideoEncodedFrame; startScreenCapture is not required.

onScreenCaptureStateChanged

public void onScreenCaptureStateChanged(@NonNull AoqScreenCaptureState state) {}
state contains the screen capture state. Started means capture or external input is ready, not that media has been sent. Screen capture failures are not also reported through onError. Fail and Stopped are terminal states emitted after cleanup.

setVideoDecoderConfig

public abstract int setVideoDecoderConfig(@NonNull AoqVideoCodecConfig config)
config specifies video decoding settings. Only the following fields take effect: trackType, codecType, width, height, fps, bitrate. Other fields apply only to encoding. Screen does not support downstream decoding. If config.trackType is Screen, the method returns AoqECUnSupport without applying the configuration. Returns 0 on success or a nonzero value on failure.

enableLocalAudioVolumeIndication

public abstract int enableLocalAudioVolumeIndication(@NonNull AoqAudioVolumeIndicationConfig config)
config specifies volume indication settings. Callbacks are emitted at config.interval. Call this method after startAudioCapture. Returns 0 on success or a nonzero value on failure.
public void onLocalAudioVolumeIndication(@NonNull AoqAudioVolume volume) {}
The volume callback argument contains the local capture volume.

Engine lifecycle

createEngine Create the engine instance. The SDK holds the engine as a global singleton; calling this method again returns the existing instance.
@NonNull
public static AoqClientEngine createEngine(
    @NonNull Context context,
    @NonNull AoqCreateConfig config,
    @NonNull AoqClientListener listener)
ParameterTypeDescription
contextContextAndroid application context
configAoqCreateConfigEngine creation configuration
listenerAoqClientListenerEngine event callback listener
Returns: AoqClientEngine instance; never null. destroy Destroy the engine instance and release all resources.
public static int destroy()
Returns: 0 on success; non-zero on failure. getVersion
@NonNull
public static String getVersion()
Returns: Version string, for example "1.0.0". connect Connect to the Relay server. Connection parameters are allocated by the application server via /api/v1/allocate and delivered to the client.
public abstract int connect(@NonNull AoqConnectConfig config)
Returns: 0 if the call was dispatched (asynchronous); non-zero if parameter validation failed. disconnect
public abstract int disconnect()
Returns: 0 if the call was dispatched (asynchronous); non-zero on failure.

Audio device management

public abstract int startAudioCapture(@NonNull AoqAudioCaptureConfig config)
public abstract int stopAudioCapture()
public abstract int muteAudioCapture(boolean mute)
public abstract int startAudioPlayer(@NonNull AoqAudioPlaybackConfig config)
public abstract int stopAudioPlayer()
public abstract int pauseAudioPlayer(int fadeMs)
public abstract int resumeAudioPlayer(int fadeMs)
public abstract int interruptAudioPlayer(@NonNull AoqTrackType trackType, int fadeMs)
public abstract int enableSpeakerphone(boolean enable)
public abstract boolean isSpeakerphoneEnabled()
fadeMs: fade-out/fade-in duration in milliseconds; 0 means immediate.

Audio codec configuration

public abstract int setAudioEncoderConfig(@NonNull AoqAudioCodecConfig config)
public abstract int setAudioDecoderConfig(@NonNull AoqAudioCodecConfig config)

Video device management

public abstract int startVideoCapture(@NonNull AoqVideoCaptureConfig config)
public abstract int stopVideoCapture()
public abstract int switchCamera(@NonNull AoqCameraDirection direction)
public abstract int setLocalView(@NonNull AoqTrackType trackType, @Nullable AoqVideoCanvas canvas)
public abstract int setRemoteView(@NonNull AoqTrackType trackType, @Nullable AoqVideoCanvas canvas)
Pass AoqTrackTypeVideo as the trackType parameter for setLocalView and setRemoteView.

Video encoding and external input

public abstract int setVideoEncoderConfig(@NonNull AoqVideoCodecConfig config)
public abstract int pushExternalVideoCapturedFrame(@NonNull AoqTrackType trackType, @NonNull AoqVideoFrame frame)
public abstract int pushExternalVideoEncodedFrame(@NonNull AoqTrackType trackType, @NonNull AoqVideoEncodedFrame frame)
pushExternalVideoCapturedFrame consumes Video frames after startVideoCapture(isExternal=true) and Screen frames after startScreenCapture(isExternal=true). If the internal buffer is full, the method returns AoqECVideoExternalBufferFull (210).

Media stream control

public abstract int enableSendMediaStream(@NonNull AoqTrackType trackType, boolean enable)
Recommended pattern: call enableSendMediaStream(false) after initialization, then enable once onConnectionStatusChange reports Connected.

Audio file playback

public abstract int startAudioFile(@NonNull String fileId, @NonNull AoqAudioFileMixConfig config)
public abstract int stopAudioFile(@NonNull String fileId)
public abstract int pauseAudioFile(@NonNull String fileId)
public abstract int resumeAudioFile(@NonNull String fileId)
public abstract long getAudioFileDuration(@NonNull String fileId)
public abstract long getAudioFileCurrentPosition(@NonNull String fileId)
public abstract int setAudioFilePositionMillis(@NonNull String fileId, long positionMillis)
public abstract int setAudioFileVolume(@NonNull String fileId, @NonNull AoqAudioStreamDirection type, int volume)
public abstract int getAudioFileVolume(@NonNull String fileId, @NonNull AoqAudioStreamDirection type)

External audio streams

public abstract int addAudioExternalStream(@NonNull String streamId, @NonNull AoqAudioExternalStreamConfig config)
public abstract int removeAudioExternalStream(@NonNull String streamId)
public abstract int pushAudioExternalStreamData(@NonNull String streamId, @NonNull AoqAudioFrameData data)
public abstract int setAudioExternalStreamVolume(@NonNull String streamId, @NonNull AoqAudioStreamDirection type, int volume)
public abstract int getAudioExternalStreamVolume(@NonNull String streamId, @NonNull AoqAudioStreamDirection type)
public abstract void clearAudioExternalStreamBuffer(@NonNull String streamId, int fadeoutMs)
When pushAudioExternalStreamData returns AoqErrorCodeAudioExternalBufferFull (110), the internal buffer is full. Wait 30 ms and retry.

Real-time messaging

public abstract int sendDataMsg(@NonNull AoqDataMsg msg)

Audio frame callbacks

public abstract int setAudioFrameObserver(@Nullable AoqClientListener.AoqAudioFrameListener listener)
public abstract int enableAudioFrameObserver(boolean enabled, @NonNull AoqAudioSource audioSource, @NonNull AoqAudioObserverConfig config)

Video frame callbacks

public abstract int setVideoFrameObserver(@Nullable AoqClientListener.AoqVideoFrameListener listener)
public abstract int enableVideoFrameObserver(boolean enabled, @NonNull AoqVideoSource videoSource, @NonNull AoqVideoObserverConfig config)

AoqClientListener callbacks

AoqClientListener is the unified delivery point for all asynchronous events from the SDK. All callback methods have a default empty implementation, so you only need to override the ones you care about.
public void onError(int code, String message)
public void onWarning(int code, String message)
public void onConnectionStatusChange(@NonNull AoqConnectionStatus status)
public void onStats(@NonNull AoqStats stats)
public void onAudioDeviceStateChanged(@NonNull AoqAudioDeviceState state)
public void onAudioDeviceRouteChanged(int routeType)
public void onAudioDeviceInterrupted(boolean interrupt)
public void onVideoDeviceStateChanged(@NonNull AoqVideoDeviceState state)
public void onAudioDeviceFocusChanged(int audioFocus)
public void onAudioFileState(@NonNull AoqAudioFileState state)
public void onDataMsg(@NonNull AoqDataMsg msg)
Connection state transitions: Disconnected → Connecting → Connected/Failed → Disconnected.

AoqAudioFrameListener

public interface AoqAudioFrameListener {
    default void onCapturedAudioFrame(@NonNull AoqAudioFrameData frame) {}
    default void onProcessCapturedAudioFrame(@NonNull AoqAudioFrameData frame) {}
    default void onPublishAudioFrame(@NonNull AoqTrackType trackType, @NonNull AoqAudioFrameData frame) {}
    default void onPlaybackAudioFrame(@NonNull AoqAudioFrameData frame) {}
}

AoqVideoFrameListener

public interface AoqVideoFrameListener {
    default boolean onCapturedVideoFrame(@NonNull AoqTrackType trackType, @NonNull AoqVideoFrameData frame) { return false; }
    default boolean onPreEncodeVideoFrame(@NonNull AoqTrackType trackType, @NonNull AoqVideoFrameData frame) { return false; }
    default boolean onRemoteVideoFrame(@NonNull AoqTrackType trackType, @NonNull AoqVideoFrameData frame) { return false; }
}
Return true to indicate that you have modified the frame data and want the SDK to read it back (write-back only takes effect for I420 format). The ByteBuffer and textureId in frame are valid only during the callback; copy them before any asynchronous use.

Data types and enumerations

AoqScreenCaptureState

FieldTypeDefaultDescription
stateAoqScreenCaptureStateCodeAoqScreenCaptureNoneScreen capture state.
reasonint00 for normal states; an AoqErrorCode on failure.

AoqScreenCaptureStateCode

ValueNumberDescription
AoqScreenCaptureNone0None
AoqScreenCaptureStarting1Starting
AoqScreenCaptureStarted2Input ready; does not indicate transmission
AoqScreenCaptureStopping3Stopping
AoqScreenCaptureStopped4Stopped
AoqScreenCaptureFail5Start or runtime failure

AoqScreenShareNotificationFactory

public interface AoqScreenShareNotificationFactory {
    @Nullable Notification createNotification(@NonNull Context serviceContext);
}
Return null to use the default notification. Create the NotificationChannel with createNotificationChannel before returning a custom notification; otherwise, the foreground service fails to start.

AoqScreenCaptureConfig

FieldTypeDefaultDescription
isExternalbooleanfalseWhether the application supplies raw screen frames.
mediaProjectionIntentIntentnullPass an existing MediaProjection permission intent, or null to let the SDK request permission. Ignored for external capture.
notificationFactoryAoqScreenShareNotificationFactorynullForeground service notification factory. Null uses the default notification. Ignored for external capture.

AoqAudioVolume

FieldTypeDefaultDescription
isSpeechbooleanfalseWhether speech is detected.
volumeint0Smoothed instantaneous volume, from 0 to 255.

AoqAudioVolumeIndicationConfig

FieldTypeDefaultDescription
reportSpeechbooleanfalseWhether to detect speech.
intervalint0Callback interval in milliseconds. Values of 0 or less disable callbacks; values between 0 and 10 use 10.
smoothint3Smoothing factor, from 0 to 10. Higher values produce smoother results.

AoqTrackParam.trackMode

FieldTypeDefaultDescription
trackModeAoqTrackModeAoqTrackModeSegmentApplies only to downstream audio.

AoqTrackMode

ValueNumberDescription
AoqTrackModeSegment0Segment mode: delivers data in semantic segments, such as sentences. Applies only to downstream audio.
AoqTrackModeStream1Stream mode: delivers data continuously. Applies only to downstream audio.

General types

AoqCreateConfig
FieldTypeDefaultDescription
workDirString""SDK working directory
isBTScoModebooleanfalsetrue: Bluetooth SCO mode; false: A2DP mode
enableDumpAudiobooleanfalseEnable audio dump (for debugging)
extrasString""Extra parameters string
maxEncodedVideoFrameBytesint190 × 1024Maximum encoded frame size in bytes. Applies only to the SDK internal JPEG encoder.
enableDropOversizedVideoFramebooleanfalseFor the SDK internal JPEG encoder, whether to drop a frame that remains oversized at the lowest quality.
AoqConnectConfig subscribeTracks must not include AoqTrackTypeScreen; otherwise, connect returns AoqECUnSupport without starting a connection. setRemoteView also returns AoqECUnSupport for Screen.
FieldTypeDefaultDescription
tokenString""Authentication token
sidString""Session ID
certFingerprintString""Server certificate fingerprint
relayEndpointsList<AoqRelayEndpoint>emptyList of Relay endpoints
workspaceIdHashString""Workspace ID hash
publishTracksList<AoqTrackParam>emptyLocal tracks to publish
subscribeTracksList<AoqTrackParam>emptyRemote tracks to subscribe to

Statistics types

AoqNetworkStats
FieldTypeDescription
sendBitrateintSend bitrate (bps)
sendByteslongCumulative bytes sent
recvBitrateintReceive bitrate (bps)
recvByteslongCumulative bytes received
lossintPacket loss rate (0-100)
rttintRound-trip time (ms)

Enumerations

AoqErrorCode
Enum valueValueDescription
AoqErrorCodeOK0Success
AoqErrorCodeParamInvalid1Invalid parameter
AoqErrorCodeStateInvalid2Invalid state
AoqErrorCodeUnSupport3Not supported
AoqErrorCodeAudio100Audio generic error
AoqErrorCodeAudioExternalBufferFull110External audio buffer full
AoqErrorCodeAudioDevice120Audio device generic error
AoqErrorCodeAudioDeviceRecordingAuthFailed121Recording permission not granted
AoqErrorCodeAudioDeviceRecordingOccupied122Recording device in use
AoqErrorCodeAudioDeviceRecordingBackgroundStart123Failed to start recording in background
AoqErrorCodeAudioDeviceRecordingStartFail124Recording start failed
AoqErrorCodeAudioDevicePlayoutOccupied125Playback device in use
AoqErrorCodeAudioDevicePlayoutBackgroundStart126Failed to start playback in background
AoqErrorCodeAudioDevicePlayoutStartFail127Playback start failed
AoqErrorCodeAudioDeviceEarpieceRequiresVoipMode128Earpiece requires VoIP mode
AoqErrorCodeVideo200Video generic error
AoqErrorCodeVideoExternalBufferFull210External video buffer full
AoqErrorCodeVideoExternalCaptureNotEnabled211External video capture not enabled
AoqErrorCodeVideoExternalEncoderNotEnabled212External video encoder not enabled
AoqErrorCodeVideoDevice220Video device generic error
AoqErrorCodeVideoDeviceCameraOpenFail221Camera open failed
AoqErrorCodeVideoDeviceCameraAuthFailed222Camera permission not granted
AoqErrorCodeVideoDeviceCameraOccupied223Camera in use
AoqErrorCodeVideoDeviceCameraRunningError224Camera runtime error
AoqErrorCodeVideoCodec230Video codec generic error
AoqErrorCodeVideoCodecEncoderInitFail231Video encoder initialization failed
AoqErrorCodeVideoRender240Video rendering generic error
AoqErrorCodeVideoRenderCreateFail241Video renderer creation failed
AoqErrorCodeVideoRenderDrawError242Video rendering draw error
AoqECScreen300General screen sharing error
AoqECScreenAuthFailed310Screen sharing permission denied
AoqECScreenStartFailed311Failed to start screen sharing
AoqWarningCode
Enum valueValueDescription
AoqWCOK0No warning
AoqWCAudio100Audio generic warning
AoqWCAudioHowling101Audio howling detected
AoqWCAudioDevice120Audio device generic warning
AoqWCAudioDeviceMicEnumerateError121Microphone enumeration error
AoqWCAudioDeviceMicStartTimeout122Microphone start timeout
AoqWCAudioDeviceRecordingError123Recording error
AoqWCAudioDeviceSpeakerEnumerateError124Speaker enumeration error
AoqWCAudioDeviceSpeakerStartTimeout125Speaker start timeout
AoqWCAudioDevicePlayoutError126Playback error
AoqWCVideo200Video generic warning
AoqWCVideoCameraEnumerateError201Camera enumeration error
AoqWCVideoEncoderSwitched202Video encoder switched
AoqWCVideoRenderDowngrade203Video rendering downgraded
AoqTrackType
Enum valueValueDescription
AoqTrackTypeAudio0Audio track
AoqTrackTypeVideo1Video track
AoqTrackTypeData2Data messaging track
AoqTrackTypeScreen3Screen sharing track. Uplink only.
AoqEncoderType
Enum valueValueDescription
AoqEncoderTypeUnknown0Unknown format
AoqEncoderTypeAudioPCM1Audio PCM
AoqEncoderTypeAudioOpus2Audio Opus
AoqEncoderTypeVideoH2643Video H.264
AoqEncoderTypeVideoJpeg4Video JPEG
AoqEncoderTypeDataText5Data text
AoqConnectionStatus
Enum valueValueDescription
AoqConnectionStatusDisconnected0Disconnected
AoqConnectionStatusConnecting1Connecting
AoqConnectionStatusConnected2Connected
AoqConnectionStatusFailed3Connection failed

Audio types

AoqAudioCaptureConfig
FieldTypeDefaultDescription
isExternalbooleanfalseWhether to use external capture mode
isVoipModebooleanfalseWhether to enable VoIP mode (affects device routing, e.g., earpiece)
channelint1Channel count (default: mono)
AoqAudioPlaybackConfig
FieldTypeDefaultDescription
isVoipModebooleanfalseWhether to enable VoIP mode (hardware AEC); applies to mobile
isDefaultSpeakerbooleantrueWhether to default to the speaker; applies to mobile
isExternalbooleanfalseWhether to use external playback mode
channelint1Channel count (default: mono)
AoqAudioCodecConfig
FieldTypeDefaultDescription
trackTypeAoqTrackTypeAudioTrack type
codecTypeAoqEncoderTypeAudioOpusCodec format
sampleRateint48000Sample rate (Hz)
channelint1Channel count
bitrateint32000Bitrate (bps)

Video types

AoqVideoCaptureConfig
FieldTypeDefaultDescription
widthint1280Capture width (pixels); ignored when isExternal=true
heightint720Capture height (pixels); ignored when isExternal=true
fpsint15Capture frame rate; ignored when isExternal=true
isExternalbooleanfalseExternal capture mode; when true, the camera is not opened
cameraDirectionAoqCameraDirectionFrontCamera direction; ignored when isExternal=true
AoqVideoCodecConfig
FieldTypeDefaultDescription
trackTypeAoqTrackTypeVideoTrack type
codecTypeAoqEncoderTypeVideoH264Codec format
widthint540Encoding width (pixels)
heightint960Encoding height (pixels)
fpsint5Encoding frame rate
bitrateint500000Target bitrate (bps)
minBitrateint128000Minimum bitrate (bps)
keyframeIntervalint2Keyframe interval (seconds)
mirrorModeAoqMirrorModeDisabledMirror mode
orientationModeAoqOrientationModeAutoVideo orientation mode
isExternalbooleanfalseWhen true, the SDK skips re-encoding; use pushExternalVideoEncodedFrame to deliver pre-encoded data
AoqVideoPixelFormat
Enum valueValueDescription
AoqVideoPixelFormatUnknown0Unknown format
AoqVideoPixelFormatI4201I420 (YUV planar)
AoqVideoPixelFormatNV122NV12 (YUV semi-planar)
AoqVideoPixelFormatNV213NV21 (YUV semi-planar)
AoqVideoPixelFormatBGRA4BGRA 32-bit
AoqVideoPixelFormatRGBA5RGBA 32-bit
AoqVideoPixelFormatTextureOES7External OES texture
AoqVideoPixelFormatTexture2D8Standard 2D texture

External audio stream types

AoqAudioExternalStreamConfig
FieldTypeDefaultDescription
trackTypeAoqTrackTypeAudioAudio track type
codecTypeAoqEncoderTypeAudioPCMAudio stream format
channelsint1Channel count
sampleRateint48000Sample rate (Hz)
playoutVolumeint100Playback volume [0-100]
publishVolumeint100Publishing volume [0-100]
maxBufferDurationint1000Maximum buffer duration (milliseconds)
enable3AbooleanfalseWhether to apply 3A processing to input PCM
AoqAudioStreamDirection
Enum valueValueDescription
AoqAudioStreamPublish0Publish stream (send)
AoqAudioStreamPlayout1Playout stream (receive)

Data message types

AoqDataMsg
FieldTypeDefaultDescription
databyte[]new byte[0]Message data (byte array)
Android SDK - QwenCloud