protocol_specification.txt 7.23 KB
Newer Older
Roman Haefeli's avatar
Roman Haefeli committed
1
2
3
4
5
6
Abstract
--------

Protocol Version: 1.0

This document describes the protocol used by the TPF (telematic performances format [1]) tool
7
set which consists of a client part and a server part. This document describes how
Roman Haefeli's avatar
Roman Haefeli committed
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
the client interacts with the server. It serves as a reference to allow for a client
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


Underlying protocol
-------------------

This specification is based on the OSC 1.1 [2] format and uses TCP as transport method. Since
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.


About notation style
--------------------

OSC supports a wide range of data types as payload. Since we're dealing only with strings
and integers, we assume any number to be of the type integer and any non-numeric data
to be of type string. To facilitate notation in this document, we omit any type specification
in OSC messages and write only OSC address, optionally followed by payload. An OSC message
with the adress '/some/path/' and 'string' (type string)  and '43' (type int) as payload is
written as:

/some/path string 43

A 'C: ' is prepended to denote messages sent by the client, while server messages are
prepended by a 'S: '.


Initialization
--------------

Clients are identified by their socket number, which is assigned by the server.
When the client connects to the server, it requests its own socket number:

C: /s/server/socket

The server responds with:

S: /s/server/socket 4

Once the client knows its socket number, it negotiates the protocol version to ensure
that client and server speak the same language:

C: /s/tpf/protocol/version
S: /s/tpf/protocol/version 1 0

The client is supposed to disconnect with an appropriate error message in case of a
protocol version mismatch.

Once the procol version is agreed upon, the client registers its given name, which
can be any string configured by the user:

61
C: /s/tpf/register/client <room> <nick>
Roman Haefeli's avatar
Roman Haefeli committed
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
S: /s/tpf/register/done

If the server responds with:

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.



[1] https://blog.zhdk.ch/telematic/
[2] http://cnmat.berkeley.edu/system/files/attachments/Nime09OSCfinal.pdf
[3] https://puredata.info/
[4] https://tools.ietf.org/html/rfc1055