跳转到主要内容
SDK简介

Electron 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推送外部已编码视频帧

媒体流发送控制

接口简介
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采集裸音频数据回调
onProcessCapturedAudioFrame3A 处理后音频数据回调
onPublishAudioFrame推流音频数据回调
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 连接参数并下发给客户端。
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」(见视频渲染)。

视频编解码与外部输入

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

媒体流发送控制

enableSendMediaStream(trackType: AoqTrackType, enable: boolean): number
控制本地某路媒体流是否发送。建议初始化后先 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 内置的软渲染器,承担移动端 setLocalView / setRemoteView 的预览职责。
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 数值(见 AoqErrorCode)。 onWarning
onWarning: (code: number, message: string) => void
引擎警告回调。code 对应 AoqWarningCode 数值(见 AoqWarningCode)。 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 数值(见 AoqAudioDeviceRouteType)。 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 开启。 视频帧事件
onCapturedVideoFrame:  (frame: AoqVideoFrameEvent) => void  /* 采集后(前处理前) */
onPreEncodeVideoFrame: (frame: AoqVideoFrameEvent) => void  /* 编码前(前处理后) */
onRemoteVideoFrame:    (frame: AoqVideoFrameEvent) => void  /* 远端解码后、渲染前 */
需先调 setVideoFrameObserver(true)enableVideoFrameObserver 开启。帧事件为只读,回调中修改 buffer 不会写回 SDK。
事件回调中避免重计算:native 回调经异步线程投递到 JS 主线程,高频帧事件中做耗时操作会造成堆积。

数据类型与枚举

所有类型均从包根导出,可直接 import { ... } from 'aoq-electron-sdk'。枚举为 TypeScript enum,运行时可用;接口(interface)仅类型约束。标记为可选的字段缺省时取表中默认值。

通用类型

AoqCreateConfig
字段类型必填默认值说明
workDirstring""SDK 工作目录(日志与临时文件)
enableDumpAudiobooleanfalse是否开启音频数据保存(调试用)
extrasstring""扩展参数(JSON 字符串)
Android 的 isBTScoMode 为移动端字段,Electron 不提供。
AoqConnectConfig
字段类型必填默认值说明
tokenstring-连接鉴权 Token
sidstring-会话 ID
certFingerprintstring""服务器证书指纹
workspaceIdHashstring工作空间 ID Hash;空字符串等同不传
relayEndpointsArray<AoqRelayEndpoint>-Relay 接入点列表
publishTracksArray<AoqTrackParam>-本端发布轨道列表
subscribeTracksArray<AoqTrackParam>-本端订阅轨道列表
AoqRelayEndpoint
字段类型必填默认值说明
routeIndexnumber-1路由序号
endpointstring-Relay 服务器域名或 IP
portnumber-Relay 服务器端口
AoqTrackParam
字段类型必填默认值说明
trackTypeAoqTrackType-轨道类型
trackModeAoqTrackModeAoqTrackModeSegment流式 / 非流式模式,仅对音频下行生效

统计信息类型

