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

softins

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

ann0see · 2026-07-26T14:58:10Z

Please squash the commits here.

…ixes

mcfnord · 2026-08-20T21:00:30Z

🤖 AI: Squashed to a single commit. Ready for re-review.

pljones · 2026-08-21T16:17:47Z

 This is defined in `CServer::OnNewConnection()`

-The client on a new connection will:
+The Client on a new connection will:


"On new connection" - i.e. regardless of the REQ_xxx messages coming from the Server? Needs to be made clear either way.

Fundamentally what - for the Client - is a "new connection"? It's clearly stated for the Server. (Is it "when I start sending audio" or "when I get a Channel ID assigned" or something else...?)

pljones · 2026-08-21T16:20:56Z

 This is defined in `CClient::OnNewConnection()`

-At the end of the session, the client calls the `CLM_DISCONNECTION (1010, 0xf203)` message, until the server stops streaming audio to it.
+At the end of the session, the Client repeatedly sends a `CLM_DISCONNECTION (1010, 0xf203)` message, until the Server stops streaming audio to it.


So
a) this is CLM so no ACKN but
b) it's up to the Server to stop sending or the Client is stuck?

pljones · 2026-08-21T16:22:32Z

+
+- A Server registers with `CLM_REGISTER_SERVER_EX (1017)` (older versions: `CLM_REGISTER_SERVER (1004)`) and receives `CLM_REGISTER_SERVER_RESP (1016)` carrying the result (registered, list full, version too old, requirements not fulfilled). If no response arrives, registration is retried every 500 ms, up to 5 times.
+- Registration is refreshed every 15 minutes; the Directory drops a Server it has not heard from for 33 minutes. `CLM_UNREGISTER_SERVER (1005)` removes the entry immediately at shutdown or when changing Directory through the Server UI.
+- A Client requests the list with `CLM_REQ_SERVER_LIST (1007)`. The Directory answers with both `CLM_RED_SERVER_LIST (1018)` (a shorter form that reduces UDP fragmentation) and `CLM_SERVER_LIST (1006)` (the full information). The Client then pings each listed Server with `CLM_PING_MS_WITHNUMCLIENTS (1002)` to display latency and occupancy.


Suggested change

- A Client requests the list with `CLM_REQ_SERVER_LIST (1007)`. The Directory answers with both `CLM_RED_SERVER_LIST (1018)` (a shorter form that reduces UDP fragmentation) and `CLM_SERVER_LIST (1006)` (the full information). The Client then pings each listed Server with `CLM_PING_MS_WITHNUMCLIENTS (1002)` to display latency and occupancy.

- A Client requests the server list with `CLM_REQ_SERVER_LIST (1007)`. The Directory answers with both `CLM_RED_SERVER_LIST (1018)` (a shorter form that reduces UDP fragmentation) and `CLM_SERVER_LIST (1006)` (the full information). The Client then pings each listed Server with `CLM_PING_MS_WITHNUMCLIENTS (1002)` to display latency and occupancy.

(my pedantry...)

pljones · 2026-08-21T16:23:19Z

+- A Server registers with `CLM_REGISTER_SERVER_EX (1017)` (older versions: `CLM_REGISTER_SERVER (1004)`) and receives `CLM_REGISTER_SERVER_RESP (1016)` carrying the result (registered, list full, version too old, requirements not fulfilled). If no response arrives, registration is retried every 500 ms, up to 5 times.
+- Registration is refreshed every 15 minutes; the Directory drops a Server it has not heard from for 33 minutes. `CLM_UNREGISTER_SERVER (1005)` removes the entry immediately at shutdown or when changing Directory through the Server UI.
+- A Client requests the list with `CLM_REQ_SERVER_LIST (1007)`. The Directory answers with both `CLM_RED_SERVER_LIST (1018)` (a shorter form that reduces UDP fragmentation) and `CLM_SERVER_LIST (1006)` (the full information). The Client then pings each listed Server with `CLM_PING_MS_WITHNUMCLIENTS (1002)` to display latency and occupancy.
+- NAT hole punching: when it answers a list request, the Directory also sends every registered Server a `CLM_SEND_EMPTY_MESSAGE (1008)` carrying the Client's public address; each Server responds by sending `CLM_EMPTY_MESSAGE (1009)` to that address, in order to open its own NAT/firewall for the Client's subsequent packets. It doesn't matter whether the Client receives this message, as it will ignore it. The Directory and its registered Servers also ping each other about once a minute to keep their NAT mappings alive.


