跳转到主要内容
SDK简介

AOQ Client SDK Electron API 参考

本文介绍 AOQ Client SDK Electron 版的 TypeScript 接口、事件和数据类型。该 SDK 适用于 macOS x64/arm64 和 Windows x64,要求 Node.js 16 或更高版本。

适用包:aoq-electron-sdk(npm)。支持平台:macOS(x64 / arm64)、Windows x64;Node.js >= 16。

接口目录

引擎入口与生命周期

接口简介
createAoqClientEngine获取引擎包装实例(模块级懒加载单例)
createEngine创建 native 引擎实例
destroy销毁引擎实例
getVersion获取 SDK 版本号
connect连接 Relay 服务器
disconnect断开服务器连接

音频设备管理

接口简介
startAudioCapture打开音频采集设备(麦克风)
stopAudioCapture关闭音频采集设备
muteAudioCapture静音或取消静音音频采集
startAudioPlayer开始音频渲染(播放远端音频)
stopAudioPlayer停止音频渲染
pauseAudioPlayer暂停音频渲染,支持淡出
resumeAudioPlayer恢复音频渲染,支持淡入
interruptAudioPlayer打断本轮音频通话

音频编解码配置

接口简介
setAudioEncoderConfig设置音频编码参数
setAudioDecoderConfig设置音频解码参数

视频设备管理

接口简介
startVideoCapture打开视频采集设备(摄像头)
stopVideoCapture关闭视频采集设备

视频编解码与外部输入

接口简介
setVideoEncoderConfig设置视频编码参数
setVideoDecoderConfig设置视频解码参数
pushExternalVideoCapturedFrame推送外部采集视频帧
pushExternalVideoEncodedFrame推送外部已编码视频帧

屏幕采集

接口简介
getScreenSourceList获取可共享的桌面和窗口列表
startScreenCapture启动屏幕采集
stopScreenCapture停止屏幕采集

媒体流发送控制

接口简介
enableSendMediaStream控制本地媒体流的发送开关

音频文件播放

接口简介
startAudioFile开始推流播放本地音频文件
stopAudioFile停止音频文件播放
pauseAudioFile暂停音频文件播放
resumeAudioFile恢复音频文件播放
getAudioFileDuration获取音频文件总时长
getAudioFileCurrentPosition获取音频文件当前播放位置
setAudioFilePositionMillis设置音频文件播放位置(seek)
setAudioFileVolume设置音频文件音量
getAudioFileVolume获取音频文件当前音量

外部音频流

接口简介
addAudioExternalStream新增一条外部音频流
removeAudioExternalStream移除外部音频流
pushAudioExternalStreamData输入外部音频 PCM 数据
setAudioExternalStreamVolume设置外部音频流音量
getAudioExternalStreamVolume获取外部音频流音量
clearAudioExternalStreamBuffer清空外部音频流缓存

实时消息

接口简介
sendDataMsg发送实时数据消息

音频帧回调

接口简介
setAudioFrameObserver开启或关闭音频帧数据观察者
enableAudioFrameObserver开启或关闭指定位置的音频帧回调

本地音量提示

接口简介
enableLocalAudioVolumeIndication开启或关闭本地采集音量提示回调

视频帧回调

接口简介
setVideoFrameObserver开启或关闭视频帧数据观察者
enableVideoFrameObserver开启或关闭指定位置的视频帧回调

视频渲染(YUVCanvasRenderer)

接口简介
bind绑定 canvas 元素
unbind解绑并清空画面
bound查询当前是否已绑定
drawFrame绘制一帧 I420 视频数据

引擎事件(IAoqEngineEvents)

接口简介
onError引擎错误回调
onWarning引擎警告回调
onConnectionStatusChange连接状态变化回调
onStats引擎统计信息回调
onAudioDeviceStateChanged音频设备操作状态变化回调
onAudioDeviceRouteChanged音频输出路由变化回调
onAudioFileState音频文件播放状态回调
onLocalAudioVolumeIndication本地采集音量提示回调
onVideoDeviceStateChanged视频设备操作状态变化回调
onDataMsg收到实时数据消息回调

音频帧事件

接口简介
onCapturedAudioFrame采集到原始音频帧时触发。数据为采集后的原始 PCM,未经任何处理。
onProcessCapturedAudioFrame3A 处理后的音频帧回调。数据经过回声消除、噪声抑制、自动增益等 3A 处理。
onPublishAudioFrame推流前的音频帧回调。数据即将通过编码后发送到 Relay 服务器。
onPlaybackAudioFrame播放前的远端音频帧回调。数据为远端解码后、混音前即将播放的音频。

视频帧事件

接口简介
onCapturedVideoFrame采集到原始视频帧时触发(前处理前)。数据为摄像头或屏幕采集后的原始帧,未经前处理。
onPreEncodeVideoFrame编码前的视频帧回调(前处理后)。数据经过前处理后、编码前。
onRemoteVideoFrame远端解码后、渲染前的视频帧回调。数据为远端接收并解码后的视频帧。

接口详情

引擎入口与生命周期

createAoqClientEngine

获取引擎包装实例。模块级懒加载单例,重复调用返回同一实例,与 native 引擎单例语义对齐;也是包的 default export。
import createAoqClientEngine from 'aoq-electron-sdk';
export function createAoqClientEngine(): IAoqClientEngine
返回值:IAoqClientEngine 引擎实例。注意本方法仅创建 JS 包装层与 native bridge,真正创建引擎需再调 createEngine()。

createEngine

创建 native 引擎实例。引擎为全局单例,重复调用直接返回成功。
createEngine(config: AoqCreateConfig): number
参数类型说明
configAoqCreateConfig引擎创建配置
返回值:0 成功;-1 表示创建失败或参数不是合法 JSON。
Windows 上 createEngine() 会在当前 JS 线程的 libuv 循环上挂一个 16ms 的 Win32 消息泵(摄像头采集依赖),destroy() 时停掉;因此不要在 createEngine() 之后长时间同步阻塞 JS 线程。