AoqStats 引擎统计信息汇总,通过 onStats 周期性上报。数组字段无数据时为空数组,networkStats 无数据时不下发。
字段类型说明
audioPublishStatsArray<AoqAudioPublishStats>音频推流统计
videoPublishStatsArray<AoqVideoPublishStats>视频推流统计
dataMsgPublishStatsArray<AoqDataMsgPublishStats>数据消息推流统计
audioSubscribeStatsArray<AoqAudioSubscribeStats>音频拉流统计
videoSubscribeStatsArray<AoqVideoSubscribeStats>视频拉流统计
dataMsgSubscribeStatsArray<AoqDataMsgSubscribeStats>数据消息拉流统计
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数据消息轨道
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 错误码为 native 层定义,onErrorcode 与接口返回值均使用该数值(TS 层未将其导出为 enum)。
枚举值说明
AoqErrorCodeOK0成功
AoqErrorCodeParamInvalid1参数非法
AoqErrorCodeStateInvalid2状态非法
AoqErrorCodeUnSupport3当前平台 / 模式不支持
AoqErrorCodeAudio100音频通用错误
AoqErrorCodeAudioExternalBufferFull110外部音频缓冲区满
AoqErrorCodeAudioDevice120音频设备通用错误
AoqErrorCodeAudioDeviceRecordingAuthFailed121录音权限未获取
AoqErrorCodeAudioDeviceRecordingOccupied122录音设备被占用
AoqErrorCodeAudioDeviceRecordingBackgroundStart123后台启动录音失败
AoqErrorCodeAudioDeviceRecordingStartFail124录音启动失败
AoqErrorCodeAudioDevicePlayoutOccupied125播放设备被占用
AoqErrorCodeAudioDevicePlayoutBackgroundStart126后台启动播放失败
AoqErrorCodeAudioDevicePlayoutStartFail127播放启动失败
AoqErrorCodeVideo200视频通用错误
AoqErrorCodeVideoExternalBufferFull210外部视频缓冲区满
AoqErrorCodeVideoExternalCaptureNotEnabled211外部视频采集未启用
AoqErrorCodeVideoExternalEncoderNotEnabled212外部视频编码未启用
AoqErrorCodeVideoDevice220视频设备通用错误
AoqErrorCodeVideoDeviceCameraOpenFail221摄像头打开失败
AoqErrorCodeVideoDeviceCameraAuthFailed222摄像头权限未获取
AoqErrorCodeVideoDeviceCameraOccupied223摄像头被占用
AoqErrorCodeVideoDeviceCameraRunningError224摄像头运行异常
AoqErrorCodeVideoCodec230视频编解码通用错误
AoqErrorCodeVideoCodecEncoderInitFail231视频编码器初始化失败
AoqErrorCodeVideoRender240视频渲染通用错误
AoqErrorCodeVideoRenderCreateFail241视频渲染创建失败
AoqErrorCodeVideoRenderDrawError242视频渲染绘制错误
除上述 native 错误码外,Electron 层还会在引擎未创建 / 已销毁、或参数不是合法 JSON 时返回 -1
AoqWarningCode
枚举值说明
AoqWCOK0无警告
AoqWCAudio100音频通用警告
AoqWCAudioHowling101音频啸叫检测
AoqWCAudioDevice120音频设备通用警告
AoqWCAudioDeviceMicEnumerateError121麦克风枚举错误
AoqWCAudioDeviceMicStartTimeout122麦克风启动超时
AoqWCAudioDeviceRecordingError123录音过程错误
AoqWCAudioDeviceSpeakerEnumerateError124扬声器枚举错误
AoqWCAudioDeviceSpeakerStartTimeout125扬声器启动超时
AoqWCAudioDevicePlayoutError126播放过程错误
AoqWCVideo200视频通用警告
AoqWCVideoCameraEnumerateError201摄像头枚举错误
AoqWCVideoEncoderSwitched202视频编码器已切换
AoqWCVideoRenderDowngrade203视频渲染降级

音频类型

AoqAudioCaptureConfig
字段类型必填默认值说明
isExternalbooleanfalse是否为外部采集模式
channelnumber1音频采集通道数,支持 1 / 2
AoqAudioPlaybackConfig
字段类型必填默认值说明
isExternalbooleanfalse是否为外部播放模式
channelnumber1音频播放通道数,支持 1 / 2
isVoipMode / isDefaultSpeaker 为移动端字段,Electron 不提供。
AoqAudioCodecConfig
字段类型必填默认值说明
trackTypeAoqTrackTypeAoqTrackTypeAudio轨道类型
codecTypeAoqEncoderTypeAoqEncoderTypeAudioPCM编码格式
sampleRatenumber48000采样率(Hz)。编码支持 Opus 8/16/48K、PCM 8/16/32/48K;解码额外支持 24K(仅 Segment 模式)
channelnumber1声道数,支持 1 / 2
bitratenumber32000比特率(bps)
AoqAudioDeviceRouteType 下表为 onAudioDeviceRouteChanged 的合法 routeType 取值,由 native 层定义,TypeScript 层不导出为 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 表示无限循环
startPosMsnumber0起始播放位置(毫秒)
publishVolumenumber100推流音量,取值范围 0-100
playoutVolumenumber100播放音量,取值范围 0-100
AoqAudioFileStateCode
枚举值说明
AoqAudioFileNone0无状态
AoqAudioFileStarted1播放已启动
AoqAudioFileStopped2播放已停止
AoqAudioFilePaused3播放已暂停
AoqAudioFileResumed4播放已恢复
AoqAudioFileEnded5播放已结束
AoqAudioFileBuffering6播放缓冲中
AoqAudioFileBufferingEnd7缓冲结束
AoqAudioFileFailed8播放失败
AoqAudioFileErrorCode 下表为合法的 AoqAudioFileState.errorCode 取值,由 native 层定义,TypeScript 层以 number 形式下发。
枚举值说明
AoqAudioFileNoError0无错误
AoqAudioFileOpenFailed1文件打开失败
AoqAudioFileDecodeFailed2文件解码失败
AoqAudioFileState
字段类型说明
fileIdstring文件标识符
stateCodeAoqAudioFileStateCode文件播放状态码
errorCodenumber文件错误码(参考 AoqAudioFileErrorCode)

