GGWave audio plugin

This is an OVOS audio transformer plugin for ggwave. It decodes audio QR codes (sound-based data messages) heard by the microphone and acts on them.

You can test the plugin from your browser, including WiFi setup.

The companion skill OpenVoiceOS/ovos-skill-ggwave lets you enable or disable this plugin by voice.

These skill stores support installing skills through GGWave:

To install skills this way, allow ovos-core to install Python packages:

"skills": {
    "installer": {
      "allow_pip": true,
      "allow_alphas": true,
      "break_system_packages": false
    }
}

TIP Allow ovos-core to install Python packages. Otherwise the install commands from this plugin fail.

Install

pip install ovos-audio-transformer-plugin-ggwave

ggwave fails to install on Python 3.11. Use the wheel from whl.smartgic.io instead, then the plugin install works.

Listener plugin

To load this plugin from dinkum-listener, enable it in mycroft.conf.

WARNING This is currently not recommended. See the bug report in dinkum-listener.

"listener": {
    "audio_transformers": {
        "ovos-audio-transformer-plugin-ggwave": {
            "start_enabled": true,
            "listen_timeout": 300
        }
    }
}

listen_timeout (seconds, default 300) auto-disables the listener after it has been enabled over the bus with ovos.ggwave.enable, so a stray or forgotten enable does not leave data-over-sound listening on forever. This is a security default: an enabled listener can trigger opcodes such as BUS:, PIP:, and GHS: (install a skill from a GitHub URL) for anyone in earshot. Set it to 0 (or a negative number) to disable this behavior and listen indefinitely once enabled. It has no effect on start_enabled: enabling the listener via config is an explicit operator decision to run always-on, and does not arm the timer.

Valid audio data

This repo provides a test interface on GitHub Pages. You can also test your own payloads at ggwave-js.ggerganov.com.

WiFi setup

Emit a message that sets the WiFi SSID:

SSID:123456

After the SSID is set, emit a message that sets the WiFi password:

PSWD:123456

If the password is empty, the plugin treats the network as open:

PSWD:

Once the password is received, the plugin sends a bus message for ovos-PHAL-plugin-network-manager to handle.

Install a GitHub skill

Install a skill from a GitHub URL:

GHS:https://github.com/OpenVoiceOS/skill-ovos-icanhazdadjokes

Install a Python package

Install any package from PyPI:

PIP:skill-wikipedia-for-humans

Utterance

Inject an utterance into the messagebus, as if the user spoke it to the microphone:

UTT:hello cruel world

Speak

Make an OVOS device speak:

SPEAK:hello world

Bus

Inject a simple message into the messagebus:

BUS:recognizer_loop:sleep

JSON

Inject a serialized message into the messagebus:

JSON:{"type": "speak", "data": {"utterance": "hello"}, "context": {}}

OpenVoiceOS/ovos-skill-ggwave — voice control for this plugin
OpenVoiceOS/ovos-PHAL-plugin-network-manager — handles WiFi setup messages sent by this plugin
OpenVoiceOS/ovos-dinkum-listener — listener service that can load this plugin

Release files for ovos-audio-transformer-plugin-ggwave 1.1.0a3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ovos-audio-transformer-plugin-ggwave 1.1.0a3
File	Size	Uploaded
ovos_audio_transformer_plugin_ggwave-1.1.0a3.tar.gz	13.2 kB	Sep 26, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ovos-audio-transformer-plugin-ggwave 1.1.0a3
File	Interpreter	ABI	Platform	Reset
ovos_audio_transformer_plugin_ggwave-1.1.0a3-py3-none-any.whl 11.9 kB Sep 26, 2026	Python 3	none	any	Details

Total release size: 25.1 kB

Release files / ovos_audio_transformer_plugin_ggwave-1.1.0a3.tar.gz

Download URL	ovos_audio_transformer_plugin_ggwave-1.1.0a3.tar.gz
Size	13.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`b8ede6aaa46582b92a74064ab1257799d5e5fb6fd8476890d092825217e2339e`
BLAKE2b-256 checksum How to use checksums	`4a5a636845f19689e5874d5bc075a4ab0a2c117db0adb3a5a2e72c4c7df8f4e0`
Upload date	Sep 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / ovos_audio_transformer_plugin_ggwave-1.1.0a3-py3-none-any.whl

Download URL	ovos_audio_transformer_plugin_ggwave-1.1.0a3-py3-none-any.whl
Size	11.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`088046d567329870c324f6c1746c4b7d0cfa09cb852921effe868dc2bdd4bf62`
BLAKE2b-256 checksum How to use checksums	`490c502095c3b2048dbc55d49acf7785cdbe2c509eb8c77fb89be4058ae94ac9`
Upload date	Sep 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`