Commit 6e5f9356 authored by Roman Haefeli's avatar Roman Haefeli
Browse files

finalized protocol specification

parent 96521752
...@@ -10,6 +10,7 @@ the client interacts with the server. It serves as a reference to allow for a cl ...@@ -10,6 +10,7 @@ the client interacts with the server. It serves as a reference to allow for a cl
implementation in any programming language that supports OSC (Open Sound Control [2]). Along implementation in any programming language that supports OSC (Open Sound Control [2]). Along
with that document comes a client implementation done in Pure Data [3]: tpf-client.pd with that document comes a client implementation done in Pure Data [3]: tpf-client.pd
Underlying protocol Underlying protocol
------------------- -------------------
...@@ -17,6 +18,7 @@ This specification is based on the OSC 1.1 [2] format and uses TCP as transport ...@@ -17,6 +18,7 @@ This specification is based on the OSC 1.1 [2] format and uses TCP as transport
OSC consists of packets and TCP is a stream oriented protocol, SLIP [4] is used as an OSC consists of packets and TCP is a stream oriented protocol, SLIP [4] is used as an
encapsulation mechanism to allow OSC packets to be transported over TCP. encapsulation mechanism to allow OSC packets to be transported over TCP.
About notation style About notation style
-------------------- --------------------
...@@ -62,7 +64,152 @@ S: /s/tpf/register/done ...@@ -62,7 +64,152 @@ S: /s/tpf/register/done
If the server responds with: If the server responds with:
S: S: /s/tpf/register/error
The chosen name is already used by another client or is invalid. The client should
display an appropriate error message to the user and must not proceed.
If the server sends the following at any time while the client is connected:
S: /s/tpf/register/again
The client must send its register message again:
C: /s/tpf/register/name ZHdK
Client list
-----------
Each client stores a list of connected clients, which is updated by the server.
Whenever a new client connects (is successfully registered) or when a connected
client disconnects, the server sends an update notification:
S: /s/tpf/updated/clients
It's the clients turn now to request the current list of connected clients:
C: /s/tpf/refresh/clients
The server sends the list upon above request:
S: /s/tpf/clients/begin
S: /s/tpf/clients 4 ZHdK 1
S: /s/tpf/clients 5 UCSD 0
S: /s/tpf/clients 6 MIT 0
S: /s/tpf/clients/end
In order for the client to know when the list is complete, the server sends the
'/s/tpf/clients/end' message at the end of the list. Above example is a list of
three clients. The first element of client list message is the socket number, the
second is the clients self-given name, the third is either 0 or 1 and denotes the
client with directing privileges.
The client may request the client list from the server at any time after it has been
successfully registered.
Link list
---------
The server distributes port numbers among connected clients, so that each pair of
clients shares a port for a distinct jacktrip connection. The logic of the assignment
is done on the server and each client requests its own specific list of ports and
respective peer clients to connect to.
Whenever the server re-calculates the links (when a client connects or disconnects),
it sends an update notification:
S: /s/tpf/updated/mylinks
Whenever the client receives such a message, it should request the current
link list from the server:
C: /s/tpf/refresh/mylinks
The server sends the specific link list for the requesting client:
S: /s/tpf/mylinks/begin
S: /s/tpf/mylinks 5 0
S: /s/tpf/mylinks 6 1
S: /s/tpf/mylinks/end
Since in this example three clients are connected, each client needs to establish
two links. The first number in each mylinks message denotes the corresponding peer
client by its ID (socket number) and the second number represents the port offset
that should be used for the jacktrip instance. By looking up the list of connected
clients, the client software knows which ID belongs to which given name.
The link list can be requested again by the client at any time while connected.
Parameter list
--------------
In order for all nodes to be able to establish jacktrip connections with each other,
some parameters need to be agreed upon. Those settings are synchronized among clients.
Only the client with directing privileges (see third field in client list) is supposed
to change those parameters. However, this is not enforced by the server, but expected
to be checked on the client side.
Whenever the client with directing privileges changes a value of a certain parameter,
the server notifies all clients with the following message:
S: /s/tpf/updated/params
The client requests the parameter list with:
C: /s/tpf/refresh/params
The server sends the full parameter list:
S: /s/tpf/params/begin
S: /s/tpf/params buffersize 128
S: /s/tpf/params samplerate 44100
S: /s/tpf/params channels 4
S: /s/tpf/params bitres 16
S: /s/tpf/params/end
'buffersize' and 'samplerate' are relevant for running JACK, while 'channels' and
'bitres' are parameters given as options to the jacktrip command.
Unlike the client list and link list, the client needs to request the parameter
list after initialization without waiting for a notification, since a notification
would occur only after a parameter change.
Updating parameters
-------------------
Only the client with directing privileges (3rd field=1 in client list) is supposed
to be able to change parameters. It does so by sending the following messages:
C: /s/tpf/params/begin
C: /s/tpf/params samplerate 48000
C: /s/tpf/params/end
The server ignores updates that do not start with a 'begin' message and end with
an 'end' message.
Starting jacktrip instances
---------------------------
With the three data sets (client list, link list, parameter list) the client now
has enough information to start the necessary number of jacktrip instances. By using
the data of above examples and assuming our client is given the name 'ZHdK', the client
knows that it needs to start two instances (two links in link list) of jacktrip and it
also knows the name of the corresponding peer node and the required parameter values:
jacktrip -c telematic.zhdk.ch -b 16 -n 4 -o 0 --clientname UCSD
jacktrip -c telematic.zhdk.ch -b 16 -n 4 -o 1 --clientname MIT
Disconnecting
-------------
Clients are supposed to properly end the connection to the server before quitting in
order to avoid stale entries in the server's client list.
...@@ -70,4 +217,3 @@ S: ...@@ -70,4 +217,3 @@ S:
[2] http://cnmat.berkeley.edu/system/files/attachments/Nime09OSCfinal.pdf [2] http://cnmat.berkeley.edu/system/files/attachments/Nime09OSCfinal.pdf
[3] https://puredata.info/ [3] https://puredata.info/
[4] https://tools.ietf.org/html/rfc1055 [4] https://tools.ietf.org/html/rfc1055
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment