Cordova 鸿蒙空间音频实战:让网页里的声音“绕着头转“
WebView 里能不能有"真"空间音频、Web Audio 的 HRTF 在 ArkWeb 里到底支持到什么程度、零原生代码的纯 JS 插件怎么进 hcordova 宿主——这篇文章用一个一行 ArkTS 都没写的 Cordova 插件,把这三个问题一次讲透。
仓库地址:https://atomgit.com/oh-tpc/spatial-audio-cordova
版本地址:https://atomgit.com/oh-tpc
三方库框架:https://atomgit.com/CPF-Cordova
0. 环境与实测设备
| 项 | 版本/型号 |
|---|---|
| DevEco Studio | 26.0.0.851(HarmonyOS SDK 7.0.0 / API 26) |
| Cordova | 14.0.2 + cordova-ohos 7.0.0(hcordova CLI 1.0.7) |
| WebView | ArkWeb(Chromium 内核),页面源 https://www.example.com/www/ |
| 构建链 | esbuild 0.25 + TypeScript 5.9 + vitest 3.2(Node v24.14.1,DevEco 自带) |
| spatial-audio-cordova | 1.0.0(本仓库,www 产物 + 手工注入宿主) |
| 实测设备 | OpenHarmony 模拟器 7.0.0.107(SP8DEVC00E999R4P11),Mate 90 Pro 档位,ohos-x64 |
1. 从"写个原生插件"到一份 JS bundle
系列的第三个库轮到 Cordova。前两个成员一个在 ArkTS 里自渲染双耳 PCM(Flutter 版),一个把系统能力感知桥进 JS(RN 版),轮到 WebView 这边,我原来的打算是:老老实实写个原生插件,ArkTS 侧做个合成引擎,exec 桥一来一回——毕竟"WebView 里搞不了真音频"这个印象太根深蒂固了。
动手之前先做了个五分钟的对照实验,正是这五分钟推翻了我原来的判断:在 ArkWeb 的页面里跑一行 new AudioContext(),再 ctx.createPanner()、设 panningModel = 'HRTF'——全部成立。ArkWeb 就是 Chromium,Web Audio 是它自带的能力;HRTF 卷积空间化这种"听起来最贵"的能力,在 WebView 里是一行配置。实测探测的数据后来被固化进了插件的测量文件:pannerSupported=true,采样率 48000Hz,页面 console 打点经 hilog 透出 probe=108.70ms。
这个结果推翻了我原来的计划:Cordova 版不但不用写原生合成,连一行原生代码都不用写——plugin.xml 里没有 <feature>,没有平台源码目录,整个插件就是一份 TS 源码编译出来的 JS bundle。剩下的难题是两个:一是能力边界要摸清(HRTF 支持到什么程度、降级链怎么设计、WebView 里哪些音频焦点行为缺失);二是纯 JS 插件怎么进宿主(hcordova 1.0.7 拒绝 file 型插件,这个坑比想象里深)。
先把场景动机交代清楚:WebView 混合应用在今天依然是主流形态之一——营销活动页、H5 商城、内嵌帮助中心,这些页面往往大量使用音效与交互反馈。给这类页面加方位感,原生插件路线意味着每个平台各写一份 exec 桥,而 Web Audio 路线意味着同一份 JS 全平台通用。三件套的分工在这里正好互补:Cordova 成员管页面内的合成,感知与播放让给 RN 成员,自渲染让给 Flutter 成员——每个框架干自己生态里最顺手的事,共享同一组声学常数。
所以这个题目的边界收敛成三件事,对应「媒体:空间音频」题目的三个技术方向:
- 声音的方位感怎么合成——用 Web Audio 的 PannerNode(HRTF) 在页面内合成,配一条探测出来的降级链;
- 设备与焦点怎么办——WebView 内拿不到系统输出设备枚举、也没有 audioInterrupt,这两条缺席要如实声明,把感知职责让给 RN 成员;
- 纯 JS 插件的宿主接入——手工注入三步,外加浏览器直开的兼容设计。
提前交代能力边界:实测在 API 26 模拟器的 ArkWeb 上完成,探测、建图、方位拖动的数值链路全部验证到理论值级别;"听感"仍需真机耳机——三个成员的 demo 都标注了这一条,本库的页面文案里还额外写明了前后镜像的固有歧义。
2. 效果展示
先看效果。demo 页是一张卡片式面板,所有控件都是为了"边听边看数值"设计的。
页面加载完,deviceready 徽标先亮起来——绿色边框一行字:deviceready · SpatialAudio v1.0.0 · HRTF。这行字是三段信息的拼接:cordova 事件总线就绪、插件版本、以及 probe() 的结论。探测在 deviceready 里做了一次 performance.now 打点,经 console 直达 hilog(ARKWEB-CONSOLE 标签):SPA-PERF probe=108.70ms model=HRTF rate=48000 webAudio=true——ArkWeb 对 Web Audio 的支持程度,第一次有了精确读数。deviceready 之外还留了一个 10 秒的兜底:就算 cordova.js 缺席(比如把页面拖进桌面浏览器调试),徽标也会变成"浏览器模式 · HRTF"照常工作——bundle 自挂 window.SpatialAudio,deviceready 只是提供了一个更明确的就绪时机。这个双路兜底在调试期派上过用场:hcordova 宿主没配好时页面照样能在 WebView 里跑起来,插件层的问题和宿主层的问题从此可以分开排查。徽标上模型名(HRTF / stereo-panner-fallback)的可视化也是同理——能力探测的结果如果只留在日志里,接入方永远不知道自己听的是哪一档:

