CCRMA Documentation links:   index   contents   overview   rooms   account   staff   about


(contents of this file: links to each section)

jacktrip

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.

features

(Deprecated: older version exists that doesn’t use JACK; you could switch on rtaudio to avoid usign JACK as audio subsystem)

Limitations

uses

hardware requirements

  1. Computer: desktop, laptop, mini, or smaller systems running linux, macOS, windows10, or raspbian. (Various systems can connect with one another in group sessions)

  2. Network:

  1. Audio

software installation

Jacktrip requires JACK to be:

You must install JACK before installing jacktrip.

Installing jacktrip

Also Dave Kerr has a beta OSX 1.2 build.

The “jacktrip” package consists exclusively of the single executable file jacktrip:

Managing Multiple Versions of jacktrip

If 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).


MUS-C02SX1BYGTF1:bin matt$ cd /usr/local/bin
MUS-C02SX1BYGTF1:bin matt$ ./jacktrip -version
JackTrip VERSION: 1.1
Copyright (c) 2008-2009 Juan-Pablo Caceres, Chris Chafe.
SoundWIRE group at CCRMA, Stanford University

MUS-C02SX1BYGTF1: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:


MUS-C02SX1BYGTF1: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
MUS-C02SX1BYGTF1:bin matt$ ./jacktrip -version
JackTrip VERSION: 1.2
Copyright (c) 2008-2018 Juan-Pablo Caceres, Chris Chafe.
SoundWIRE group at CCRMA, Stanford University

MUS-C02SX1BYGTF1: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

Building jacktrip from source

jacktrip installation verification

To 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

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.

Terminology

JACK server
system audio process (jackd)
JACK client
audio application that connects audio through JACK e.g., audacity, jacktrip
jacktrip hub mode
network group: multiple people connect to a hub server
hub server
the common hub for the group
jacktrip simple mode
2 sites only, no common hub, aka “peer-to-peer” mode
peer
the other guy
peer-to-peer server
ready to make a simple two-way connection to one jacktrip client
jacktrip client
a site that connects to either a hub server or peer-to-peer server

Operation

Hub Server Operation

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.

Hub patching

A jacktrip hub server can be launched with the option -p (aka --hubpatch), followed by a number specifying one of these “hub patching modes”:

0 “server-to-clients” (default)
All clients get mixed to server’s output; server’s input feeds to all clients. (How would this be useful? Imagine a central site with a large mixing board with remote clients piped in: something outside of 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.)
1 “client loopback”
Each client hears only herself
2 “client fan out/in but not loopback”
Everybody hears everybody else, but not themselves. Recommended for attempting to play together when latency is high (to avoid the annoying delayed-echo-of-yourself)
3 “reserved for TUB”
??? (XXX what does this do?)
4 “full mix”
Each client hears the full mix including herself. (Like a combination of 1 and 2.) Recommended for initial connection testing and in cases where all players need to hear exactly the same mix.

Recipe for Starting jacktrip Hub Server

Simple aka Peer-to-Peer Operation

    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 options

Commonly used command line options (and their default values):

-n
number of channels (2)
-q
number of packets of input queue (4)
-z
(wavetable repeat last packet instead of muting with zeroes if network packet droput happens)
-o
UDP port 4464, 0 offset

Launch jacktrip with no arguments to print all the possible command-line options:

    jacktrip

Running multiple jacktrip processes on the same machine

You 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).

patching jacktrip audio to other audio applications on the same machine

XXX write me

Commonly used commands

ps

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”.)

killall

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-kill

netstat

Use netstat to see which process is using a given UDP or TCP port.

Linux example: display programs using port 61000:

    netstat -p -n | grep 61000

Using jacktrip alongside video chat

Video 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).

Details that Get in the Way

Debugging

mismatch between local and peer sample rate
restart qjackctl with same sample rate as peer
mismatch between local and peer buffer size
restart qjackctl with same buffer size as peer, also called frames / period
“waiting for peer” forever
usually this is because computer firewall or router firewall (or sometimes ISP) is blocking incoming data.
measure QoS
Try iperf, traceroute, ping; check Internet quality
windows security settings
Allow an app through firewall.
windows
Peer to Peer Collaboration Foundation
windows: MMCSS API not used
ignore that
ISP’s shutting traffic after detecting flows a few seconds in.
These are cases where the ISP contract prohibits running a server. Even if you are a client in the jacktrip sense, you are actually “serving” heavy upload traffic to the jacktrip server in their eyes. XXX how to proceed?

Troubleshooting recipe

  1. local audio test

  2. 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

  3. Articulate exactly how you’re trying to use jacktrip, which machines have which roles, and the JACK settings.

  4. Turn everything off and on again

  5. Which network ports are you trying to use? Can another program (e.g., iperf) connect these machines over each of these network ports?

  6. Which parts work and which parts don’t work?

  7. 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…)

  8. Craft a minimal reproducible example, preferably one that is minimal, complete and verifiable

  9. If you still haven’t solved it on your own, ask for help.

best practices, ensemble sound checks

    jacktrip -S -p4
    jacktrip -C <server_IP_address> -n1
    jacktrip -S -p2

Network Ports

Jacktrip 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.

Check Internet Quality

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.

Tuning the System

Network quality:

Audio quality:

upgrade maintenance

courses

Capitalization and Alternate Spellings

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”.

Publications

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, offering several programs since Fall 2020.

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.

Old jacktrip home page

Michael Dessen “Jacktrip Basics Part 1” youtube video

Stanford New Ensemble’s Jacktrip Rehearsal Procedure

jacktrip source on github

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:

Future Work:

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). 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?

About this document

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 updated Fri Nov 20 09:14:39 PST 2020 by matt.