aoq-electron-sdk 1.2.0-57013983

package/README.md

@@ -0,0 +1,369 @@
+# AoqClientSdk for Electron
+
+AoqClientSdk 的 Electron 平台封装（架构参考 Agora Electron-SDK）：
+C++ NAPI addon 桥接原生 SDK，TypeScript 提供强类型 API 与事件，
+npm 包形态供 Electron 应用消费。
+
+## 架构
+
+```
+JS/TS 调用方 (Electron renderer / node)
+    │  import createAoqClientEngine from 'aoq-electron-sdk'
+    ▼
+ts/  TypeScript API 层
+    ├── AoqSdk.ts                 入口：createAoqClientEngine() 单例工厂
+    ├── Types.ts                  枚举/配置接口（与 AoqClientEngine.h 逐字段对齐，
+    │                             同时是 TS <-> native JSON 协议的唯一事实来源）
+    ├── IAoqClientEngine.ts       引擎接口 + IAoqEngineEvents 事件定义
+    ├── internal/                 内部实现：require .node、JSON 序列化、事件分发
+    └── Renderer/                 YUVCanvasRenderer：I420 帧 → canvas 软件渲染
+    │  JSON 参数 / 单通道事件（call_back_with_event）+ Buffer
+    ▼
+source_code/aoq_node_ext/  C++ NAPI addon（node-addon-api）
+    ├── aoq_node_ext.cc           NODE_API_MODULE 入口
+    ├── aoq_electron_bridge.*     Napi::ObjectWrap 包装 AoqClientEngine 单例，
+    │                             rapidjson 解析 JSON 参数组装 C++ 结构体
+    ├── node_aoq_event_handler.*  AoqEngineEventListener → ThreadSafeFunction
+    │                             跨线程投递 JS 主线程
+    └── node_aoq_frame_observers.* IAudioFrameObserver / IVideoFrameObserver
+                                  适配（meta JSON + PCM/I420 buffer 上抛）
+    │  链接
+    ▼
+AoqClientSdk.framework  原生 SDK（api/Mac/AoqClientSdk 构建产物，
+                        POST_BUILD 拷到 .node 同目录，@loader_path 解析）
+```
+
+## 目录结构
+
+| 路径 | 说明 |
+|---|---|
+| `CMakeLists.txt` | cmake-js 工程；Darwin 链接 framework，Windows 分支预留 |
+| `source_code/aoq_node_ext/` | NAPI addon C++ 源码 |
+| `ts/` | TypeScript 源码（发布时经 tsc 编到 `js/` + `types/`） |
+| `build/Release/` | 构建产物：`aoq_node_ext.node` + `AoqClientSdk.framework`（由 CMakeLists 的 `OUTPUT_DIRECTORY` 与 POST_BUILD 拷贝指定） |
+| `dist/` | `npm pack` 产出的 tgz 二进制依赖包（Pack 模式） |
+| `package.json` | npm 包定义，main=`js/AoqSdk`；`files` 字段决定 tgz 内容 |
+
+## 构建
+
+前置：需要一份 Mac 原生 framework，**支持三种来源**（按优先级）：
+
+```bash
+# 来源 1：指定本地目录（远程预编译产物已自行下载解压）
+AOQ_MAC_SDK_DIR=/path/to/dir sh aoq-client-sdk/build_scripts/Electron/generate_aoq_sdk.sh Release
+
+# 来源 2：远程 zip（内含 AoqClientSdk.framework，允许嵌套目录），
+#         自动下载解压到 prebuilt/<Config>/ 缓存，Rebuild 时重下
+AOQ_MAC_SDK_URL=https://xxx/AoqClientSdk.framework.zip \
+    sh aoq-client-sdk/build_scripts/Electron/generate_aoq_sdk.sh Release Build Pack
+
+# 来源 3（默认）：本地构建产物 api/Mac/AoqClientSdk/build/<Config>/
+sh aoq-client-sdk/build_scripts/Electron/generate_aoq_sdk.sh [Debug|Release] [Build|Rebuild]
+```
+
+适用场景：只改 Electron 桥/demo 或 CI 出包时用远程预编译产物（来源 1/2，
+免去原生 SDK 全量编译且与发布二进制一致）；改了 rtc_core 源码联调时用本地构建（来源 3）。
+
+手动构建（在本目录）：
+
+```bash
+npm install
+npm run build_mac_debug     # / build_mac_release，cmake-js 编 addon
+# 指定外部 framework：npm run build_mac_release -- --CDAOQ_MAC_SDK_DIR=/path/to/dir
+npm run buildJS             # tsc 编 ts/ → js/ + types/
+```
+
+冒烟验证：
+
+```bash
+node -e "const s=require('./js/AoqSdk');console.log(s.createAoqClientEngine().getVersion())"
+```
+
+## API 自动化测试
+
+对齐 iOS/Mac/Android/OHOS 自动化体系的 Jest 测试套件（17 个测试类 / 281 用例，
+API 覆盖率 100%）。
+
+### 运行方式
+
+```bash
+# 推荐：runner 脚本（产物检查 → 依赖安装 → 执行用例 → 覆盖率 + 多格式报告）
+# ⚠️ 必须用 bash 执行：脚本用了进程替换等 bash 特性，用 sh 会报语法错误
+bash aoq-client-sdk/build_scripts/test/run-automated-tests-electron.sh
+
+# 或在本目录直接跑 Jest（不生成报告）
+npm test                                             # 全量
+npx jest --runInBand test/AoqEngineConnect.test.js   # 单个测试类
+```
+
+> 脚本位于 `build_scripts/test/`，与其他平台的
+> `run-automated-tests-{ios,android,ohos}.sh` 同目录。
+
+### runner 参数
+
+| 参数 | 说明 |
+|---|---|
+| `-c ClassName` | 只跑指定测试类（如 `-c AoqEngineConnect`，可重复指定多个） |
+| `-m Class/用例名` | 只跑单个用例，类名自动提取，无需再写 `-c`；可重复 |
+| `-t "用例名"` | 按标题匹配用例（Jest `-t`，支持部分匹配） |
+| `-o dir` | 输出目录，默认 `build_scripts/test/test-results-electron`（相对脚本所在目录，不是当前工作目录） |
+| `--skip-build` | 跳过 SDK 构建（要求 `js/` 与 `build/Release` 产物已存在） |
+| `--coverage` / `--skip-coverage` | 启用（默认已启用）/ 跳过覆盖率与报告生成 |
+| `--no-pull` | 跳过编译前对 demo/sdk/libaoq 三仓的 git pull（默认开启；仅 main 分支拉取，`--skip-build` 时不拉） |
+| `--no-retry` | 禁用失败 suite 的隔离重试 |
+| `-h`, `--help` | 完整帮助 |
+
+退出码：全部通过 `0`；存在失败/超时/崩溃 `1`。
+
+示例：
+
+```bash
+# 快速回归：只验证连接与生命周期，跳过构建与 git pull
+bash .../run-automated-tests-electron.sh -c AoqEngineConnect -c AoqEngineLifecycle --skip-build
+
+# 定位单个用例
+bash .../run-automated-tests-electron.sh -m AoqEngineCallback/onConnectionStatusChange --skip-build
+```
+
+### 报告输出
+
+默认写到 `build_scripts/test/test-results-electron/`（可用 `-o` 指定到其他位置；
+脚本结尾会打印 Markdown/HTML 报告的绝对路径）：
+
+| 文件 | 内容 |
+|---|---|
+| `report.html` | 可视化 HTML 报告（与 iOS/Mac/Android 端同模板） |
+| `summary.json` | 机器可读摘要（schema 与他端一致，供 CI 解析） |
+| `report.md` | Markdown 报告：总览 + API 覆盖率 + 测试类汇总 + 失败详情 + 用例明细；可直接贴 PR / 语雀 / 钉钉 |
+| `report.json` | 与 Markdown 同源的结构化明细 |
+| `jest-results.json` | Jest 原始结果（含隔离重试的合并结果） |
+| `retry-<Suite>.json` | 失败 suite 隔离重试的原始结果（仅发生重试时生成） |
+| `repo-commits.txt` | 本次执行时三仓（demo/sdk/libaoq）的分支与 commit 溯源 |
+| `test-run.log` | 完整执行日志（含 native SDK 全量输出，排查时看这个） |
+| `logs/` | 崩溃诊断：`<Suite>_crash.log` + `crash_reports/*.ips` |
+
+Markdown 报告结构示例：
+
+```markdown
+# AoqClientSdk Electron API 测试报告
+> SDK 版本 `1.2.0.xxxx` · 生成时间 2026-08-03 11:20:00 · 平台 macOS(arm64)
+
+## 总览
+| 指标 | 值 |
+| 结论 | **✅ 全部通过** |
+| 用例总数 | 281 |
+| API 覆盖率 | 100% (42/42) |
+
+## 测试类汇总
+| 测试类 | 结果 | 用例 | 通过 | 失败 | 耗时 |
+| AoqEngineVideo | ✅ | 36 | 36 | 0 | 11.1s |
+...
+```
+
+失败时自动插入「失败详情」章节（已清理 ANSI 色码，包含完整断言与调用栈）。
+
+### 测试类清单
+
+| 测试类 | 用例数 | 覆盖范围 |
+|---|---|---|
+| `AoqEngineLifecycle` | 26 | getVersion / createEngine 参数矩阵 / 单例行为 / connect-disconnect 组合 |
+| `AoqEngineConnect` | 25 | connect 参数校验（空值/越界 port）/ 状态机序列 / 生命周期混乱 |
+| `AoqEnginePreCondition` | 15 | 未连接与未启动状态下的全 API 矩阵 + 状态完整性 |
+| `AoqEngineCallback` | 12 | 连接状态/音频设备状态等回调的触发与字段校验 |
+| `AoqEngineStats` | 6 | 统计回调（onStats）内容与频率 |
+| `AoqEngineAudio` | 31 | 采集/播放启停、静音、编解码配置、设备状态 |
+| `AoqEngineAudioFile` | 27 | 音频文件混音（启停/暂停/位置/音量/多文件） |
+| `AoqEngineAudioStream` | 29 | 外部音频流（add/push/音量/clear/remove/多流） |
+| `AoqEnginePlayerMixerNullPtr` | 5 | 播放器/混音器空指针保护 |
+| `AoqEngineVideo` | 36 | 视频采集、编解码配置、外部推帧（BGRA/I420/JPEG） |
+| `AoqEngineVideoCamera` | 8 | 摄像头控制与切换 |
+| `AoqEngineVideoDecoderConfig` | 5 | 视频解码配置 |
+| `AoqEngineVideoPipeline` | 7 | 视频管线组合场景 |
+| `AoqEngineFrameObserver` | 12 | 音视频帧观察者注册/开关/帧数据与 stride 校验 |
+| `AoqEngineTrackModeConfig` | 5 | trackMode 配置 |
+| `AoqEngineDataMsg` | 19 | 数据消息参数矩阵、大载荷（64KB~8MB）、压力循环 |
+| `AoqEngineDestroy` | 13 | destroy 幂等、销毁后 API 短路、重建可用性 |
+
+设计要点（与 iOS 一致）：
+- **不连真实服务**：所有 connect 指向不可达端点 `127.0.0.1:9999`，只验证参数处理与 API 安全性
+- **armed 隔离**：引擎为单例，MockDelegate 用 armed 开关丢弃前序残留回调
+- **串行执行**：`--runInBand`，避免多 worker 抢音频/摄像头设备与 native 单例锁
+- **环境降级**：无麦克风/摄像头权限时，帧回调类用例以 `got` 守护跳过断言，不误报
+- **超时预算**：`callWithBudget` 对可能阻塞的接口测耗时，超预算以 `[SDK BUG]` 标记暴露
+
+### 新增用例
+
+在 `test/` 下新建 `<类名>.test.js` 即自动被发现（`testMatch: test/**/*.test.js`），
+公共能力从 `test/helpers/TestHelper.js` 取：
+
+```js
+const { createEngineOrFail, makeConnectConfig, sleep, T } = require('./helpers/TestHelper')
+
+describe('AoqEngineXxx', () => {
+    let engine, delegate
+    beforeEach(() => { ({ engine, delegate } = createEngineOrFail('xxx')) })
+    afterEach(async () => { engine.disconnect(); await sleep(300); delegate.uninstall() })
+
+    test('某接口返回 0', () => {
+        expect(engine.someApi({ /* ... */ })).toBe(0)
+    })
+})
+```
+
+新增用例后重跑 runner，覆盖率会自动重算（静态扫描 `engine.<method>(` 调用）。
+
+## 依赖引入方式（两种均支持）
+
+**方式一：源码目录（file: 符号链接，仓内联调默认）**
+
+```json
+"dependencies": { "aoq-electron-sdk": "file:../../aoq-client-sdk/api/electron/AoqClientSdk" }
+```
+
+npm 创建符号链接指向本目录，重编 SDK 后消费方无需重新 install 即生效。
+
+**方式二：二进制包（npm tgz，发布形态 / 外部工程集成）**
+
+```bash
+# 打包：构建 + npm pack → dist/aoq-electron-sdk-<ver>.tgz
+sh aoq-client-sdk/build_scripts/Electron/generate_aoq_sdk.sh Release Build Pack
+
+# 消费方安装（真实拷贝进 node_modules）
+npm install /path/to/aoq-electron-sdk-1.0.0.tgz
+```
+
+注意：`.framework` 内含符号链接而 npm pack 会丢弃 symlink，故打包时用
+ditto 压成 `AoqClientSdk.framework.zip` 随包分发（`files` 已排除 framework
+目录本体），安装时由 `scripts/postinstall.js` 自动解压还原。
+
+demo 工程可用 `aoq-client-demo/Electron/use_sdk.sh source|package` 一键切换。
+
+## 发布到 npm 仓库（外部客户 npm install 直接下载）
+
+### 一次性准备（首次发布前）
+
+```bash
+# 1. 登录 npm 账号（浏览器完成授权，建议开启 2FA）
+npm login --registry https://registry.npmjs.org/
+
+# 2. 检查包名是否被占用（404 = 可用）
+npm view aoq-electron-sdk --registry https://registry.npmjs.org/
+```
+
+包名已定为 **`aoq-electron-sdk`**（裸名，对齐 agora-electron-sdk 的命名风格）。
+裸名在 npm 上先到先得，建议尽早完成首次发布占住名字；若 `npm view` 发现
+已被占用，再考虑切换 scoped 形式（改 package.json 的 `name` 字段并同步
+demo 侧 import/配置即可）。`publishConfig.access` 保持 `public`（对裸名包
+无副作用，未来切 scoped 时免踩 private 默认值）。
+
+### 每次发布流程
+
+```bash
+# 1. 构建 Release 产物 + 生成 framework.zip（必须走 Pack）
+sh aoq-client-sdk/build_scripts/Electron/generate_aoq_sdk.sh Release Build Pack
+
+# 2. 升版本号（npm 不允许覆盖已发布的版本）
+cd aoq-client-sdk/api/electron/AoqClientSdk
+npm version patch        # 或 minor / major，自动改 package.json
+
+# 3. 发布（自动触发 prepublishOnly 产物校验）
+npm publish
+
+# 4. 验证
+npm view aoq-electron-sdk
+```
+
+客户侧从此可直接：`npm install aoq-electron-sdk`。
+
+发布前可用 `npm publish --dry-run` 预检（不上传，展示包内容与体积）。
+
+### 已内置的发布防护（package.json）
+
+| 配置 | 作用 |
+|---|---|
+| `prepublishOnly` → `scripts/prepublish-check.js` | 发布前强制校验 `js/`、`types/`、`.node`、`framework.zip` 四类产物齐全，防止忘跑 Pack 发出缺原生库的废包 |
+| `os: ["darwin"]` / `cpu: ["arm64"]` | Windows/Linux/x64 用户 install 时直接报平台不支持，而非运行时崩溃 |
+| `publishConfig.registry/access` | 锁定发布到 registry.npmjs.org；access 显式 public，未来切 scoped 包名时免踩 private 默认值 |
+
+### 注意事项
+
+- **合规**：framework 是完整原生 SDK 二进制，发到公网 npm 意味着任何人可
+  下载（含符号信息），发布前需确认商务/安全侧允许对外分发。
+- **CI 发布**：用 npm Access Token（`npm token create` → CI 环境变量
+  `NPM_TOKEN`，`.npmrc` 写 `//registry.npmjs.org/:_authToken=${NPM_TOKEN}`），
+  避免人肉 login。
+- **发布目标**：本包面向公网所有用户，固定发布到 registry.npmjs.org（已由
+  `publishConfig.registry` 锁定），不使用内部 registry。
+- **版本不可覆盖**：发错了只能 `npm deprecate` 标废 + 发新版本，
+  `npm unpublish` 有 72 小时等严格限制，发布前务必 dry-run 确认。
+
+## 使用
+
+```js
+import createAoqClientEngine, { AoqTrackType } from 'aoq-electron-sdk'
+
+const engine = createAoqClientEngine()
+engine.on('onConnectionStatusChange', (status) => console.log(status))
+engine.on('onDataMsg', (data) => console.log(Buffer.from(data).toString()))
+
+engine.createEngine({ workDir: '/tmp/aoq', enableDumpAudio: false, extras: '' })
+engine.connect({
+  token, sid, certFingerprint,
+  relayEndpoints: [{ routeIndex: 0, endpoint, port }],
+  publishTracks: [{ trackType: AoqTrackType.AoqTrackTypeAudio }],
+  subscribeTracks: [{ trackType: AoqTrackType.AoqTrackTypeAudio }]
+})
+engine.startAudioCapture({ channel: 1 })
+engine.startAudioPlayer({ channel: 1 })
+engine.sendDataMsg('hello')
+engine.disconnect()
+engine.destroy()
+```
+
+Electron 集成注意（renderer 直接加载模式）：
+- `nodeIntegration: true`，webpack `externals: {'aoq-electron-sdk': 'commonjs2 aoq-electron-sdk'}`
+- 生产应用建议改走 main 进程 + IPC
+
+## API 面（与 AoqClientEngine.h 对齐）
+
+- 生命周期/连接：`createEngine / destroy / getVersion / connect / disconnect`
+- 音频：采集/播放/静音/暂停/恢复/打断、`setAudioEncoderConfig / setAudioDecoderConfig`
+- 视频：`startVideoCapture / stopVideoCapture`、`setVideoEncoder/DecoderConfig`、
+  `pushExternalVideoCapturedFrame(BGRA/I420)`、`pushExternalVideoEncodedFrame(JPEG)`
+- 音频文件混音：start/stop/pause/resume/时长/位置/音量 全套
+- 外部音频流：add/remove/push(PCM buffer)/音量/clearBuffer
+- 帧观察者：`setAudioFrameObserver / enableAudioFrameObserver`、
+  `setVideoFrameObserver / enableVideoFrameObserver`（仅只读模式）
+- 数据消息/流控制：`sendDataMsg / enableSendMediaStream`
+
+事件（`engine.on(...)`）：`onError / onWarning / onConnectionStatusChange / onStats /
+onAudioDeviceStateChanged / onAudioDeviceRouteChanged / onAudioFileState /
+onVideoDeviceStateChanged / onDataMsg` + 帧观察者
+`onCaptured/ProcessCaptured/Publish/PlaybackAudioFrame`、
+`onCaptured/PreEncode/RemoteVideoFrame`。
+
+## 视频渲染方案
+
+Electron renderer 是 Chromium，无法嵌入原生 view，故不透传
+`setLocalView/setRemoteView`。预览/渲染统一走：
+
+```
+enableVideoFrameObserver(I420) → 帧事件(meta + Y/U/V 拼接 buffer)
+    → YUVCanvasRenderer.drawFrame(canvas)
+```
+
+`ts/Renderer/YUVCanvasRenderer.ts` 基于 yuv-buffer + yuv-canvas 软件渲染，
+渲染模式（auto/stretch/fill/crop）由调用方用 CSS object-fit 近似。
+
+## 平台支持
+
+| 平台 | 状态 |
+|---|---|
+| macOS (arm64) | 已支持，链接 `AoqClientSdk.framework` |
+| Windows | 预留（CMakeLists Windows 分支 / 脚本注释），等原生 SDK Windows 构建链就绪后填入 |
+
+## 约束
+
+- 帧观察者仅支持只读（ReadWrite 跨进程回写不支持）；音频观察者 mode 固定 ReadOnly
+- CVPixelBuffer 外部推帧为 Apple 平台专属，Electron 侧提供 BGRA/I420/JPEG 路径
+- native 回调经 TSFN 异步投递，事件处理内请勿做重计算，避免高频帧事件堆积

