ggwave README

项目的 README,来自 github.com/ggerganov/ggwave。合并为一个 markdown 文件:README.md。

ggwave

Actions Status License: MIT ggwave badge pypi npm

Tiny data-over-sound library.

Click on the images below to hear what it sounds like:

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

Details

This library allows you to communicate small amounts of data between air-gapped devices using sound. It implements a simple FSK-based transmission protocol that can be easily integrated in various projects. The bandwidth rate is between 8-16 bytes/sec depending on the protocol parameters. Error correction codes (ECC) are used to improve demodulation robustness.

This library is used only to generate and analyze the RAW waveforms that are played and captured from your audio devices (speakers, microphones, etc.). You are free to use any audio backend (e.g. PulseAudio, ALSA, etc.) as long as you provide callbacks for queuing and dequeuing audio samples.

Here is a list of possible applications of ggwave with a few examples:

Try it out

You can easily test the library using the free waver application which is available on the following platforms:

Download on the App Store Get it on Google Play Get it from the Snap Store

Browser demos

HTTP service

# 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

Technical details

Below is a short summary of the modulation and demodulation algorithm used in ggwave for encoding and decoding data into sound.

Modulation (Tx)

The current approach uses a multi-frequency Frequency-Shift Keying (FSK) modulation scheme. The data to be transmitted is first split into 4-bit chunks. At each moment of time, 3 bytes are transmitted using 6 tones - one tone for each 4-bit chunk. The 6 tones are emitted in a 4.5kHz range divided in 96 equally-spaced frequencies:

Freq, [Hz] Value, [bits] Freq, [Hz] Value, [bits] ... Freq, [Hz] Value, [bits]
F0 + 00*dF Chunk 0: 0000 F0 + 16*dF Chunk 1: 0000 ... F0 + 80*dF Chunk 5: 0000
F0 + 01*dF Chunk 0: 0001 F0 + 17*dF Chunk 1: 0001 ... F0 + 81*dF Chunk 5: 0001
F0 + 02*dF Chunk 0: 0010 F0 + 18*dF Chunk 1: 0010 ... F0 + 82*dF Chunk 5: 0010
... ... ... ... ... ... ...
F0 + 14*dF Chunk 0: 1110 F0 + 30*dF Chunk 1: 1110 ... F0 + 94*dF Chunk 5: 1110
F0 + 15*dF Chunk 0: 1111 F0 + 31*dF Chunk 1: 1111 ... F0 + 95*dF Chunk 5: 1111

For all protocols: dF = 46.875 Hz. For non-ultrasonic protocols: F0 = 1875.000 Hz. For ultrasonic protocols: F0 = 15000.000 Hz.

The original data is encoded using Reed-Solomon error codes. The number of ECC bytes is determined based on the length of the original data. The encoded data is the one being transmitted.

Demodulation (Rx)