destroy

销毁引擎实例,释放所有资源。
destroy(): number
返回值:0 表示成功;非 0 表示失败。引擎未创建时返回 0。

getVersion

获取 SDK 当前版本号,无需先调 createEngine()。
getVersion(): string
返回值:版本号字符串,如 "1.2.0";取不到时返回空字符串。

connect

连接 Relay 服务器。业务 AppServer 应根据所用协议获取临时 AOQ 连接参数并下发给客户端,具体操作请参见Token 鉴权。
connect(config: AoqConnectConfig): number
参数类型说明
configAoqConnectConfig连接配置,包含 Token、SID、Relay 接入点列表、推拉流 track 列表等
返回值:0 表示调用已下发(异步执行);非 0 表示参数校验失败。连接结果由 onConnectionStatusChange 事件通知。

disconnect

断开与服务器的连接,释放连接相关资源。
disconnect(): number
返回值:0 表示调用已下发(异步执行);非 0 表示失败。

音频设备管理

startAudioCapture

startAudioCapture(config: AoqAudioCaptureConfig): number
打开音频采集设备(麦克风)。首次采集会触发系统授权,macOS 需在应用 Info.plist 中声明 NSMicrophoneUsageDescription。

stopAudioCapture

stopAudioCapture(): number
关闭音频采集设备。

muteAudioCapture

muteAudioCapture(mute: boolean): number
静音或取消静音音频采集。mute=true 静音,false 取消静音。

startAudioPlayer

startAudioPlayer(config: AoqAudioPlaybackConfig): number
开始音频渲染(播放远端音频)。

stopAudioPlayer / pauseAudioPlayer / resumeAudioPlayer

stopAudioPlayer(): number
pauseAudioPlayer(fadeMs: number): number
resumeAudioPlayer(fadeMs: number): number
fadeMs:淡出/淡入时长(毫秒);0 表示立即执行。

interruptAudioPlayer

interruptAudioPlayer(trackType: AoqTrackType, fadeMs: number): number
打断本轮音频通话,丢弃已缓存的本轮下行数据。
参数类型说明
trackTypeAoqTrackType轨道类型
fadeMsnumber淡出时长(毫秒)

音频编解码配置

setAudioEncoderConfig(config: AoqAudioCodecConfig): number
setAudioDecoderConfig(config: AoqAudioCodecConfig): number
建议在 connect() 之前调用。使用 Opus(AoqEncoderTypeAudioOpus)需 SDK 内置或随包分发 PluginOpus 插件。

视频设备管理

startVideoCapture(config: AoqVideoCaptureConfig): number
stopVideoCapture(): number
打开/关闭视频采集设备。macOS 需在 Info.plist 中声明 NSCameraUsageDescription。当 config.isExternal=true 时不打开摄像头,由 pushExternalVideoCapturedFrame 送帧。
Electron renderer 为 Chromium 环境,无法嵌入原生视图,因此未提供 setLocalView / setRemoteView / switchCamera;预览请使用「帧观察者 + YUVCanvasRenderer」(见 2.13)。

视频编解码与外部输入

setVideoEncoderConfig(config: AoqVideoCodecConfig): number
setVideoDecoderConfig(config: AoqVideoCodecConfig): number
pushExternalVideoCapturedFrame(meta: AoqExternalVideoFrameMeta, buffer: Uint8Array): number
pushExternalVideoEncodedFrame(meta: AoqExternalVideoEncodedFrameMeta, buffer: Uint8Array): number
参数类型说明
metaAoqExternalVideoFrameMeta / AoqExternalVideoEncodedFrameMeta帧元信息(尺寸、格式、时间戳)
bufferUint8Array帧数据(像素数据或已编码数据)
  • pushExternalVideoCapturedFrame Video 轨道需先调用 startVideoCapture({ isExternal: true }),Screen 轨道需先调用 startScreenCapture({ isExternal: true });未开启时返回 211,缓冲区满时返回 210。
  • 支持 AoqVideoPixelFormatI420 与打包格式(NV12 / NV21 / BGRA / RGBA);I420 时 buffer 必须为紧凑布局(stride = width),Y / U / V 三平面顺序拼接。
  • pushExternalVideoEncodedFrame 需先 setVideoEncoderConfig({ isExternal: true });未开启时返回 212。当前仅支持 JPEG。
  • meta.timeStamp 为 0 时由 SDK 使用本地时间补齐。

屏幕采集

startScreenCapture(config: AoqScreenCaptureConfig): number
stopScreenCapture(): number
config 为屏幕采集配置。屏幕画面通过 AoqTrackTypeScreen 轨道发送。 返回值:0 表示成功;非 0 表示失败。 先调用 getScreenSourceList 获取屏幕或窗口源,再将选定的 sourceId 和 sourceType 传入采集配置。 外部原始帧:设置 isExternal=true 后,通过 pushExternalVideoCapturedFrame 输入 Screen 轨道的原始帧,由 SDK 编码。外部已编码帧:先通过 setVideoEncoderConfig 将 Screen 轨道设置为外部编码,再调用 pushExternalVideoEncodedFrame。

getScreenSourceList

getScreenSourceList(): AoqScreenSourceInfo[]
返回屏幕源数组,仅支持 Electron macOS/Windows。

媒体流发送控制

enableSendMediaStream(trackType: AoqTrackType, enable: boolean): number
trackType 支持 AoqTrackTypeAudio、AoqTrackTypeVideo 和 AoqTrackTypeScreen。 控制本地某路媒体流是否发送。建议初始化后先 enableSendMediaStream(trackType, false),待 onConnectionStatusChange 上报 AoqConnectionStatusConnected 后再开启。

