AOQ Client SDK OHOS (HarmonyOS) API 参考

createEngine

创建引擎实例。SDK 内部以全局单例方式持有引擎，重复调用会返回已创建的实例。native 创建失败时返回 null。

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

返回值：AoqClientEngine | null（native 创建失败时返回 null）

注意事项：与 Android 不同，OHOS 端创建失败会返回 null，调用方需判空处理。context 必须是有效的 UIAbility 或 Page Context。

destroy

销毁引擎单例，释放所有资源。调用后需重新 createEngine 才能继续使用。

static destroy(): number

返回值：0 表示成功；非 0 表示失败

getVersion

获取 SDK 当前版本号。

static getVersion(): string

返回值：版本号字符串，如 "1.0.0"

connect

连接 Relay 服务器。连接参数由业务方 AppServer 通过 /api/v1/allocate 分配后下发给客户端。

connect(config: AoqConnectConfig): number

返回值：0 表示调用已下发（异步执行）；非 0 表示参数校验失败

注意事项：连接状态变化通过 onConnectionStatusChange 异步通知。建议在 connect 前调用 enableSendMediaStream(false)。

disconnect

断开与服务器的连接，释放连接相关资源。音视频采集/播放设备不会自动停止。

disconnect(): number

返回值：0 表示调用已下发（异步执行）；非 0 表示失败

startAudioCapture

打开音频采集设备（麦克风）。

startAudioCapture(config: AoqAudioCaptureConfig): number

返回值：0 表示成功；非 0 表示失败

stopAudioCapture

关闭音频采集设备。

stopAudioCapture(): number

muteAudioCapture

静音或取消静音音频采集。

muteAudioCapture(mute: boolean): number

startAudioPlayer

开始音频渲染（扬声器/听筒播放远端音频）。

startAudioPlayer(config: AoqAudioPlaybackConfig): number

stopAudioPlayer

停止音频渲染。

stopAudioPlayer(): number

pauseAudioPlayer

暂停音频渲染，可指定淡出时长实现平滑过渡。

pauseAudioPlayer(fadeMs: number): number

resumeAudioPlayer

恢复音频渲染，可指定淡入时长实现平滑过渡。

resumeAudioPlayer(fadeMs: number): number

interruptAudioPlayer

打断本轮音频通话。

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

enableSpeakerphone

切换音频输出路由到扬声器或听筒。

enableSpeakerphone(enable: boolean): number

isSpeakerphoneEnabled

查询当前是否使用扬声器输出。

isSpeakerphoneEnabled(): boolean

返回值：true 表示当前为扬声器模式；false 表示听筒模式

setAudioEncoderConfig

设置音频编码参数。

setAudioEncoderConfig(config: AoqAudioCodecConfig): number

setAudioDecoderConfig

设置音频解码参数。

setAudioDecoderConfig(config: AoqAudioCodecConfig): number

startVideoCapture

打开视频采集设备（摄像头）。当 config.isExternal = true 时不打开摄像头，由调用方通过 pushExternalVideoCapturedFrame 喂帧。

startVideoCapture(config: AoqVideoCaptureConfig): number

stopVideoCapture

关闭视频采集设备。

stopVideoCapture(): number

switchCamera

切换前后置摄像头。

switchCamera(direction: AoqCameraDirection): number

setLocalView

设置或移除本地视频渲染窗口。

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

注意：OHOS 上必须在 XComponent.onLoad 回调之后调用，canvas.view 应传入 AoqXComponentController 实例。

setRemoteView

设置或移除远端视频渲染窗口。

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

setVideoEncoderConfig

设置视频编码参数，按 config.trackType 路由到对应轨道。

setVideoEncoderConfig(config: AoqVideoCodecConfig): number

pushExternalVideoCapturedFrame

推送外部采集视频帧。

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

路由规则：仅在 startVideoCapture(isExternal=true) 后消费。支持格式：NV12 / NV21 / BGRA / RGBA / I420。

若缓冲区满，会返回错误码 AoqECVideoExternalBufferFull(210)，调用方需 sleep 后重试，禁止 busy loop。

pushExternalVideoEncodedFrame

推送外部已编码视频帧。SDK 不做二次编码，直接打包发送。

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

路由规则：仅在 setVideoEncoderConfig(isExternal=true) 配置后才消费。

enableSendMediaStream

控制本地媒体流的发送，按 trackType 路由到对应轨道。

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

使用建议：初始化后先调用 enableSendMediaStream(trackType, false)，待 connect 成功且会话握手完成（收到 onConnectionStatusChange(AoqConnectionStatusConnected)）后再开启发送。

startAudioFile

开始推流播放本地音频文件。音频文件播放会混音到推流和本地播放中。

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      // 返回总时长(ms)；负值表示失败
getAudioFileCurrentPosition(fileId: string): number // 返回当前位置(ms)；负值表示失败

setAudioFilePositionMillis

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

setAudioFileVolume / getAudioFileVolume

setAudioFileVolume(fileId: string, type: AoqAudioStreamDirection, volume: number): number
getAudioFileVolume(fileId: string, type: AoqAudioStreamDirection): number // 返回 [0,100]；负值表示失败

addAudioExternalStream

新增一条外部音频流。

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

pushAudioExternalStreamData

输入外部音频 PCM 数据。若缓冲区满返回 AoqECAudioExternalBufferFull(110)。

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

setAudioExternalStreamVolume / getAudioExternalStreamVolume

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

clearAudioExternalStreamBuffer

清空外部音频流缓存。无返回值，异步执行。

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

removeAudioExternalStream

removeAudioExternalStream(streamId: string): number

sendDataMsg

发送实时数据消息，通过 MoQT Data 通道传输。

sendDataMsg(msg: AoqDataMsg): number

setAudioFrameObserver

设置音频帧数据回调监听。先注册监听，再 enableAudioFrameObserver 开启回调。

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 是 native 内存的 Uint8Array 拷贝，当前 ReadOnly（修改不写回 SDK）。

IVideoFrameObserver

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

frame 各 buffer 是 native 内存的 Uint8Array 拷贝，回调期间有效。当前等效 ReadOnly，P2 实现真写回。

AoqCreateConfig

与 Android 不同：OHOS 无 isBTScoMode 字段。

AoqConnectConfig

AoqRelayEndpoint

AoqTrackParam

AoqErrorCode

AoqWarningCode

AoqTrackType

与 Android 不同：OHOS 当前不包含 AoqTrackTypeScreen(3)，屏幕采集功能暂未对外开放。

AoqConnectionStatus

AoqEncoderType / AoqMirrorMode / AoqOrientationMode

同原文档，无变化。

AoqAudioCaptureConfig

AoqAudioPlaybackConfig

AoqAudioCodecConfig

AoqVideoCaptureConfig

AoqVideoCodecConfig

与 Android 不同：OHOS 码率单位为 kbps（默认 500/128），Android 为 bps（默认 500000/128000）。

AoqVideoCanvas

AoqVideoPixelFormat

OHOS 不支持 TextureOES/Texture2D。

AoqVideoFrame

AoqVideoEncodedFrame

AoqAudioFileMixConfig

AoqAudioExternalStreamConfig

AoqAudioFrameData

AoqAudioObserverConfig

AoqVideoObserverConfig

AoqStats

统计子类型

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