Skip to main content

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

参数

类型

说明

config

AoqCreateConfig

引擎创建配置

返回值: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

参数

类型

说明

config

AoqConnectConfig

连接配置,包含 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
打断本轮音频通话,丢弃已缓存的本轮下行数据。

参数

类型

说明

trackType

AoqTrackType

轨道类型

fadeMs

number

淡出时长(毫秒)

音频编解码配置

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

参数

类型

说明

meta

AoqExternalVideoFrameMeta / AoqExternalVideoEncodedFrameMeta

帧元信息(尺寸、格式、时间戳)

buffer

Uint8Array

帧数据(像素数据或已编码数据)

  • 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

参数

类型

说明

config

AoqAudioFileMixConfig

文件混音配置,fileId 作为配置字段携带

fileId

string

文件标识,由调用方定义,后续接口以此定位

positionMs

number

目标播放位置(毫秒)

type

AoqAudioStreamDirection

推流音量或本地播放音量

volume

number

音量,取值范围 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

参数

类型

说明

config

AoqAudioExternalStreamConfig

外部音频流配置,streamId 作为配置字段携带

streamId

string

流标识,由调用方定义

meta

AoqAudioExternalFrameMeta

PCM 帧元信息,streamId 作为元信息字段携带

buffer

Uint8Array

PCM 数据

fadeoutMs

number

清空缓存时的淡出时长(毫秒)

  • 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

参数

类型

说明

enable

boolean

true 注册内置音频帧观察者,false 注销

params

AoqAudioObserverParams

指定回调位置、开关与回调格式

使用步骤:先 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

参数

类型

说明

enable

boolean

true 注册内置视频帧观察者,false 注销

params

AoqVideoObserverParams

指定回调位置、开关、像素格式与对齐策略

回调数据以 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 周期性上报音视频推拉流及网络统计数据,可用于实时监测通话质量、网络状态、诊断音视频问题。

参数

类型

说明

stats

AoqStats

包含音频 / 视频 / 数据消息的推拉流统计及网络统计

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

字段

类型

必填

默认值

说明

workDir

string

否

""

SDK 工作目录(日志与临时文件)

enableDumpAudio

boolean

否

false

是否开启音频数据保存(调试用)

extras

string

否

""

扩展参数(JSON 字符串)

AoqConnectConfig

字段

类型

必填

默认值

说明

token

string

是

-

连接鉴权 Token

sid

string

是

-

会话 ID

certFingerprint

string

否

""

服务器证书指纹

workspaceIdHash

string

否

空

工作空间 ID Hash;空字符串等同不传

relayEndpoints

Array

是

-

Relay 接入点列表

publishTracks

Array

是

-

本端发布轨道列表

subscribeTracks

Array

是

-

本端订阅轨道列表

AoqRelayEndpoint

字段

类型

必填

默认值

说明

routeIndex

number

否

-1

路由序号

endpoint

string

是

-

Relay 服务器域名或 IP

port

number

是

-

Relay 服务器端口

tcpPortnumber否0TCP 降级端口;0 表示使用 SDK 默认端口 443。

AoqTrackParam

字段

类型

必填

默认值

说明

trackType

AoqTrackType

是

-

轨道类型

trackMode

AoqTrackMode

否

AoqTrackModeSegment

流式 / 非流式模式,仅对音频下行生效

统计信息类型

AoqStats

引擎统计信息汇总,通过 onStats 周期性上报。数组字段无数据时为空数组,networkStats 无数据时不下发。

字段

类型

说明

audioPublishStats

Array

音频推流统计

videoPublishStats

Array

视频推流统计

dataMsgPublishStats

Array

数据消息推流统计

audioSubscribeStats

Array

音频拉流统计

videoSubscribeStats

Array

视频拉流统计

dataMsgSubscribeStats

Array

数据消息拉流统计

networkStats

AoqNetworkStats

网络统计信息

AoqAudioPublishStats

字段

类型

说明

trackType

AoqTrackType

轨道类型

bitrate

number

码率(bps)

bytes

number

累计发送字节数

encodeVolume