音频文件播放

startAudioFile(config: AoqAudioFileMixConfig): number
stopAudioFile(fileId: string): number
pauseAudioFile(fileId: string): number
resumeAudioFile(fileId: string): number
getAudioFileDuration(fileId: string): number
getAudioFileCurrentPosition(fileId: string): number
setAudioFilePositionMillis(fileId: string, positionMs: number): number
setAudioFileVolume(fileId: string, type: AoqAudioStreamDirection, volume: number): number
getAudioFileVolume(fileId: string, type: AoqAudioStreamDirection): number
参数类型说明
configAoqAudioFileMixConfig文件混音配置,fileId 作为配置字段携带
fileIdstring文件标识,由调用方定义,后续接口以此定位
positionMsnumber目标播放位置(毫秒)
typeAoqAudioStreamDirection推流音量或本地播放音量
volumenumber音量,取值范围 0-100
返回值说明:
  • getAudioFileDuration / getAudioFileCurrentPosition 返回毫秒数;
  • getAudioFileVolume 返回当前音量值;
  • 上述 getter 在引擎未创建时返回 -1。
播放状态变化通过 onAudioFileState 事件上报。

外部音频流

addAudioExternalStream(config: AoqAudioExternalStreamConfig): number
removeAudioExternalStream(streamId: string): number
pushAudioExternalStreamData(meta: AoqAudioExternalFrameMeta, buffer: Uint8Array): number
setAudioExternalStreamVolume(streamId: string, type: AoqAudioStreamDirection, volume: number): number
getAudioExternalStreamVolume(streamId: string, type: AoqAudioStreamDirection): number
clearAudioExternalStreamBuffer(streamId: string, fadeoutMs: number): number
参数类型说明
configAoqAudioExternalStreamConfig外部音频流配置,streamId 作为配置字段携带
streamIdstring流标识,由调用方定义
metaAoqAudioExternalFrameMetaPCM 帧元信息,streamId 作为元信息字段携带
bufferUint8ArrayPCM 数据
fadeoutMsnumber清空缓存时的淡出时长(毫秒)
  • pushAudioExternalStreamData 缓存时长超过 maxBufferDuration 时返回 110(外部音频缓冲区满)。
  • getAudioExternalStreamVolume 返回当前音量值;引擎未创建时返回 -1。
  • clearAudioExternalStreamBuffer native 侧无返回值,调用成功固定返回 0。

实时消息

sendDataMsg(data: Uint8Array | string): number
发送实时数据消息。传入 string 时内部按 UTF-8 编码为 Buffer 后发送。对端消息通过 onDataMsg 事件回调。

音频帧回调

setAudioFrameObserver(enable: boolean): number
enableAudioFrameObserver(params: AoqAudioObserverParams): number
参数类型说明
enablebooleantrue 注册内置音频帧观察者,false 注销
paramsAoqAudioObserverParams指定回调位置、开关与回调格式
使用步骤:先 setAudioFrameObserver(true) 注册观察者,再对需要的位置调 enableAudioFrameObserver,数据通过对应事件下发。
engine.setAudioFrameObserver(true)
engine.enableAudioFrameObserver({
  enabled: true,
  audioSource: AoqAudioSource.AoqAudioSourceCaptured,
  sampleRate: 48000,
  channels: 1
})
engine.on('onCapturedAudioFrame', (frame) => { /* frame.buffer 为 PCM 数据 */ })
Electron 侧帧观察者仅支持只读模式,回调中不支持回写帧数据(native 内部固定 ReadOnly)。

本地音量提示

enableLocalAudioVolumeIndication(config: AoqAudioVolumeIndicationConfig): number
开启/关闭本地采集音量提示。config.interval <= 0 时关闭回调;开启后按 config.interval 周期触发 onLocalAudioVolumeIndication。需在 startAudioCapture() 之后调用才有音量数据。

视频帧回调

setVideoFrameObserver(enable: boolean): number
enableVideoFrameObserver(params: AoqVideoObserverParams): number
参数类型说明
enablebooleantrue 注册内置视频帧观察者,false 注销
paramsAoqVideoObserverParams指定回调位置、开关、像素格式与对齐策略
回调数据以 AoqVideoFrameEvent 形式通过 onCapturedVideoFrame / onPreEncodeVideoFrame / onRemoteVideoFrame 下发;I420 时 buffer 为 Y / U / V 三平面按 stride 拼接,其余打包格式为原数据透传。同样仅支持只读模式。

视频渲染(YUVCanvasRenderer)

SDK 内置的软渲染器。
import { YUVCanvasRenderer } from 'aoq-electron-sdk';

class YUVCanvasRenderer {
  bind(canvas: HTMLCanvasElement): void
  unbind(): void
  get bound(): boolean
  drawFrame(frame: AoqVideoFrameEvent): void
}
接口说明
bind绑定 canvas(重复绑定会替换 sink)
unbind解绑并清空画面
bound是否已绑定
drawFrame绘制一帧;仅支持 I420,非 I420 / 尺寸或 buffer 长度不足时静默返回
const renderer = new YUVCanvasRenderer()
renderer.bind(document.getElementById('preview'))

engine.setVideoFrameObserver(true)
engine.enableVideoFrameObserver({
  enabled: true,
  videoSource: AoqVideoSource.AoqVideoSourceCaptured,
  format: AoqVideoPixelFormat.AoqVideoPixelFormatI420
})
engine.on('onCapturedVideoFrame', (frame) => renderer.drawFrame(frame))
渲染填充模式(拉伸 / 裁剪等)用 CSS object-fit 控制 canvas 即可。

引擎事件(IAoqEngineEvents)