外部音频流类型

AoqAudioStreamDirection
枚举值说明
AoqAudioStreamPublish0发布流(推流)
AoqAudioStreamPlayout1播放流(本地播放)
AoqAudioExternalStreamConfig
字段类型必填默认值说明
streamIdstring-流标识符
trackTypeAoqTrackTypeAoqTrackTypeAudio音频轨道类型
codecTypeAoqEncoderTypeAoqEncoderTypeAudioPCM音频流格式,当前支持 PCM
channelsnumber1声道数,受限推流 Codec,支持 1 / 2
sampleRatenumber48000采样率(Hz),支持 8/12/16/24/32/44.1/48/64/88.2/96/176.4/192K
playoutVolumenumber100播放音量,取值范围 0-100
publishVolumenumber100推流音量,取值范围 0-100
maxBufferDurationnumber600000最大缓冲时长(毫秒),取值范围 100 以上;超过时 push 失败
enable3Abooleanfalse是否对输入 PCM 做 3A 处理
AoqAudioExternalFrameMeta 外部音频帧元信息,PCM 数据另走 buffer 参数。
字段类型必填默认值说明
streamIdstring-目标外部音频流标识
numOfSamplesnumber0采样点数(单声道)
bytesPerSamplenumber2每个采样点的字节数
numOfChannelsnumber1声道数
samplesPerSecnumber48000每秒采样点数(采样率)
pushSequencenumber0PCM 输入轮次
timeStampnumber0时间戳
AoqAudioFrameEvent 音频帧观察者事件数据。
字段类型说明
trackTypeAoqTrackType轨道类型
numOfSamplesnumber采样点数(单声道)
bytesPerSamplenumber每个采样点的字节数
numOfChannelsnumber声道数
samplesPerSecnumber每秒采样点数(采样率)
timeStampnumber时间戳
autoGenMutebooleantrue 表示 SDK 生成的静音数据
bufferUint8Array音频 PCM 数据(native 侧已拷贝)
AoqAudioSource
枚举值说明
AoqAudioSourceCaptured0采集的音频数据
AoqAudioSourceProcessCaptured13A 处理后的音频数据
AoqAudioSourcePublish2推流的音频数据(需 connect 成功)
AoqAudioSourcePlayback3播放的音频数据
AoqAudioObserverParams
字段类型必填默认值说明
enabledbooleanfalse开启或关闭该位置的回调
audioSourceAoqAudioSourceAoqAudioSourceCaptured回调位置
sampleRatenumber48000回调音频采样率(Hz),不一致时重采样
channelsnumber1回调音频声道数,支持 1 / 2
回调模式固定为只读,Electron 不开放读写模式。
AoqAudioVolumeIndicationConfig
字段类型必填默认值说明
intervalnumber0回调间隔(毫秒);小于等于 0 表示关闭回调,大于 0 且小于 10 时按 10 处理
smoothnumber3音量平滑系数,取值越大越平滑,取值范围 0-10
AoqAudioVolume
字段类型说明
volumenumber平滑后的瞬时音量,取值范围 0-255

视频类型