package/js/AoqSdk.js

@@ -0,0 +1,32 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAoqClientEngine = createAoqClientEngine;
+const AoqClientEngineInternal_1 = require("./internal/AoqClientEngineInternal");
+__exportStar(require("./IAoqClientEngine"), exports);
+__exportStar(require("./Renderer/YUVCanvasRenderer"), exports);
+__exportStar(require("./Types"), exports);
+let instance;
+/**
+ * 获取引擎包装实例（懒加载单例，与 native AoqClientEngine 单例语义对齐）。
+ */
+function createAoqClientEngine() {
+    if (instance === undefined) {
+        instance = new AoqClientEngineInternal_1.AoqClientEngineInternal();
+    }
+    return instance;
+}
+exports.default = createAoqClientEngine;

package/js/IAoqClientEngine.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/js/Renderer/YUVCanvasRenderer.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YUVCanvasRenderer = void 0;
+/*
+ * YUVCanvasRenderer — 将视频帧观察者事件的 I420 数据画到 HTMLCanvasElement。
+ *
+ * Electron 没有原生 view，本渲染器承担 Mac 端 setLocalView/setRemoteView 的
+ * 预览职责：页面把 canvas 绑定到某个帧回调位置（captured/remote），
+ * 每次帧事件调用 drawFrame 即可。软件渲染基于 yuv-buffer + yuv-canvas。
+ */
+const Types_1 = require("../Types");
+/* yuv-canvas 依赖 DOM，延迟到首次 bind 时再 require，
+ * 避免在无 DOM 的 node/main 进程里加载 SDK 入口即失败。 */
+let YUVBuffer;
+let YUVCanvas;
+function ensureYuvLibs() {
+    if (!YUVBuffer) {
+        YUVBuffer = require('yuv-buffer');
+        YUVCanvas = require('yuv-canvas');
+    }
+}
+class YUVCanvasRenderer {
+    /** 绑定 canvas（重复绑定会替换 sink） */
+    bind(canvas) {
+        ensureYuvLibs();
+        this.canvas = canvas;
+        this.frameSink = YUVCanvas.attach(canvas, { webGL: false });
+    }
+    /** 解绑并清空画面 */
+    unbind() {
+        if (this.canvas) {
+            const ctx = this.canvas.getContext('2d');
+            ctx?.clearRect(0, 0, this.canvas.width, this.canvas.height);
+        }
+        this.frameSink = undefined;
+        this.canvas = undefined;
+    }
+    get bound() {
+        return this.frameSink !== undefined;
+    }
+    /** 绘制一帧（仅支持 I420；buffer 为 Y/U/V 平面按 stride 拼接） */
+    drawFrame(frame) {
+        if (!this.frameSink)
+            return;
+        if (frame.format !== Types_1.AoqVideoPixelFormat.AoqVideoPixelFormatI420)
+            return;
+        if (!frame.width || !frame.height || !frame.buffer?.length)
+            return;
+        const ySize = frame.strideY * frame.height;
+        const uSize = frame.strideU * (frame.height / 2);
+        const vSize = frame.strideV * (frame.height / 2);
+        if (frame.buffer.length < ySize + uSize + vSize)
+            return;
+        const format = YUVBuffer.format({
+            width: frame.width,
+            height: frame.height,
+            chromaWidth: frame.width / 2,
+            chromaHeight: frame.height / 2,
+        });
+        const yuvFrame = YUVBuffer.frame(format, { bytes: frame.buffer.subarray(0, ySize), stride: frame.strideY }, { bytes: frame.buffer.subarray(ySize, ySize + uSize), stride: frame.strideU }, {
+            bytes: frame.buffer.subarray(ySize + uSize, ySize + uSize + vSize),
+            stride: frame.strideV,
+        });
+        this.frameSink.drawFrame(yuvFrame);
+    }
+}
+exports.YUVCanvasRenderer = YUVCanvasRenderer;

