Quacktrip is a computer application that makes low-latency uncompressed audio interconnections over the network, intended for musicians wishing to play together remotely. Netty McNetface is a multi-user version, for up to 12 musicians, that relies on a central repeater. Music101 is an attempt to serve larger groups, up to 50 or 100 musicians, such as a class or choral group.
All three are available as Pure Data patches or as stand-alone applications. Quacktrip is also available as a plug-in (VST2 and VST3 for Mac, VST3 only for Windows).
This version is 0.92. You can get the latest version from Miller Puckette’s website, more specifically here.
Copyright 2020 Miller Puckette. This is free open source software, which you can use and modify under the Standard Improved BSD License (lib/LICENSE.txt in this distribution).
Mike O’Connor’s links to jacktrip resources
[Quaxtrip - Quacktrip running in Max, by Damon Holzborn]https://github.com/damonholzborn/QuaxTrip/
VRR from IEM, like Netty, better at streaming performances, but more setup needed
Quacktrip is an implementation, in Pure Data, of Chris Chafe’s Jacktrip network protocol, based on jacktrip.pd by Roman Haefeli and Johannes Schuett. It establishes a low-latency, point-to-point connection between two sites, with no audio compression. Quacktrip is available as Mac and Windows apps, as patches you can load yourself into Pure Data, and as a VST plug-in.
Netty McNetface connects up to 12 musicians, with the help of a central server set up on a machine with a public IP address. The server repeats audio from each to all the others. Each musician can make her own mix of all the signals.
Music101 is intended for larger groups and relies on one musician, the “chef”, to manage a roster of the group, possibly arranging them in subgroups, and making a mixdown for everyone to hear. As with Netty McNetface, a central server has to be set up. Here though, the server does the mixing instead of simply forwarding all audio to all participants as with Netty.
If you possibly can, run an ethernet cable from your computer to your router. These apps will all work over “wifi” (wireless networks) but you will then probably get dropouts because of packet collisions in the air. See the “hiccups” section for more troubleshooting tips.
Download the app for MacOS or Windows, or just grab the patches and run them in Pure Data 0.51-0 or later. (You can get Pd from msp.ucsd.edu/Software/). In any case, once either one is running you should see two windows, a “Pd” window and the patch. You will probably also have to open Pd’s audio settings dialog to select an audio device and sample rate. The patch will show you further directions for setting the call name and buffer size and for starting and ending the call.
To run the patch from your own copy of Pd, unzip and open the “quack-and-netty” directory (called a “folder” in MACOS). You should see files named “quacktrip.pd”, “netty-mcnetface.pd”, and “music101.pd” (possibly with the “.pd” extension hidden), and a sub-directory named “lib”. Open one of the apps 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.
To run the VSTs (Quacktrip only), download the one you prefer and put it in your computer’s VST library directory. (On Mac, this will be Library/Audio/Plug-ins/VST or Library/Audio/Plug-ins/VST3, either in your home directory or in the system one. I don’t know how this is done on PCs.) You’ll have to un-archive it, but make sure the name is exactly what it was in the archive (like “Quacktrip.vst3, with no”copy 2" or whatnot).
On a Mac 10.15 or later you will have to do stupid stuff to calm your computer’s distrust of my unknown-developer-hood: “open package contents”, click through to and open the file “Contents/MacOS/CamomileFx”. The Mac will complain but say “open anyway”. This will create a terminal window showing a nonsensical error message. Ignore the error message. The Mac should now be willing to run the plug-in.
To make a call, start the plug-in, start audio in the host program, open the VST interface, double-click on the “call name” and type it in (followed by “enter”) and turn on the “ON/OFF” toggle (so that it has an “x” in it). Note the level controls for “Send”, “Receive” and “Thru”. If you drop this in the master channel of Ableton (for example), Thru should be 50 (unit gain), so that you hear your own output too, but if you use a side channel so that you can independently control the inputs and outputs, then “Thru” should be zero. Be sure, as always, that you and your peer are running at the same sample rate. For best results, set the host program to use a buffer size of 64 samples. (If it’s higher, you might notice that the delay creeps up over the duration of a call).
You might have to experiment with the “input delay” control, which is roughly in milliseconds, to get reasonably low latency without dropouts. Typical latencies in DAWs such as Ableton are 10 or 20 milliseconds higher than what you can get with the standalone apps.
Quacktrip is a Pure Data patch allowing musicians (or others) to make point-to-point, uncompressed, low-latency audio connections, through home routers, between their computers.
Quacktrip is best suited for small (2 or 3 people) rehearsals in which connections can run point-to-point. This gives the lowest latency (delay) you can get, but gets messy when more than three people are involved. Also, to reduce latency, late or missing audio is simply replaced with silence—so this solution is probably not suitable for performances.
To make a call, enter a unique “call name” (click on the text area that says “this-call-name” and type in a new name), then click “ON/OFF so that an”X" appears. When someone else makes a call with the same name, quacktrip should connect you together in a call. A public “conniption” server (by default foo.ucsd.edu) helps make the connection but the audio runs straight between the two computers.
If the “calling” button is flashing we’re either waiting for a response from the server, or from the peer. Once both of these arrive the “connected” toggle turns on (gets an “x” mark.) At this point a call is in progress and the “packets in” counter should be changing. Press the “reset” button to set packet and drop counts back to zero.
The input delay can be set to absorb network time variations (in units of 64 samples). The “fill” counter shows how far ahead of the incoming stream we are. If this number drops below 2 there will be a dropout in the audio output.
You can also change the number of channels and/or the block size of the audio you send to the other site. Click “2X” to send each outgoing packet twice (this doubles the data rate but might give fewer dropped packets).
Be sure your sample rate matches your peer’s - if they don’t you’ll get breaks in the sound. (Sample rate is set in Pd’s Media menu, not in this window).
“IN” and “OUT” panels: the “level” control is 50 for unit gain, 100 for +24 dB. Meters are post-fader. The “test” button sends sine tones (660 and 880 Hz), also affected by the level control.
The “IN” panel also has a monitoring level and delay that you can set to hear your own signal. If one of the two callers monitors herself with a delay equal to the round-trip delay of the call (typically 50 milliseconds or more) then both callers will hear both signals in sync. The two callers can also split the delay, setting local monitoring delays that add up to the total round-trip delay.
By default quacktrip uses a ‘conniption’ server at foo.ucsd.edu, port 3840 (hexadecimal “f00”) to connect calls. You can enter an alternative server name or IP address in the “server” control. Or you can script the setup as shown in the “pd more-stuff” sub-window.
The conniption server itself is just another Pd patch, included in the “lib” directory here. If you want to make calls between computers behind the same router, you will need also to run a copy of that patch behind the same router. It can reside on one of the computers you’re connecting. Calls between two patches on the same computer won’t work (but see below about client/server mode).
The conniption server may be run from a command line as in “pd -nosound -nrt -nogui -noprefs conniption-server.pd”.
You can measure round-trip latency by opening the quacktrip panels at both ends of a call. (First, set the input gains to zero.) You open them by right-clicking the panels. Inside that there’s a sub-patch called “latency”. At one end, select “loop-back”, and on the other, “measure latency”. At bottom in the window you should see the measured latency in msec. If the audio breaks up a button will flash and the readout will be wrong. Between two machines on the same network I was able to get 16 msec latency, using block size 64 and FIFO size 7 Increasing block size to 128 might make the network run more smoothly but I’ve never noticed a difference. In this case the minimum latency seems to be 18 msec. I haven’t done any latency testing across real networks yet.
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 in “lib” 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.
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.
Also, if you’re making your own version of the patch, you can script the quack-panel object (as in the message box below - the name “quack-panel-1” addresses the “quack-panel 1” object in the distributed patch). You might also want to assign input and output channels differently by replacing the in-panel and out-panel objects. While you’re at it, consider learning more about Pd - you can do a lot of other stuff with it.
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. You can use this to make calls between Quacktrips that are behind the same NAT router.
In client-server mode quacktrip is compatible with jacktrip; i.e., one party can use a jacktrip server and the other can use a quacktrip client or vice versa. You might also want to use client/server connections to build a hub-and-spokes solution like vrr. See the quacktrip help window for a very rough example. In this usage you don’t need a conniption server at all.
OR… you can use the conniption server without quacktrip to make other kinds of peer-to-peer connections, such as sending Pd messages from one machine to another, by incorporating the conniption-client abstraction into your own patch.
Netty McNetface is designed for ensembles of up to 8 players, each of whom runs one copy of the patch. The patch calls a server, which should be running the server patch, netty-mcserver.pd, found in the lib subdirectory, on a machine with a public IP address. This server machine will need plenty of bandwidth since it repeats every player’s signal to all the players (including the originator). For 4 players, even if each is only sending mono, this means 16 channels, totaling about 12 megabits per second of output from the server. If there are 8 players this goes up by a factor of 4 - and if everyone is sending stereo, double that again.
There’s no automatic gain or feedback control. Everyone who is using an open microphone should wear headphones; if not, everyone else’s signal will be repeated back via the microphone, and this will probably cause havoc.
Each player makes a separate call to the hub, specifying the hub’s IP address and base port number, and a name for the player’s channel on the mixer. (You can use your own name for example.) No two two players should ask for the same channel name, or else neither will get through. For this reason, if a player hasn’t filled in a name the patch will make one up for you.
If desired, you can pre-select which channel each player will show up on. To do this, one player should become the administrator (“chef”). To do so, open the “chef’s corner” sub-patch and click the “act as chef” toggle. The chef can assign a name to each of the 8 channels. When a player joins the session, the server patch checks the player’s channel name against the pre-arranged ones and if one matches the player shows up on that channel; if not, a free channel is used.
Additionally, if the server is on a publicly-known machine - for instance at a school where several ensembles might use it at different times - the chef can set a session name. If this is done, only players who have set their session names to match will be allocated a channel. This offers some protection against unwanted players (“bombers”) crashing your session. If the session name is just a hyphen (“-”) no checking is done.
As of version 0.92 there are buttons to save and reread your caller settings (call name, channel name, server address and port number) to and from a text file so you don’t have to retype everything every time. You can also edit the text file, so you can copy/paste to and from it, which you can’t do with the Pd controls.
The server is a patch, in the “lib” subdirectory of the patch directory, named netty-mcserver.pd . You can just open this file in Pd and leave it running if you want (but be careful not to run the server and any copies of Netty-McNetface in the same instance of Pd - if you want both patches running on one machine, start a separate copy of Pd for each). You can also run the server patch from the command line using a command such as:
.../pd-0.51-2/bin/pd -r 48000 -nosound -nogui -noprefs netty-mcserver.pd(on linux or Microsoft Windows) or
.../Pd-0.51-2.app/Contents/Resources/bin/pd -r 48000 -nosound -nogui -noprefs netty-mcserver.pd(on MacOS). I throw an extra -nrt flag in on linux; not sure if that matters or not. The server can be configured to set a port range and/or a call name. This is done using a configuration file like this example:
port 38400
password -This file specifies the UDP base port and the chef’s password (in this case, the defaults, hexadecimal F00 times ten for the base port, and no password.)
The machine the server runs on should have a range of 421 (!) UDP ports open starting at the base port, for example, 38400-38821 . Each connected client uses a separate port to receive each channel and yet another port to send its own. There is room in this “port space” for up to 20 channels, although only 12 are built out in the patches.
Music101 is the most recent addition. As with Netty McNetface, using Music101 requires setting up a dedicated server that all audio packets are routed through. Each musician is hardwired to send one or two channels and receive two from the server. One musician also acts as “chef”, whose duties are to organize the roster of musicians and control the mix.
Each musician runs the patch (either by downloading and running the app or by downloading the patch and running it in Pd). The “chef” should tell you the call name, your channel name, and the server address and port. To make a call, fill these four into the entry fields in the patch (click on the entries, type the value, and hit the Enter key) and then click the “call” toggle at top left.
Before joining the call it’s a good idea to test audio. The “test” toggle simply connects the patch input to its output with a short delay so you can sing or play something into the mic and hear what it sounds like coming back out. You might want to adjust input and output levels, and/or open the Pd audio settings (from the “media” menu) to select the sample rate and audio input/output device to use. (You should probably always set the sample rate to 48000, unless you know a good reason not to).
Once sound is going in and out of your computer cleanly (so you can turn the “test” toggle back off) and you’ve joined the call, you should hear a mix of the entire group.
As with Netty, there are “save settings” and “read settings” buttons so you can keep the call and channel names and server info around without having to retype them every time.
Before the call, someone has to start a copy of the server patch dedicated to the call. The server patch is named “server101.pd”. It reads a configuration file, “server101-config.txt”, that specifies port number and admin password as in Netty-McServer.pd described above. But unlike the Netty server, this one has to have DSP running at the same sample rate as all the callers. The easiest way to do this is to use a hardware audio device on the server machine, but it should also work to run “-nosound” as long as the sample rate is correct.
Like the Netty server, “server101.pd” also reads a configuration file, named “server101-config.txt”. This file can specify an admin password and base port number, and also the delay, in 64-sample blocks, for receiving audio packets. The default one included in the distribution is:
port 10100
password -
delay 20Note that the default port range is 10100-10199, different from Netty’s. These are the ports you’ll have to open (UDP only) on the server firewall.
Once the server is running, anyone (or anyone with the password, if there is one) can take the role of chef and start a call, by opening the “chef’s corner” of the Music100 patch, reading a roster file, and starting the call.
If you are acting as chef, you should get on the call first and set the roster. You can look at an example roster file in lib/example-roster.txt . The roster should be a plain text file, not HTML or Word or any such monstrosity; you can make one by just copying the example to another file and editing the copy. The example is as shown:
chef 0 5
fred 2 6
sue 0 6
bob 0 6
gaston 0 6
elise 1 6
hepzibah 0 6
fido 2 9
rhonda 0 9
blanche 2 4
buddy 0 4
elvis 0 4The first column is the caller name, the second one is a flag to separate groups, and the third is initial pan from 0 to 10 inclusive. If the flag for a caller is one, that caller will appear at the top of a new column in the mixer panel, and if 2, a new group (with a group fader) is started. You yourself (“chef”) will have your own column, at left, not belonging to any group. Here is the resulting mixer window:
You will notice that this is an unusual kind of mixer interface. It’s designed to facilitate quickly seeing whatever major problems arise and for getting to at least an acceptable mix without losing time testing each channel individually.
Also unusually, the sub-master sliders to the left of each group do not reflect an additional gain stage (as they would in a normal mixer) - instead, they bump the individual levels up and down, so that the individual levels are always the truth.
The pink (mauve? lavender?) squares indicate signal power. The vertical slider is gain and the horizontal one is pan. The toggle (next to the pan) is “solo” which only affects what the chef hears - everyone else still hears the mix.
In order for the mix to be at least approximately OK at the outset, there is a simple auto-gain-control (AGC) circuit included in each musician’s patch. This measures the 90th percentile of signal power (not counting silence, which is declared if the incoming signal is below 60dB out of 100.) This 90th percentile is adjusted to -90 dB (out of 100) and then a limiter kicks in if the corrected signal exceeds 100. The time constant on the AGC circuit is 10 seconds (not counting silences). The AGC and the limiter impose no additional audio delay.
Anyone in the call can open the “chef’s corner” and click “open mixer panel” to see everyone’s level and gain/pan controls. Only the chef can set the gain/pans though. Another musician can also “save roster file” and then become chef (once the previous chef has abdicated by leaving the call or switching to another channel name). To do this, just follow the “chef” instructions above using the roster you saved.
The server currently has a hardwired input delay that’s equal for all incoming channels. It needs to be fixed to automatically figure out the minimum workable delay for each one separately.
There should be a chat channel so people can exchange text messages while they’re untangling audio.
The process of setting up a call can be confusing. It’s easy to “join” the call before it is set up, which gives rise to peculiar behavior. It’s a good idea to carefully follow th order of the instructions given above. (I want to put in some better safeguards but haven’t managed that yet).
This section describes some things that might go wrong, and how to avoid them.
If you’re getting lots of drop-outs, first, remember to run an ethernet cable from your computer to your router; “WIFI” is an excellent source of dropouts. If that’s in order, next check that you and your peer(s) are using the same sample rate, and finally try raising the “delay” which typically ranges from 10 to 50 but can be set as high as 100.
On installation, and probably the first time you run Quacktrip or Netty McNetface, 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.
Call names are case sensitive and can’t have white space in them. “me-and-you” will work but not “me and you”.
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).
If two copies of Quacktrip are behind the same router, peer-to-peer calling won’t work unless you use client/server mode (described above). This shouldn’t be a problem for most people since the whole point is to make connections between people in different places. (Netty McNetface uses a public-IP hub so it doesn’t have this problem.) Quacktrip should now be able to deal with at least one situation that stopped 0.7, so-called CGNAT routing which some ISPs use. But if one endpoint is behind a “symmetric NAT” (as some university networks seem to be), peer-to-peer calling probably won’t work at all. If either caller is behind such a router, quacktrip will repeatedly say “connected” but then loop back to trying to make a new call.
Don’t rearrange the “quacktrip” or “lib” directories (except to move or remove the Pd application if you want). The patches use auxiliary files in “lib” and won’t find them if they aren’t adjacent in the way that they’re distributed.
(VST on MAC): There have been problems getting Ableton to see the VST3 version but it seems to work now. Max 7 only knows about VST2s, so the VST3 only works with Max 8. But, mysteriously, if you have both the VST2 and VST3 versions in the same directory, the VST3 one doesn’t load - if this happens, you can just move the VST2 somewhere else and then the VST3 should load. But anyway if you’re using Max, consider using Damon Holzborn’s Quacktrip-via-pdmax and skipping the VST thing altogether.
Client-mode quacktrip leaves the return port number unspecified so there should be fewer of those strange “netreceive: listen failed: Address already in use (48)” problems in Netty and Music101.
Netty is expanded to allow up to 12 channels. The Netty server now needs 421 open ports (for instance, 38400-38821), although if nobody gets assigned a channel number greater than 9 everything should still fit in the old (100-port) range. The new server should otherwise be compatible with older clients and vice versa.
The gain controls on Netty should be easier to understand. Also, “mono” is now automatically set for receive channels when appropriate, and the fast-updating fill indicator is now given as a range which is updated more slowly.
Music101 now allows clients to send stereo signals and the server is updated to automatically “do the right thing”. It should all be compatible with older versions of both server and client.
Quacktrip manages 0-channel paths better (used to drop calls sometimes) and reports byte counts in kilobits, not megabits.
Netty and Music101 have “save” and “load” buttons for call settings.
Bug fixes: the dreadful “use callbacks” toggle (which crashed or hung the apps) is gone unless you have it turned on by default - if that happens, turn it off and save defaults and it will not appear again. If you then really want to watch Pd crash again you can still turn it on via command line.
Also, chef’s controls in 0.9 acted funny; this is now fixed.
A new app, Music101, is intended to serve groups of more than 8 people. It’s experimental and not likely to be very useful in its current state. If you’re looking for something that will work with a larger group I can work with you to try to make this a reality.
The Netty McChef app has been folded into Netty McNetface so that there don’t have to be 2 separate apps. No more than one musician should act as chef, and it’s just fine if nobody wants to.
The quacktrip VST should now save its server info, call name, and a new control, “always call”, which instructs it to automatically start a call when it’s loaded.
I think all three apps need a facility for automatically selecting good delay values for incoming packets.