引擎继承 EventEmitter<IAoqEngineEvents>,事件是 SDK 所有异步通知的统一出口,与 native AoqEngineEventListener 回调一一对应。不关心的事件无需注册。
engine.on('onError', (code, message) => {})
engine.off('onError', handler)
engine.once('onStats', (stats) => {})
engine.removeAllListeners()

onError

onError: (code: number, message: string) => void
引擎错误回调。code 对应 AoqErrorCode 数值(见 3.3)。

onWarning

onWarning: (code: number, message: string) => void
引擎警告回调。code 对应 AoqWarningCode 数值(见 3.3)。

onConnectionStatusChange

onConnectionStatusChange: (status: AoqConnectionStatus) => void
连接状态变化回调。状态流转:Disconnected -> Connecting -> Connected / Failed -> Disconnected。

onStats

onStats: (stats: AoqStats) => void
引擎统计信息回调。SDK 周期性上报音视频推拉流及网络统计数据,可用于实时监测通话质量、网络状态、诊断音视频问题。
参数类型说明
statsAoqStats包含音频 / 视频 / 数据消息的推拉流统计及网络统计

onAudioDeviceStateChanged

onAudioDeviceStateChanged: (state: AoqAudioDeviceState) => void
音频设备采集 / 播放操作状态变化回调。

onAudioDeviceRouteChanged

onAudioDeviceRouteChanged: (routeType: number) => void
音频输出路由变化回调。routeType 对应 AoqAudioDeviceRouteType 数值(见 3.4)。

onAudioFileState

onAudioFileState: (state: AoqAudioFileState) => void
音频文件播放状态回调。

onLocalAudioVolumeIndication

onLocalAudioVolumeIndication: (volume: AoqAudioVolume) => void
本地采集音量提示回调,需调用 enableLocalAudioVolumeIndication 开启。

onVideoDeviceStateChanged

onVideoDeviceStateChanged: (state: AoqVideoDeviceState) => void
视频设备采集操作状态变化回调。

onDataMsg

onDataMsg: (data: Uint8Array) => void
收到实时数据消息回调。data 为 native 侧拷贝后的 Buffer,可安全异步持有;文本消息用 Buffer.from(data).toString() 转字符串。

音频帧事件

onCapturedAudioFrame:        (frame: AoqAudioFrameEvent) => void  /* 采集裸数据 */
onProcessCapturedAudioFrame: (frame: AoqAudioFrameEvent) => void  /* 3A 后数据 */
onPublishAudioFrame:         (frame: AoqAudioFrameEvent) => void  /* 推流数据 */
onPlaybackAudioFrame:        (frame: AoqAudioFrameEvent) => void  /* 播放数据 */
需先调 setAudioFrameObserver(true) 与 enableAudioFrameObserver 开启。

onCapturedAudioFrame

采集到原始音频帧时触发。数据为采集后的原始 PCM,未经任何处理。
engine.on('onCapturedAudioFrame', (frame: AoqAudioFrameEvent) => { ... })
参数类型说明
frameAoqAudioFrameEvent采集的音频帧数据,PCM 在 frame.buffer 字段
返回值:无(void)。Electron 侧为只读模式。
frame.buffer 为 Uint8Array,引用 SDK 内部内存,仅在回调期间有效,异步使用需自行拷贝。

onProcessCapturedAudioFrame

3A 处理后的音频帧回调。数据经过回声消除、噪声抑制、自动增益等 3A 处理。
engine.on('onProcessCapturedAudioFrame', (frame: AoqAudioFrameEvent) => { ... })
参数类型说明
frameAoqAudioFrameEvent3A 处理后的音频帧数据,PCM 在 frame.buffer 字段
返回值:无(void)。Electron 侧为只读模式。
frame.buffer 为 Uint8Array,引用 SDK 内部内存,仅在回调期间有效,异步使用需自行拷贝。

onPublishAudioFrame

推流前的音频帧回调。数据即将通过编码后发送到 Relay 服务器。
engine.on('onPublishAudioFrame', (frame: AoqAudioFrameEvent) => { ... })
参数类型说明
frameAoqAudioFrameEvent推流前的音频帧数据,PCM 在 frame.buffer 字段
返回值:无(void)。Electron 侧为只读模式。
frame.buffer 为 Uint8Array,引用 SDK 内部内存,仅在回调期间有效,异步使用需自行拷贝。

onPlaybackAudioFrame

播放前的远端音频帧回调。数据为远端解码后、混音前即将播放的音频。
engine.on('onPlaybackAudioFrame', (frame: AoqAudioFrameEvent) => { ... })
参数类型说明
frameAoqAudioFrameEvent播放前的远端音频帧数据,PCM 在 frame.buffer 字段
返回值:无(void)。Electron 侧为只读模式。
frame.buffer 为 Uint8Array,引用 SDK 内部内存,仅在回调期间有效,异步使用需自行拷贝。

视频帧事件

onCapturedVideoFrame:  (frame: AoqVideoFrameEvent) => void  /* 采集后(前处理前) */
onPreEncodeVideoFrame: (frame: AoqVideoFrameEvent) => void  /* 编码前(前处理后) */
onRemoteVideoFrame:    (frame: AoqVideoFrameEvent) => void  /* 远端解码后、渲染前 */
需先调 setVideoFrameObserver(true) 与 enableVideoFrameObserver 开启。帧事件为只读,回调中修改 buffer 不会写回 SDK。
事件回调中避免重计算:native 回调经异步线程投递到 JS 主线程,高频帧事件中做耗时操作会造成堆积。

onCapturedVideoFrame