AoqVideoCaptureConfig
字段类型必填默认值说明
widthnumber1280采集宽度(像素),isExternal=true 时无效
heightnumber720采集高度(像素),isExternal=true 时无效
fpsnumber15采集帧率,isExternal=true 时无效(节奏由送帧决定)
isExternalbooleanfalse是否外部采集,true 时不打开摄像头
cameraDirection 为移动端字段,桌面端无此字段。
AoqVideoCodecConfig 编码与解码共用同一结构(setVideoEncoderConfig / setVideoDecoderConfig)。
字段类型必填默认值说明
isExternalbooleanfalsetrue 时 SDK 不做采集与编码,由 pushExternalVideoEncodedFrame 直推
trackTypeAoqTrackTypeAoqTrackTypeVideo轨道类型
codecTypeAoqEncoderTypeAoqEncoderTypeVideoH264编码格式
widthnumber540编码宽度(像素)
heightnumber960编码高度(像素)
fpsnumber5编码帧率
bitratenumber500000起始比特率(bps)
minBitratenumber128000最小比特率(bps)
keyframeIntervalnumber2关键帧间隔(秒)
mirrorModeAoqMirrorModeAoqMirrorModeDisabled镜像模式
orientationModeAoqOrientationModeAoqOrientationModeAuto视频方向模式
AoqVideoPixelFormat Electron 侧支持的像素格式(不包含移动端的纹理 / CVPixelBuffer 格式)。
枚举值说明
AoqVideoPixelFormatUnknown0未知格式
AoqVideoPixelFormatI4201I420(YUV 三平面格式)
AoqVideoPixelFormatNV122NV12(YUV 半平面格式)
AoqVideoPixelFormatNV213NV21(YUV 半平面格式)
AoqVideoPixelFormatBGRA4BGRA(32 位)
AoqVideoPixelFormatRGBA5RGBA(32 位)
AoqExternalVideoFrameMeta 外部视频裸帧元信息,像素数据另走 buffer 参数。
字段类型必填默认值说明
trackTypeAoqTrackTypeAoqTrackTypeVideo轨道类型
formatAoqVideoPixelFormat-像素格式
widthnumber-视频宽度(像素)
heightnumber-视频高度(像素)
timeStampnumber0时间戳(毫秒);0 时 SDK 使用本地时间补齐
format = I420buffer 必须为紧凑布局(stride = width),Y / U / V 三平面顺序拼接;其余打包格式直接传整帧字节。
AoqVideoCodecType
枚举值说明
AoqVideoCodecTypeJPEG0JPEG 编码
AoqExternalVideoEncodedFrameMeta 外部已编码视频帧元信息,编码数据另走 buffer 参数。
字段类型必填默认值说明
trackTypeAoqTrackTypeAoqTrackTypeVideo轨道类型
codecAoqVideoCodecTypeAoqVideoCodecTypeJPEG编码格式
widthnumber-宽度(像素)
heightnumber-高度(像素)
timeStampnumber0时间戳(毫秒);0 时 SDK 使用本地时间补齐
AoqVideoDeviceStateCode
枚举值说明
AoqVideoDeviceNone0无状态
AoqVideoDeviceCaptureStarting1采集启动中
AoqVideoDeviceCaptureStarted2采集已启动
AoqVideoDeviceCaptureStopping3采集停止中
AoqVideoDeviceCaptureStopped4采集已停止
AoqVideoDeviceCaptureFail5采集失败(权限拒绝、设备不可用等)
AoqVideoDeviceState
字段类型说明
stateAoqVideoDeviceStateCode设备采集操作状态
reasonnumber错误原因代码(参考 AoqErrorCode)

视频帧回调类型

AoqVideoSource
枚举值说明
AoqVideoSourceCaptured0采集后的视频数据(前处理前)
AoqVideoSourcePreEncode1编码前的视频数据(前处理后)
AoqVideoSourceRemote2远端解码后、渲染前的视频数据
AoqVideoObserverAlignment
枚举值说明
AoqVideoObserverAlignmentDefault0默认对齐
AoqVideoObserverAlignmentEven1偶数对齐
AoqVideoObserverAlignment424 字节对齐
AoqVideoObserverAlignment838 字节对齐
AoqVideoObserverAlignment16416 字节对齐
AoqVideoObserverParams
字段类型必填默认值说明
enabledbooleanfalse开启或关闭该位置的回调
videoSourceAoqVideoSourceAoqVideoSourceCaptured回调位置
formatAoqVideoPixelFormatAoqVideoPixelFormatI420期望回调像素格式
alignmentAoqVideoObserverAlignmentAoqVideoObserverAlignmentDefault宽度对齐策略
mirrorAppliedbooleanfalse是否对回调数据应用镜像
回调模式固定为只读,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 侧已拷贝,可异步持有