number

推流编码音量

AoqAudioSubscribeStats

字段

类型

说明

trackType

AoqTrackType

轨道类型

bitrate

number

码率(bps)

bytes

number

累计接收字节数

playVolume

number

播放音量

AoqVideoPublishStats

字段

类型

说明

trackType

AoqTrackType

轨道类型

bitrate

number

码率(bps)

bytes

number

累计发送字节数

encodeFps

number

编码帧率

AoqVideoSubscribeStats

字段

类型

说明

trackType

AoqTrackType

轨道类型

bitrate

number

码率(bps)

bytes

number

累计接收字节数

decodeFps

number

解码帧率

renderFps

number

渲染帧率

AoqDataMsgPublishStats / AoqDataMsgSubscribeStats

字段

类型

说明

trackType

AoqTrackType

轨道类型

bitrate

number

码率(bps)

bytes

number

累计发送 / 接收字节数

AoqNetworkStats

字段

类型

说明

sendBitrate

number

发送码率(bps)

sendBytes

number

累计发送字节数

recvBitrate

number

接收码率(bps)

recvBytes

number

累计接收字节数

loss

number

丢包率(0-100)

rtt

number

往返延迟(ms)

枚举类型

AoqTrackType

枚举值

值

说明

AoqTrackTypeAudio

0

音频轨道

AoqTrackTypeVideo

1

视频轨道

AoqTrackTypeData

2

数据消息轨道

AoqTrackTypeScreen3屏幕共享轨道,仅支持上行。

AoqTrackMode

枚举值

值

说明

AoqTrackModeSegment

0

分段:数据按语义片段(如一句话)打包送达

AoqTrackModeStream

1

流式:数据持续、连续地送达

AoqEncoderType

枚举值

值

说明

AoqEncoderTypeUnknown

0

未知格式

AoqEncoderTypeAudioPCM

1

音频 PCM

AoqEncoderTypeAudioOpus

2

音频 Opus(插件化,需 PluginOpus)

AoqEncoderTypeVideoH264

3

视频 H.264

AoqEncoderTypeVideoJpeg

4

视频 JPEG

AoqEncoderTypeDataText

5

数据文本

AoqConnectionStatus

枚举值

值

说明

AoqConnectionStatusDisconnected

0

未连接

AoqConnectionStatusConnecting

1

连接中

AoqConnectionStatusConnected

2

已连接

AoqConnectionStatusFailed

3

连接失败

AoqMirrorMode

枚举值

值

说明

AoqMirrorModeDisabled

0

关闭镜像

AoqMirrorModeEnabled

1

开启镜像

AoqOrientationMode

枚举值

值

说明

AoqOrientationModeAuto

0

自动适应

AoqOrientationModePortrait

1

竖屏

AoqOrientationModeLandscape

2

横屏

AoqErrorCode

下表列出底层 C++ 引擎的错误码名称。Electron TypeScript 层不导出此枚举,onError 的 code 类型为 number。 错误码为 native 层定义,onError 的 code 与接口返回值均使用该数值(TS 层未将其导出为 enum)。

枚举值

值

说明

AoqECOK

0

成功

AoqECParamInvalid

1

参数非法

AoqECStateInvalid

2

状态非法

AoqECUnSupport

3

当前平台 / 模式不支持

AoqECAudio

100

音频通用错误

AoqECAudioExternalBufferFull

110

外部音频缓冲区满

AoqECAudioDevice

120

音频设备通用错误

AoqECAudioDeviceRecordingAuthFailed

121

录音权限未获取

AoqECAudioDeviceRecordingOccupied

122

录音设备被占用

AoqECAudioDeviceRecordingBackgroundStart

123

后台启动录音失败

AoqECAudioDeviceRecordingStartFail

124

录音启动失败

AoqECAudioDevicePlayoutOccupied

125

播放设备被占用

AoqECAudioDevicePlayoutBackgroundStart

126

后台启动播放失败

AoqECAudioDevicePlayoutStartFail

127

播放启动失败

AoqECVideo

200

视频通用错误