采集到原始视频帧时触发(前处理前)。数据为摄像头或屏幕采集后的原始帧,未经前处理。
engine.on('onCapturedVideoFrame', (frame: AoqVideoFrameEvent) => { ... })
参数类型说明
frameAoqVideoFrameEvent采集的视频帧数据
返回值:无(void)。Electron 侧为只读模式。
frame.buffer 为 Uint8Array,引用 SDK 内部内存,仅在回调期间有效,异步使用需自行拷贝。

onPreEncodeVideoFrame

编码前的视频帧回调(前处理后)。数据经过前处理后、编码前。
engine.on('onPreEncodeVideoFrame', (frame: AoqVideoFrameEvent) => { ... })
参数类型说明
frameAoqVideoFrameEvent编码前的视频帧数据
返回值:无(void)。Electron 侧为只读模式。
frame.buffer 为 Uint8Array,引用 SDK 内部内存,仅在回调期间有效,异步使用需自行拷贝。

onRemoteVideoFrame

远端解码后、渲染前的视频帧回调。数据为远端接收并解码后的视频帧。
engine.on('onRemoteVideoFrame', (frame: AoqVideoFrameEvent) => { ... })
参数类型说明
frameAoqVideoFrameEvent远端解码后的视频帧数据
返回值:无(void)。Electron 侧为只读模式。
frame.buffer 为 Uint8Array,引用 SDK 内部内存,仅在回调期间有效,异步使用需自行拷贝。

数据类型与枚举

通用类型

AoqCreateConfig

字段类型必填默认值说明
workDirstring否""SDK 工作目录(日志与临时文件)
enableDumpAudioboolean否false是否开启音频数据保存(调试用)
extrasstring否""扩展参数(JSON 字符串)

AoqConnectConfig

字段类型必填默认值说明
tokenstring是-连接鉴权 Token
sidstring是-会话 ID
certFingerprintstring否""服务器证书指纹
workspaceIdHashstring否空工作空间 ID Hash;空字符串等同不传
relayEndpointsArray是-Relay 接入点列表
publishTracksArray是-本端发布轨道列表
subscribeTracksArray是-本端订阅轨道列表

AoqRelayEndpoint

字段类型必填默认值说明
routeIndexnumber否-1路由序号
endpointstring是-Relay 服务器域名或 IP
portnumber是-Relay 服务器端口
tcpPortnumber否0TCP 降级端口;0 表示使用 SDK 默认端口 443。

AoqTrackParam

字段类型必填默认值说明
trackTypeAoqTrackType是-轨道类型
trackModeAoqTrackMode否AoqTrackModeSegment流式 / 非流式模式,仅对音频下行生效

统计信息类型

AoqStats

引擎统计信息汇总,通过 onStats 周期性上报。数组字段无数据时为空数组,networkStats 无数据时不下发。
字段类型说明
audioPublishStatsArray音频推流统计
videoPublishStatsArray视频推流统计
dataMsgPublishStatsArray数据消息推流统计
audioSubscribeStatsArray音频拉流统计
videoSubscribeStatsArray视频拉流统计
dataMsgSubscribeStatsArray数据消息拉流统计
networkStatsAoqNetworkStats网络统计信息

AoqAudioPublishStats

字段类型说明
trackTypeAoqTrackType轨道类型
bitratenumber码率(bps)
bytesnumber累计发送字节数
encodeVolumenumber推流编码音量

AoqAudioSubscribeStats

字段类型说明
trackTypeAoqTrackType轨道类型
bitratenumber码率(bps)
bytesnumber累计接收字节数
playVolumenumber播放音量

AoqVideoPublishStats

字段类型说明
trackTypeAoqTrackType轨道类型
bitratenumber码率(bps)
bytesnumber累计发送字节数
encodeFpsnumber编码帧率

AoqVideoSubscribeStats

字段类型说明
trackTypeAoqTrackType轨道类型
bitratenumber码率(bps)
bytesnumber累计接收字节数
decodeFpsnumber解码帧率
renderFpsnumber渲染帧率

AoqDataMsgPublishStats / AoqDataMsgSubscribeStats

字段类型说明
trackTypeAoqTrackType轨道类型
bitratenumber码率(bps)
bytesnumber累计发送 / 接收字节数

AoqNetworkStats

字段类型说明
sendBitratenumber发送码率(bps)
sendBytesnumber累计发送字节数
recvBitratenumber接收码率(bps)
recvBytesnumber累计接收字节数
lossnumber丢包率(0-100)
rttnumber往返延迟(ms)

枚举类型

AoqTrackType

枚举值值说明
AoqTrackTypeAudio0音频轨道
AoqTrackTypeVideo1视频轨道
AoqTrackTypeData2数据消息轨道
AoqTrackTypeScreen3屏幕共享轨道,仅支持上行。

AoqTrackMode

枚举值值说明
AoqTrackModeSegment0分段:数据按语义片段(如一句话)打包送达
AoqTrackModeStream1流式:数据持续、连续地送达

AoqEncoderType

枚举值值说明
AoqEncoderTypeUnknown0未知格式
AoqEncoderTypeAudioPCM1音频 PCM
AoqEncoderTypeAudioOpus2音频 Opus(插件化,需 PluginOpus)
AoqEncoderTypeVideoH2643视频 H.264
AoqEncoderTypeVideoJpeg4视频 JPEG
AoqEncoderTypeDataText5数据文本

AoqConnectionStatus

枚举值值说明
AoqConnectionStatusDisconnected0未连接
AoqConnectionStatusConnecting1连接中
AoqConnectionStatusConnected2已连接
AoqConnectionStatusFailed3连接失败

AoqMirrorMode

枚举值值说明
AoqMirrorModeDisabled0关闭镜像
AoqMirrorModeEnabled1开启镜像

AoqOrientationMode

枚举值值说明
AoqOrientationModeAuto0自动适应
AoqOrientationModePortrait1竖屏
AoqOrientationModeLandscape2横屏

