AOQ Client SDK HarmonyOS API reference

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.

static createEngine(config: AoqCreateConfig, listener: AoqEngineEventListener, context: common.Context): AoqClientEngine | null

Returns: 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.

static destroy(): number

Returns: 0 on success; non-zero on failure.

getVersion

Get the current SDK version string.

static getVersion(): string

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.

connect(config: AoqConnectConfig): number

Returns: 0 if the call was dispatched (asynchronous); non-zero if parameter validation failed.

Note: Connection state changes are reported asynchronously via 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.

disconnect(): number

Returns: 0 if the call was dispatched (asynchronous); non-zero on failure.

startAudioCapture

Open the audio capture device (microphone).

startAudioCapture(config: AoqAudioCaptureConfig): number

Returns: 0 on success; non-zero on failure.

stopAudioCapture

Close the audio capture device.

stopAudioCapture(): number

muteAudioCapture

Mute or unmute audio capture.

muteAudioCapture(mute: boolean): number

startAudioPlayer

Start audio playback (play remote audio through the speaker or earpiece).

startAudioPlayer(config: AoqAudioPlaybackConfig): number

stopAudioPlayer

Stop audio playback.

stopAudioPlayer(): number

pauseAudioPlayer

Pause audio playback with an optional fade-out for a smooth transition.

pauseAudioPlayer(fadeMs: number): number

resumeAudioPlayer

Resume audio playback with an optional fade-in for a smooth transition.

resumeAudioPlayer(fadeMs: number): number

interruptAudioPlayer

Interrupt the current audio call turn.

interruptAudioPlayer(trackType: AoqTrackType, fadeMs: number): number

enableSpeakerphone

Switch the audio output route between the speaker and the earpiece.

enableSpeakerphone(enable: boolean): number

isSpeakerphoneEnabled

Query whether the speaker is currently active.

isSpeakerphoneEnabled(): boolean

Returns: true if the speaker is active; false if the earpiece is active.

setAudioEncoderConfig

Set audio encoding parameters.

setAudioEncoderConfig(config: AoqAudioCodecConfig): number

setAudioDecoderConfig

Set audio decoding parameters.

setAudioDecoderConfig(config: AoqAudioCodecConfig): number

startVideoCapture

Open the video capture device (camera). When config.isExternal = true, the camera is not opened; the caller provides frames via pushExternalVideoCapturedFrame.

startVideoCapture(config: AoqVideoCaptureConfig): number

stopVideoCapture

Close the video capture device.

stopVideoCapture(): number

switchCamera

Switch between the front and rear cameras.

switchCamera(direction: AoqCameraDirection): number

setLocalView

Set or remove the local video rendering view.

setLocalView(trackType: AoqTrackType, canvas: AoqVideoCanvas | null): number

Note: On HarmonyOS, this must be called after the XComponent.onLoad callback. Pass an AoqXComponentController instance as canvas.view.

setRemoteView

Set or remove the remote video rendering view.

setRemoteView(trackType: AoqTrackType, canvas: AoqVideoCanvas | null): number

setVideoEncoderConfig

Set video encoding parameters. The call is routed to the track specified by config.trackType.

setVideoEncoderConfig(config: AoqVideoCodecConfig): number

pushExternalVideoCapturedFrame

Push an externally captured raw video frame.

pushExternalVideoCapturedFrame(trackType: AoqTrackType, frame: AoqVideoFrame): number

Only consumed after 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.

pushExternalVideoEncodedFrame(trackType: AoqTrackType, frame: AoqVideoEncodedFrame): number

Only consumed after setVideoEncoderConfig(isExternal=true) is configured.

enableSendMediaStream

Enable or disable local media stream sending. The call is routed to the track specified by trackType.

enableSendMediaStream(trackType: AoqTrackType, enable: boolean): number

Recommended pattern: call enableSendMediaStream(trackType, false) after initialization, then enable once the connection is established and the session handshake completes (onConnectionStatusChange reports AoqConnectionStatusConnected).

startAudioFile

Start streaming a local audio file. Audio file playback is mixed into both the published stream and local playback.

startAudioFile(fileId: string, config: AoqAudioFileMixConfig): number

stopAudioFile / pauseAudioFile / resumeAudioFile

stopAudioFile(fileId: string): number
pauseAudioFile(fileId: string): number
resumeAudioFile(fileId: string): number

getAudioFileDuration / getAudioFileCurrentPosition

