protocol_specification.txt 7.22 KB
Newer Older
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
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 61 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
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:

C: /s/tpf/register/name ZHdK
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