|====================================|
| ArtiWAVE Protocol Version 1.00     |
| Written by: Michel van Osenbruggen |
| CopyRight 2026 ArtiLED B.V.        |
|====================================|

Latest change                          : 15-10-2026

===============
| Description |
===============

The ArtiLED ArtiWAVE protocol sends snapshots of the waveform of one audio channel (one side of a stereo input)
as UDP packets, one packet per snapshot. One side = one channel. No answer is returned.

=======================
| Protocol Definition |
=======================

Protocol                               : UDP broadcast
Port                                   : 50400 + Channel (Channel 1-99 -> 50401-50499)
Destination                            : data/wave_send
                                         "network" = broadcast address of the sender's own primary network, never
                                         255.255.255.255
                                         "local"   = 127.255.255.255 (loopback broadcast, this box only) (default)
                                         "off"     = nothing is sent
Source port                            : Any (random, one socket per input)
Senders                                : Touch (artiled_spectrum.py, one service per input)
Receivers                              : Touch (screen/vizstream.php), see ArtiPORTS
Packet size                            : 20 + 2 x samples bytes (532 or 1044), never fragmented

===========================
| Magic Packet Definition |
===========================

Magic Packet                           : qXyhIB7o

==========================
| Data Format Definition |
==========================

Byte order                             : Big endian
0-7      magic                         : "qXyhIB7o"
8        version          uint8        : 1
9        flags            uint8        : bit 0 = silent, bit 1 = clipping (ArtiSPECTRUM)
10-13    sequence         uint32       : The ArtiSPECTRUM frame the snapshot was taken at
14-15    rate             uint16       : Snapshots/s x 10 (300, 500, 600)
16-17    samples          uint16       : 256, 512
18-19    sample rate      uint16       : Hz / 100 (480)
20-      sample1 - sampleN int16 x N   : -32768 - 32767

=====================
| Value Definition  |
=====================

sample1 - sampleN                      : The newest N samples at that frame, oldest first, input counts with the
                                         centre removed (0 dB sine at 2 Vrms = peak ~28140 at reference 19900)

=====================
| Rate Definition   |
=====================

Snapshot rate                          : data/wave_rate 30 or 60 (default 60), at most the ArtiSPECTRUM frame rate
Timing                                 : One snapshot every 48000 / rate samples of the input, on ArtiSPECTRUM frames
Silence                                : As ArtiSPECTRUM (silent 60 s -> at most 1 per 1.0 s), no catch-up after

=======================
| Channel Definition  |
=======================

Left / Right                           : As ArtiSPECTRUM (data/spectrum_N_left_channel, spectrum_N_right_channel)
Samples                                : data/wave_samples 256 or 512 (default 512)

=====================
| Receive Definition |
=====================

Validation                             : magic, version 1, length = 20 + 2 x samples
Samples                                : Touch accepts 512 only (256 = rejected, no Waves)
Source                                 : Touch accepts 127.0.0.1 and its own address only
Shared ports                           : Several receivers on one box share a port with SO_REUSEADDR

=====================
| Cross References  |
=====================

ArtiPORTS                              : 50401-50499 UDP-B ArtiWAVE Channel 1-99
ArtiSPECTRUM                           : Same input, same sequence
ArtiTouchAPI                           : Waves (screen/vizstream.php)