信号源三选一:440Hz 纯音、白噪声、扫频(带通滤波器中心频率 800Hz、由 0.3Hz 的 LFO 在 ±600Hz 范围往复扫动的白噪声)。听方位感用白噪声——稳态纯音的时间差线索在听感上最弱(系列第一篇 Flutter 版踩过这个认知坑),白噪声的全频段瞬态结构让方位感的线索最强。点"开始发声",hilog 里第二行打点亮出来:SPA-PERF start=75.90ms——这 75.9ms 里包含 AudioContext 从 suspended 到 running 的 resume、建图(信号源 → PannerNode → 增益 → destination)、以及首块音频送进渲染端。默认方位角 90°(正右方),电平表显示 ITD 0.650ms、左/右增益 0.200 / 1.000、远耳低通 1000Hz:

拖动方位角滑块时,数值变化最直观:拖到 170°,电平表实时刷新成 ITD 0.113ms、增益 0.756 / 1.000、低通 1992Hz——这三个数正是 sin(170°) = 0.1736 的理论值(0.65×0.1736 = 0.113;10^(−14×0.1736/20) = 0.756;2200−1200×0.1736 = 1992)。HRTF 输出声音的同时,参数随拖动实时更新,页面里的声音确实在跟着方位角移动:

音源切换与停止的交互也有细节:running 状态下点音源按钮,引擎内部走 teardown → rebuild(旧信号源 stop、伴生节点逐个停掉,新图无缝顶上),听感上没有爆音——方位角参数保留了,不会因为切音源回到 90°。点"停止"只拆信号源、保留 AudioContext(下次 start 免去重建),彻底释放走 dispose()——生命周期两档(stop / dispose)在 仓库说明的 API 表里写得明明白白。
页面底部有一段说明文字,把前后镜像的固有边界直接写给用户:把方位角拉到 180°,ITD/ILD 归零,但声音"去向"依旧含混——θ 和 180°−θ 的侧向分量相同,这是纯双耳线索的物理极限,不是实现缺陷。把边界直接写在页面上,是这个系列三个库共同的做法。
3. 原理:Web Audio 的图,WebView 的边界
3.1 信号链:方位感由 PannerNode 决定
Web Audio 的空间化是一张流水线图:信号源(OscillatorNode 或 AudioBufferSourceNode)→ PannerNode → 增益 → destination。方位感全部发生在 PannerNode:panningModel: 'HRTF' 时,Chromium 把声源信号与一组头脉冲响应做卷积,双耳时间差、强度差、耳廓滤波一次到位——这比手工实现 ITD/ILD/低通三件套(Flutter 成员干的事)要"真"得多,因为它连耳廓的频谱纹理都带着。
声源位置用右手坐标系描述:本插件把方位角映射到单位圆上,listenerPosition(180°) 给出 {x: 0, y: 0, z: 1}(正后),listenerPosition(90°) 给出 {x: 1, y: 0, z: 0}(正右)。拖动用 positionX/Y/Z 的 AudioParam 直接赋值——Chromium 内部做插值,听感是平滑移动而不是瞬移。
和手工三件套(ITD 延迟 + ILD 增益 + 低通)相比,HRTF 卷积多了两样东西:一是耳廓滤波——头脉冲响应里带着外耳反射的频谱纹理,这正是区分前后方向的物理线索;二是距离衰减(distanceModel: 'inverse'、refDistance: 1),声源远了会自然变轻。手工三件套能做出"水平面上的方位",HRTF 能做出"空间中的位置"——这也是三件套里 Flutter 成员保留自渲染、Cordova 成员直接用卷积的分工逻辑:前者要把计算过程写出来给读者看,后者要的是效果上限。当然通用 HRTF 也有它的档位:系统级方案用的是个性化 HRTF(基于人头扫描为每个人定制),加上头部追踪的动态线索,体验上限更高;Chromium 的 HRTF 是通用模型,方向感对所有人都成立但谈不上"量身"——这条档位线在三件套的原理篇里反复出现过,这里只划重点:通用卷积 > 手工三件套 > 纯声像,代价与覆盖面则反过来。
3.2 降级链:HRTF 不一定可用
HRTF 在 ArkWeb 上可用,不代表在所有 WebView 上可用。插件的 probe() 一次给出四个事实(webAudioSupported / pannerSupported / stereoPannerSupported / sampleRate),并据此定下本次会话的模型:
| 探测结果 | 采用模型 | 方位感质量 |
|---|---|---|
createPanner 存在 | HRTF | 卷积级,含耳廓滤波 |
| 无 PannerNode、有 StereoPannerNode | stereo-panner-fallback | 仅左右声像(无前后/距离感) |
| 有 AudioContext,但 PannerNode 和 StereoPannerNode 都没有 | equalpower | 仅左右声像,由插件分配左右增益 |
| 连 Web Audio 都没有 | 拒绝启动 + 事件通知 | 无 |
降级链由 probe 的输出决定:demo 页徽标上写的就是当前模型,用户永远知道自己听的是哪一档。探测做了会话级缓存:模型一次定死、中途不换,因为 WebView 的能力在运行中突变(内核热更新之类)不是值得为之复杂化的场景,真发生了走 probe({ refresh: true }) 强制刷新。这条链也回应了一个更根本的问题:WebView 的能力是设备能力的子集,任何"WebView 里一定有 XX"的假设都应该被 probe 一次代替。
3.3 WebView 缺失的两项能力,如实声明
一是音频焦点不存在。鸿蒙的 audioInterrupt 礼仪(来电抢占、拔耳机暂停)运行在系统音频服务层,WebView 内的 Web Audio 图对它不可见。页面切后台时 AudioContext 的生命周期由宿主 App 决定——建议宿主监听 visibilitychange:页面隐藏时 stop()(或挂起 AudioContext),回到前台再由用户手势恢复。这是宿主的职责,插件提供能力,但不负责这一层。另外,Web Audio 的 stop 语义:stop() 拆的是信号源、保留 AudioContext(下一次 start 免重建,实测更快),dispose() 才关闭上下文并清空探测缓存——两个生命周期档位在 仓库说明的 API 表里写明,接入方按场景选档。二是设备枚举不存在:probe() 能告诉你 HRTF 支不支持,但"当前声音从哪个设备出、系统空间音频开没开"在 WebView 里无从谈起——这正是 RN 成员(系统能力感知路线)的管辖范围。三个库的分工按边界划开:Cordova 管页面内的合成,RN 管系统层的感知,Flutter 管不依赖任何一方的自渲染。
还有一条小边界:WebView 里拿不到"插拔耳机"事件,所以 Flutter 版那条"拔出耳机自动暂停"的礼仪在这里没有对应物——同类混合应用若需要它,得由宿主原生层补事件桥。把不能做的事写进文档,比让接入方在运行时才发现要好。
3.4 与三件套路线的对照
| 成员 | 方位感来源 | 原生代码量 | 最适用的场景 |
|---|---|---|---|
| flutter_spatial_audio | ArkTS 自渲染双耳 PCM | 重(三个引擎) | 游戏、交互声效、听感实验 |
| spatial-audio-rn | 系统能力感知 + AVPlayer | 轻(一个 TurboModule) | 音乐播控、设备能力展示 |
| spatial-audio-cordova | ArkWeb Web Audio 合成 | 零 | WebView 混合应用、跨端一致性优先 |
纯 JS 路线最大的好处是跨端一致性:同一份 www/spatial-audio.js 在鸿蒙 ArkWeb、Android WebView、iOS WKWebView 里行为一致——插件没有一行 exec 调用,它就是一个带 Cordova 兼容外壳的 Web Audio 库。
4. 工程怎么搭:一个包,两份产物
spatial-audio-cordova/ # npm 包根(package.json v1.0.0)
├─ src/
│ ├─ spatial-audio.ts # 控制器:probe / start / setAzimuth / stop / dispose
│ ├─ math.ts # 双耳公式(三件套同常数)+ listenerPosition
│ ├─ types.ts / index.ts
├─ www/spatial-audio.js # esbuild IIFE 产物(已提交,三重兼容)
├─ types/ # 已提交的 .d.ts
├─ plugin.xml # id=com.lqjmac.cordova.spatialaudio,js-module 双声明
├─ __tests__/ # vitest 16(FakeAudioContext 桩)
├─ demo/index.html # 纯浏览器直开(不依赖 Cordova)
└─ example/
├─ www/ # 演示页源文件
└─ harmonyos/ # hcordova 宿主工程(整树入库)
└─ entry/src/main/resources/rawfile/www/ # 运行时页面(注入目标)
打包只有一个动作:esbuild 把 src/index.ts 打成 IIFE,footer 里做三重兼容——
// scripts/build.mjs(节选)
footer: {
js: [
'var __SA__ = SpatialAudioBundle.SpatialAudio;',
'if (typeof module !== "undefined" && module.exports) { module.exports = __SA__; }',
'if (typeof window !== "undefined") { window.SpatialAudio = __SA__; }',
].join('\n'),
},
这三行的意义:Cordova 的 js-module 机制用 CommonJS 的 cordova.define 加载,走第二行;手工 <script> 注入的场景走第三行(window.SpatialAudio 自挂);纯浏览器打开 demo 也走这一行。一份产物,三种宿主,零条件编译。types/ 目录同步提交 esbuild 之外的 tsc 声明(tsconfig.types.json 单独一份 emit 配置),接入方的 IDE 补全不依赖本地构建。本地门禁一条命令:npm run verify = tsc --noEmit(类型关)→ esbuild(产物关)→ vitest(16 个用例的逻辑关),三关全绿才允许动 www 产物。scripts 一览:build(类型关+产物关)、typecheck、test、verify、prepack(npm pack 前自动重跑 build,保证发出去的产物永远和源码同代)。www 产物与 types 声明都提交进仓库——消费方零构建直接用,这是 JS-only 插件区别于普通 npm 包的一个实用取舍:它的构建产物本来就是要原样塞进 WebView 的那份 JS。对使用方来说,最终看到的 API 就是 window.SpatialAudio 这个单例:
var cap = window.SpatialAudio.probe(); // {webAudioSupported, pannerSupported, ...}
window.SpatialAudio.start({ tone: 'noise', azimuthDeg: 90 }).then(function () {
window.SpatialAudio.setAzimuth(170); // 拖动中,电平表实时刷新
});
document.addEventListener('spatialaudio:state', function (e) { /* 引擎状态 */ });
5. 把代码讲透
5.1 probe:先问能力,再谈建图
// src/spatial-audio.ts - probe()(节选)
const AC = (globalThis as Record<string, unknown>)['AudioContext'] ??
(globalThis as Record<string, unknown>)['webkitAudioContext'];
const webAudioSupported = typeof AC === 'function';
if (webAudioSupported) {
const ctx = new (AC as new () => AudioContext)();
sampleRate = ctx.sampleRate;
pannerSupported = typeof ctx.createPanner === 'function';
stereoPannerSupported = typeof ctx.createStereoPanner === 'function';
void ctx.close(); // 探测用完即关,不留现场
}
this.model = pannerSupported ? 'HRTF'
: stereoPannerSupported ? 'stereo-panner-fallback' : 'equalpower';
调试时才意识到的地方:探测要开一个真实的 AudioContext才能拿到 sampleRate——typeof ctx.sampleRate 这种静态检查拿不到运行时事实。取构造函数时顺手兼容了 webkitAudioContext 前缀(老 WebView 的遗留命名),兼容代码只有一行,但它让插件在更多真机 WebView 上免于降级。探测上下文用完立即 close,把音频设备让给后续用于播放的上下文。probe 的结果做了会话级缓存(模型一次定死,中途不换),但缓存可以被 probe({ refresh: true }) 强制刷新——这个参数最初是为了单元测试加的(见坑三),后来发现它对"WebView 运行中能力突变"的场景也兜得住。
5.2 start:把 resume 塞进用户手势链
// src/spatial-audio.ts - start()(节选)
const cap = this.probe();
if (!cap.webAudioSupported) {
this.emit('error', { message: 'Web Audio not supported in this WebView' });
return;
}
this.ensureContext();
if (this.ctx!.state === 'suspended') {
await this.ctx!.resume(); // 必须在用户手势任务链内
}
this.teardownSource();
this.buildGraph();
Chromium 的自动播放策略:无用户手势时 AudioContext 停在 suspended,此时建图成功也无声。所以 start() 的第一件事是 resume,而 resume 必须与点击事件处于同一条 Promise 调用链——demo 里"开始发声"按钮的 onClick 直接调 start(),75.9ms 的实测时延就是这条链的全程(resume + 建图 + 首块音频)。拆成"点击置标志、定时器再启动"的写法会永远 suspended,这类问题控制台不报错、只能靠耳朵发现,是 Web Audio 最经典的坑。排查姿势倒是有仪可依:ctx.state 只有 running / suspended / closed 三态,start 之后不响就先看它——suspended 说明手势链断了,closed 说明哪里误调了 close,一眼定位。
5.3 建图与降级:一张图,两条路
// src/spatial-audio.ts - buildGraph()(节选)
const cap = this.probe();
this.source = this.createSource(ctx, this.tone); // 纯音/噪声/扫频
const gain = ctx.createGain();
gain.gain.value = 0.6;
if (cap.pannerSupported) {
this.panner = ctx.createPanner();
this.panner.panningModel = 'HRTF';
this.panner.distanceModel = 'inverse';
this.panner.refDistance = 1;
const pos = listenerPosition(this.azimuthDeg);
this.panner.positionX.value = pos.x;
this.panner.positionY.value = pos.y;
this.panner.positionZ.value = pos.z;
this.source.connect(this.panner);
this.panner.connect(gain);
} else {
// StereoPanner 兜底:只有左右声像,方位感质量降档
this.stereoPanner = ctx.createStereoPanner();
this.stereoPanner.pan.value = Math.max(-1, Math.min(1, Math.sin(this.azimuthDeg * Math.PI / 180)));
this.source.connect(this.stereoPanner);
this.stereoPanner.connect(gain);
}
gain.connect(ctx.destination);
this.source.start();
信号源的实现也值得一提:白噪声是 2 秒循环的 AudioBufferSourceNode(预生成随机 buffer,不是每帧 Math.random 糊振荡器——前者是标准的带宽噪声,后者会被采样率整形出怪调);扫频是同一个噪声 buffer 过一个带通滤波器(中心 800Hz、Q=2.5),滤波器频率由 0.3Hz 的 LFO 在 ±600Hz 摆动——听感上能明显听出中心频率在移动,拖方位角时它是最好的测试信号。扫频链里的 LFO 是一个额外的 OscillatorNode,stop 时要一并停掉,否则它会在引擎停止后继续运行——__tail 数组就是为挂这些"伴生节点"留的,teardown 时逐个 stop。setAzimuth 在 HRTF 路径写 positionX/Y/Z、在兜底路径写 pan,对外 API 不变——降级细节被封在引擎里。
5.4 测试桩:没有 AudioContext 的单元测试
jsdom 没有 Web Audio,__tests__ 里手写了一个 FakeAudioContext——记录每一次 connect、每一个参数写入,控制器逻辑就靠这些记录来断言:
// __tests__/spatial-audio.test.ts(节选)
it('positions the HRTF panner at the requested azimuth (90° = +x)', async () => {
await SpatialAudio.start({ azimuthDeg: 90 });
const panner = ctx.nodes.find((n) => n.kind === 'panner')!;
expect(panner.positionX.value).toBeCloseTo(1, 6);
expect(panner.positionZ.value).toBeCloseTo(0, 6);
});
it('stereo-panner fallback drives pan with the lateral value', async () => {
// 干掉 createPanner 再 start → 断言 stereopanner.pan = 1
});
16 个用例覆盖了降级链选择(有 PannerNode → HRTF / 无 PannerNode → stereo-panner)、建图连接顺序(source → panner → gain → destination 的方向性断言)、方位写入(90° 时 positionX=1、positionZ=0;前向 positionZ=−1)、setAzimuth 双路径、stop 拆图(source.stop 被调用、状态回落)、无 Web Audio 拒启动(state.running 保持 false)、以及数学层 9 个理论值锚点(与三件套另外两边同常数)。真实环境的最后一公里留给模拟器实测——performance.now 打点 + console.log + hilog 三件套,就是 WebView 里几乎零成本的可观测手段。
6. 我踩过的坑(每一条都有真实记录)
坑一:File-based plugins not yet supported——hcordova 拒绝 file 型插件。 hcordova plugin add ../ 直接被拒;更糟的是失败的 add 曾触发递归自拷,把目录撑出过 31GB(前一个项目的血泪史)。所以本插件的宿主接入只有手工注入三步:cordova.js 拷入宿主 rawfile/www/;www/spatial-audio.js 拷入 rawfile/www/js/;index.html 加一行 <script src="js/spatial-audio.js">。bundle 自挂 window.SpatialAudio,不依赖 cordova_plugins 注册表,deviceready 照常触发。
坑二:SyntaxError: Invalid or unexpected token——构建脚本里的 join 被写成真换行。 esbuild footer 的 join('\n') 需要字符串形式的 \n,用 Python 脚本生成 build.mjs 时转义层级错了,\n 变成了真换行,Node 直接语法报错:
scripts/build.mjs:27
].join('
^
SyntaxError: Invalid or unexpected token
修这类"生成器写生成物"的问题,最省事的验证是生成完立刻 node --check 一次。
坑三:测试桩自己的两个坑。 一是桩对象的参数工厂 makeParam 里把变量声明写在了 return 之后——死代码,闭包引用到的是永远未初始化的变量;二是控制器是模块级单例,probe 结果缓存跨用例残留,前一个用例把 createPanner 干掉后,后一个用例拿到的还是缓存的 HRTF 结论。修复:参数工厂改正写法,probe 加 refresh 参数,beforeEach 用 dispose() 把单例彻底归零。教训:测单例,先给它一个彻底复位的入口。
坑四:Cannot set properties of undefined (setting 'value')——桩少了个成员。 FakeNode 一开始没实现 gain 参数槽,控制器写 gain.gain.value = 0.6 时直接报错。这个报错的迷惑性在于它指向控制器代码,问题却在测试桩。修完顺手把 FakeNode 的成员补齐成 Web Audio 的真实形状。
坑五:截图截到"白屏过渡帧",差点误判样式失效。 安装启动后 8 秒截图,页面全白——一度怀疑 CSP 把内联样式拦了。先用 uitest dumpLayout 看控件树,文字全在(标题、徽标、按钮一个不少),再截一张,页面完好。真相是 ArkWeb 首帧绘制(hilog 里 FCP 3228ms)与合成器上屏之间有间隙,恰好截在空档。教训有两条:WebView 的视觉验证以控件树为准,截图只是辅助;以及 hilog 里的 PageFirstContentfulPaint 打点是现成的时序参考——截图时机跟着 FCP 走,而不是跟着 install 成功走。
坑六:宿主 app.json5 的 bundleName 不跟 config.xml 走。 只改 example/config.xml 的 widget id,hcordova 生成的 AppScope/app.json5 里 bundleName 还是旧值,aa start 报:
Error Code:10104001 Error Message:The specified ability does not exist
Error cause: The specified Ability is not installed
两处要一起改,或者以 app.json5 为准。这类"配置有两份来源"的坑在 Cordova 生态里是常态:config.xml 是 Cordova 的世界,app.json5 是鸿蒙的世界,hcordova 只在生成那一刻对齐一次,之后只能手动保持同步——生成后建议把 app.json5 里的关键项(bundleName、versionName)列进提交前检查清单。
坑七:构建路径与页面双份的纪律。 hvigor 拒绝非 ASCII 路径(中文用户名的机器上必须把构建副本放纯 ASCII 目录,仓库本体只当源码真值);example 的演示页有两份——example/www/(源)与 example/harmonyos/entry/src/main/resources/rawfile/www/(运行时),改了源页必须手动同步过去(连同一份插件 bundle),只改源页不打包,模拟器上永远跑旧页面。两条都是纪律类坑,踩一次记一辈子。还有一条环境类:构建工具链的 Node 用 DevEco 自带的那套(v24.14.1),与机器默认版本并存时优先 PATH 前置——esbuild 与 vitest 在两个版本下都能跑,但混用缓存目录曾出过产物陈旧的问题。
7. 现在怎么用:从 三方库 到依赖
插件未发布到 npm,仓库即产物:www/spatial-audio.js 与 types/ 已提交,消费方零构建。宿主接入走手工注入三步(见坑一):
# 1. cordova.js 拷入宿主 rawfile/www/
# 2. www/spatial-audio.js 拷入宿主 rawfile/www/js/
# 3. index.html 加:<script src="js/spatial-audio.js"></script>
页面代码只需三段:deviceready 里 probe()(徽标显示模型与采样率);按钮回调里 start({tone, azimuthDeg})(必须在用户手势链内);拖动回调里 setAzimuth(deg)。想看引擎状态,监听 document 上的 spatialaudio:state / azimuth / error CustomEvent。仓库文档的分工:英文接入指南、带报错原文的构建与实测记录、本库与三件套其他成员的分工边界,以及本篇引用的原始测量数据。
最后是几个常见问题的如实回答。同一份 bundle 能在 Android/iOS 的 Cordova 里用吗? 能,插件没有一行平台代码,Web Audio 在 Android WebView 与 iOS WKWebView 里都是标准能力——唯一的平台差异是各内核对 HRTF 的支持程度,probe() 会如实告诉你当前在哪一档。能同时发多个声源吗? 能,Web Audio 的图天然支持多信号源共享一个 PannerNode 或各自挂 PannerNode;本插件把 API 收敛为单声源(一个实验室该有的最小形态),多声源混音策略属于业务层。音量怎么控制? 建图里的 gain 节点目前是固定 0.6,对外没有暴露音量 API——刻意留白:音量策略(全局、按声源、按平台统一响度)是业务决策,不是引擎决策。时延呢? 合成信号没有解码开销,实测 start 75.9ms 里大头是 context resume;拖动的方位更新是 AudioParam 原子写入,听感连续。
三件套的分工在这里再对一次表:
| 成员 | 方位感来源 | 原生代码量 | 系统感知 | 页面内合成 |
|---|---|---|---|---|
| flutter_spatial_audio | ArkTS 自渲染双耳 PCM | 重 | 有(快照+事件) | 有(引擎级) |
| spatial-audio-rn | 系统能力感知 + AVPlayer | 轻 | 有(快照+事件) | 无(刻意留给 Flutter) |
| spatial-audio-cordova | ArkWeb Web Audio 合成 | 零 | 无(WebView 不提供) | 有(HRTF 卷积) |
验证清单:tsc 0 错误、esbuild 产物 node --check 通过、vitest 16/16(math 9 + 控制器 7);模拟器 ArkWeb 实测 probe 108.70ms(HRTF、48000Hz)、start 75.90ms、方位角拖到 170° 电平表实时刷新为理论值(ITD 0.113ms / 0.756 / 1992Hz)。当前版本在 Cordova 14.0.2 + cordova-ohos 7.0.0、API 26 模拟器验证。真机上插一副耳机,把方位角从 −90° 匀速拖到 +90°,可以听出声源从左耳绕到前、再到右耳。
三件套的分工可以这样对照:同一道"让声音绕着头转"的题,Flutter 成员用 ArkTS 把公式逐行写出来(教学价值),RN 成员把系统的感知礼仪带进 JS(工程价值),Cordova 成员证明一条 JS 就能在 WebView 里跑通全程(覆盖价值)——三个仓库、三种路线、一组常数,合成与感知的每一层都有得选。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐

所有评论(0)