AOQ Client SDK Android API reference - Alibaba Cloud Model Studio

The AOQ Client SDK for Android provides a full set of real-time audio/video communication capabilities, including engine lifecycle management, audio/video capture and playback, codec configuration, external audio stream injection, audio file mixing, real-time messaging, and audio/video frame callbacks. This document is the complete Java API reference for the Android platform.

API index

Engine lifecycle

API	Description
createEngine	Create the engine instance (singleton)
destroy	Destroy the engine instance
getVersion	Get the SDK version string
connect	Connect to the Relay server
disconnect	Disconnect from the server

Audio device management

API	Description
startAudioCapture	Open the audio capture device (microphone)
stopAudioCapture	Close the audio capture device
muteAudioCapture	Mute or unmute audio capture
startAudioPlayer	Start audio playback (play remote audio)
stopAudioPlayer	Stop audio playback
pauseAudioPlayer	Pause audio playback with optional fade-out
resumeAudioPlayer	Resume audio playback with optional fade-in
interruptAudioPlayer	Interrupt the current audio call turn
enableSpeakerphone	Switch audio output between speaker and earpiece
isSpeakerphoneEnabled	Query whether the speaker is currently active

Audio codec configuration

API	Description
setAudioEncoderConfig	Set audio encoding parameters
setAudioDecoderConfig	Set audio decoding parameters

Video device management

API	Description
startVideoCapture	Open the video capture device (camera)
stopVideoCapture	Close the video capture device
switchCamera	Switch between front and rear cameras
setLocalView	Set or remove the local video rendering view
setRemoteView	Set or remove the remote video rendering view

Video encoding and external input

API	Description
setVideoEncoderConfig	Set video encoding parameters
pushExternalVideoCapturedFrame	Push an externally captured raw video frame
pushExternalVideoEncodedFrame	Push an externally encoded video frame

Media stream control / real-time messaging

API	Description
enableSendMediaStream	Enable or disable local media stream sending
sendDataMsg	Send a real-time data message

Audio file playback

API	Description
startAudioFile	Start streaming a local audio file
stopAudioFile	Stop audio file playback
pauseAudioFile	Pause audio file playback
resumeAudioFile	Resume audio file playback
getAudioFileDuration	Get the total duration of the audio file
getAudioFileCurrentPosition	Get the current playback position
setAudioFilePositionMillis	Seek to a position in the audio file
setAudioFileVolume	Set the audio file volume
getAudioFileVolume	Get the current audio file volume

External audio streams

API	Description
addAudioExternalStream	Add an external audio stream
removeAudioExternalStream	Remove an external audio stream
pushAudioExternalStreamData	Push external PCM audio data
setAudioExternalStreamVolume	Set the volume for an external audio stream
getAudioExternalStreamVolume	Get the volume for an external audio stream
clearAudioExternalStreamBuffer	Clear the buffer for an external audio stream

Audio/video frame callbacks

API	Description
setAudioFrameObserver	Set the audio frame data callback listener
enableAudioFrameObserver	Enable or disable audio frame callbacks at a specified point
setVideoFrameObserver	Set the video frame data callback listener
enableVideoFrameObserver	Enable or disable video frame callbacks at a specified point

AoqClientListener callbacks

Callback	Description
onError	Engine error callback
onWarning	Engine warning callback
onConnectionStatusChange	Connection state change callback
onStats	Engine statistics callback
onAudioDeviceStateChanged	Audio device state change callback
onAudioDeviceRouteChanged	Audio output route change callback
onAudioDeviceInterrupted	Audio device interruption callback
onVideoDeviceStateChanged	Video device state change callback
onAudioDeviceFocusChanged	Audio focus change callback
onAudioFileState	Audio file playback state callback
onDataMsg	Real-time data message received callback

API details

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)