AoqErrorCode

下表列出底层 C++ 引擎的错误码名称。Electron TypeScript 层不导出此枚举,onError 的 code 类型为 number。 错误码为 native 层定义,onError 的 code 与接口返回值均使用该数值(TS 层未将其导出为 enum)。
枚举值值说明
AoqECOK0成功
AoqECParamInvalid1参数非法
AoqECStateInvalid2状态非法
AoqECUnSupport3当前平台 / 模式不支持
AoqECAudio100音频通用错误
AoqECAudioExternalBufferFull110外部音频缓冲区满
AoqECAudioDevice120音频设备通用错误
AoqECAudioDeviceRecordingAuthFailed121录音权限未获取
AoqECAudioDeviceRecordingOccupied122录音设备被占用
AoqECAudioDeviceRecordingBackgroundStart123后台启动录音失败
AoqECAudioDeviceRecordingStartFail124录音启动失败
AoqECAudioDevicePlayoutOccupied125播放设备被占用
AoqECAudioDevicePlayoutBackgroundStart126后台启动播放失败
AoqECAudioDevicePlayoutStartFail127播放启动失败
AoqECVideo200视频通用错误
AoqECVideoExternalBufferFull210外部视频缓冲区满
AoqECVideoExternalCaptureNotEnabled211外部视频采集未启用
AoqECVideoExternalEncoderNotEnabled212外部视频编码未启用
AoqECVideoDevice220视频设备通用错误
AoqECVideoDeviceCameraOpenFail221摄像头打开失败
AoqECVideoDeviceCameraAuthFailed222摄像头权限未获取
AoqECVideoDeviceCameraOccupied223摄像头被占用
AoqECVideoDeviceCameraRunningError224摄像头运行异常
AoqECVideoCodec230视频编解码通用错误
AoqECVideoCodecEncoderInitFail231视频编码器初始化失败
AoqECVideoRender240视频渲染通用错误
AoqECVideoRenderCreateFail241视频渲染创建失败
AoqECVideoRenderDrawError242视频渲染绘制错误
AoqECScreen300屏幕共享通用错误
AoqECScreenAuthFailed310屏幕共享授权失败
AoqECScreenStartFailed311屏幕共享启动失败
AoqECAudioDeviceEarpieceRequiresVoipMode128听筒需要 VoIP 模式(移动端场景,Electron 一般不会触发)。
除上述 native 错误码外,Electron 层还会在引擎未创建 / 已销毁、或参数不是合法 JSON 时返回 -1。

AoqWarningCode

枚举值值说明
AoqWCOK0无警告
AoqWCAudio100音频通用警告
AoqWCAudioHowling101音频啸叫检测
AoqWCAudioDevice120音频设备通用警告
AoqWCAudioDeviceMicEnumerateError121麦克风枚举错误
AoqWCAudioDeviceMicStartTimeout122麦克风启动超时
AoqWCAudioDeviceRecordingError123录音过程错误
AoqWCAudioDeviceSpeakerEnumerateError124扬声器枚举错误
AoqWCAudioDeviceSpeakerStartTimeout125扬声器启动超时
AoqWCAudioDevicePlayoutError126播放过程错误
AoqWCVideo200视频通用警告
AoqWCVideoCameraEnumerateError201摄像头枚举错误
AoqWCVideoEncoderSwitched202视频编码器已切换
AoqWCVideoRenderDowngrade203视频渲染降级

音频类型

AoqAudioCaptureConfig

字段类型必填默认值说明
isExternalboolean否false是否为外部采集模式
channelnumber否1音频采集通道数,支持 1 / 2

AoqAudioPlaybackConfig

字段类型必填默认值说明
isExternalboolean否false是否为外部播放模式
channelnumber否1音频播放通道数,支持 1 / 2

AoqAudioCodecConfig

字段类型必填默认值说明
trackTypeAoqTrackType否AoqTrackTypeAudio轨道类型
codecTypeAoqEncoderType否AoqEncoderTypeAudioOpus编码格式
sampleRatenumber否48000采样率(Hz)。编码支持 Opus 8/16/48K、PCM 8/16/32/48K;解码额外支持 24K(仅 Segment 模式)
channelnumber否1声道数,支持 1 / 2
bitratenumber否32000比特率(bps)

AoqAudioDeviceRouteType

onAudioDeviceRouteChanged 的 routeType 取值(native 定义,TS 层未导出为 enum)。
枚举值值说明
AoqAudioDeviceRouteDefault0默认路由
AoqAudioDeviceRouteHeadset1有麦克风的头戴设备
AoqAudioDeviceRouteEarpiece2听筒
AoqAudioDeviceRouteHeadsetNoMic3无麦克风的头戴设备
AoqAudioDeviceRouteSpeakerPhone4扬声器
AoqAudioDeviceRouteUsb5USB 音频设备
AoqAudioDeviceRouteBluetooth6蓝牙 SCO 模式
AoqAudioDeviceRouteBluetoothA2dp7蓝牙 A2DP 模式

AoqAudioDeviceStateCode

枚举值值说明
AoqAudioDeviceNone0无状态
AoqAudioDeviceRecordStarting1采集启动中
AoqAudioDeviceRecordStarted2采集已启动
AoqAudioDeviceRecordStopping3采集停止中
AoqAudioDeviceRecordStopped4采集已停止
AoqAudioDeviceRecordFail5采集失败
AoqAudioDevicePlayStarting6播放启动中
AoqAudioDevicePlayStarted7播放已启动
AoqAudioDevicePlayStopping8播放停止中
AoqAudioDevicePlayStopped9播放已停止
AoqAudioDevicePlayFail10播放失败

AoqAudioDeviceState

字段类型说明
stateAoqAudioDeviceStateCode设备操作状态
reasonnumber错误原因代码(参考 AoqErrorCode)

