AOQ HarmonyOS SDK API reference
AOQ Client SDK HarmonyOS (OHOS) API reference. The platform language is ArkTS (.ets), bridged to the C++ engine via NAPI.
Create the engine instance. The SDK holds the engine as a global singleton; calling this method again returns the existing instance. Returns null if the native engine fails to initialize.
Returns:
Destroy the engine singleton and release all resources. You must call
Returns: 0 on success; non-zero on failure.
Get the current SDK version string.
Returns: Version string, for example
Connect to the Relay server. Connection parameters are allocated by the application server via
Returns: 0 if the call was dispatched (asynchronous); non-zero if parameter validation failed.
Note: Connection state changes are reported asynchronously via
Disconnect from the server and release connection-related resources. Audio and video capture/playback devices are not stopped automatically.
Returns: 0 if the call was dispatched (asynchronous); non-zero on failure.
Open the audio capture device (microphone).
Returns: 0 on success; non-zero on failure.
Close the audio capture device.
Mute or unmute audio capture.
Start audio playback (play remote audio through the speaker or earpiece).
Stop audio playback.
Pause audio playback with an optional fade-out for a smooth transition.
Resume audio playback with an optional fade-in for a smooth transition.
Interrupt the current audio call turn.
Switch the audio output route between the speaker and the earpiece.
Query whether the speaker is currently active.
Returns: true if the speaker is active; false if the earpiece is active.
Set audio encoding parameters.
Set audio decoding parameters.
Open the video capture device (camera). When
Close the video capture device.
Switch between the front and rear cameras.
Set or remove the local video rendering view.
Note: On HarmonyOS, this must be called after the
Set or remove the remote video rendering view.
Set video encoding parameters. The call is routed to the track specified by
Push an externally captured raw video frame.
Only consumed after
Push an externally encoded video frame. The SDK sends it directly without re-encoding.
Only consumed after
Enable or disable local media stream sending. The call is routed to the track specified by
Recommended pattern: call
Start streaming a local audio file. Audio file playback is mixed into both the published stream and local playback.
Add an external audio stream.
Push external PCM audio data. Returns
Clear the external audio stream buffer. No return value; executes asynchronously.
Send a real-time data message over the MoQT data channel.
Set the audio frame data callback observer. Register the observer first, then call
All callbacks are optional properties (
Frame buffers are
Unlike Android,
Unlike Android,
Same as the Android SDK; no changes.
Unlike Android, bitrate units on HarmonyOS are kbps (defaults: 500/128). On Android they are bps (defaults: 500000/128000).
TextureOES and Texture2D are not supported on HarmonyOS.
AoqAudioPublishStats: trackType / bitrate / bytes / encodeVolume
AoqVideoPublishStats: trackType / bitrate / bytes / encodeFps
AoqAudioSubscribeStats: trackType / bitrate / bytes / playVolume
AoqVideoSubscribeStats: trackType / bitrate / bytes / decodeFps / renderFps
AoqDataMsgPublishStats / AoqDataMsgSubscribeStats: trackType / bitrate / bytes
AoqNetworkStats: sendBitrate / sendBytes / recvBitrate / recvBytes / loss / rtt
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
| API | Description |
|---|---|
| enableSendMediaStream | Enable or disable local media stream sending |
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 |
Real-time messaging
| API | Description |
|---|---|
| sendDataMsg | Send a real-time data message |
Audio frame callbacks
| API | Description |
|---|---|
| setAudioFrameObserver | Set the audio frame data callback observer |
| enableAudioFrameObserver | Enable or disable audio frame callbacks at a specified point |
Video frame callbacks
| API | Description |
|---|---|
| setVideoFrameObserver | Set the video frame data callback observer |
| enableVideoFrameObserver | Enable or disable video frame callbacks at a specified point |
AoqEngineEventListener callbacks
| Callback | Description |
|---|---|
| onError | Engine error callback |
| onWarning | Engine warning callback |
| onConnectionStatusChange | Connection state change callback |
| onStats | 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 |
| onAudioFileState | Audio file playback state callback |
| onDataMsg | Real-time data message received callback |
| IAudioFrameObserver | Audio frame data observer interface |
| IVideoFrameObserver | Video frame data observer interface |
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. Returns null if the native engine fails to initialize.
| Parameter | Type | Description |
|---|---|---|
| config | AoqCreateConfig | Engine creation configuration |
| listener | AoqEngineEventListener | Engine event callback listener (interface; all callbacks are optional) |
| context | common.Context | UIAbility/Page context, used for aki+ACPM initialization |
AoqClientEngine | null -- null if native creation fails.
Note: Unlike Android, this SDK returns null on failure. Always null-check the return value. The context must be a valid UIAbility or Page context.
destroy
Destroy the engine singleton and release all resources. You must call createEngine again before resuming use.
getVersion
Get the current SDK version string.
"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.
| Parameter | Type | Description |
|---|---|---|
| config | AoqConnectConfig | Connection configuration, including token, SID, and Relay endpoint list |
onConnectionStatusChange. It is recommended to call enableSendMediaStream(false) before calling connect.
disconnect
Disconnect from the server and release connection-related resources. Audio and video capture/playback devices are not stopped automatically.
Audio device management
startAudioCapture
Open the audio capture device (microphone).
| Parameter | Type | Description |
|---|---|---|
| config | AoqAudioCaptureConfig | Capture configuration |
stopAudioCapture
Close the audio capture device.
muteAudioCapture
Mute or unmute audio capture.
| Parameter | Type | Description |
|---|---|---|
| mute | boolean | true: mute; false: unmute |
startAudioPlayer
Start audio playback (play remote audio through the speaker or earpiece).
| Parameter | Type | Description |
|---|---|---|
| config | AoqAudioPlaybackConfig | Playback configuration |
stopAudioPlayer
Stop audio playback.
pauseAudioPlayer
Pause audio playback with an optional fade-out for a smooth transition.
| Parameter | Type | Description |
|---|---|---|
| fadeMs | number | Fade-out duration (milliseconds); 0 means immediate |
resumeAudioPlayer
Resume audio playback with an optional fade-in for a smooth transition.
| Parameter | Type | Description |
|---|---|---|
| fadeMs | number | Fade-in duration (milliseconds); 0 means immediate |
interruptAudioPlayer
Interrupt the current audio call turn.
| Parameter | Type | Description |
|---|---|---|
| trackType | AoqTrackType | Target track type; typically AoqTrackTypeAudio |
| fadeMs | number | Fade-out duration (milliseconds) |
enableSpeakerphone
Switch the audio output route between the speaker and the earpiece.
| Parameter | Type | Description |
|---|---|---|
| enable | boolean | true: use speaker; false: use earpiece |
isSpeakerphoneEnabled
Query whether the speaker is currently active.
Audio codec configuration
setAudioEncoderConfig
Set audio encoding parameters.
setAudioDecoderConfig
Set audio decoding parameters.
Video device management
startVideoCapture
Open the video capture device (camera). When config.isExternal = true, the camera is not opened; the caller provides frames via pushExternalVideoCapturedFrame.
stopVideoCapture
Close the video capture device.
switchCamera
Switch between the front and rear cameras.
| Parameter | Type | Description |
|---|---|---|
| direction | AoqCameraDirection | AoqCameraDirectionFront or AoqCameraDirectionBack |
setLocalView
Set or remove the local video rendering view.
| Parameter | Type | Description |
|---|---|---|
| trackType | AoqTrackType | AoqTrackTypeVideo |
| canvas | AoqVideoCanvas | null | Rendering canvas configuration; pass null or set canvas.view to null to remove the rendering view |
XComponent.onLoad callback. Pass an AoqXComponentController instance as canvas.view.
setRemoteView
Set or remove the remote video rendering view.
| Parameter | Type | Description |
|---|---|---|
| trackType | AoqTrackType | AoqTrackTypeVideo |
| canvas | AoqVideoCanvas | null | Rendering canvas configuration; pass null or set canvas.view to null to remove the rendering view |
Video encoding and external input
setVideoEncoderConfig
Set video encoding parameters. The call is routed to the track specified by config.trackType.
pushExternalVideoCapturedFrame
Push an externally captured raw video frame.
| Parameter | Type | Description |
|---|---|---|
| trackType | AoqTrackType | AoqTrackTypeVideo |
| frame | AoqVideoFrame | Video frame data |
startVideoCapture(isExternal=true). Supported formats: NV12, NV21, BGRA, RGBA, I420.
If the internal buffer is full, the method returns AoqECVideoExternalBufferFull(210). Sleep and retry; do not busy-loop.
pushExternalVideoEncodedFrame
Push an externally encoded video frame. The SDK sends it directly without re-encoding.
| Parameter | Type | Description |
|---|---|---|
| trackType | AoqTrackType | AoqTrackTypeVideo |
| frame | AoqVideoEncodedFrame | Encoded frame data |
setVideoEncoderConfig(isExternal=true) is configured.
Media stream control
enableSendMediaStream
Enable or disable local media stream sending. The call is routed to the track specified by trackType.
| Parameter | Type | Description |
|---|---|---|
| trackType | AoqTrackType | AoqTrackTypeAudio or AoqTrackTypeVideo |
| enable | boolean | true: enable sending; false: disable sending |
enableSendMediaStream(trackType, false) after initialization, then enable once the connection is established and the session handshake completes (onConnectionStatusChange reports AoqConnectionStatusConnected).
Audio file playback
startAudioFile
Start streaming a local audio file. Audio file playback is mixed into both the published stream and local playback.
| Parameter | Type | Description |
|---|---|---|
| fileId | string | Unique identifier for the audio file, specified by the caller |
| config | AoqAudioFileMixConfig | Playback configuration |
stopAudioFile / pauseAudioFile / resumeAudioFile
getAudioFileDuration / getAudioFileCurrentPosition
setAudioFilePositionMillis
setAudioFileVolume / getAudioFileVolume
External audio streams
addAudioExternalStream
Add an external audio stream.
pushAudioExternalStreamData
Push external PCM audio data. Returns AoqECAudioExternalBufferFull(110) if the internal buffer is full.
setAudioExternalStreamVolume / getAudioExternalStreamVolume
clearAudioExternalStreamBuffer
Clear the external audio stream buffer. No return value; executes asynchronously.
| Parameter | Type | Description |
|---|---|---|
| fadeoutMs | number | -1: default fade-out; 0: clear immediately; >0: retain the specified duration then fade out |
removeAudioExternalStream
Real-time messaging
sendDataMsg
Send a real-time data message over the MoQT data channel.
Audio frame callbacks
setAudioFrameObserver
Set the audio frame data callback observer. Register the observer first, then call enableAudioFrameObserver to start receiving callbacks.
enableAudioFrameObserver
Video frame callbacks
setVideoFrameObserver
enableVideoFrameObserver
AoqEngineEventListener callbacks
All callbacks are optional properties (?).
IAudioFrameObserver
frame.dataPtr is a Uint8Array copy of native memory and is currently read-only (modifications are not written back to the SDK).
IVideoFrameObserver
Uint8Array copies of native memory, valid only during the callback. They are currently equivalent to read-only; write-back support is planned for a future release.
Data types and enumerations
General types
AoqCreateConfig
| Field | Type | Default | Description |
|---|---|---|---|
| workDir | string | "" | SDK working directory |
| enableDumpAudio | boolean | false | Enable raw audio dump (for debugging) |
| extras | string | "" | Extra parameters string |
AoqCreateConfig on HarmonyOS does not include isBTScoMode.
AoqConnectConfig
| Field | Type | Default | Description |
|---|---|---|---|
| token | string | "" | Authentication token |
| sid | string | "" | Session ID |
| certFingerprint | string | "" | Server certificate fingerprint |
| relayEndpoints | AoqRelayEndpoint[] | [] | List of Relay endpoints |
| workspaceIdHash | string | "" | Workspace ID hash |
| publishTracks | AoqTrackParam[] | [] | Local tracks to publish |
| subscribeTracks | AoqTrackParam[] | [] | Remote tracks to subscribe to |
AoqRelayEndpoint
| Field | Type | Description |
|---|---|---|
| endpoint | string | Relay server hostname or IP |
| port | number | Relay server port |
AoqTrackParam
| Field | Type | Description |
|---|---|---|
| trackType | AoqTrackType | Track type |
AoqErrorCode
| Enum value | Value | Description |
|---|---|---|
| AoqECOK | 0 | Success |
| AoqECParamInvalid | 1 | Invalid parameter |
| AoqECStateInvalid | 2 | Invalid state |
| AoqECUnSupport | 3 | Not supported |
| AoqECAudio | 100 | Audio generic error |
| AoqECAudioExternalBufferFull | 110 | External audio buffer full |
| AoqECAudioDevice | 120 | Audio device generic error |
| AoqECAudioDeviceRecordingAuthFailed | 121 | Recording permission not granted |
| AoqECAudioDeviceRecordingOccupied | 122 | Recording device in use |
| AoqECAudioDeviceRecordingBackgroundStart | 123 | Failed to start recording in background |
| AoqECAudioDeviceRecordingStartFail | 124 | Recording start failed |
| AoqECAudioDevicePlayoutOccupied | 125 | Playback device in use |
| AoqECAudioDevicePlayoutBackgroundStart | 126 | Failed to start playback in background |
| AoqECAudioDevicePlayoutStartFail | 127 | Playback start failed |
| AoqECAudioDeviceEarpieceRequiresVoipMode | 128 | Earpiece requires VoIP mode |
| AoqECVideo | 200 | Video generic error |
| AoqECVideoExternalBufferFull | 210 | External video buffer full |
| AoqECVideoExternalCaptureNotEnabled | 211 | External video capture not enabled |
| AoqECVideoExternalEncoderNotEnabled | 212 | External video encoder not enabled |
| AoqECVideoDevice | 220 | Video device generic error |
| AoqECVideoDeviceCameraOpenFail | 221 | Camera open failed |
| AoqECVideoDeviceCameraAuthFailed | 222 | Camera permission not granted |
| AoqECVideoDeviceCameraOccupied | 223 | Camera in use |
| AoqECVideoDeviceCameraRunningError | 224 | Camera runtime error |
| AoqECVideoCodec | 230 | Video codec generic error |
| AoqECVideoCodecEncoderInitFail | 231 | Video encoder initialization failed |
| AoqECVideoRender | 240 | Video rendering generic error |
| AoqECVideoRenderCreateFail | 241 | Video renderer creation failed |
| AoqECVideoRenderDrawError | 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 |
AoqTrackTypeScreen(3) is not included on HarmonyOS. Screen capture is not yet available.
AoqConnectionStatus
| Enum value | Value | Description |
|---|---|---|
| AoqConnectionStatusDisconnected | 0 | Disconnected |
| AoqConnectionStatusConnecting | 1 | Connecting |
| AoqConnectionStatusConnected | 2 | Connected |
| AoqConnectionStatusFailed | 3 | Connection failed |
AoqEncoderType / AoqMirrorMode / AoqOrientationMode
Same as the Android SDK; no changes.
Audio types
AoqAudioCaptureConfig
| Field | Type | Default | Description |
|---|---|---|---|
| isExternal | boolean | false | true: use external audio input |
| isVoipMode | boolean | false | true: enable VoIP mode (hardware AEC) |
| channel | number | 1 | Channel count: 1 or 2 |
AoqAudioPlaybackConfig
| Field | Type | Default | Description |
|---|---|---|---|
| isVoipMode | boolean | false | true: enable VoIP mode (hardware AEC); first-write-wins between capture and playback config |
| isDefaultSpeaker | boolean | true | true: default to speaker; false: default to earpiece |
| isExternal | boolean | false | true: use external audio output |
| channel | number | 1 | Channel count: 1 or 2 |
AoqAudioCodecConfig
| Field | Type | Default | Description |
|---|---|---|---|
| trackType | AoqTrackType | AoqTrackTypeAudio | Target track |
| codecType | AoqEncoderType | AoqEncoderTypeAudioPCM | Codec format |
| sampleRate | number | 48000 | Sample rate (Hz) |
| channel | number | 1 | Channel count |
| bitrate | number | 32000 | Bitrate (bps) |
Video types
AoqVideoCaptureConfig
| Field | Type | Default | Description |
|---|---|---|---|
| width | number | 1280 | Capture width; ignored when isExternal=true |
| height | number | 720 | Capture height |
| fps | number | 15 | Capture frame rate |
| isExternal | boolean | false | true: do not open the camera; provide frames via pushExternalVideoCapturedFrame |
| cameraDirection | AoqCameraDirection | Front | Camera direction |
AoqVideoCodecConfig
| Field | Type | Default | Description |
|---|---|---|---|
| trackType | AoqTrackType | AoqTrackTypeVideo | Target track |
| codecType | AoqEncoderType | AoqEncoderTypeVideoH264 | Codec format |
| width | number | 720 | Encoding width |
| height | number | 1280 | Encoding height |
| fps | number | 15 | Frame rate |
| bitrate | number | 500 | Bitrate (kbps) |
| minBitrate | number | 128 | Minimum bitrate (kbps) |
| keyframeInterval | number | 2 | Keyframe interval (seconds) |
| mirrorMode | AoqMirrorMode | Disabled | Mirror mode |
| orientationMode | AoqOrientationMode | Auto | Video orientation |
| isExternal | boolean | false | true: the SDK skips re-encoding |
AoqVideoCanvas
| Field | Type | Default | Description |
|---|---|---|---|
| view | Object | null | null | AoqXComponentController instance; pass null to remove the rendering binding |
| renderMode | AoqRenderMode | AoqRenderModeAuto | Display mode |
AoqVideoPixelFormat
| Enum value | Value | Description |
|---|---|---|
| AoqVideoPixelFormatUnknown | 0 | Unknown |
| AoqVideoPixelFormatI420 | 1 | I420 |
| AoqVideoPixelFormatNV12 | 2 | NV12 |
| AoqVideoPixelFormatNV21 | 3 | NV21 |
| AoqVideoPixelFormatBGRA | 4 | BGRA |
| AoqVideoPixelFormatRGBA | 5 | RGBA |
AoqVideoFrame
| Field | Type | Description |
|---|---|---|
| format | AoqVideoPixelFormat | Pixel format |
| width | number | Width (pixels) |
| height | number | Height (pixels) |
| dataPtr | ArrayBuffer | Uint8Array | null | Packed format data |
| dataSize | number | Packed data size (bytes) |
| dataY / dataU / dataV | ArrayBuffer | Uint8Array | null | I420 planes |
| strideY / strideU / strideV | number | Plane stride |
| timeStamp | number | Timestamp (ms); when 0, the SDK uses the local clock |
AoqVideoEncodedFrame
| Field | Type | Description |
|---|---|---|
| codec | AoqVideoCodecType | Encoding format (AoqVideoCodecTypeJPEG = 0) |
| data | ArrayBuffer | Uint8Array | Encoded frame data |
| width | number | Width |
| height | number | Height |
| timeStamp | number | Timestamp (ms) |
Audio file and external stream types
AoqAudioFileMixConfig
| Field | Type | Default | Description |
|---|---|---|---|
| fileName | string | "" | File name (including path) |
| cycles | number | -1 | Loop count; -1 means loop indefinitely |
| startPosMs | number | 0 | Starting playback position (ms) |
| publishVolume | number | 100 | Publishing volume [0, 100] |
| playoutVolume | number | 100 | Local playback volume [0, 100] |
AoqAudioExternalStreamConfig
| Field | Type | Default | Description |
|---|---|---|---|
| trackType | AoqTrackType | AoqTrackTypeAudio | Track type |
| codecType | AoqEncoderType | AoqEncoderTypeAudioPCM | Audio format |
| channels | number | 1 | Channel count |
| sampleRate | number | 48000 | Sample rate (Hz) |
| playoutVolume | number | 100 | Playback volume [0, 100] |
| publishVolume | number | 100 | Publishing volume [0, 100] |
| maxBufferDuration | number | 1000 | Maximum buffer duration (ms) |
| enable3A | boolean | false | Whether to apply 3A processing to input PCM |
AoqAudioFrameData
| Field | Type | Description |
|---|---|---|
| dataPtr | ArrayBuffer | Uint8Array | null | Raw PCM audio data |
| dataSize | number | PCM data size (bytes) |
| numOfSamples | number | Sample count (mono) |
| bytesPerSample | number | Bytes per sample |
| numOfChannels | number | Channel count |
| samplesPerSec | number | Sample rate |
| pushSequence | number | PCM push sequence number |
| timeStamp | number | Timestamp |
| autoGenMute | boolean | true: this is SDK-generated silence data |
Observer configuration types
AoqAudioObserverConfig
| Field | Type | Default | Description |
|---|---|---|---|
| sampleRate | number | 48000 | Callback sample rate |
| channels | number | 1 | Callback channel count |
| mode | AoqAudioObserverMode | ReadOnly | Read/write mode |
AoqVideoObserverConfig
| Field | Type | Default | Description |
|---|---|---|---|
| format | AoqVideoPixelFormat | I420 | Callback pixel format |
| alignment | AoqVideoObserverAlignment | Default | Width alignment |
| mode | AoqVideoObserverMode | ReadOnly | Read/write mode |
| mirrorApplied | boolean | false | Whether to apply mirroring |
Statistics types
AoqStats
| Field | Type | Description |
|---|---|---|
| audioPublishStats | AoqAudioPublishStats[] | Audio publish statistics |
| videoPublishStats | AoqVideoPublishStats[] | Video publish statistics |
| dataMsgPublishStats | AoqDataMsgPublishStats[] | Data message publish statistics |
| audioSubscribeStats | AoqAudioSubscribeStats[] | Audio subscribe statistics |
| videoSubscribeStats | AoqVideoSubscribeStats[] | Video subscribe statistics |
| dataMsgSubscribeStats | AoqDataMsgSubscribeStats[] | Data message subscribe statistics |
| networkStats | AoqNetworkStats | null | Network statistics |
Statistics subtypes
AoqAudioPublishStats: trackType / bitrate / bytes / encodeVolume
AoqVideoPublishStats: trackType / bitrate / bytes / encodeFps
AoqAudioSubscribeStats: trackType / bitrate / bytes / playVolume
AoqVideoSubscribeStats: trackType / bitrate / bytes / decodeFps / renderFps
AoqDataMsgPublishStats / AoqDataMsgSubscribeStats: trackType / bitrate / bytes
AoqNetworkStats: sendBitrate / sendBytes / recvBitrate / recvBytes / loss / rtt
Key differences from the Android SDK
| Category | Android | HarmonyOS |
|---|---|---|
| Implementation language | Java | ArkTS (.ets), NAPI-bridged to C++ |
| Return value type | int / long / boolean | number / boolean |
| createEngine return | @NonNull AoqClientEngine | AoqClientEngine | null |
| createEngine context | android.content.Context | common.Context (UIAbility/Page) |
| Listener form | Abstract class with default empty methods | TS interface; all callbacks are optional (?) |
| Frame observer form | Interface with default methods | TS interface; all callbacks are optional (?) |
| AoqCreateConfig | Includes isBTScoMode | Does not include isBTScoMode |
| AoqAudioPlaybackConfig | No isVoipMode | Includes isVoipMode; first-write-wins between capture and playback |
| onAudioDeviceFocusChanged | Provided | Not provided (no audio focus abstraction) |
| Video rendering view | View (SurfaceView/TextureView) | AoqXComponentController (extends XComponentController) |
| Pixel format enum | Includes TextureOES (7) / Texture2D (8) | Does not include texture formats |
| Video frame extra fields | textureId / transformMatrix / eglContext | Not included |
| Frame data container | byte[] / ByteBuffer | ArrayBuffer / Uint8Array |
| Video encoding bitrate unit | bps (defaults: 500000/128000) | kbps (defaults: 500/128) |
| AoqTrackType | Includes AoqTrackTypeScreen (3) | Does not include AoqTrackTypeScreen; screen capture not yet available |
| Screen capture APIs | startScreenCapture / stopScreenCapture | Not yet provided |
| Observer write-back | I420 write-back supported | Currently equivalent to read-only; write-back planned for future release |
| Observer re-registration safety | Relies on SDK internals | UAF protection using tombstone pattern |
| Device monitoring | Implicit in Java layer | AoqDeviceMonitor (internal) starts automatically |
| Error code namespace | AoqErrorCodeXxx | AoqECXxx (e.g., AoqECOK, AoqECParamInvalid) |
Architecture notes
-
AoqXComponentController: Extends
XComponentControllerand overridesonSurfaceCreated,onSurfaceChanged, andonSurfaceDestroyed. Create an instance, attach it to anXComponent, and pass it ascanvas.viewwhen callingsetLocalVieworsetRemoteView. -
NAPI architecture: facade (
AoqClientEngine.ets) -> implementation (AoqClientEngineImpl.ets) -> NAPI (libaoq_client_sdk.so). Configuration objects are flattened into individual parameters at the implementation layer. -
Device monitoring (internal):
AoqDeviceMonitorstarts automatically aftercreateEngineand forwards network state and app foreground/background state to the C++ engine. - Observer UAF protection: Re-registration follows a three-step sequence: cut old reference in C++ -> push old observer to tombstone -> point to new observer.
-
Frame payload semantics:
Uint8Arraybuffers in audio/video frame callbacks are copies of native memory. Write-back is not supported in P1; zero-copy is planned for P2.