ggwave

小巧的数据声波传输库。

点击下方图片聆听实际音效：

https://user-images.githubusercontent.com/1991296/166411509-5e1b9bcb-3655-40b1-9dc3-9bec72889dcf.mp4

https://user-images.githubusercontent.com/1991296/168469004-aeb9b9fe-cf81-4db7-b602-62e4ae659341.mp4

详细说明

本库可让空气隔离的设备间通过声音传输少量数据。它实现了一种基于FSK的简单传输协议，便于集成到各类项目中。根据协议参数不同，带宽速率在8-16字节/秒之间。通过使用纠错码（ECC）提升了解调的稳健性。

本库仅用于生成和分析从音频设备（扬声器、麦克风等）播放和捕获的原始波形。您可自由选用任何音频后端（如PulseAudio、ALSA等），只需提供用于排队和出队音频样本的回调函数。

以下是ggwave的部分可能应用场景及示例：

• 无服务器一对多广播
  • wave-share - 通过声音分享文件
• 物联网
  • esp32-rx、arduino-rx、rp2040-rx、arduino-tx - 在微控制器上发送和接收声音数据
  • r2t2 - 使用PC扬声器传输数据
  • buttons - 通过语音按钮录制和发送指令
• 音频二维码
  • [Twitter] - 向附近设备广播剪贴板内容
• 设备配对/联系人交换
  • PairSonic - 与附近设备交换联系信息和公钥
• 授权认证

体验一下

您可以通过免费的 waver 应用轻松测试该库，该应用支持以下平台：

浏览器演示

• https://waver.ggerganov.com
  • https://ggwave.ggerganov.com
  • https://ggwave-js.ggerganov.com

HTTP 服务

  # audible example
  curl -sS 'https://ggwave-to-file.ggerganov.com/?m=Hello%20world!' --output hello.wav

  # ultrasound example
  curl -sS 'https://ggwave-to-file.ggerganov.com/?m=Hello%20world!&p=4' --output hello.wav

技术细节

以下是 ggwave 用于将数据编码和解码为声音所采用的调制与解调算法的简要概述。

调制（发送端）

当前方法采用多频频移键控（FSK）调制方案。待传输的数据首先被分割为 4 位的块。在每个时间点，通过 6 个音调传输 3 字节的数据——每个 4 位块对应一个音调。这 6 个音调在 4.5kHz 的频率范围内发出，该范围被划分为 96 个等间隔的频率：

频率 [Hz]	值 [比特]	频率 [Hz]	值 [比特]	...	频率 [Hz]	值 [比特]
F0 + 00*dF	块 0: 0000	F0 + 16*dF	块 1: 0000	...	F0 + 80*dF	块 5: 0000
F0 + 01*dF	块 0: 0001	F0 + 17*dF	块 1: 0001	...	F0 + 81*dF	块 5: 0001
F0 + 02*dF	块 0: 0010	F0 + 18*dF	块 1: 0010	...	F0 + 82*dF	块 5: 0010
...	...	...	...	...	...	...
F0 + 14*dF	块 0: 1110	F0 + 30*dF	块 1: 1110	...	F0 + 94*dF	块 5: 1110
F0 + 15*dF	块 0: 1111	F0 + 31*dF	块 1: 1111	...	F0 + 95*dF	块 5: 1111

对于所有协议：dF = 46.875 Hz。对于非超声波协议：F0 = 1875.000 Hz。对于超声波协议：F0 = 15000.000 Hz。

原始数据使用里德-所罗门纠错码进行编码。纠错码字节数根据原始数据的长度确定。经过编码后的数据才会被传输。

解调（接收端）

传输的开始和结束由特殊的声音标记标记（#13）。接收器监听这些标记，并记录标记之间的声音数据。然后对记录的数据进行傅里叶变换以获得频谱。检测到的频率按照与编码相同的方式被解码回二进制数据。

最后执行里德-所罗门解码以获取原始数据。

示例

examples 文件夹包含了该库的多个示例应用：

示例	描述	音频
ggtag	声音可编程电子纸徽章	PDM 麦克风
ggwave-rx	非常基础的仅接收程序	SDL
ggwave-cli	通过声音发送/接收数据的命令行工具	SDL
ggwave-wasm	用于 Web 应用的 WebAssembly 模块	SDL
ggwave-to-file	将生成的波形输出到未压缩的 WAV 文件	-
ggwave-from-file	从未压缩的 WAV 文件中解码波形	-
waver	通过声音发送/接收数据的 GUI 应用	SDL
ggwave-py	Python 示例	PortAudio
ggwave-js	JavaScript 示例	Web Audio API
spectrogram	频谱图工具	SDL
ggweb-spike	使用 WebView 将 ggwave 包装成简单应用的 Android 示例	WebAudio
buttons	通过语音按钮录制和发送命令	Web Audio API
r2t2	通过 PC 扬声器传输数据	PC 扬声器
ggwave-objc	使用 ggwave 的极简 Objective-C iOS 应用	AudioToolbox
ggwave-java	使用 ggwave 的极简 Java Android 应用	android.media
ggwave-kmm	使用 ggwave 的 Kotlin 多平台项目	android.media, javax.sound.sampled
ggwave-fm	使用 HackRF 传输 ggwave 消息	无线电
esp32-rx	使用 ESP32 发送和接收消息	-
rp2040-rx	使用树莓派 Pico (RP2040) 发送和接收消息	-
arduino-rx	使用 Arduino RP2040 发送和接收消息	-
arduino-tx	使用 Arduino Uno 发送消息	-
arduino-rx-web	接收来自 Arduino Uno 的消息	Web Audio API

其他使用 ggwave 或其原型之一的项目：

• wave-gui - 用于探索不同调制协议的 GUI
• wave-share - 带有声音信令的 WebRTC 文件共享

构建

基于SDL的示例的依赖项

[Ubuntu] $ sudo apt install libsdl2-dev

[使用brew的Mac OS]
$ brew install sdl2

[MSYS2]
$ pacman -S git cmake make mingw-w64-x86_64-dlfcn mingw-w64-x86_64-gcc mingw-w64-x86_64-SDL2

Linux、Mac、Windows (MSYS2)

# build
git clone https://github.com/ggerganov/ggwave --recursive
cd ggwave && mkdir build && cd build
cmake ..
make

# running
./bin/ggwave-cli

本地 Debian 软件包

构建可复现的 libggwave-dev 和 python3-ggwave Debian 软件包：

# Fetch source
git clone https://github.com/ggerganov/ggwave --recursive
cd ggwave

# Configure
cmake . -DGGWAVE_BUILD_EXAMPLES=OFF -DCMAKE_BUILD_TYPE=Release

# Build
make deb

# Install
sudo dpkg -i dist/*.deb

Emscripten

git clone https://github.com/ggerganov/ggwave --recursive
cd ggwave
mkdir build && cd build
emcmake cmake ..
make

Python

pip install ggwave

更多信息：https://pypi.org/project/ggwave/

Node.js

npm install ggwave

更多信息：https://www.npmjs.com/package/ggwave

iOS

可作为 Swift 包使用：https://github.com/ggerganov/ggwave-spm

安装 Waver 应用

Linux

sudo snap install waver
sudo snap connect waver:audio-record :audio-record

Mac OS

  brew install ggerganov/ggerganov/waver

参考文献

• Evaluating Acoustic Data Transmission Schemes for Ad-Hoc Communication Between Nearby Smart Devices