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.
The
createEngine
Create the engine instance. The SDK holds the engine as a global singleton; calling this method again returns the existing instance.
Returns: AoqClientEngine instance; never null.
destroy
Destroy the engine instance and release all resources.
Returns: 0 on success; non-zero on failure.
getVersion
Returns: Version string, for example
Returns: 0 if the call was dispatched (asynchronous); non-zero if parameter validation failed.
disconnect
Returns: 0 if the call was dispatched (asynchronous); non-zero on failure.
Pass
Recommended pattern: call
Connection state transitions: Disconnected → Connecting → Connected/Failed → Disconnected.
Return
Return null to use the default notification. Create the NotificationChannel with
AoqCreateConfig
AoqConnectConfig
AoqNetworkStats
AoqErrorCode
AoqWarningCode
AoqTrackType
AoqEncoderType
AoqConnectionStatus
AoqAudioCaptureConfig
AoqAudioPlaybackConfig
AoqAudioCodecConfig
AoqVideoCaptureConfig
AoqVideoCodecConfig
AoqVideoPixelFormat
AoqAudioExternalStreamConfig
AoqAudioStreamDirection
AoqDataMsg
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 |
| enableLocalAudioVolumeIndication | Configure local capture volume indication |
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 |
| startScreenCapture | Start screen capture |
| stopScreenCapture | Stop screen capture |
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 |
| setVideoDecoderConfig | Set video decoding parameters |
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 |
| onLocalAudioVolumeIndication | Local capture volume callback |
| onScreenCaptureStateChanged | Screen 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
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
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
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
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.
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.
| Parameter | Type | Description |
|---|---|---|
| context | Context | Android application context |
| config | AoqCreateConfig | Engine creation configuration |
| listener | AoqClientListener | Engine event callback listener |
"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.
Audio device management
fadeMs: fade-out/fade-in duration in milliseconds; 0 means immediate.
Audio codec configuration
Video device management
AoqTrackTypeVideo as the trackType parameter for setLocalView and setRemoteView.
Video encoding and external input
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
enableSendMediaStream(false) after initialization, then enable once onConnectionStatusChange reports Connected.
Audio file playback
External audio streams
When
pushAudioExternalStreamData returns AoqErrorCodeAudioExternalBufferFull (110), the internal buffer is full. Wait 30 ms and retry.Real-time messaging
Audio frame callbacks
Video frame callbacks
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.
AoqAudioFrameListener
AoqVideoFrameListener
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
| Field | Type | Default | Description |
|---|---|---|---|
| state | AoqScreenCaptureStateCode | AoqScreenCaptureNone | Screen capture state. |
| reason | int | 0 | 0 for normal states; an AoqErrorCode on failure. |
AoqScreenCaptureStateCode
| Value | Number | Description |
|---|---|---|
| AoqScreenCaptureNone | 0 | None |
| AoqScreenCaptureStarting | 1 | Starting |
| AoqScreenCaptureStarted | 2 | Input ready; does not indicate transmission |
| AoqScreenCaptureStopping | 3 | Stopping |
| AoqScreenCaptureStopped | 4 | Stopped |
| AoqScreenCaptureFail | 5 | Start or runtime failure |
AoqScreenShareNotificationFactory
createNotificationChannel before returning a custom notification; otherwise, the foreground service fails to start.
AoqScreenCaptureConfig
| Field | Type | Default | Description |
|---|---|---|---|
| isExternal | boolean | false | Whether the application supplies raw screen frames. |
| mediaProjectionIntent | Intent | null | Pass an existing MediaProjection permission intent, or null to let the SDK request permission. Ignored for external capture. |
| notificationFactory | AoqScreenShareNotificationFactory | null | Foreground service notification factory. Null uses the default notification. Ignored for external capture. |
AoqAudioVolume
| Field | Type | Default | Description |
|---|---|---|---|
| isSpeech | boolean | false | Whether speech is detected. |
| volume | int | 0 | Smoothed instantaneous volume, from 0 to 255. |
AoqAudioVolumeIndicationConfig
| Field | Type | Default | Description |
|---|---|---|---|
| reportSpeech | boolean | false | Whether to detect speech. |
| interval | int | 0 | Callback interval in milliseconds. Values of 0 or less disable callbacks; values between 0 and 10 use 10. |
| smooth | int | 3 | Smoothing factor, from 0 to 10. Higher values produce smoother results. |
AoqTrackParam.trackMode
| Field | Type | Default | Description |
|---|---|---|---|
| trackMode | AoqTrackMode | AoqTrackModeSegment | Applies only to downstream audio. |
AoqTrackMode
| Value | Number | Description |
|---|---|---|
| AoqTrackModeSegment | 0 | Segment mode: delivers data in semantic segments, such as sentences. Applies only to downstream audio. |
| AoqTrackModeStream | 1 | Stream mode: delivers data continuously. Applies only to downstream audio. |
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 |
| maxEncodedVideoFrameBytes | int | 190 × 1024 | Maximum encoded frame size in bytes. Applies only to the SDK internal JPEG encoder. |
| enableDropOversizedVideoFrame | boolean | false | For the SDK internal JPEG encoder, whether to drop a frame that remains oversized at the lowest quality. |
subscribeTracks must not include AoqTrackTypeScreen; otherwise, connect returns AoqECUnSupport without starting a connection. setRemoteView also returns AoqECUnSupport for Screen.
| 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 |
| AoqECScreen | 300 | General screen sharing error |
| AoqECScreenAuthFailed | 310 | Screen sharing permission denied |
| AoqECScreenStartFailed | 311 | Failed to start screen sharing |
| 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 |
| Enum value | Value | Description |
|---|---|---|
| AoqTrackTypeAudio | 0 | Audio track |
| AoqTrackTypeVideo | 1 | Video track |
| AoqTrackTypeData | 2 | Data messaging track |
| AoqTrackTypeScreen | 3 | Screen sharing track. Uplink only. |
| 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 |
| 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) |
| 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) |
| Field | Type | Default | Description |
|---|---|---|---|
| trackType | AoqTrackType | Audio | Track type |
| codecType | AoqEncoderType | AudioOpus | 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 |
| Field | Type | Default | Description |
|---|---|---|---|
| trackType | AoqTrackType | Video | Track type |
| codecType | AoqEncoderType | VideoH264 | Codec format |
| width | int | 540 | Encoding width (pixels) |
| height | int | 960 | 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 |
| 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 |
| 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) |