Suggested change

- NAT hole punching: when it answers a list request, the Directory also sends every registered Server a `CLM_SEND_EMPTY_MESSAGE (1008)` carrying the Client's public address; each Server responds by sending `CLM_EMPTY_MESSAGE (1009)` to that address, in order to open its own NAT/firewall for the Client's subsequent packets. It doesn't matter whether the Client receives this message, as it will ignore it. The Directory and its registered Servers also ping each other about once a minute to keep their NAT mappings alive.

- NAT hole punching: when it answers a server list request, the Directory also sends every registered Server a `CLM_SEND_EMPTY_MESSAGE (1008)` carrying the Client's public address; each Server responds by sending `CLM_EMPTY_MESSAGE (1009)` to that address, in order to open its own NAT/firewall for the Client's subsequent packets. It doesn't matter whether the Client receives this message, as it will ignore it. The Directory and its registered Servers also ping each other about once a minute to keep their NAT mappings alive.

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

pljones reviewed Jul 18, 2026

View reviewed changes

Comment thread docs/JAMULUS_PROTOCOL.md Outdated

pljones reviewed Jul 18, 2026

View reviewed changes

Comment thread docs/JAMULUS_PROTOCOL.md Outdated

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

ann0see requested changes Jul 22, 2026

View reviewed changes

Comment thread docs/JAMULUS_PROTOCOL.md

Comment thread docs/JAMULUS_PROTOCOL.md

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

softins reviewed Jul 23, 2026

View reviewed changes

Comment thread docs/JAMULUS_PROTOCOL.md

Comment thread docs/JAMULUS_PROTOCOL.md

Comment thread docs/JAMULUS_PROTOCOL.md Outdated

Comment thread docs/JAMULUS_PROTOCOL.md Outdated

Comment thread docs/JAMULUS_PROTOCOL.md Outdated

Comment thread docs/JAMULUS_PROTOCOL.md Outdated

mcfnord force-pushed the enhance-protocol-doc branch from 5d057a5 to 2386d21 Compare July 27, 2026 06:41

pljones reviewed Jul 27, 2026

View reviewed changes

Comment thread docs/JAMULUS_PROTOCOL.md Outdated

pljones reviewed Jul 27, 2026

View reviewed changes

Comment thread docs/JAMULUS_PROTOCOL.md Outdated

pljones reviewed Jul 27, 2026

View reviewed changes

Comment thread docs/JAMULUS_PROTOCOL.md Outdated

pljones reviewed Jul 29, 2026

View reviewed changes

Comment thread docs/JAMULUS_PROTOCOL.md

ann0see requested review from ann0see and removed request for ann0see August 9, 2026 14:11

docs/JAMULUS_PROTOCOL.md: message reference, directory flows, small f…

29ea574

…ixes

mcfnord force-pushed the enhance-protocol-doc branch from be4b4e7 to 29ea574 Compare August 20, 2026 20:59

pljones reviewed Aug 21, 2026

View reviewed changes

	- A Client requests the list with `CLM_REQ_SERVER_LIST (1007)`. The Directory answers with both `CLM_RED_SERVER_LIST (1018)` (a shorter form that reduces UDP fragmentation) and `CLM_SERVER_LIST (1006)` (the full information). The Client then pings each listed Server with `CLM_PING_MS_WITHNUMCLIENTS (1002)` to display latency and occupancy.
	- A Client requests the server list with `CLM_REQ_SERVER_LIST (1007)`. The Directory answers with both `CLM_RED_SERVER_LIST (1018)` (a shorter form that reduces UDP fragmentation) and `CLM_SERVER_LIST (1006)` (the full information). The Client then pings each listed Server with `CLM_PING_MS_WITHNUMCLIENTS (1002)` to display latency and occupancy.

Uh oh!

Conversation

mcfnord commented Jul 17, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

softins left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ann0see commented Jul 26, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mcfnord commented Aug 20, 2026

Uh oh!

pljones Aug 21, 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 Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

pljones Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

pljones Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

pljones Aug 21, 2026 •

edited

Loading