CCRMA Documentation links: index contents overview rooms account staff about
(contents of this file: links to each section)
jacktrip is a linux, macOS and windows multi-machine
audio system used for network music performance over the internet. It
has a nice looking website that
might be your best starting point. This CCRMA
docs page provides some detailed technical information in a terse
style.
(Deprecated: older version exists that doesn’t use JACK; you could switch on rtaudio to avoid usign JACK as audio subsystem)
Computer: desktop, laptop, mini, or smaller systems running linux, macOS, windows10, or raspbian. (Various systems can connect with one another in group sessions)
Network:
jacktrip (but not
regular web browsing?!?) with two different Apple-branded Thunderbolt-2
to ethernet dongles but had success with other brands.Can work with built-in sound, but there can be pitfalls, including squealing audio feedback through the frame of your laptop (the built-in speaker exciting the built-in microphone). Definitely use headphones if you’re using built-in sound. Also sometimes there is contention between JACK/jacktrip and other audio software running on your machine, such as problems setting the sample rate or JACK “stealing” the microphone signal that you’d like to use simultaneously with other applications.
best with audio interface (to provide external inputs for mic / instrument, loudspeakers / headphones, but built-in audio can be used for testing). Can provide much more flexibility and system complexity.
typically using USB audio interfaces (aka soundcard), even old ones; you may need to install drivers.
USB mic works great. Note that most USB mics also have headphone ports, so they are audio output devices as well as audio input devices.
Jacktrip requires JACK to be:
You must install JACK before
installing jacktrip.
The “jacktrip” package consists mainly of the single executable file
jacktrip:
/usr/local/bin/jacktrip/usr/bin/jacktripjacktripIf you want to try a new version of jacktrip without
losing your current(ly working) version, you can simply rename the executable file.
Here’s an example of how to do this from a command-line terminal: go to
/usr/local/bin (where jacktrip is installed),
see what version is
currently installed (in this example the answer is version 1.1),
then rename that file
jacktrip-1.1 (which makes sense in this example; you can of
course make up whatever naming convention makes sense to you).
MyComputer:bin matt$ cd /usr/local/bin
MyComputer:bin matt$ ./jacktrip -version
JackTrip VERSION: 1.1
Copyright (c) 2008-2009 Juan-Pablo Caceres, Chris Chafe.
SoundWIRE group at CCRMA, Stanford University
MyComputer:bin matt$ mv jacktrip jacktrip-1.1
Now you can install the new version however you like, which will
result in /usr/local/bin/jacktrip now being the new
version, with the older version also still accessible (via its new
name), like so:
MyComputer:bin matt$ ls -l jackt*
-rwxr-xr-x 1 root wheel 4555152 May 1 03:18 jacktrip
-rwxr-xr-x 1 root wheel 5196608 Apr 17 2016 jacktrip-1.1
MyComputer:bin matt$ ./jacktrip -version
JackTrip VERSION: 1.2
Copyright (c) 2008-2018 Juan-Pablo Caceres, Chris Chafe.
SoundWIRE group at CCRMA, Stanford University
MyComputer:bin matt$ ./jacktrip-1.1 -version
JackTrip VERSION: 1.1
Copyright (c) 2008-2009 Juan-Pablo Caceres, Chris Chafe.
SoundWIRE group at CCRMA, Stanford University
git clone or download .zip and uncompresscd <installation_directory>/src; ./buildTo see whether jacktrip is successfully installed, run
it with the -v argument to print the version number (as
shown below). If it prints something like
JackTrip VERSION: 1.2 then jacktrip is
installed; if it instead prints something like “command not found” then
jacktrip is not successfully installed.
jacktrip -v cd <installation_directory>/src; ./jacktrip -v cd <installation_directory>/src; ./jacktrip.exe -v If you’re sure you installed jacktrip but you get
“command not found” then you probably have a problem with your search path
and/or where the jacktrip executable was
installed.
jackd)
jacktrip
JACK is required for running
jacktrip, so before going on the network, first test to see whether
JACK is working. jacktrip inherits JACK’s sample rate
and buffer size settings and
these must be the same on all jacktrip-connected machines.
To change these you must quit jacktrip, stop JACK, restart
JACK with new settings, then restart jacktrip.
You must launch jacktrip from the command line (or from Qjacktrip)
Successful use depends on which jacktrip mode to run
(detailed below).
Determine who is to be server and the server’s public IP address; verify audio settings are identical across server and all clients.
The ensemble has a central server computer with a public IP
address, running jacktrip in “hub mode”; all clients
connect to the server.
In brief:
jacktrip -S jacktrip -C <IP Address or Name of server>Recommendation: when first experiencing jacktrip, have
somebody who knows what they’re doing set up a hub server in
advance.
A jacktrip hub server can be launched with the option
-p (aka --hubpatch), followed by a number
specifying one of these “hub patching modes”:
jacktrip makes “the mix” including the remote clients’
sound plus local sound, and feeds that mix back to the remote clients
through the jacktrip server machine. Could also use for
music broadcast.)
jacktrip Hub Serverstart jackd from command
line
start jacktrip server in hub mode, perhaps with one
of the automatic audio patching
modes.
use tmux to be able to detach job and leave it running 24/7
jacktrip -s jacktrip -c <IP Address or Name of server>Only one client can connect to a peer-to-peer server. But you can run multiple instances of the jacktrip server on the same machine if you want multiple clients to be able to connect.
jacktrip
command-line optionsCommonly used command line options (and their default values):
Launch jacktrip with no arguments to print all the
possible command-line options:
jacktripjacktrip processes on the same machineYou can run jacktrip multiple times on the same machine.
Each has to be listening on a distinct UDP port (because only one
program at a time can “own” a UDP receive port on a given computer) so
you probably want to use the -o “port offset” option.
Each will appear as an independent program you can make JACK audio connections with.
To keep all the different jacktrips straight in QjackCtl’s
connections window you probably want to use the
--clientname option and pick names that are meaningful to
your particular context (e.g., names of the musicians connecting
remotely).
jacktrip audio to other audio applications on the same
machineXXX write me
To see what JACK-related processes a
computer is currently running (for example if you can’t start JACK on a
CCRMA Linux
Workstation and need to know if somebody else is already running
jackd):
ps -ef | grep jack (The ps
command lists all processes, one of which will be the grep into which the output of
ps is piped in order
to filter through these processes looking for the word
jack. So if JACK is not
running then the one and only process grep will see will be itself,
namely “grep jack”.)
To kill
all instances of a given program, e.g., jackd,
qjackctl, jacktrip, that might be running on
your (Linux or OSX) machine:
killall jackd
killall qjackctl
killall jacktrip
killall any-program-you-want-to-killUse netstat to see which process is using a given UDP or TCP port.
Linux example: display programs using port 61000:
netstat -p -n | grep 61000Video chat software includes Zoom, Skype, FaceTime, GoToMeeting, Google Hangouts, BlueJeans, etc.
Almost all attempts to set up long-distance jacktrip connections begin with the participants meeting on a video chat to confirm they’re there and talk through all the details of how it’s going to work, when participants should try connecting, etc.
The best practice is to use a different “sound system” for the video chat, for example, let Zoom use your laptop’s built-in mic and speakers while JACK and jacktrip use an external microphone and either headphones or external loudspeakers.
Once jacktrip is working it’s usually best for everybody to mute their audio in the video chat software. Usually people want to leave it running so they can see each other (even though the visuals will usually be significantly delayed compared to the audio).
qjackctl with same sample rate as peer
qjackctl with same buffer size as peer, also called
frames / period
iperf, traceroute, ping; check Internet quality
jacktrip sense, you are actually
“serving” heavy upload traffic to the jacktrip server in
their eyes. XXX how to proceed?
Try being a client to cmn16, the always on
perennial loopback test server, currently (5/18/20) running 48k,
buffersize 1024, hub loopback server
jacktrip -S -p4 -q4
Articulate exactly how you’re trying to use jacktrip, which machines have which roles, and the JACK settings.
Turn everything off and on again
Which network ports are you trying to use? Can another program (e.g., iperf) connect these machines over each of these network ports?
Which parts work and which parts don’t work?
For the parts that don’t work, can other software successfully use “it” (e.g., the audio hardware, Internet connectivity, specific UDP/TCP ports being open…)
Craft a minimal reproducible example, preferably one that is minimal, complete and verifiable
If you still haven’t solved it on your own, ask for help.
get the group talking together on Zoom, jitsi, skype or the like.
have each member test their local audio
loopback: In qjackctl, connect capture ->
playback.
Make sure everybody knows the IP address of the server.
tech lead person start group server in full mix mode:
jacktrip -S -p4Everybody mute audio in Zoom (but keep an eye on chat)
have each member test their network audio:
jacktrip -C <server_IP_address> -n1when everyone can hear everyone else well, end all the
jacktrip connections (e.g., by stopping the server and
having all the client jacktrips crash)
tech lead person restarts group server in hub patch mode 2:
jacktrip -S -p2Jacktrip always needs at least one UDP
port; in hub mode jacktrip also uses TCP
port 4464. You typically only need to know about this when you have
a firewall
that is preventing jacktrip communication by blocking certain ports.
In peer-to-peer
mode jacktrip defaults to using UDP port 4464,
that is, “listening” on UDP port 4464 for incoming audio from the remote
peer, and “sending” outgoing audio to UDP port 4464 on the remote peer.
Several command-line
options allow you to change these port numbers, including
-o (aka --portoffset),
--bindport, and --peerport. (So in fact
peer-to-peer jacktrip can use absolutely any UDP port as
long as both sides agree.)
In hub mode the hub server always listens on TCP port 4464 for clients newly wishing to connect. New clients perform a handshake via this TCP port, during which the hub server allocates a unique UDP port for the client to use to send audio to the server. This UDP port is normally in the range from 61002 to 62000. (The server hands out UDP ports sequentially starting from 61002, so for example if there are four clients then the server will use ports 61002, 61003, 61004, and 61005.)
As jacktrip performance depends on the quality of your network connection, you may wish to quantify the current performance of your (home) Internet service.
We recommend https://musicianstogetherapart.com/network-test, a jacktrip-specific network test, which tells you the ping time (average latency) and jitter (variation of latency) as well as upload and download data rates. (Scroll down then select San Francisco as the “nearest server location”; CCRMA servers will give similar performance.)
As a rough rule of thumb each channel of audio requires 1.5 mpbs (48000 samples/second times 32 bits/sample equals 1536000 bits per second). But that’s a measurement of the “bulk” (relatively long term) data transfer rate, an average measurement over time that is good at predicting the performance of downloading or streaming pre-existing content, like what you get from network speed tests from Google or Netflix.
Jacktrip needs this bandwidth, but it needs it to be low-latency and low-jitter. Jacktrip audio problems are caused by occasional network packets not making it to the destination on time (usually because of bursty network traffic), so what really matters is the worst-case packet delay.
Network quality:
Audio quality:
upgrade maintenance
courses
As the command-line
program jacktrip is often case-sensitive, to minimize
confusion, all-lowercase “jacktrip” is the prefered name for the
jacktrip project in general.
Other documentation uses “JackTrip” or “jack.trip”.
Juan-Pablo Cáceres and Chris Chafe (2010) JackTrip: Under the Hood of an Engine for Network Audio Journal of New Music Research, 39: 3, 183–187.
Roger Dannenberg “Music Performance over Networks and the Latency Problem”
jacktrip.org (also .com works) - the JackTrip Foundation, central source of jacktrip info since Fall 2020, especially help.
CCRMA’s old JackTrip software page, now superseded by The JackTrip project’s Installation page.
9/18/20 Stanford News Stanford-developed software enables musicians isolated by the coronavirus pandemic to jam together again in real-time
CCRMA’s Virtual Studio partnership with Ragazzi Boys Chorus: Virtual Studio is the name for the setup that the Foundation is providing (raspberry pi’s and cloud servers). The Ragazzi Boys Chorus is the first group to use it large scale.
Jan Stoltenberg’s Jacktrip Tutorial Series for OSX.
Michael Dessen “Jacktrip Basics Part 1” youtube video
Stanford New Ensemble’s Jacktrip Rehearsal Procedure
2015 jacktrip page on sourceforge
CCRMA SoundWIRE Research Group
Anna Xambó Network Music Performance During COVID-19 and Beyond: A Quick Review of Available Software (June 2, 2020)
All these programs attempt to do some variant of what
jacktrip does, at varying levels of sound quality and ease
of use:
Harmonize this documentation with https://github.com/jacktrip/jacktrip/README.md and https://ccrma.stanford.edu/software/jacktrip including https://ccrma.stanford.edu/software/jacktrip/linux/index.html etc. Also there’s https://blog.zhdk.ch/zmoduletelematic/files/2014/02/Operation-Jacktrip-Manual.pdf
Insert more curated academic citations on jacktrip
A whole other document on routing jacktrip through other
audio processing programs, both a list of use cases and also specific
recommendations on the connectivity methods (manual JACK patching,
JackPilot/JackRouter on pre-Catalina OSX, Soundflower on
OSX, BlackHole on OSX, VB Audio Voicemeeter on Windows). In
particular recording (e.g., allocating multiple recording channels).
Checklist step-by-step instructions for everything:
Martha suggests testing and troubleshooting each step rather than have a single huge troubleshooting section of the document
XXX Do we know whether jacktrip works on chromebook?
Nice writeup of the analogy “glass of water with a hole in the bottom”
Bridging.
Comparison to usual chamber music listening ability; developing new skills to match the medium. Learn to adapt your playing to your own delay, to play “actually” together when what you hear isn’t together. (Hans)
Comparison to the usual skill of leading a rehearsal.
Best practices for having a back channel (e.g., Zoom on a separate device) for initial contact and setup, then mute that audio when you’re ready to switch to jacktrip.
Recommended use cases for meterbridge both on the server and on musicians’ local machines.
“Comments section” or some way to get community input on this kind of documentation. Ty recommends https://disqus.com
Consolidate everything about latency into an explicit section of this documentation?
Chris Chafe began this jacktrip documentation in spring 2020 as part of his class Music 153b “Internet Ensemble Tech Force”. Matt Wright converted to Markdown and added it to his CCRMA documentation system. The class collectively edited and enriched the document during a Zoom class on May 4, 2020 and Matt has continued to update it.
This page of CCRMA documentation last committed on Fri Jan 7 12:36:38 2022 -0800 by Matthew James Wright. Stanford has a page for Digital Accessibility.