docs/JAMULUS_PROTOCOL.md: message reference, directory flows, small fixes by mcfnord · Pull Request #3794 · jamulussoftware/jamulus

mcfnord · 2026-07-17T21:32:37Z

One file. Fills the main gaps in the protocol doc, verified against src/protocol.cpp / src/socket.cpp / src/serverlist.cpp on current main:

How a receiver tells protocol packets from audio packets (they share one port; parse-or-audio in CSocket::ProcessPacket()), the CRC parameters, and how acknowledge/retransmit actually works — previously the doc said only "must be acknowledged".
A complete message-ID reference table for both message classes, with the legacy IDs called out. This is the piece a Wireshark user or protocol reader currently has to reconstruct from protocol.h.
A new section on directories: registration and refresh/timeout intervals, server-list responses (why both reduced and full lists are sent), and the CLM_SEND_EMPTY_MESSAGE/CLM_EMPTY_MESSAGE NAT hole-punch flow — previously undocumented here despite being a third of the connectionless messages.
Fixes message names that drifted from protocol.h (REQ_CHANNEL_INFOS, CHANNEL_INFOS, REQ_CONN_CLIENTS_LIST).

CHANGELOG: SKIP

🤖 Generated with Claude Code

…ixes - Explain how receivers classify datagrams (protocol frame vs audio) and specify the CRC and the acknowledge/retransmit mechanism - Add a complete message-ID reference for connection-based and connectionless messages - Add a section on directory registration, server lists and NAT hole punching (registration refresh/timeout intervals, CLM message flows) - Fix message names to match protocol.h (REQ_CHANNEL_INFOS, CHANNEL_INFOS, REQ_CONN_CLIENTS_LIST) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

pljones · 2026-07-18T15:00:28Z

+| 34 | `REQ_SPLIT_MESS_SUPPORT` | Request split-message support |
+| 35 | `SPLIT_MESS_SUPPORTED` | Split messages are supported |
+| 36 | `RAWAUDIO_SUPPORTED` | Raw (uncompressed) audio is supported |
+| 2001 | `SPECIAL_SPLIT_MESSAGE` | Container for split messages |


Without commentary, this looks peculiar.

2001 is a different type of message from the (other) connection-oriented messages. I'd not put it in the same table.

pljones · 2026-07-18T15:06:05Z


+## Directory Registration and Server Lists
+
+A directory is a Jamulus server acting as a registry (implemented in `src/serverlist.cpp`, both roles). All directory traffic uses connectionless messages:


Can you check through and make sure the following adhere to the style guide:

Client

Server

Directory

all always capitalised when referring to Jamulus "running as a...". The style guide covers a few other things.

Probably applies to the other docs as well.

Co-authored-by: Peter L Jones <pljones@users.noreply.github.com>

Per review: Client, Server and Directory capitalised when referring to Jamulus in that role, per https://jamulus.io/contribute/Style-and-Tone. Also applies the guide's other defined terms present here (Channel, Jitter Buffer), sentence-case headings, and unit spacing (48 kHz). Code identifiers, message names and file paths unchanged. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

… unregister wording SPECIAL_SPLIT_MESSAGE (2001) moved out of the connection-based table into its own paragraph explaining it is a transport container, not a message type, though each fragment frame is acknowledged/retransmitted (per CProtocol::ParseMessageBody). Connectionless range stated as 1000-1999. Unregister line takes pljones's suggested wording. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

ann0see · 2026-07-22T22:09:11Z


+The CRC is 16 bits, generator polynomial x¹⁶ + x¹² + x⁵ + 1 (CCITT), initial state all ones, calculated over the entire message and transmitted inverted.
+
+Audio and protocol messages share one UDP port. A receiver classifies every incoming datagram by attempting to parse it as a protocol frame — zero TAG bytes, consistent length, valid CRC. Anything that fails this parse is treated as an audio packet (see `CSocket::ProcessPacket()` in `src/socket.cpp`).


This will probably change soon since we have TCP support then. Probably worth thinking about rephrasing this.

In the TCP PR, we can add a sentence or paragraph here explaining that certain messages can arrive over TCP, but any that don't parse correctly are dropped and not treated as audio.

ann0see · 2026-07-22T22:10:15Z

+
+Connection-based messages (acknowledged; `PROTMESSID_` prefix omitted). Full payload layouts are in the header comment of `src/protocol.cpp`.
+
+| ID | Name | Purpose |


Thing is that this may get out of date. Maybe it's better to just link the source file. It should already have descriptions

I think it's good to have as part of this document. Once a message has been defined and merged to main, it is set in stone and will not change. The only out-of-date-ness would be if a new message was defined and didn't get added here. We can always add a comment in protocol.h reminding to update this file too.

softins

This looks good. Just a few comments and suggested changes.

softins · 2026-07-23T13:41:51Z