AoqECVideoExternalBufferFull

210

外部视频缓冲区满

AoqECVideoExternalCaptureNotEnabled

211

外部视频采集未启用

AoqECVideoExternalEncoderNotEnabled

212

外部视频编码未启用

AoqECVideoDevice

220

视频设备通用错误

AoqECVideoDeviceCameraOpenFail

221

摄像头打开失败

AoqECVideoDeviceCameraAuthFailed

222

摄像头权限未获取

AoqECVideoDeviceCameraOccupied

223

摄像头被占用

AoqECVideoDeviceCameraRunningError

224

摄像头运行异常

AoqECVideoCodec

230

视频编解码通用错误

AoqECVideoCodecEncoderInitFail

231

视频编码器初始化失败

AoqECVideoRender

240

视频渲染通用错误

AoqECVideoRenderCreateFail

241

视频渲染创建失败

AoqECVideoRenderDrawError

242

视频渲染绘制错误

AoqECScreen300屏幕共享通用错误
AoqECScreenAuthFailed310屏幕共享授权失败
AoqECScreenStartFailed311屏幕共享启动失败
AoqECAudioDeviceEarpieceRequiresVoipMode128听筒需要 VoIP 模式(移动端场景,Electron 一般不会触发)。
除上述 native 错误码外,Electron 层还会在引擎未创建 / 已销毁、或参数不是合法 JSON 时返回 -1。

AoqWarningCode

枚举值

值

说明

AoqWCOK

0

无警告

AoqWCAudio

100

音频通用警告

AoqWCAudioHowling

101

音频啸叫检测

AoqWCAudioDevice

120

音频设备通用警告

AoqWCAudioDeviceMicEnumerateError

121

麦克风枚举错误

AoqWCAudioDeviceMicStartTimeout

122

麦克风启动超时

AoqWCAudioDeviceRecordingError

123

录音过程错误

AoqWCAudioDeviceSpeakerEnumerateError

124

扬声器枚举错误

AoqWCAudioDeviceSpeakerStartTimeout

125

扬声器启动超时

AoqWCAudioDevicePlayoutError

126

播放过程错误

AoqWCVideo

200

视频通用警告

AoqWCVideoCameraEnumerateError

201

摄像头枚举错误

AoqWCVideoEncoderSwitched

202

视频编码器已切换

AoqWCVideoRenderDowngrade

203

视频渲染降级

音频类型

AoqAudioCaptureConfig

字段

类型

必填

默认值

说明

isExternal

boolean

否

false

是否为外部采集模式

channel

number

否

1

音频采集通道数,支持 1 / 2

AoqAudioPlaybackConfig

字段

类型

必填

默认值

说明

isExternal

boolean

否

false

是否为外部播放模式

channel

number

否

1

音频播放通道数,支持 1 / 2

AoqAudioCodecConfig

字段

类型

必填

默认值

说明

trackType

AoqTrackType

否

AoqTrackTypeAudio

轨道类型

codecType

AoqEncoderType

否

AoqEncoderTypeAudioOpus

编码格式

sampleRate

number

否

48000

采样率(Hz)。编码支持 Opus 8/16/48K、PCM 8/16/32/48K;解码额外支持 24K(仅 Segment 模式)

channel

number

否

1

声道数,支持 1 / 2

bitrate

number

否

32000

比特率(bps)

AoqAudioDeviceRouteType

onAudioDeviceRouteChanged 的 routeType 取值(native 定义,TS 层未导出为 enum)。

枚举值

值

说明

AoqAudioDeviceRouteDefault

0

默认路由

AoqAudioDeviceRouteHeadset

1

有麦克风的头戴设备

AoqAudioDeviceRouteEarpiece

2

听筒

AoqAudioDeviceRouteHeadsetNoMic

3

无麦克风的头戴设备

AoqAudioDeviceRouteSpeakerPhone

4

扬声器

AoqAudioDeviceRouteUsb

5

USB 音频设备

AoqAudioDeviceRouteBluetooth

6

蓝牙 SCO 模式

AoqAudioDeviceRouteBluetoothA2dp

