更新记录

1.0.0（2026-07-19）

首发：用 原生实现声波数据传输核心：FSK（频移键控）把短文本编码为音频样本/WAV，再由麦克风/PCM 解码还原，帧含前导同步音 + 长度 + 载荷 + CRC-1

平台兼容性

uni-app x(5.14)

nex-sonic · 声波数据传输（FSK）

自研声波数据传输核心：FSK（频移键控） 把短文本调制成音频样本/WAV，再由 PCM/麦克风采集解调还原。提供 uni-app 可调的 JS 对象 API。

思路：发送端把字节按位映射到两个固定频率的「双音」（mark/space），相位连续地拼成波形播放；接收端按符号宽度滑窗、用 Goertzel 测两频功率判 bit，重组出帧并 CRC 校验。

适用：近场设备配网（喇叭 → 麦克风传 WiFi 配置）、碰一碰/靠近传短数据、离线无网环境的小数据交换、声波红包/口令。

支持 App 端（Android / iOS） 与 H5 端（同一自研核心 编译为 H5 端， encodeToPcm / decodeFromPcm + sonicDefaultConfig / sonicCoreVersion 可用，样本可直接对接 Web Audio API；WAV 文件型 4 API（encodeToWav/decodeFromWav/sonicEncodeWav/sonicDecodeWav） 浏览器无文件系统不支持、调用即抛错；bash scripts/build-H5 端引擎.sh sonic 构建、 node scripts/H5 端引擎-smoke/sonic.test.mjs 验真值；H5 端建议应用启动时 await ensureReady() 一次， 详见 docs/h5-H5 端引擎-support.md）；小程序不支持。uni-app x（uvue）与经典 uni-app（vue3）都可引入。 全自研（无 iOS C 依赖）。

能力一览

• 对象 new SonicModem(config)：建一次（持采样率/波特率/双音频率），反复用。
• 编码：encodeToPcm(text) → number[]（PCM f32，值域 [-1,1]）/ encodeToWav(text, outPath) → {sampleCount, durationMs}。
• 解码：decodeFromPcm(samples) → string / decodeFromWav(path) → string。
• 便捷自由函数：sonicEncodeWav(text, outPath, config) / sonicDecodeWav(path, config)（免建对象）/ sonicDefaultConfig() / sonicCoreVersion()。

帧结构

[前导持续 mark 音] [1 个 space 起始分隔符] [长度(u16) + 载荷 + CRC-16]，每字节 MSB 先展开为 bit，bit=1→freqHigh、bit=0→freqLow。CRC-16/IBM-SDLC 覆盖「长度 + 载荷」。

配置（全可选，缺省取默认）

最小用法

import { SonicModem } from '@/uni_modules/nex-sonic';

const modem = new SonicModem({});                  // {} = 全默认
const pcm = modem.encodeToPcm('HELLO 声波 2026');  // number[]，喂给 AudioContext 播放
// ... 采集到 PCM 样本 number[] 后：
try {
  const text = modem.decodeFromPcm(pcm);           // 'HELLO 声波 2026'
  console.log(text);
} catch (e) {
  // 无前导 / 信号截断 / CRC 校验失败 / 非 UTF-8 → 抛错
  console.error('解码失败', e);
}

// WAV 文件版（避免在 JS 侧搬运巨 buffer）
const res = modem.encodeToWav('配网口令 abc123', '/path/out.wav'); // {sampleCount, durationMs}
const back = modem.decodeFromWav('/path/out.wav');

约定 / 诚实边界（重要）

• 近场 / 安静信道 v1：CRC 仅检错、不纠错（无 FEC 前向纠错）；嘈杂环境、远距离、多径回声下识别率显著下降，应用层应自带「失败重传/确认」。
• 载荷是短数据：单帧载荷上限 8 KiB；FSK 速率低（默认 100 baud ≈ 12.5 字节/秒），适合口令/配置等短文本，不适合大文件。
• 文本即 UTF-8 字节：需要传二进制请在调用方 base64 编码成文本再传。
• 解码假设符号边界对齐：本插件自身 encode 产出满足；整数倍符号的前导静音可容忍，分数级时间偏移的精同步是 v2 项。
• WAV 为单声道 16-bit PCM Int；decodeFromWav 用 WAV 实际采样率做符号定时（频率为绝对 Hz）。
• 出错时原生层抛 SonicError/SonicException（InvalidParam / Io / Decode / Crc），UTS/JS 侧 try/catch。

实现 / 验证状态

• 自研核心：FSK 调制（相位连续 CPFSK）+ Goertzel 解调 + CRC-16，test 全绿、clippy --all-targets -D warnings 零告警。
• UTS 桥接：对象型 + 跨 Vec<f32>（PCM number[]）范式（同 nex-physics），已对账 绑定生成 真实生成签名。
• 真机 / HBuilderX cli --compile：与全仓同闸门，gated。