音频文件类型

AoqAudioFileMixConfig

字段类型必填默认值说明
fileIdstring是-文件标识符,后续接口以此定位
fileNamestring是-文件名(含路径)
cyclesnumber否-1循环次数,-1 表示无限循环
startPosMsnumber否0起始播放位置(毫秒)
publishVolumenumber否100推流音量,取值范围 0-100
playoutVolumenumber否100播放音量,取值范围 0-100

AoqAudioFileStateCode

枚举值值说明
AoqAudioFileNone0无状态
AoqAudioFileStarted1播放已启动
AoqAudioFileStopped2播放已停止
AoqAudioFilePaused3播放已暂停
AoqAudioFileResumed4播放已恢复
AoqAudioFileEnded5播放已结束
AoqAudioFileBuffering6播放缓冲中
AoqAudioFileBufferingEnd7缓冲结束
AoqAudioFileFailed8播放失败

AoqAudioFileErrorCode

AoqAudioFileState.errorCode 的取值(native 定义,TS 层作为 number 下发)。
枚举值值说明
AoqAudioFileNoError0无错误
AoqAudioFileOpenFailed1文件打开失败
AoqAudioFileDecodeFailed2文件解码失败

AoqAudioFileState

字段类型说明
fileIdstring文件标识符
stateCodeAoqAudioFileStateCode文件播放状态码
errorCodenumber文件错误码(参考 AoqAudioFileErrorCode)

外部音频流类型

AoqAudioStreamDirection

枚举值值说明
AoqAudioStreamPublish0发布流(推流)
AoqAudioStreamPlayout1播放流(本地播放)

AoqAudioExternalStreamConfig

字段类型必填默认值说明
streamIdstring是-流标识符
trackTypeAoqTrackType否AoqTrackTypeAudio音频轨道类型
codecTypeAoqEncoderType否AoqEncoderTypeAudioPCM音频流格式,当前支持 PCM
channelsnumber否1声道数,受限推流 Codec,支持 1 / 2
sampleRatenumber否48000采样率(Hz),支持 8/12/16/24/32/44.1/48/64/88.2/96/176.4/192K
playoutVolumenumber否100播放音量,取值范围 0-100
publishVolumenumber否100推流音量,取值范围 0-100
maxBufferDurationnumber否600000最大缓冲时长(毫秒),取值范围 100 以上;超过时 push 失败
enable3Aboolean否false是否对输入 PCM 做 3A 处理

AoqAudioExternalFrameMeta

外部音频帧元信息,PCM 数据另走 buffer 参数。
字段类型必填默认值说明
streamIdstring是-目标外部音频流标识
numOfSamplesnumber是0采样点数(单声道)
bytesPerSamplenumber是2每个采样点的字节数
numOfChannelsnumber是1声道数
samplesPerSecnumber是48000每秒采样点数(采样率)
pushSequencenumber否0PCM 输入轮次
timeStampnumber否0时间戳

AoqAudioFrameEvent

音频帧观察者事件数据。
字段类型说明
trackTypeAoqTrackType轨道类型
numOfSamplesnumber采样点数(单声道)
bytesPerSamplenumber每个采样点的字节数
numOfChannelsnumber声道数
samplesPerSecnumber每秒采样点数(采样率)
timeStampnumber时间戳
autoGenMutebooleantrue 表示 SDK 生成的静音数据
bufferUint8Array音频 PCM 数据(native 侧已拷贝)

AoqAudioSource

枚举值值说明
AoqAudioSourceCaptured0采集的音频数据
AoqAudioSourceProcessCaptured13A 处理后的音频数据
AoqAudioSourcePublish2推流的音频数据(需 connect 成功)
AoqAudioSourcePlayback3播放的音频数据

AoqAudioObserverParams

字段类型必填默认值说明
enabledboolean是false开启或关闭该位置的回调
audioSourceAoqAudioSource是AoqAudioSourceCaptured回调位置
sampleRatenumber否48000回调音频采样率(Hz),不一致时重采样
channelsnumber否1回调音频声道数,支持 1 / 2
回调模式固定为只读,Electron 不开放读写模式。

AoqAudioVolumeIndicationConfig

字段类型必填默认值说明
intervalnumber否0回调间隔(毫秒);小于等于 0 表示关闭回调,大于 0 且小于 10 时按 10 处理
smoothnumber否3音量平滑系数,取值越大越平滑,取值范围 0-10

AoqAudioVolume

字段类型说明
volumenumber平滑后的瞬时音量,取值范围 0-255

视频类型

AoqVideoCaptureConfig

字段类型必填默认值说明
widthnumber否1280采集宽度(像素),isExternal=true 时无效
heightnumber否720采集高度(像素),isExternal=true 时无效
fpsnumber否15采集帧率,isExternal=true 时无效(节奏由送帧决定)
isExternalboolean否false是否外部采集,true 时不打开摄像头

AoqVideoCodecConfig

编码与解码共用同一结构(setVideoEncoderConfig / setVideoDecoderConfig)。
字段类型必填默认值说明
isExternalboolean否falsetrue 时 SDK 不做采集与编码,由 pushExternalVideoEncodedFrame 直推
trackTypeAoqTrackType否AoqTrackTypeVideo轨道类型
codecTypeAoqEncoderType否AoqEncoderTypeVideoH264编码格式
widthnumber否540编码宽度(像素)
heightnumber否960编码高度(像素)
fpsnumber否5编码帧率
bitratenumber否500000起始比特率(bps)
minBitratenumber否128000最小比特率(bps)
keyframeIntervalnumber否2关键帧间隔(秒)
mirrorModeAoqMirrorMode否AoqMirrorModeDisabled镜像模式
orientationModeAoqOrientationMode否AoqOrientationModeAuto视频方向模式