7

蓝牙 A2DP 模式

AoqAudioDeviceStateCode

枚举值

值

说明

AoqAudioDeviceNone

0

无状态

AoqAudioDeviceRecordStarting

1

采集启动中

AoqAudioDeviceRecordStarted

2

采集已启动

AoqAudioDeviceRecordStopping

3

采集停止中

AoqAudioDeviceRecordStopped

4

采集已停止

AoqAudioDeviceRecordFail

5

采集失败

AoqAudioDevicePlayStarting

6

播放启动中

AoqAudioDevicePlayStarted

7

播放已启动

AoqAudioDevicePlayStopping

8

播放停止中

AoqAudioDevicePlayStopped

9

播放已停止

AoqAudioDevicePlayFail

10

播放失败

AoqAudioDeviceState

字段

类型

说明

state

AoqAudioDeviceStateCode

设备操作状态

reason

number

错误原因代码(参考 AoqErrorCode)

音频文件类型

AoqAudioFileMixConfig

字段

类型

必填

默认值

说明

fileId

string

是

-

文件标识符,后续接口以此定位

fileName

string

是

-

文件名(含路径)

cycles

number

否

-1

循环次数,-1 表示无限循环

startPosMs

number

否

0

起始播放位置(毫秒)

publishVolume

number

否

100

推流音量,取值范围 0-100

playoutVolume

number

否

100

播放音量,取值范围 0-100

AoqAudioFileStateCode

枚举值

值

说明

AoqAudioFileNone

0

无状态

AoqAudioFileStarted

1

播放已启动

AoqAudioFileStopped

2

播放已停止

AoqAudioFilePaused

3

播放已暂停

AoqAudioFileResumed

4

播放已恢复

AoqAudioFileEnded

5

播放已结束

AoqAudioFileBuffering

6

播放缓冲中

AoqAudioFileBufferingEnd

7

缓冲结束

AoqAudioFileFailed

8

播放失败

AoqAudioFileErrorCode

AoqAudioFileState.errorCode 的取值(native 定义,TS 层作为 number 下发)。

枚举值

值

说明

AoqAudioFileNoError

0

无错误

AoqAudioFileOpenFailed

1

文件打开失败

AoqAudioFileDecodeFailed

2

文件解码失败

AoqAudioFileState

字段

类型

说明

fileId

string

文件标识符

stateCode

AoqAudioFileStateCode

文件播放状态码

errorCode

number

文件错误码(参考 AoqAudioFileErrorCode)

外部音频流类型

AoqAudioStreamDirection

枚举值

值

说明

AoqAudioStreamPublish

0

发布流(推流)

AoqAudioStreamPlayout

1

播放流(本地播放)

AoqAudioExternalStreamConfig

字段

类型

必填

默认值

说明

streamId

string

是

-

流标识符

trackType

AoqTrackType

否

AoqTrackTypeAudio

音频轨道类型

codecType

AoqEncoderType

否

AoqEncoderTypeAudioPCM

音频流格式,当前支持 PCM

channels

number

否

1

声道数,受限推流 Codec,支持 1 / 2

sampleRate

number

否

48000

采样率(Hz),支持 8/12/16/24/32/44.1/48/64/88.2/96/176.4/192K

playoutVolume

number

否

100

播放音量,取值范围 0-100

publishVolume

number

否

100

推流音量,取值范围 0-100

maxBufferDuration

number

否

600000

最大缓冲时长(毫秒),取值范围 100 以上;超过时 push 失败

enable3A

boolean

否

false

是否对输入 PCM 做 3A 处理

AoqAudioExternalFrameMeta

外部音频帧元信息,PCM 数据另走 buffer 参数。

字段

类型

必填

默认值

说明

streamId

string

是

-

目标外部音频流标识

numOfSamples

number

是

0

采样点数(单声道)

bytesPerSample

number

是

2

每个采样点的字节数

numOfChannels

number

是

1

声道数

samplesPerSec

number

是

48000

每秒采样点数(采样率)

pushSequence

number

否

0

PCM 输入轮次

