vail/docs/protocol.md

The Vail Protocol
=============

Vail messages can be encoded with JSON or marshaled into a "binary" format.

Go Definition
--------------------

```go
type Message struct {
	// Timestamp of this message. Milliseconds since epoch.
	Timestamp int64

	// Message timing in milliseconds.
	// Timings alternate between tone and silence.
	// For example, `A` could be sent as [80, 80, 240]
	Duration []uint16
}
```

JSON
-------

JSON-encoded Vail messages are a direct encoding of the struct:

```json
{
    "Timestamp": 1702846980,
    "Duration": [80, 80, 240]
}
```

This represents a transmission at Sun 17 Dec 2023 09:03:00 PM UTC, consisting of an 80ms tone, an 80ms silence, and a 240ms tone.


Binary Marshalling
---------------------

The binary marshalled version of a Vail message is encoded big-endian:

    00 00 00 00 65 7f 62 04   00 50 00 50 00 f0

Is decoded as:

* Timestamp (int64): `00 00 00 00 65 7f 62 04` = 1702846980
* Duration ([]uint16):
  * `00 50` = 80
  * `00 50` = 80
  * `00 f0` = 240

This represents a transmission at Sun 17 Dec 2023 09:03:00 PM UTC, consisting of an 80ms tone, an 80ms silence, and a 240ms tone.


WebSockets
==========

The reference Vail server accepts WebSockets communications to the path `/chat`,
with the channel sent as the 'repeater' query parameter.

For instance, the "Example" channel is
wss://vail.woozle.org/chat?repeater=Example

The WebSockets subprotocol may be either:

* `json.vail.woozle.org` for JSON packets
* `binary.vail.woozle.org` for binary marshalled packets


Practical Considerations
==================

I am a network protocol designer:
Vail was designed to contend with
Internet latency and jitter.
It relies heavily on an accurate Real-Time Clock on each client.

Playback Delay
------------------

Clients should implement a delay on playback of all recieved messages,
to allow for network latency and jitter.

I have found that a 2-second delay is usually enough, but people on very high-latency links may need a larger delay.

If the timestamp + delay on a recieved packet is after the current time of day,
it may be appropriate to increase the delay.

Clock skew
---------------

On connecting,
clients will recieve a packet with no Durations.
Clients should use this timestamp
to estimate skew between the client and server's clock.