Commit 7536500d authored by Roman Haefeli's avatar Roman Haefeli

add protocol_specification.txt

parent 7e3a88a9
Abstract
--------
Protocol Version: 1.0
This document describes the protocol used by the TPF (telematic performances format [1]) tool
set which consists of a client part and a server part. An implementation of the server
is always running on telematic.zhdk.ch on TCP port 3025. This document describes how
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
Markdown is supported
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