+
+Connection-based messages (acknowledged; `PROTMESSID_` prefix omitted). Full payload layouts are in the header comment of `src/protocol.cpp`.
+
+| ID | Name | Purpose |


I think it's good to have as part of this document. Once a message has been defined and merged to main, it is set in stone and will not change. The only out-of-date-ness would be if a new message was defined and didn't get added here. We can always add a comment in protocol.h reminding to update this file too.

softins · 2026-07-23T13:44:31Z


+The CRC is 16 bits, generator polynomial x¹⁶ + x¹² + x⁵ + 1 (CCITT), initial state all ones, calculated over the entire message and transmitted inverted.
+
+Audio and protocol messages share one UDP port. A receiver classifies every incoming datagram by attempting to parse it as a protocol frame — zero TAG bytes, consistent length, valid CRC. Anything that fails this parse is treated as an audio packet (see `CSocket::ProcessPacket()` in `src/socket.cpp`).


In the TCP PR, we can add a sentence or paragraph here explaining that certain messages can arrive over TCP, but any that don't parse correctly are dropped and not treated as audio.

softins · 2026-07-23T13:58:42Z

 The OPUS codec is used to compress the audio over the network and the packets are documented [here](https://datatracker.ietf.org/doc/html/rfc6716).

-Jamulus uses a custom OPUS encoder / decoder, giving some different frame sizes, but always uses a 48kHz sample rate. OPUS and OPUS64 codecs are the only supported options currently.
+Jamulus uses a custom OPUS encoder / decoder, giving some different frame sizes, but always uses a 48 kHz sample rate. OPUS and OPUS64 codecs are the only supported options currently.


I guess we should mention the new raw audio option here now.

Co-authored-by: Tony Mountifield <tony@mountifield.org>

ann0see self-requested a review July 17, 2026 22:08

pljones reviewed Jul 18, 2026

View reviewed changes

Comment thread docs/JAMULUS_PROTOCOL.md Outdated

mcfnord and others added 3 commits July 18, 2026 12:46

Update docs/JAMULUS_PROTOCOL.md

8f8e929

Co-authored-by: Peter L Jones <pljones@users.noreply.github.com>

ann0see added the AI AI generated or potentially AI generated label Jul 21, 2026

ann0see requested changes Jul 22, 2026

View reviewed changes

ann0see requested a review from softins July 23, 2026 09:17

softins reviewed Jul 23, 2026

View reviewed changes

mcfnord and others added 3 commits July 23, 2026 10:00

Apply suggestion from @softins

2722efd

Co-authored-by: Tony Mountifield <tony@mountifield.org>

Apply suggestion from @softins

8dd5d78

Co-authored-by: Tony Mountifield <tony@mountifield.org>

Apply suggestion from @softins

bd397ed

Co-authored-by: Tony Mountifield <tony@mountifield.org>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs/JAMULUS_PROTOCOL.md: message reference, directory flows, small fixes#3794

docs/JAMULUS_PROTOCOL.md: message reference, directory flows, small fixes#3794
mcfnord wants to merge 7 commits into
jamulussoftware:mainfrom
mcfnord:enhance-protocol-doc

mcfnord commented Jul 17, 2026

Uh oh!

pljones Jul 18, 2026 •

edited

Loading

Uh oh!

pljones Jul 18, 2026 •

edited

Loading

Uh oh!

Uh oh!

ann0see Jul 22, 2026

Uh oh!

softins Jul 23, 2026

Uh oh!

ann0see Jul 22, 2026

Uh oh!

softins Jul 23, 2026

Uh oh!

softins left a comment

Uh oh!

softins Jul 23, 2026

Uh oh!

softins Jul 23, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

softins Jul 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		## Directory Registration and Server Lists

		A directory is a Jamulus server acting as a registry (implemented in `src/serverlist.cpp`, both roles). All directory traffic uses connectionless messages:


		The CRC is 16 bits, generator polynomial x¹⁶ + x¹² + x⁵ + 1 (CCITT), initial state all ones, calculated over the entire message and transmitted inverted.

		Audio and protocol messages share one UDP port. A receiver classifies every incoming datagram by attempting to parse it as a protocol frame — zero TAG bytes, consistent length, valid CRC. Anything that fails this parse is treated as an audio packet (see `CSocket::ProcessPacket()` in `src/socket.cpp`).


		Connection-based messages (acknowledged; `PROTMESSID_` prefix omitted). Full payload layouts are in the header comment of `src/protocol.cpp`.

		\| ID \| Name \| Purpose \|

Uh oh!

Conversation

mcfnord commented Jul 17, 2026

Uh oh!

pljones Jul 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pljones Jul 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ann0see Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

softins Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

ann0see Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

softins Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

softins left a comment

Choose a reason for hiding this comment

Uh oh!

softins Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

softins Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

softins Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

pljones Jul 18, 2026 •

edited

Loading

pljones Jul 18, 2026 •

edited

Loading