本文介绍 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,未经任何处理。 |
| onProcessCapturedAudioFrame | 3A 处理后的音频帧回调。数据经过回声消除、噪声抑制、自动增益等 3A 处理。 |
| onPublishAudioFrame | 推流前的音频帧回调。数据即将通过编码后发送到 Relay 服务器。 |
| onPlaybackAudioFrame | 播放前的远端音频帧回调。数据为远端解码后、混音前即将播放的音频。 |
视频帧事件
| 接口 | 简介 |
|---|---|
| onCapturedVideoFrame | 采集到原始视频帧时触发(前处理前)。数据为摄像头或屏幕采集后的原始帧,未经前处理。 |
| onPreEncodeVideoFrame | 编码前的视频帧回调(前处理后)。数据经过前处理后、编码前。 |
| onRemoteVideoFrame | 远端解码后、渲染前的视频帧回调。数据为远端接收并解码后的视频帧。 |
接口详情
引擎入口与生命周期
createAoqClientEngine
获取引擎包装实例。模块级懒加载单例,重复调用返回同一实例,与 native 引擎单例语义对齐;也是包的 default export。
IAoqClientEngine 引擎实例。注意本方法仅创建 JS 包装层与 native bridge,真正创建引擎需再调 createEngine()。
createEngine
创建 native 引擎实例。引擎为全局单例,重复调用直接返回成功。
参数 | 类型 | 说明 |
|---|---|---|
config | AoqCreateConfig | 引擎创建配置 |
0 成功;-1 表示创建失败或参数不是合法 JSON。
createEngine() 会在当前 JS 线程的 libuv 循环上挂一个 16ms 的 Win32 消息泵(摄像头采集依赖),destroy() 时停掉;因此不要在 createEngine() 之后长时间同步阻塞 JS 线程。destroy
销毁引擎实例,释放所有资源。
0 表示成功;非 0 表示失败。引擎未创建时返回 0。
getVersion
获取 SDK 当前版本号,无需先调 createEngine()。
connect
连接 Relay 服务器。业务 AppServer 应根据所用协议获取临时 AOQ 连接参数并下发给客户端,具体操作请参见Token 鉴权。
参数 | 类型 | 说明 |
|---|---|---|
config | AoqConnectConfig | 连接配置,包含 Token、SID、Relay 接入点列表、推拉流 track 列表等 |
0 表示调用已下发(异步执行);非 0 表示参数校验失败。连接结果由 onConnectionStatusChange 事件通知。
disconnect
断开与服务器的连接,释放连接相关资源。
0 表示调用已下发(异步执行);非 0 表示失败。
音频设备管理
startAudioCapture
Info.plist 中声明 NSMicrophoneUsageDescription。
stopAudioCapture
muteAudioCapture
mute=true 静音,false 取消静音。
startAudioPlayer
stopAudioPlayer / pauseAudioPlayer / resumeAudioPlayer
fadeMs:淡出/淡入时长(毫秒);0 表示立即执行。
interruptAudioPlayer
参数 | 类型 | 说明 |
|---|---|---|
trackType | AoqTrackType | 轨道类型 |
fadeMs | number | 淡出时长(毫秒) |
音频编解码配置
connect() 之前调用。使用 Opus(AoqEncoderTypeAudioOpus)需 SDK 内置或随包分发 PluginOpus 插件。
视频设备管理
Info.plist 中声明 NSCameraUsageDescription。当 config.isExternal=true 时不打开摄像头,由 pushExternalVideoCapturedFrame 送帧。
setLocalView / setRemoteView / switchCamera;预览请使用「帧观察者 + YUVCanvasRenderer」(见 2.13)。视频编解码与外部输入
参数 | 类型 | 说明 |
|---|---|---|
meta | AoqExternalVideoFrameMeta / AoqExternalVideoEncodedFrameMeta | 帧元信息(尺寸、格式、时间戳) |
buffer | Uint8Array | 帧数据(像素数据或已编码数据) |
pushExternalVideoCapturedFrameVideo 轨道需先调用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 使用本地时间补齐。
屏幕采集
config 为屏幕采集配置。屏幕画面通过 AoqTrackTypeScreen 轨道发送。
返回值:0 表示成功;非 0 表示失败。
先调用 getScreenSourceList 获取屏幕或窗口源,再将选定的 sourceId 和 sourceType 传入采集配置。
外部原始帧:设置 isExternal=true 后,通过 pushExternalVideoCapturedFrame 输入 Screen 轨道的原始帧,由 SDK 编码。外部已编码帧:先通过 setVideoEncoderConfig 将 Screen 轨道设置为外部编码,再调用 pushExternalVideoEncodedFrame。
getScreenSourceList
媒体流发送控制
trackType 支持 AoqTrackTypeAudio、AoqTrackTypeVideo 和 AoqTrackTypeScreen。
控制本地某路媒体流是否发送。建议初始化后先 enableSendMediaStream(trackType, false),待 onConnectionStatusChange 上报 AoqConnectionStatusConnected 后再开启。
音频文件播放
参数 | 类型 | 说明 |
|---|---|---|
config | AoqAudioFileMixConfig | 文件混音配置, |
fileId | string | 文件标识,由调用方定义,后续接口以此定位 |
positionMs | number | 目标播放位置(毫秒) |
type | AoqAudioStreamDirection | 推流音量或本地播放音量 |
volume | number | 音量,取值范围 0-100 |
getAudioFileDuration/getAudioFileCurrentPosition返回毫秒数;getAudioFileVolume返回当前音量值;- 上述 getter 在引擎未创建时返回
-1。
onAudioFileState 事件上报。
外部音频流
参数 | 类型 | 说明 |
|---|---|---|
config | AoqAudioExternalStreamConfig | 外部音频流配置, |
streamId | string | 流标识,由调用方定义 |
meta | AoqAudioExternalFrameMeta | PCM 帧元信息, |
buffer | Uint8Array | PCM 数据 |
fadeoutMs | number | 清空缓存时的淡出时长(毫秒) |
pushAudioExternalStreamData缓存时长超过maxBufferDuration时返回110(外部音频缓冲区满)。getAudioExternalStreamVolume返回当前音量值;引擎未创建时返回-1。clearAudioExternalStreamBuffernative 侧无返回值,调用成功固定返回0。
实时消息
string 时内部按 UTF-8 编码为 Buffer 后发送。对端消息通过 onDataMsg 事件回调。
音频帧回调
参数 | 类型 | 说明 |
|---|---|---|
enable | boolean |
|
params | AoqAudioObserverParams | 指定回调位置、开关与回调格式 |
setAudioFrameObserver(true) 注册观察者,再对需要的位置调 enableAudioFrameObserver,数据通过对应事件下发。
ReadOnly)。本地音量提示
config.interval <= 0 时关闭回调;开启后按 config.interval 周期触发 onLocalAudioVolumeIndication。需在 startAudioCapture() 之后调用才有音量数据。
视频帧回调
参数 | 类型 | 说明 |
|---|---|---|
enable | boolean |
|
params | AoqVideoObserverParams | 指定回调位置、开关、像素格式与对齐策略 |
AoqVideoFrameEvent 形式通过 onCapturedVideoFrame / onPreEncodeVideoFrame / onRemoteVideoFrame 下发;I420 时 buffer 为 Y / U / V 三平面按 stride 拼接,其余打包格式为原数据透传。同样仅支持只读模式。
视频渲染(YUVCanvasRenderer)
SDK 内置的软渲染器。
接口 | 说明 |
|---|---|
bind | 绑定 canvas(重复绑定会替换 sink) |
unbind | 解绑并清空画面 |
bound | 是否已绑定 |
drawFrame | 绘制一帧;仅支持 I420,非 I420 / 尺寸或 buffer 长度不足时静默返回 |
object-fit 控制 canvas 即可。
引擎事件(IAoqEngineEvents)
引擎继承 EventEmitter<IAoqEngineEvents>,事件是 SDK 所有异步通知的统一出口,与 native AoqEngineEventListener 回调一一对应。不关心的事件无需注册。
onError
code 对应 AoqErrorCode 数值(见 3.3)。
onWarning
code 对应 AoqWarningCode 数值(见 3.3)。
onConnectionStatusChange
onStats
参数 | 类型 | 说明 |
|---|---|---|
stats | AoqStats | 包含音频 / 视频 / 数据消息的推拉流统计及网络统计 |
onAudioDeviceStateChanged
onAudioDeviceRouteChanged
routeType 对应 AoqAudioDeviceRouteType 数值(见 3.4)。
onAudioFileState
onLocalAudioVolumeIndication
enableLocalAudioVolumeIndication 开启。
onVideoDeviceStateChanged
onDataMsg
data 为 native 侧拷贝后的 Buffer,可安全异步持有;文本消息用 Buffer.from(data).toString() 转字符串。
音频帧事件
setAudioFrameObserver(true) 与 enableAudioFrameObserver 开启。
onCapturedAudioFrame
采集到原始音频帧时触发。数据为采集后的原始 PCM,未经任何处理。
| 参数 | 类型 | 说明 |
|---|---|---|
| frame | AoqAudioFrameEvent | 采集的音频帧数据,PCM 在 frame.buffer 字段 |
onProcessCapturedAudioFrame
3A 处理后的音频帧回调。数据经过回声消除、噪声抑制、自动增益等 3A 处理。
| 参数 | 类型 | 说明 |
|---|---|---|
| frame | AoqAudioFrameEvent | 3A 处理后的音频帧数据,PCM 在 frame.buffer 字段 |
onPublishAudioFrame
推流前的音频帧回调。数据即将通过编码后发送到 Relay 服务器。
| 参数 | 类型 | 说明 |
|---|---|---|
| frame | AoqAudioFrameEvent | 推流前的音频帧数据,PCM 在 frame.buffer 字段 |
onPlaybackAudioFrame
播放前的远端音频帧回调。数据为远端解码后、混音前即将播放的音频。
| 参数 | 类型 | 说明 |
|---|---|---|
| frame | AoqAudioFrameEvent | 播放前的远端音频帧数据,PCM 在 frame.buffer 字段 |
视频帧事件
setVideoFrameObserver(true) 与 enableVideoFrameObserver 开启。帧事件为只读,回调中修改 buffer 不会写回 SDK。
onCapturedVideoFrame
采集到原始视频帧时触发(前处理前)。数据为摄像头或屏幕采集后的原始帧,未经前处理。
| 参数 | 类型 | 说明 |
|---|---|---|
| frame | AoqVideoFrameEvent | 采集的视频帧数据 |
onPreEncodeVideoFrame
编码前的视频帧回调(前处理后)。数据经过前处理后、编码前。
| 参数 | 类型 | 说明 |
|---|---|---|
| frame | AoqVideoFrameEvent | 编码前的视频帧数据 |
onRemoteVideoFrame
远端解码后、渲染前的视频帧回调。数据为远端接收并解码后的视频帧。
| 参数 | 类型 | 说明 |
|---|---|---|
| frame | AoqVideoFrameEvent | 远端解码后的视频帧数据 |
数据类型与枚举
通用类型
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 服务器端口 |
| tcpPort | number | 否 | 0 | TCP 降级端口;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 | 数据消息轨道 |
| AoqTrackTypeScreen | 3 | 屏幕共享轨道,仅支持上行。 |
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 | 视频渲染绘制错误 |
| AoqECScreen | 300 | 屏幕共享通用错误 |
| AoqECScreenAuthFailed | 310 | 屏幕共享授权失败 |
| AoqECScreenStartFailed | 311 | 屏幕共享启动失败 |
| AoqECAudioDeviceEarpieceRequiresVoipMode | 128 | 听筒需要 VoIP 模式(移动端场景,Electron 一般不会触发)。 |
-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 |
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
| 枚举值 | 值 | 说明 |
|---|---|---|
| AoqScreenShareSourceTypeDesktop | 0 | 整个桌面 |
| AoqScreenShareSourceTypeWindow | 1 | 指定窗口 |
AoqScreenSourceInfo
| 字段 | 类型 | 说明 |
|---|---|---|
| sourceType | AoqScreenShareSourceType | 源类型 |
| sourceId | string | 源 ID,以字符串返回以避免 int64 精度丢失。 |
| sourceName | string | 源名称 |
| sourceIsSelf | boolean | 是否为自身进程窗口 |
AoqScreenCaptureConfig
所有字段均可选,isExternal 默认 false。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| isExternal | boolean | false | 是否由应用提供屏幕原始帧。 |
| sourceId | string | number | — | 屏幕源 ID。可选;推荐字符串,number 必须为安全整数。 |
| sourceType | AoqScreenShareSourceType | — | 屏幕源类型。 |
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 | 是否对回调数据应用镜像 |
| trackType | AoqTrackType | 否 | AoqTrackTypeVideo | 需要观察的视频轨道;仅支持 Video / Screen。 |
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 |
|
接收 | Uint8Array |
|