package/js/Types.js

@@ -0,0 +1,138 @@
+"use strict";
+/*
+ * Types.ts — 枚举与配置结构定义。
+ *
+ * 字段名与 rtc_core/biz_engine/api/cpp_engine_api/AoqClientEngine.h
+ * 中对应结构体成员保持一致；本文件同时是 TS <-> native 之间
+ * JSON 协议的唯一事实来源。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AoqVideoCodecType = exports.AoqOrientationMode = exports.AoqMirrorMode = exports.AoqVideoObserverAlignment = exports.AoqVideoPixelFormat = exports.AoqVideoSource = exports.AoqAudioSource = exports.AoqAudioStreamDirection = exports.AoqVideoDeviceStateCode = exports.AoqAudioFileStateCode = exports.AoqAudioDeviceStateCode = exports.AoqConnectionStatus = exports.AoqEncoderType = exports.AoqTrackMode = exports.AoqTrackType = void 0;
+/** track 媒体类型，对齐 AoqTrackType */
+var AoqTrackType;
+(function (AoqTrackType) {
+    AoqTrackType[AoqTrackType["AoqTrackTypeAudio"] = 0] = "AoqTrackTypeAudio";
+    AoqTrackType[AoqTrackType["AoqTrackTypeVideo"] = 1] = "AoqTrackTypeVideo";
+    AoqTrackType[AoqTrackType["AoqTrackTypeData"] = 2] = "AoqTrackTypeData";
+    AoqTrackType[AoqTrackType["AoqTrackTypeScreen"] = 3] = "AoqTrackTypeScreen";
+})(AoqTrackType || (exports.AoqTrackType = AoqTrackType = {}));
+/** 流式与非流式模式（仅音频下行生效），对齐 AoqTrackMode */
+var AoqTrackMode;
+(function (AoqTrackMode) {
+    AoqTrackMode[AoqTrackMode["AoqTrackModeSegment"] = 0] = "AoqTrackModeSegment";
+    AoqTrackMode[AoqTrackMode["AoqTrackModeStream"] = 1] = "AoqTrackModeStream";
+})(AoqTrackMode || (exports.AoqTrackMode = AoqTrackMode = {}));
+/** track 媒体格式，对齐 AoqEncoderType */
+var AoqEncoderType;
+(function (AoqEncoderType) {
+    AoqEncoderType[AoqEncoderType["AoqEncoderTypeUnknown"] = 0] = "AoqEncoderTypeUnknown";
+    AoqEncoderType[AoqEncoderType["AoqEncoderTypeAudioPCM"] = 1] = "AoqEncoderTypeAudioPCM";
+    AoqEncoderType[AoqEncoderType["AoqEncoderTypeAudioOpus"] = 2] = "AoqEncoderTypeAudioOpus";
+    AoqEncoderType[AoqEncoderType["AoqEncoderTypeVideoH264"] = 3] = "AoqEncoderTypeVideoH264";
+    AoqEncoderType[AoqEncoderType["AoqEncoderTypeVideoJpeg"] = 4] = "AoqEncoderTypeVideoJpeg";
+    AoqEncoderType[AoqEncoderType["AoqEncoderTypeDataText"] = 5] = "AoqEncoderTypeDataText";
+})(AoqEncoderType || (exports.AoqEncoderType = AoqEncoderType = {}));
+/** 引擎连接状态，对齐 AoqConnectionStatus */
+var AoqConnectionStatus;
+(function (AoqConnectionStatus) {
+    AoqConnectionStatus[AoqConnectionStatus["AoqConnectionStatusDisconnected"] = 0] = "AoqConnectionStatusDisconnected";
+    AoqConnectionStatus[AoqConnectionStatus["AoqConnectionStatusConnecting"] = 1] = "AoqConnectionStatusConnecting";
+    AoqConnectionStatus[AoqConnectionStatus["AoqConnectionStatusConnected"] = 2] = "AoqConnectionStatusConnected";
+    AoqConnectionStatus[AoqConnectionStatus["AoqConnectionStatusFailed"] = 3] = "AoqConnectionStatusFailed";
+})(AoqConnectionStatus || (exports.AoqConnectionStatus = AoqConnectionStatus = {}));
+/** 音频设备状态码，对齐 AoqAudioDeviceStateCode */
+var AoqAudioDeviceStateCode;
+(function (AoqAudioDeviceStateCode) {
+    AoqAudioDeviceStateCode[AoqAudioDeviceStateCode["AoqAudioDeviceNone"] = 0] = "AoqAudioDeviceNone";
+    AoqAudioDeviceStateCode[AoqAudioDeviceStateCode["AoqAudioDeviceRecordStarting"] = 1] = "AoqAudioDeviceRecordStarting";
+    AoqAudioDeviceStateCode[AoqAudioDeviceStateCode["AoqAudioDeviceRecordStarted"] = 2] = "AoqAudioDeviceRecordStarted";
+    AoqAudioDeviceStateCode[AoqAudioDeviceStateCode["AoqAudioDeviceRecordStopping"] = 3] = "AoqAudioDeviceRecordStopping";
+    AoqAudioDeviceStateCode[AoqAudioDeviceStateCode["AoqAudioDeviceRecordStopped"] = 4] = "AoqAudioDeviceRecordStopped";
+    AoqAudioDeviceStateCode[AoqAudioDeviceStateCode["AoqAudioDeviceRecordFail"] = 5] = "AoqAudioDeviceRecordFail";
+    AoqAudioDeviceStateCode[AoqAudioDeviceStateCode["AoqAudioDevicePlayStarting"] = 6] = "AoqAudioDevicePlayStarting";
+    AoqAudioDeviceStateCode[AoqAudioDeviceStateCode["AoqAudioDevicePlayStarted"] = 7] = "AoqAudioDevicePlayStarted";
+    AoqAudioDeviceStateCode[AoqAudioDeviceStateCode["AoqAudioDevicePlayStopping"] = 8] = "AoqAudioDevicePlayStopping";
+    AoqAudioDeviceStateCode[AoqAudioDeviceStateCode["AoqAudioDevicePlayStopped"] = 9] = "AoqAudioDevicePlayStopped";
+    AoqAudioDeviceStateCode[AoqAudioDeviceStateCode["AoqAudioDevicePlayFail"] = 10] = "AoqAudioDevicePlayFail";
+})(AoqAudioDeviceStateCode || (exports.AoqAudioDeviceStateCode = AoqAudioDeviceStateCode = {}));
+/** 音频文件播放状态码，对齐 AoqAudioFileStateCode */
+var AoqAudioFileStateCode;
+(function (AoqAudioFileStateCode) {
+    AoqAudioFileStateCode[AoqAudioFileStateCode["AoqAudioFileNone"] = 0] = "AoqAudioFileNone";
+    AoqAudioFileStateCode[AoqAudioFileStateCode["AoqAudioFileStarted"] = 1] = "AoqAudioFileStarted";
+    AoqAudioFileStateCode[AoqAudioFileStateCode["AoqAudioFileStopped"] = 2] = "AoqAudioFileStopped";
+    AoqAudioFileStateCode[AoqAudioFileStateCode["AoqAudioFilePaused"] = 3] = "AoqAudioFilePaused";
+    AoqAudioFileStateCode[AoqAudioFileStateCode["AoqAudioFileResumed"] = 4] = "AoqAudioFileResumed";
+    AoqAudioFileStateCode[AoqAudioFileStateCode["AoqAudioFileEnded"] = 5] = "AoqAudioFileEnded";
+    AoqAudioFileStateCode[AoqAudioFileStateCode["AoqAudioFileBuffering"] = 6] = "AoqAudioFileBuffering";
+    AoqAudioFileStateCode[AoqAudioFileStateCode["AoqAudioFileBufferingEnd"] = 7] = "AoqAudioFileBufferingEnd";
+    AoqAudioFileStateCode[AoqAudioFileStateCode["AoqAudioFileFailed"] = 8] = "AoqAudioFileFailed";
+})(AoqAudioFileStateCode || (exports.AoqAudioFileStateCode = AoqAudioFileStateCode = {}));
+/** 视频设备状态码，对齐 AoqVideoDeviceStateCode */
+var AoqVideoDeviceStateCode;
+(function (AoqVideoDeviceStateCode) {
+    AoqVideoDeviceStateCode[AoqVideoDeviceStateCode["AoqVideoDeviceNone"] = 0] = "AoqVideoDeviceNone";
+    AoqVideoDeviceStateCode[AoqVideoDeviceStateCode["AoqVideoDeviceCaptureStarting"] = 1] = "AoqVideoDeviceCaptureStarting";
+    AoqVideoDeviceStateCode[AoqVideoDeviceStateCode["AoqVideoDeviceCaptureStarted"] = 2] = "AoqVideoDeviceCaptureStarted";
+    AoqVideoDeviceStateCode[AoqVideoDeviceStateCode["AoqVideoDeviceCaptureStopping"] = 3] = "AoqVideoDeviceCaptureStopping";
+    AoqVideoDeviceStateCode[AoqVideoDeviceStateCode["AoqVideoDeviceCaptureStopped"] = 4] = "AoqVideoDeviceCaptureStopped";
+    AoqVideoDeviceStateCode[AoqVideoDeviceStateCode["AoqVideoDeviceCaptureFail"] = 5] = "AoqVideoDeviceCaptureFail";
+})(AoqVideoDeviceStateCode || (exports.AoqVideoDeviceStateCode = AoqVideoDeviceStateCode = {}));
+/** 音频流方向，对齐 AoqAudioStreamDirection */
+var AoqAudioStreamDirection;
+(function (AoqAudioStreamDirection) {
+    AoqAudioStreamDirection[AoqAudioStreamDirection["AoqAudioStreamPublish"] = 0] = "AoqAudioStreamPublish";
+    AoqAudioStreamDirection[AoqAudioStreamDirection["AoqAudioStreamPlayout"] = 1] = "AoqAudioStreamPlayout";
+})(AoqAudioStreamDirection || (exports.AoqAudioStreamDirection = AoqAudioStreamDirection = {}));
+/** 音频数据源类型，对齐 AoqAudioSource */
+var AoqAudioSource;
+(function (AoqAudioSource) {
+    AoqAudioSource[AoqAudioSource["AoqAudioSourceCaptured"] = 0] = "AoqAudioSourceCaptured";
+    AoqAudioSource[AoqAudioSource["AoqAudioSourceProcessCaptured"] = 1] = "AoqAudioSourceProcessCaptured";
+    AoqAudioSource[AoqAudioSource["AoqAudioSourcePublish"] = 2] = "AoqAudioSourcePublish";
+    AoqAudioSource[AoqAudioSource["AoqAudioSourcePlayback"] = 3] = "AoqAudioSourcePlayback";
+})(AoqAudioSource || (exports.AoqAudioSource = AoqAudioSource = {}));
+/** 视频帧回调数据源（管线位置），对齐 AoqVideoSource */
+var AoqVideoSource;
+(function (AoqVideoSource) {
+    AoqVideoSource[AoqVideoSource["AoqVideoSourceCaptured"] = 0] = "AoqVideoSourceCaptured";
+    AoqVideoSource[AoqVideoSource["AoqVideoSourcePreEncode"] = 1] = "AoqVideoSourcePreEncode";
+    AoqVideoSource[AoqVideoSource["AoqVideoSourceRemote"] = 2] = "AoqVideoSourceRemote";
+})(AoqVideoSource || (exports.AoqVideoSource = AoqVideoSource = {}));
+/** 视频像素格式，对齐 AoqVideoPixelFormat */
+var AoqVideoPixelFormat;
+(function (AoqVideoPixelFormat) {
+    AoqVideoPixelFormat[AoqVideoPixelFormat["AoqVideoPixelFormatUnknown"] = 0] = "AoqVideoPixelFormatUnknown";
+    AoqVideoPixelFormat[AoqVideoPixelFormat["AoqVideoPixelFormatI420"] = 1] = "AoqVideoPixelFormatI420";
+    AoqVideoPixelFormat[AoqVideoPixelFormat["AoqVideoPixelFormatNV12"] = 2] = "AoqVideoPixelFormatNV12";
+    AoqVideoPixelFormat[AoqVideoPixelFormat["AoqVideoPixelFormatNV21"] = 3] = "AoqVideoPixelFormatNV21";
+    AoqVideoPixelFormat[AoqVideoPixelFormat["AoqVideoPixelFormatBGRA"] = 4] = "AoqVideoPixelFormatBGRA";
+    AoqVideoPixelFormat[AoqVideoPixelFormat["AoqVideoPixelFormatRGBA"] = 5] = "AoqVideoPixelFormatRGBA";
+})(AoqVideoPixelFormat || (exports.AoqVideoPixelFormat = AoqVideoPixelFormat = {}));
+/** 视频宽度对齐方式，对齐 AoqVideoObserverAlignment */
+var AoqVideoObserverAlignment;
+(function (AoqVideoObserverAlignment) {
+    AoqVideoObserverAlignment[AoqVideoObserverAlignment["AoqVideoObserverAlignmentDefault"] = 0] = "AoqVideoObserverAlignmentDefault";
+    AoqVideoObserverAlignment[AoqVideoObserverAlignment["AoqVideoObserverAlignmentEven"] = 1] = "AoqVideoObserverAlignmentEven";
+    AoqVideoObserverAlignment[AoqVideoObserverAlignment["AoqVideoObserverAlignment4"] = 2] = "AoqVideoObserverAlignment4";
+    AoqVideoObserverAlignment[AoqVideoObserverAlignment["AoqVideoObserverAlignment8"] = 3] = "AoqVideoObserverAlignment8";
+    AoqVideoObserverAlignment[AoqVideoObserverAlignment["AoqVideoObserverAlignment16"] = 4] = "AoqVideoObserverAlignment16";
+})(AoqVideoObserverAlignment || (exports.AoqVideoObserverAlignment = AoqVideoObserverAlignment = {}));
+/** 镜像模式，对齐 AoqMirrorMode */
+var AoqMirrorMode;
+(function (AoqMirrorMode) {
+    AoqMirrorMode[AoqMirrorMode["AoqMirrorModeDisabled"] = 0] = "AoqMirrorModeDisabled";
+    AoqMirrorMode[AoqMirrorMode["AoqMirrorModeEnabled"] = 1] = "AoqMirrorModeEnabled";
+})(AoqMirrorMode || (exports.AoqMirrorMode = AoqMirrorMode = {}));
+/** 方向模式，对齐 AoqOrientationMode */
+var AoqOrientationMode;
+(function (AoqOrientationMode) {
+    AoqOrientationMode[AoqOrientationMode["AoqOrientationModeAuto"] = 0] = "AoqOrientationModeAuto";
+    AoqOrientationMode[AoqOrientationMode["AoqOrientationModePortrait"] = 1] = "AoqOrientationModePortrait";
+    AoqOrientationMode[AoqOrientationMode["AoqOrientationModeLandscape"] = 2] = "AoqOrientationModeLandscape";
+})(AoqOrientationMode || (exports.AoqOrientationMode = AoqOrientationMode = {}));
+/** 外部编码帧 codec，对齐 AoqVideoCodecType */
+var AoqVideoCodecType;
+(function (AoqVideoCodecType) {
+    AoqVideoCodecType[AoqVideoCodecType["AoqVideoCodecTypeJPEG"] = 0] = "AoqVideoCodecTypeJPEG";
+})(AoqVideoCodecType || (exports.AoqVideoCodecType = AoqVideoCodecType = {}));