Parameter	Type	Description
context	Context	Android application context
config	AoqCreateConfig	Engine creation configuration
listener	AoqClientListener	Engine 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 only consumes frames after startVideoCapture(isExternal=true) has been called. If the internal buffer is full, the method returns AoqErrorCodeVideoExternalBufferFull (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 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

General types

AoqCreateConfig

Field	Type	Default	Description
workDir	String	""	SDK working directory
isBTScoMode	boolean	false	true: Bluetooth SCO mode; false: A2DP mode
enableDumpAudio	boolean	false	Enable audio dump (for debugging)
extras	String	""	Extra parameters string

AoqConnectConfig

Field	Type	Default	Description
token	String	""	Authentication token
sid	String	""	Session ID
certFingerprint	String	""	Server certificate fingerprint
relayEndpoints	List<AoqRelayEndpoint>	empty	List of Relay endpoints
workspaceIdHash	String	""	Workspace ID hash
publishTracks	List<AoqTrackParam>	empty	Local tracks to publish
subscribeTracks	List<AoqTrackParam>	empty	Remote tracks to subscribe to

Statistics types

AoqNetworkStats

Field	Type	Description
sendBitrate	int	Send bitrate (bps)
sendBytes	long	Cumulative bytes sent
recvBitrate	int	Receive bitrate (bps)
recvBytes	long	Cumulative bytes received
loss	int	Packet loss rate (0–100)
rtt	int	Round-trip time (ms)

Enumerations

AoqErrorCode

Enum value	Value	Description
AoqErrorCodeOK	0	Success
AoqErrorCodeParamInvalid	1	Invalid parameter
AoqErrorCodeStateInvalid	2	Invalid state
AoqErrorCodeUnSupport	3	Not supported
AoqErrorCodeAudio	100	Audio generic error
AoqErrorCodeAudioExternalBufferFull	110	External audio buffer full
AoqErrorCodeAudioDevice	120	Audio device generic error
AoqErrorCodeAudioDeviceRecordingAuthFailed	121	Recording permission not granted
AoqErrorCodeAudioDeviceRecordingOccupied	122	Recording device in use
AoqErrorCodeAudioDeviceRecordingBackgroundStart	123	Failed to start recording in background
AoqErrorCodeAudioDeviceRecordingStartFail	124	Recording start failed
AoqErrorCodeAudioDevicePlayoutOccupied	125	Playback device in use
AoqErrorCodeAudioDevicePlayoutBackgroundStart	126	Failed to start playback in background
AoqErrorCodeAudioDevicePlayoutStartFail	127	Playback start failed
AoqErrorCodeAudioDeviceEarpieceRequiresVoipMode	128	Earpiece requires VoIP mode
AoqErrorCodeVideo	200	Video generic error
AoqErrorCodeVideoExternalBufferFull	210	External video buffer full
AoqErrorCodeVideoExternalCaptureNotEnabled	211	External video capture not enabled
AoqErrorCodeVideoExternalEncoderNotEnabled	212	External video encoder not enabled
AoqErrorCodeVideoDevice	220	Video device generic error
AoqErrorCodeVideoDeviceCameraOpenFail	221	Camera open failed
AoqErrorCodeVideoDeviceCameraAuthFailed	222	Camera permission not granted
AoqErrorCodeVideoDeviceCameraOccupied	223	Camera in use
AoqErrorCodeVideoDeviceCameraRunningError	224	Camera runtime error
AoqErrorCodeVideoCodec	230	Video codec generic error
AoqErrorCodeVideoCodecEncoderInitFail	231	Video encoder initialization failed
AoqErrorCodeVideoRender	240	Video rendering generic error
AoqErrorCodeVideoRenderCreateFail	241	Video renderer creation failed
AoqErrorCodeVideoRenderDrawError	242	Video rendering draw error

AoqWarningCode

Enum value	Value	Description
AoqWCOK	0	No warning
AoqWCAudio	100	Audio generic warning
AoqWCAudioHowling	101	Audio howling detected
AoqWCAudioDevice	120	Audio device generic warning
AoqWCAudioDeviceMicEnumerateError	121	Microphone enumeration error
AoqWCAudioDeviceMicStartTimeout	122	Microphone start timeout
AoqWCAudioDeviceRecordingError	123	Recording error
AoqWCAudioDeviceSpeakerEnumerateError	124	Speaker enumeration error
AoqWCAudioDeviceSpeakerStartTimeout	125	Speaker start timeout
AoqWCAudioDevicePlayoutError	126	Playback error
AoqWCVideo	200	Video generic warning
AoqWCVideoCameraEnumerateError	201	Camera enumeration error
AoqWCVideoEncoderSwitched	202	Video encoder switched
AoqWCVideoRenderDowngrade	203	Video rendering downgraded

AoqTrackType

Enum value	Value	Description
AoqTrackTypeAudio	0	Audio track
AoqTrackTypeVideo	1	Video track
AoqTrackTypeData	2	Data messaging track

AoqEncoderType

Enum value	Value	Description
AoqEncoderTypeUnknown	0	Unknown format
AoqEncoderTypeAudioPCM	1	Audio PCM
AoqEncoderTypeAudioOpus	2	Audio Opus
AoqEncoderTypeVideoH264	3	Video H.264
AoqEncoderTypeVideoJpeg	4	Video JPEG
AoqEncoderTypeDataText	5	Data text

AoqConnectionStatus

Enum value	Value	Description
AoqConnectionStatusDisconnected	0	Disconnected
AoqConnectionStatusConnecting	1	Connecting
AoqConnectionStatusConnected	2	Connected
AoqConnectionStatusFailed	3	Connection failed

Audio types

AoqAudioCaptureConfig

Field	Type	Default	Description
isExternal	boolean	false	Whether to use external capture mode
isVoipMode	boolean	false	Whether to enable VoIP mode (affects device routing, e.g., earpiece)
channel	int	1	Channel count (default: mono)

AoqAudioPlaybackConfig

Field	Type	Default	Description
isVoipMode	boolean	false	Whether to enable VoIP mode (hardware AEC); applies to mobile
isDefaultSpeaker	boolean	true	Whether to default to the speaker; applies to mobile
isExternal	boolean	false	Whether to use external playback mode
channel	int	1	Channel count (default: mono)

AoqAudioCodecConfig

Field	Type	Default	Description
trackType	AoqTrackType	Audio	Track type
codecType	AoqEncoderType	AudioPCM	Codec format
sampleRate	int	48000	Sample rate (Hz)
channel	int	1	Channel count
bitrate	int	32000	Bitrate (bps)

Video types

AoqVideoCaptureConfig

Field	Type	Default	Description
width	int	1280	Capture width (pixels); ignored when `isExternal=true`
height	int	720	Capture height (pixels); ignored when `isExternal=true`
fps	int	15	Capture frame rate; ignored when `isExternal=true`
isExternal	boolean	false	External capture mode; when true, the camera is not opened
cameraDirection	AoqCameraDirection	Front	Camera direction; ignored when `isExternal=true`

AoqVideoCodecConfig

Field	Type	Default	Description
trackType	AoqTrackType	Video	Track type
codecType	AoqEncoderType	VideoH264	Codec format
width	int	720	Encoding width (pixels)
height	int	1280	Encoding height (pixels)
fps	int	5	Encoding frame rate
bitrate	int	500000	Target bitrate (bps)
minBitrate	int	128000	Minimum bitrate (bps)
keyframeInterval	int	2	Keyframe interval (seconds)
mirrorMode	AoqMirrorMode	Disabled	Mirror mode
orientationMode	AoqOrientationMode	Auto	Video orientation mode
isExternal	boolean	false	When true, the SDK skips re-encoding; use `pushExternalVideoEncodedFrame` to deliver pre-encoded data

AoqVideoPixelFormat

Enum value	Value	Description
AoqVideoPixelFormatUnknown	0	Unknown format
AoqVideoPixelFormatI420	1	I420 (YUV planar)
AoqVideoPixelFormatNV12	2	NV12 (YUV semi-planar)
AoqVideoPixelFormatNV21	3	NV21 (YUV semi-planar)
AoqVideoPixelFormatBGRA	4	BGRA 32-bit
AoqVideoPixelFormatRGBA	5	RGBA 32-bit
AoqVideoPixelFormatTextureOES	7	External OES texture
AoqVideoPixelFormatTexture2D	8	Standard 2D texture

External audio stream types

AoqAudioExternalStreamConfig

Field	Type	Default	Description
trackType	AoqTrackType	Audio	Audio track type
codecType	AoqEncoderType	AudioPCM	Audio stream format
channels	int	1	Channel count
sampleRate	int	48000	Sample rate (Hz)
playoutVolume	int	100	Playback volume [0–100]
publishVolume	int	100	Publishing volume [0–100]
maxBufferDuration	int	1000	Maximum buffer duration (milliseconds)
enable3A	boolean	false	Whether to apply 3A processing to input PCM

AoqAudioStreamDirection

Enum value	Value	Description
AoqAudioStreamPublish	0	Publish stream (send)
AoqAudioStreamPlayout	1	Playout stream (receive)

Data message types

AoqDataMsg

Field	Type	Default	Description
data	byte[]	new byte[0]	Message data (byte array)

​API index

​Engine lifecycle

​Audio device management

​Audio codec configuration

​Video device management

​Video encoding and external input

​Media stream control / real-time messaging

​Audio file playback

​External audio streams

​Audio/video frame callbacks

​AoqClientListener callbacks

​API details

​Engine lifecycle

​Audio device management

​Audio codec configuration

​Video device management

​Video encoding and external input

​Media stream control

​Audio file playback

​External audio streams

​Real-time messaging

​Audio frame callbacks

​Video frame callbacks

​AoqClientListener callbacks

​AoqAudioFrameListener

​AoqVideoFrameListener

​Data types and enumerations

​General types

​Statistics types

​Enumerations

​Audio types

​Video types

​External audio stream types

​Data message types

API index

Engine lifecycle

Audio device management

Audio codec configuration

Video device management

Video encoding and external input

Media stream control / real-time messaging

Audio file playback

External audio streams

Audio/video frame callbacks

AoqClientListener callbacks

API details

Engine lifecycle

Audio device management

Audio codec configuration

Video device management

Video encoding and external input

Media stream control

Audio file playback

External audio streams

Real-time messaging

Audio frame callbacks

Video frame callbacks

AoqClientListener callbacks

AoqAudioFrameListener

AoqVideoFrameListener

Data types and enumerations

General types

Statistics types

Enumerations

Audio types

Video types

External audio stream types

Data message types