AOQ HarmonyOS SDK API reference
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
| 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 |
| 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). pushExternalVideoEncodedFrame requires external encoding on the corresponding track; otherwise, it returns AoqECVideoExternalEncoderNotEnabled (212).
Screen capture
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 without a duplicate failure event. 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 the screen and the system prompts for permission. You do not need to wait for Started before enabling transmission or producing external frames.
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. Callbacks are delivered asynchronously on the JS thread.
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. 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) first. For Screen, call startScreenCapture(isExternal=true) first. 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
In v1.3.0, Index.ets exports the following enums and interfaces:
- Enums:
AoqTrackMode,AoqScreenCaptureStateCode. - Interfaces:
AoqAudioVolumeIndicationConfig,AoqAudioVolume,AoqScreenCaptureConfig,AoqScreenCaptureState.
AoqScreenCaptureState
| Field | Type | Default | Description |
|---|---|---|---|
| state | AoqScreenCaptureStateCode | — | Screen capture state. |
| reason | number | — | 0 for normal states; an AoqErrorCode on failure. |
AoqScreenCaptureStateCode
| Enum value | Value | 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 |
AoqScreenCaptureConfig
| Field | Type | Default | Description |
|---|---|---|---|
| isExternal | boolean | false | Whether the application supplies raw screen frames. |
AoqAudioVolume
| Field | Type | Description |
|---|---|---|
| isSpeech | boolean | Whether speech is detected. |
| volume | number | Smoothed instantaneous volume, from 0 to 255. |
AoqAudioVolumeIndicationConfig
| Field | Type | Default | Description |
|---|---|---|---|
| reportSpeech | boolean | false | Whether to detect speech. |
| interval | number | 0 | Callback interval in milliseconds. Values of 0 or less disable callbacks; values between 0 and 10 use 10. |
| smooth | number | 3 | Smoothing factor, from 0 to 10. Higher values produce smoother results. |
AoqTrackMode
| Enum value | Value | 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 |
| enableDumpAudio | boolean | false | Enable raw audio dump (for debugging) |
| extras | string | "" | Extra parameters string |
| maxEncodedVideoFrameBytes | number | 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. |
AoqCreateConfig on HarmonyOS does not include isBTScoMode.
AoqConnectConfig
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 | 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 |
| routeIndex | number | Route index. Default: -1. |
| tcpPort | number | Default: 0. TCP fallback port. A value of 0 uses the SDK default port, 443. |
AoqTrackParam
| Field | Type | Description |
|---|---|---|
| trackType | AoqTrackType | Track type |
| trackMode | AoqTrackMode | Default: AoqTrackModeSegment. Applies only to downstream audio. |
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 |
| AoqECScreen | 300 | General screen sharing error |
| AoqECScreenAuthFailed | 310 | Screen sharing permission denied |
| AoqECScreenStartFailed | 311 | Failed to start screen sharing |
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 | Screen sharing track. Uplink only. |
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 | AoqEncoderTypeAudioOpus | 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 | 540 | Encoding width |
| height | number | 960 | Encoding height |
| fps | number | 5 | Frame rate |
| bitrate | number | 500000 | Bitrate (bps) |
| minBitrate | number | 128000 | Minimum bitrate (bps) |
| 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 |
| trackType | AoqTrackType | AoqTrackTypeVideo | Video track to observe. Supports Video and Screen only. |
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 |
| 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.