getAudioFileDuration(fileId: string): number      // Returns total duration (ms); negative on failure
getAudioFileCurrentPosition(fileId: string): number // Returns current position (ms); negative on failure

setAudioFilePositionMillis

setAudioFilePositionMillis(fileId: string, positionMillis: number): number

setAudioFileVolume / getAudioFileVolume

setAudioFileVolume(fileId: string, type: AoqAudioStreamDirection, volume: number): number
getAudioFileVolume(fileId: string, type: AoqAudioStreamDirection): number // Returns [0, 100]; negative on failure

addAudioExternalStream

Add an external audio stream.

addAudioExternalStream(streamId: string, config: AoqAudioExternalStreamConfig): number

pushAudioExternalStreamData

Push external PCM audio data. Returns AoqECAudioExternalBufferFull (110) if the internal buffer is full.

pushAudioExternalStreamData(streamId: string, data: AoqAudioFrameData): number

setAudioExternalStreamVolume / getAudioExternalStreamVolume

setAudioExternalStreamVolume(streamId: string, type: AoqAudioStreamDirection, vol: number): number
getAudioExternalStreamVolume(streamId: string, type: AoqAudioStreamDirection): number

clearAudioExternalStreamBuffer

Clear the external audio stream buffer. No return value; executes asynchronously.

clearAudioExternalStreamBuffer(streamId: string, fadeoutMs: number): void

removeAudioExternalStream

removeAudioExternalStream(streamId: string): number

sendDataMsg

Send a real-time data message over the MoQT data channel.

sendDataMsg(msg: AoqDataMsg): number

setAudioFrameObserver

Set the audio frame data callback observer. Register the observer first, then call enableAudioFrameObserver to start receiving callbacks.

setAudioFrameObserver(observer: IAudioFrameObserver | null): number

enableAudioFrameObserver

enableAudioFrameObserver(enabled: boolean, audioSource: AoqAudioSource, config: AoqAudioObserverConfig): number

setVideoFrameObserver

setVideoFrameObserver(observer: IVideoFrameObserver | null): number

enableVideoFrameObserver

enableVideoFrameObserver(enabled: boolean, videoSource: AoqVideoSource, config: AoqVideoObserverConfig): number

IAudioFrameObserver

export interface IAudioFrameObserver {
  onCapturedAudioFrame?: (frame: AoqAudioFrameData) => void;
  onProcessCapturedAudioFrame?: (frame: AoqAudioFrameData) => void;
  onPublishAudioFrame?: (trackType: AoqTrackType, frame: AoqAudioFrameData) => void;
  onPlaybackAudioFrame?: (frame: AoqAudioFrameData) => void;
}

frame.dataPtr is a Uint8Array copy of native memory and is currently read-only (modifications are not written back to the SDK).

IVideoFrameObserver

export interface IVideoFrameObserver {
  onCapturedVideoFrame?: (frame: AoqVideoFrame) => boolean;
  onPreEncodeVideoFrame?: (trackType: AoqTrackType, frame: AoqVideoFrame) => boolean;
  onRemoteVideoFrame?: (trackType: AoqTrackType, frame: AoqVideoFrame) => boolean;
}

Frame buffers are 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.

AoqCreateConfig

Unlike Android, AoqCreateConfig on HarmonyOS does not include isBTScoMode.

AoqConnectConfig

AoqRelayEndpoint

AoqTrackParam

AoqErrorCode

AoqWarningCode

AoqTrackType

Unlike Android, AoqTrackTypeScreen (3) is not included on HarmonyOS. Screen capture is not yet available.

AoqConnectionStatus

AoqEncoderType / AoqMirrorMode / AoqOrientationMode

Same as the Android SDK; no changes.

AoqAudioCaptureConfig

AoqAudioPlaybackConfig

AoqAudioCodecConfig

AoqVideoCaptureConfig

AoqVideoCodecConfig

Unlike Android, bitrate units on HarmonyOS are kbps (defaults: 500/128). On Android they are bps (defaults: 500000/128000).

AoqVideoCanvas

AoqVideoPixelFormat

TextureOES and Texture2D are not supported on HarmonyOS.

AoqVideoFrame

AoqVideoEncodedFrame

AoqAudioFileMixConfig

AoqAudioExternalStreamConfig

AoqAudioFrameData

AoqAudioObserverConfig

AoqVideoObserverConfig

AoqStats

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