QUACKTRIP -- PEER-TO-PEER HIGH-QUALITY LOW-LATENCY AUDIO -- Version 0.1

Copyright 2020 Miller Puckette.  This is open source software. free to use and
modify under the Standard Improved BSD License (lib/LICENSE.txt in this
distribution).

Quacktrip is an implementation, in Pure Data, of Chris Chafe's Jacktrip network
protocol.  The easiest way to use it is by opening the file, "quacktrip.pd",
using Pure Data (Pd)  version 0.51 .  You might have to upgrade your Pd
installation; the first test version of 0.51 appeared May 28, 2020.

If you have Pd 0.51 installed you only need the patches, about 30 kbytes. There
is also a downloadable archive for Macintoshes containing both the patches and
Pd itself (a few megabytes).

-------------------------------- QUICK START --------------------------

Unzip and open the "quacktrip" directory (called a "folder" in MACOS.)  You
should see a file named "quacktrip.pd", a sub-directory named "lib", and
possibly a version of Pd if you downloaded one.  The file "quacktrip.pd" might
simply appear as "quacktrip" if your OS is set to hide filename extensions.

If you are on Microsoft Windows, you should get PD 0.51-1test1 separately.  The easiest
way to get it is using the "installer" available here: 
http://msp.ucsd.edu/Software/pd-0.51-0test1.windows-installer.exe
If on linux, grab and compile the source from http://msp.ucsd.edu/Software/ .

Open "quacktrip" (the file, not the whole directory) using Pure Data, either
by dragging the file over to the App (on MACOS) or by starting Pure Data and
opening the file from within it.  You should see two windows, a "Pd" window
and the patch.  The patch will show you further directions for setting the
call name and buffer size and for starting and ending the call.

-------------------------------- HICCUPS --------------------------

1.  On installation, and probably the first time you run quacktrip, your OS
will complain about untrusted third-party software trying to open network
connections. You should allow them; but this process might disrupt the first
call you try to make.  Change the name of the call and try again - it should
work for the second call.  However:

2.  Quacktrip can get confused if you retry a failed call using the same call
name.  You can wait 30 seconds for the server to clear its memory of the call,
or better yet choose another name.

3.  Call names are case sensitive and can't have white space in them.
"me-and-you" will work but not "me and you".

4.  It's easy to run under an older version of Pd and not know it.  If things
aren't working check the version of Pd ("about Pd" in the help menu).

5.  If two copies of quacktrip are behind the same router, peer-to-peer calling
won't work unless you take extra steps described below.  This shouldn't be a
problem for most people since the whole point is to make connections between
people in different places.

6. Don't rearrange the "quacktrip" or "lib" directories (except to move or
remove the Pd application if you want).  "quacktrip" uses auxiliary files in
"lib" and won't find them if they aren't adjacent to quacktrip.

-------------------------------- GORY DETAILS --------------------------

You don't need to read this part unless you want to do something more than a
single peer-to-peer call at a time, between two machines behind different
routers.

The "main patch", quacktrip.pd, uses a graph-on-parent abstraction called
quacktrip-panel.pd, which in turn uses the quacktrip~ object that does the real
work.  These are in the lib directory.  Also there are the conniption server
and client.  The conniption client is used by quacktrip~ to set up calls by
communicating with the conniption server.  There is a copy of the conniption
server running on the machine foo.ucsd.edu, so you don't need to do anything
about this unless you want to run your own.

quacktrip can be run in client/server mode; in this configuration one caller
acts as the server and needs to have an IP address that is visible to the
other.  This functionality isn't available via the quacktrip.pd patch, but
can be set up by directly opening the help window for quacktrip~.  (You can
even make a connection between the two copies of quacktrip~ in the help file).
You can use that help file itself, modified for your own addresses, to make
local connections between machines behind the same router.

In client-server mode quacktrip should be compatible with jacktrip; i.e., one
party can use a jacktrip server and the other can use a quacktrip client or
vice versa.  It might be possible to connect to a jacktrip hub this way, so
that many different parties with quacktrip and/or jacktrip running can share
audio that is routed through the hub instead of point-to-point.  As far as I
know nobody has tried this yet.

In version 0.1, quacktrip is fixed at two channels, 16 bit audio, and a
block size of 256 sample frames (1024 bytes).  If you're going between
quacktrip and jacktrip, then jacktrip has to be set up likewise.  (actually,
the quacktrip~ abstraction can handle 0, 1, or 2 channels and needn't have
the same number of channels in and out, and can also be set to repeat packets
for greater reliability; this isn't brought out to the main patch yet.)

If you want to make 2 or more calls simultaneously, you can: (1) run two copies
of the patch in two copies of Pd; (2; better) run them in the same copy of Pd;
or (3; best of all) copy and paste the objects in the main patch, quacktrip.pd
as many times as desired.