Beginning and ending of the transmission are marked with special sound markers (#13). The receiver listens for these markers and records the in-between sound data. The recorded data is then Fourier transformed to obtain a frequency spectrum. The detected frequencies are decoded back to binary data in the same way they were encoded.

Reed-Solomon decoding is finally performed to obtain the original data.

Examples

The examples folder contains several sample applications of the library:

Example Description Audio
ggtag Sound-programmable e-paper badge PDM mic
ggwave-rx Very basic receive-only program SDL
ggwave-cli Command line tool for sending/receiving data through sound SDL
ggwave-wasm WebAssembly module for web applications SDL
ggwave-to-file Output a generated waveform to an uncompressed WAV file -
ggwave-from-file Decode a waveform from an uncompressed WAV file -
waver GUI application for sending/receiving data through sound SDL
ggwave-py Python examples PortAudio
ggwave-js Javascript example Web Audio API
spectrogram Spectrogram tool SDL
ggweb-spike Android example using a WebView to wrap ggwave into a simple app WebAudio
buttons Record and send commands via Talking buttons Web Audio API
r2t2 Transmit data through the PC speaker PC speaker
ggwave-objc Minimal Objective-C iOS app using ggwave AudioToolbox
ggwave-java Minimal Java Android app using ggwave android.media
ggwave-kmm Kotlin Multiplatform Project using ggwave android.media, javax.sound.sampled
ggwave-fm Transmit ggwave messages with HackRF Radio
esp32-rx Transmit and receive messages using ESP32 -
rp2040-rx Transmit and receive messages using Raspberry Pi Pico (RP2040) -
arduino-rx Transmit and receive messages using Arduino RP2040 -
arduino-tx Transmit messages using Arduino Uno -
arduino-rx-web Receive messages from Arduino Uno Web Audio API

Other projects using ggwave or one of its prototypes:

Building

Dependencies for SDL-based examples

[Ubuntu]
$ sudo apt install libsdl2-dev

[Mac OS with brew]
$ 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

Local Debian packages

Build reproducible libggwave-dev and python3-ggwave Debian packages:

# 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

More info: https://pypi.org/project/ggwave/

Node.js

npm install ggwave

More info: https://www.npmjs.com/package/ggwave

iOS

Available as a Swift Package: https://github.com/ggerganov/ggwave-spm

Installing the Waver application

Get it from the Snap Store

Linux

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

Mac OS

brew install ggerganov/ggerganov/waver

References

ggwave (ggerganov/ggwave)

正在搜索数据库…

7.9K ·GitHub
这是什么?ggwave 是一个小巧的 C++ 库,它使用多频 FSK 调制把数据编码成声音来发送和接收。这样两台设备就能通过扬声器和麦克风交换少量数据,而不需要网络。
这是库还是现成的应用?核心是一个 C++ 库,并提供 Python、JavaScript/WASM、Swift 和 Java/Kotlin 的绑定。库周围还有一些示例程序,比如命令行工具 ggwave-cli,以及用于实际收发数据的图形界面应用 Waver。
我该如何构建或安装它?克隆仓库后使用 CMake 构建。基于 SDL 的示例需要先安装 SDL2(Ubuntu 上用 apt install libsdl2-dev,Mac 上用 brew install sdl2,Windows 上用 MSYS2 的相关软件包)。也提供 Python 和 Node.js 包,iOS 可以通过 Swift Package 引入。
运行这些示例还需要其他库吗?只有基于 SDL 的示例(如 ggwave-rx、ggwave-cli、waver 等)需要 SDL2;纯粹的编码/解码库本身没有这项依赖。
解码总是可靠的吗?从设计上看,并不能仅凭噪声就保证可靠。库使用 Reed-Solomon 纠错码来保护数据,但实际可靠性仍取决于扬声器和麦克风的质量以及环境噪声。
它实际能在哪些平台和设备上运行?除了桌面版 Linux、Mac 和 Windows,还有可运行的示例适用于 iOS(Objective-C/Swift)、Android(Java 和 Kotlin Multiplatform),以及 ESP32、树莓派 Pico(RP2040)和 Arduino 等微控制器。
Waver 应用是什么?Waver 是基于 ggwave 构建的现成图形界面应用,用于通过声音收发数据,可在 Linux 和 Mac OS 上安装。
这能在没有任何网络或互联网连接的情况下工作吗?可以,这正是它的核心所在。数据完全通过扬声器和麦克风之间的声波传输,因此适用于无服务器的设备配对或物联网场景。
它能进行超声波传输,让我听不到吗?可以。除了约 1875 Hz 左右的常规可听频段调制外,还提供从 15000 Hz 开始的超声波协议变体。
微控制器能发送和接收 ggwave 信号吗?可以。提供了专门针对 ESP32、树莓派 Pico(RP2040)和 Arduino 的示例,展示通过声音进行发送和接收。
作者
ggerganov
大小
19.7 MB
星标
7.9K
时长
5年
提交 · 90 天