CCRMA Documentation links:   index   contents   overview   rooms   account   staff   about


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

(XXX some find that jacktrip is good for specific learning needs not met by Zoom, e.g., perception of rhythm. Low-latency realtime service.)

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:


MUS-C02SX1BYGTF1:bin matt$ pwd
/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

[Install the new version]


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.

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, for example port 61000:

    netstat -p -n | grep 61000

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, network speed test (e.g., Google, Netflix, …)
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

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.

jacktrip.com

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

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 Thu Jul 2 14:05:50 PDT 2020 by matt.