README.md 4.46 KB
Newer Older
Roman Haefeli's avatar
Roman Haefeli committed
1
tpf-client
Roman Haefeli's avatar
Roman Haefeli committed
2
==========
Roman Haefeli's avatar
Roman Haefeli committed
3

4
5
![alt text](tpf-client.png "tpf-client")

Roman Haefeli's avatar
Roman Haefeli committed
6
7
8
About
-----

9
10
tpf-client is a low-latency multi-channel audio transmission software
based on the jacktrip protocol and built in Pure Data.
Roman Haefeli's avatar
Roman Haefeli committed
11
12
13
14

It tries to overcome some limitations that are often encountered
when using the traditional jacktrip commandline utility:

15
16
 * No need for clients to run with a public IP address and no need
   for setting up port-forwarding on the client side.
Roman Haefeli's avatar
Roman Haefeli committed
17
18
19
20
21

 * The tpf-client reduces complexity when configuring a session
   with many endpoints.

The client registers itself to a tpf-server which keeps track
22
23
24
25
26
of the connected clients. While connected to the server, clients
establish a jacktrip audio connection to their peers either by
routing the audio packets through the tpf-server (a UDP-proxy running
on a separate port) or directly to their peers by employing a
technique called UDP hole punching (https://en.wikipedia.org/wiki/UDP_hole_punching).
Roman Haefeli's avatar
Roman Haefeli committed
27

Roman Haefeli's avatar
Roman Haefeli committed
28
You can download the client from:
Roman Haefeli's avatar
Roman Haefeli committed
29

Roman Haefeli's avatar
Roman Haefeli committed
30
  https://github.com/zhdk/tpf-client
Roman Haefeli's avatar
Roman Haefeli committed
31

32
The server software is hosted separately at:
Roman Haefeli's avatar
Roman Haefeli committed
33

Roman Haefeli's avatar
Roman Haefeli committed
34
  https://github.com/zhdk/tpf-server
Roman Haefeli's avatar
Roman Haefeli committed
35

Roman Haefeli's avatar
Roman Haefeli committed
36
37
38
39
Depending on the locations of the endpoints it is advised to
run a server closer to one of the endpoints in order to
keep transmission latency low.

40
41
42
43
44
45
46
#### Scope

tpf-client doesn't have any mixing, levelling, routing capabilities. It is meant
as a pure transmission utility. For concerts and experiments, we usually interface
it with a DAW like Ardour. Further instructions and Ardour template sessions are in
progress and will be provided.

Roman Haefeli's avatar
Roman Haefeli committed
47

Roman Haefeli's avatar
Roman Haefeli committed
48
49
Prerequisites
-------------
Roman Haefeli's avatar
Roman Haefeli committed
50
51
52
53
54
55
56
57
58
59
60
61
62
63

Make sure to get the latest Pure Data from:

  https://puredata.info/downloads/

You need the following externals to run tpf-client
  * iemnet
  * osc
  * slip

You can install externals through the Pd menu:
'Help' -> 'Find Externals'


Roman Haefeli's avatar
Roman Haefeli committed
64
65
66
Running the client
------------------

Roman Haefeli's avatar
Roman Haefeli committed
67
#### Run
68
To run the client, open the patch tpf-client.pd in Pure Data. Typically,
Roman Haefeli's avatar
Roman Haefeli committed
69
70
71
72
you run Pd with jack as audio backend, so that you can send audio from
and to the tpf-client to other software. When running from the command-
line, the recommended parameters are:

Roman Haefeli's avatar
Roman Haefeli committed
73
74
~~~sh
pd -rt -jack -inchannels 8 -outchannels 65 -nojackconnect \
Roman Haefeli's avatar
Roman Haefeli committed
75
     -jackname tpf-client -open tpf-client/tpf-client.pd
Roman Haefeli's avatar
Roman Haefeli committed
76
~~~
Roman Haefeli's avatar
Roman Haefeli committed
77

Roman Haefeli's avatar
Roman Haefeli committed
78
#### Configure
79
80

Before anything, open 'Settings' and configure the field 'server' and 'name'. If
81
you don't know about a server, you can run your own (see https://github.com/zhdk/tpf-server/
82
83
84
85
86
87
88
89
for details).

All parameters from the 'Settings' panel need to be configured prior to
connecting to the server. Any changes will take only effect after a reconnection.
The parameters 'samplerate' and 'blocksize' must be shared by all clients. An error
is displayed, when a mismatch occurs. The first client joining a room sets those parameters
for the lifetime of the room. The room exists as long as there are any clients connected to it.

Roman Haefeli's avatar
Roman Haefeli committed
90
#### Connect
91
92
93
94

The client connects to the server by clicking the top left button. Blue indicates connection
is established. Red indicates that some error occured. Check the message for the reason.
Reasons for connection failure include samplerate or name conflict (configured name is already in
Roman Haefeli's avatar
Roman Haefeli committed
95
96
97
98
99
100
101
102
103
104
105
106
use by someone else).

Once connected, other endpoints appear in one of the 8 rows. In order to
establish audio transmission, either of one side needs to initiate the
connection by clicking the black square in the left and the other side
has to confirm. A flashing button indicates the other side is waiting
for confirmation. Once the audio connection is established, the
corresponding button turns blue and the numbered squares indicate the
number of received channels and the level of each. The numbers on the
channel indicators correspond with the numbers in the qjackctl connection
dialog.

Roman Haefeli's avatar
Roman Haefeli committed
107
#### Peer-2-Peer connection
108

Roman Haefeli's avatar
Roman Haefeli committed
109
By double-clicking the left square, a request for a connection using
110
111
UDP hole punching is sent (button flashes purple). When confirmed, a direct transmission between
endpoints is established (no UDP proxy involved). However,
Roman Haefeli's avatar
Roman Haefeli committed
112
113
114
115
116
117
118
119
120
121
this feature is considered experimental and can't be used in certain
network environments.


Ready-to-use macOS app
----------------------

If your computer runs macOS, you may download a self-contained
application bundle from:

Roman Haefeli's avatar
Roman Haefeli committed
122
  https://github.com/zhdk/tpf-client/releases
Roman Haefeli's avatar
Roman Haefeli committed
123
124


125
126
Bugs
----
127

Roman Haefeli's avatar
Roman Haefeli committed
128
For any bug, issue, or suggestion, please open an issue [here](https://github.com/zhdk/tpf-client/issues).
129

130

Roman Haefeli's avatar
Roman Haefeli committed
131
132
133
134
135
136
Authors
-------

  * Roman Haefeli <roman.haefeli@zhdk.ch>
  * Johannes Schütt <johannes.schuett@zhdk.ch>

137

Roman Haefeli's avatar
Roman Haefeli committed
138
139
140
License
-------

141
  GPL 3.0 (see LICENSE.txt)
Roman Haefeli's avatar
Roman Haefeli committed
142