AoqVideoPixelFormat

Electron 支持的像素格式。
枚举值值说明
AoqVideoPixelFormatUnknown0未知格式
AoqVideoPixelFormatI4201I420(YUV 三平面格式)
AoqVideoPixelFormatNV122NV12(YUV 半平面格式)
AoqVideoPixelFormatNV213NV21(YUV 半平面格式)
AoqVideoPixelFormatBGRA4BGRA(32 位)
AoqVideoPixelFormatRGBA5RGBA(32 位)

AoqExternalVideoFrameMeta

外部视频裸帧元信息,像素数据另走 buffer 参数。
字段类型必填默认值说明
trackTypeAoqTrackType否AoqTrackTypeVideo轨道类型
;支持 Video / Screen 路由
formatAoqVideoPixelFormat是-像素格式
widthnumber是-视频宽度(像素)
heightnumber是-视频高度(像素)
timeStampnumber否0时间戳(毫秒);0 时 SDK 使用本地时间补齐
format = I420 时 buffer 必须为紧凑布局(stride = width),Y / U / V 三平面顺序拼接;其余打包格式直接传整帧字节。

AoqVideoCodecType

枚举值值说明
AoqVideoCodecTypeJPEG0JPEG 编码

AoqExternalVideoEncodedFrameMeta

外部已编码视频帧元信息,编码数据另走 buffer 参数。
字段类型必填默认值说明
trackTypeAoqTrackType否AoqTrackTypeVideo轨道类型
;支持 Video / Screen 路由
codecAoqVideoCodecType否AoqVideoCodecTypeJPEG编码格式
widthnumber是-宽度(像素)
heightnumber是-高度(像素)
timeStampnumber否0时间戳(毫秒);0 时 SDK 使用本地时间补齐

AoqVideoDeviceStateCode

枚举值值说明
AoqVideoDeviceNone0无状态
AoqVideoDeviceCaptureStarting1采集启动中
AoqVideoDeviceCaptureStarted2采集已启动
AoqVideoDeviceCaptureStopping3采集停止中
AoqVideoDeviceCaptureStopped4采集已停止
AoqVideoDeviceCaptureFail5采集失败(权限拒绝、设备不可用等)

AoqVideoDeviceState

字段类型说明
stateAoqVideoDeviceStateCode设备采集操作状态
reasonnumber错误原因代码(参考 AoqErrorCode)

AoqScreenShareSourceType

枚举值值说明
AoqScreenShareSourceTypeDesktop0整个桌面
AoqScreenShareSourceTypeWindow1指定窗口

AoqScreenSourceInfo

字段类型说明
sourceTypeAoqScreenShareSourceType源类型
sourceIdstring源 ID,以字符串返回以避免 int64 精度丢失。
sourceNamestring源名称
sourceIsSelfboolean是否为自身进程窗口

AoqScreenCaptureConfig

所有字段均可选,isExternal 默认 false。
字段类型默认值说明
isExternalbooleanfalse是否由应用提供屏幕原始帧。
sourceIdstring | number—屏幕源 ID。可选;推荐字符串,number 必须为安全整数。
sourceTypeAoqScreenShareSourceType—屏幕源类型。
除用于对照底层错误码、未由 TypeScript 导出的 AoqErrorCode 外,本节类型均从包根导出,可直接 import { ... } from 'aoq-electron-sdk'。已导出的枚举为 TypeScript enum,运行时可用;接口(interface)仅类型约束。标记为可选的字段缺省时取表中默认值。

视频帧回调类型

AoqVideoSource

枚举值值说明
AoqVideoSourceCaptured0采集后的视频数据(前处理前)
AoqVideoSourcePreEncode1编码前的视频数据(前处理后)
AoqVideoSourceRemote2远端解码后、渲染前的视频数据

AoqVideoObserverAlignment

枚举值值说明
AoqVideoObserverAlignmentDefault0默认对齐
AoqVideoObserverAlignmentEven1偶数对齐
AoqVideoObserverAlignment424 字节对齐
AoqVideoObserverAlignment838 字节对齐
AoqVideoObserverAlignment16416 字节对齐

AoqVideoObserverParams

字段类型必填默认值说明
enabledboolean是false开启或关闭该位置的回调
videoSourceAoqVideoSource是AoqVideoSourceCaptured回调位置
formatAoqVideoPixelFormat否AoqVideoPixelFormatI420期望回调像素格式
alignmentAoqVideoObserverAlignment否AoqVideoObserverAlignmentDefault宽度对齐策略
mirrorAppliedboolean否false是否对回调数据应用镜像
trackTypeAoqTrackType否AoqTrackTypeVideo需要观察的视频轨道;仅支持 Video / Screen。
回调模式固定为只读,Electron 不开放读写模式。使用内置 YUVCanvasRenderer 渲染时需选 I420。

AoqVideoFrameEvent

视频帧观察者事件数据。
字段类型说明
trackTypeAoqTrackType轨道类型
formatAoqVideoPixelFormat像素格式
widthnumber宽度(像素)
heightnumber高度(像素)
strideYnumberY 平面行跨度(仅 I420 有效)
strideUnumberU 平面行跨度(仅 I420 有效)
strideVnumberV 平面行跨度(仅 I420 有效)
timeStampnumber时间戳(毫秒)
bufferUint8Array帧数据;I420 为 Y / U / V 三平面按 stride 拼接,其余打包格式为原数据透传

数据消息类型

Electron 不使用 AoqDataMsg 包装类型,数据消息直接以二进制收发:
方向类型说明
发送Uint8Array 或 stringsendDataMsg(data);字符串按 UTF-8 编码
接收Uint8ArrayonDataMsg(data);native 侧已拷贝,可异步持有