timeStamp

number

否

0

时间戳

AoqAudioFrameEvent

音频帧观察者事件数据。

字段

类型

说明

trackType

AoqTrackType

轨道类型

numOfSamples

number

采样点数(单声道)

bytesPerSample

number

每个采样点的字节数

numOfChannels

number

声道数

samplesPerSec

number

每秒采样点数(采样率)

timeStamp

number

时间戳

autoGenMute

boolean

true 表示 SDK 生成的静音数据

buffer

Uint8Array

音频 PCM 数据(native 侧已拷贝)

AoqAudioSource

枚举值

值

说明

AoqAudioSourceCaptured

0

采集的音频数据

AoqAudioSourceProcessCaptured

1

3A 处理后的音频数据

AoqAudioSourcePublish

2

推流的音频数据(需 connect 成功)

AoqAudioSourcePlayback

3

播放的音频数据

AoqAudioObserverParams

字段

类型

必填

默认值

说明

enabled

boolean

是

false

开启或关闭该位置的回调

audioSource

AoqAudioSource

是

AoqAudioSourceCaptured

回调位置

sampleRate

number

否

48000

回调音频采样率(Hz),不一致时重采样

channels

number

否

1

回调音频声道数,支持 1 / 2

回调模式固定为只读,Electron 不开放读写模式。

AoqAudioVolumeIndicationConfig

字段

类型

必填

默认值

说明

interval

number

否

0

回调间隔(毫秒);小于等于 0 表示关闭回调,大于 0 且小于 10 时按 10 处理

smooth

number

否

3

音量平滑系数,取值越大越平滑,取值范围 0-10

AoqAudioVolume

字段

类型

说明

volume

number

平滑后的瞬时音量,取值范围 0-255

视频类型

AoqVideoCaptureConfig

字段

类型

必填

默认值

说明

width

number

否

1280

采集宽度(像素),isExternal=true 时无效

height

number

否

720

采集高度(像素),isExternal=true 时无效

fps

number

否

15

采集帧率,isExternal=true 时无效(节奏由送帧决定)

isExternal

boolean

否

false

是否外部采集,true 时不打开摄像头

AoqVideoCodecConfig

编码与解码共用同一结构(setVideoEncoderConfig / setVideoDecoderConfig)。

字段

类型

必填

默认值

说明

isExternal

boolean

否

false

true 时 SDK 不做采集与编码,由 pushExternalVideoEncodedFrame 直推

trackType

AoqTrackType

否

AoqTrackTypeVideo

轨道类型

codecType

AoqEncoderType

否

AoqEncoderTypeVideoH264

编码格式

width

number

否

540

编码宽度(像素)

height

number

否

960

编码高度(像素)

fps

number

否

5

编码帧率

bitrate

number

否

500000

起始比特率(bps)

minBitrate

number

否

128000

最小比特率(bps)

keyframeInterval

number

否

2

关键帧间隔(秒)

mirrorMode

AoqMirrorMode

否

AoqMirrorModeDisabled

镜像模式

orientationMode

AoqOrientationMode

否

AoqOrientationModeAuto

视频方向模式

AoqVideoPixelFormat

Electron 支持的像素格式。

枚举值

值

说明

AoqVideoPixelFormatUnknown

0

未知格式

AoqVideoPixelFormatI420

1

I420(YUV 三平面格式)

AoqVideoPixelFormatNV12

2

NV12(YUV 半平面格式)

AoqVideoPixelFormatNV21

3

NV21(YUV 半平面格式)

AoqVideoPixelFormatBGRA

4

BGRA(32 位)

AoqVideoPixelFormatRGBA

5

RGBA(32 位)

AoqExternalVideoFrameMeta

外部视频裸帧元信息,像素数据另走 buffer 参数。

字段

类型

必填

默认值

说明

trackType

AoqTrackType

否

AoqTrackTypeVideo

轨道类型

;支持 Video / Screen 路由

format

AoqVideoPixelFormat

是

-

像素格式

width

number

是

-

视频宽度(像素)

height

number

是

-

视频高度(像素)

