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 |
|
height |
int |
720 |
Capture height (pixels); ignored when |
|
fps |
int |
15 |
Capture frame rate; ignored when |
|
isExternal |
boolean |
false |
External capture mode; when true, the camera is not opened |
|
cameraDirection |
AoqCameraDirection |
Front |
Camera direction; ignored when |
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 |
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) |