Protocol Spec

Transport Requirements

ION requires a stream that is:

• Reliable
• Ordered
• Full duplex

Transport message boundaries are ignored.

Frame Format

Every message is a frame:

+---------+------+-------------------+
| u8 ver  | u8 t | u32 len (LE)      |
+---------+------+-------------------+
| payload (len bytes)               |
+-----------------------------------+

• ver: protocol version (0x01)
• t: frame type
• len: payload size in bytes (little-endian)

Unknown protocol versions must be rejected.

Frame Types

• 0x01: JSON control event (UTF-8, object with type)
• 0x02: raw PCM audio payload

Core Events

describe (client -> server):

1
{ "type": "describe" }

ready (server -> client):

1
{
2
  "type": "ready",
3
  "protocol": "ion",
4
  "sample_rate": 16000,
5
  "channels": 1,
6
  "format": "s16le"
7
}

start:

1
{ "type": "start" }

stop:

1
{ "type": "stop" }

error:

1
{ "type": "error", "message": "reason" }

Audio Rules

• Audio frames are valid only after start
• Audio stops after stop
• Chunk size is implementation-defined
• No timestamps or sequence IDs in core protocol

State Model

CONNECT
 -> describe
 <- ready
 -> start
 <- audio*
 -> stop

Extensibility

• Unknown events should be ignored
• New events and frame types may be added