timeStamp

number

否

0

时间戳(毫秒);0 时 SDK 使用本地时间补齐

format = I420 时 buffer 必须为紧凑布局(stride = width),Y / U / V 三平面顺序拼接;其余打包格式直接传整帧字节。

AoqVideoCodecType

枚举值

值

说明

AoqVideoCodecTypeJPEG

0

JPEG 编码

AoqExternalVideoEncodedFrameMeta

外部已编码视频帧元信息,编码数据另走 buffer 参数。

字段

类型

必填

默认值

说明

trackType

AoqTrackType

否

AoqTrackTypeVideo

轨道类型

;支持 Video / Screen 路由

codec

AoqVideoCodecType

否

AoqVideoCodecTypeJPEG

编码格式

width

number

是

-

宽度(像素)

height

number

是

-

高度(像素)

timeStamp

number

否

0

时间戳(毫秒);0 时 SDK 使用本地时间补齐

AoqVideoDeviceStateCode

枚举值

值

说明

AoqVideoDeviceNone

0

无状态

AoqVideoDeviceCaptureStarting

1

采集启动中

AoqVideoDeviceCaptureStarted

2

采集已启动

AoqVideoDeviceCaptureStopping

3

采集停止中

AoqVideoDeviceCaptureStopped

4

采集已停止

AoqVideoDeviceCaptureFail

5

采集失败(权限拒绝、设备不可用等)

AoqVideoDeviceState

字段

类型

说明

state

AoqVideoDeviceStateCode

设备采集操作状态

reason

number

错误原因代码(参考 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

枚举值

值

说明

AoqVideoSourceCaptured

0

采集后的视频数据(前处理前)

AoqVideoSourcePreEncode

1

编码前的视频数据(前处理后)

AoqVideoSourceRemote

2

远端解码后、渲染前的视频数据

AoqVideoObserverAlignment

枚举值

值

说明

AoqVideoObserverAlignmentDefault

0

默认对齐

AoqVideoObserverAlignmentEven

1

偶数对齐

AoqVideoObserverAlignment4

2

4 字节对齐

AoqVideoObserverAlignment8

3

8 字节对齐

AoqVideoObserverAlignment16

4

16 字节对齐

AoqVideoObserverParams

字段

类型

必填

默认值

说明

enabled

boolean

是

false

开启或关闭该位置的回调

videoSource

AoqVideoSource

是

AoqVideoSourceCaptured

回调位置

format

AoqVideoPixelFormat

否

AoqVideoPixelFormatI420

期望回调像素格式

alignment

AoqVideoObserverAlignment

否

AoqVideoObserverAlignmentDefault

宽度对齐策略

mirrorApplied

boolean

否

false

是否对回调数据应用镜像

trackTypeAoqTrackType否AoqTrackTypeVideo需要观察的视频轨道;仅支持 Video / Screen。
回调模式固定为只读,Electron 不开放读写模式。使用内置 YUVCanvasRenderer 渲染时需选 I420。

AoqVideoFrameEvent

视频帧观察者事件数据。

字段

类型

说明

trackType

AoqTrackType

轨道类型

format

AoqVideoPixelFormat

像素格式

width

number

宽度(像素)

height

number

高度(像素)

strideY

number

Y 平面行跨度(仅 I420 有效)

strideU

number

U 平面行跨度(仅 I420 有效)

strideV

number

V 平面行跨度(仅 I420 有效)

timeStamp

number

时间戳(毫秒)

buffer

Uint8Array

帧数据;I420 为 Y / U / V 三平面按 stride 拼接,其余打包格式为原数据透传

数据消息类型

Electron 不使用 AoqDataMsg 包装类型,数据消息直接以二进制收发:

方向

类型

说明

发送

Uint8Array 或 string

sendDataMsg(data);字符串按 UTF-8 编码

接收

Uint8Array

onDataMsg(data);native 侧已拷贝,可异步持有

文本生成
图像生成
视频生成
世界模型
3D模型生成
音频
  • 音频生成
Realtime API
向量与排序
决策模型
TokenPlan
模型生产