Software

JackTrip (old version) - Multimachine jam sessions over the Internet2.

NOTE: This version of JackTrip is discontinued. The new one is under development (alpha stage), and it's not compatible with this one.

JackTrip is a Linux-based system used for multi-machine jam sessions over Internet2. It supports any number of channels (as much as the computer/network can handle) of bidirectional, high quality, uncompressed audio signal steaming.

It is currently being developed and actively tested at CCRMA by the SoundWIRE group.

---

Installation instructions and requirements

In order to run JackTrip, you need a machine running a some Linux distribution. We recommend and support Fedora Core (FC). RPM packages for FC6, FC7 and FC8 are available to install via Yum (apt-get for FC4) from the Planet CCRMA repository.

If you are installing Fedora Core from scratch or you haven't optimize it for audio, please follow the instructions bellow on installation and configuration on the older distributions:

• Fedora Core 8
• Fedora Core 7
• Fedora Core 6

We strongly recommend that you install the latest distribution (FC8). The following instructions show how to install and test from scratch an FC8 machine.

---

Fedora Core 8/Planet-CCRMA installation

Important note: you need to execute the following commands as ROOT (super user).

After you install the distribution, install the Plannet-CCRMA repository:

su
rpm -Uvh http://ccrma.stanford.edu/planetccrma/mirror/fedora/linux/planetccrma/8/i386/planetccrma-repo-1.0-3.fc8.ccrma.noarch.rpm
	

Make sure that you update your system (this may take a while):

yum upgrade

Now you can install software directly from planet CCRMA repository using yum. Install the Low Latency-Kernels and Planet-CCRMA configurations:

yum install planetccrma-core

Now you need to set the Low Latency-Kernel as the default on boot. Edit the file /boot/grub/grub.conf and changing the “default=” line to point to the kernel you want to boot by default. Kernels are indexed with a zero base, “0” being the first in the list of kernels that follows the default line. Now reboot your system with the new Kernel.

After rebooting, check that you are indeed using the Planel-CCRMA kernel typing:

uname -r

You should get something like 2.6.24.2-1.rt1.3.fc8.ccrma.

Every time you do a “yum upgarde” there may be new kernels from the official FC6 repository that are going to be installed. This is going to automatically overwrite the default kernel to this new one, so you have to make sure that you change this default and that you are running the Low-Latency Kernel.

Once you are done configuring, your basically ready to install JackTrip. Just issue the following command (as root) to install JackTrip and its dependencies. We also need to install qjackctl.

yum install jacktrip qjackctl

If you want ot install all the planet-CCRMA applications (including JackTrip), you can type the following:

yum install planetccrma-apps

There is one more step before you are able to run JackTrip. The firewall in the default installation will interfere with using udp streaming. So you need to open a hole for the ports that the program is going to use for streaming. By default jacktrip uses UDP port 4464. To open the port(s), issue the following command (as root again):

/usr/bin/system-config-securitylevel

You should see a user interface for Security Level Configuration. Under Other ports add ports 4464 (UDP), 4474 (UDP), 4484 (UDP) and 4494 (UDP). The additional ports are in case you want to stream with more than one computer (up to 4 hosts in this case).

After you're done adding the ports you should have something like the following window:

NOTE: The next step doesn't seem to be necessary on Fedora 8. If you don't find the sound line (see the following) just skip this part.

If this is a machine that is going to be controlled remotely, you need to allow remote user to grab sound hardware. To do this, edit the file “/etc/security/console.perms.d/50-default.perms“ and change the line:

<console>  0600 <sound>      0600 root

to

<console>  0666 <sound>      0666 root

then to make it take effect immediately:

chmod 0666 /dev/snd/*

One last step is to make sure that your machine has a host name. Usually this is provided by the sysadmin, but if you're using your own machine, you need to write it yourself. For that, edit the file “/etc/hosts“ and make sure it contains something like this:

127.0.0.1       localhost.localdomain localhost
::1             localhost.localdomain localhost
171.64.197.150  cmn1.stanford.edu cmn1

and you replace the last line with your IP number and a host name (that can be anything).

At this point JackTrip is (hopefully) ready to run.

---

Testing your connection

You need to test your connection in order to make sure that you have enough bandwidth and that there are no firewalls or other strange network security issues interfering with the connection. You will need to contact the IT people in your area in case this happens.

To test the connection between two (or more) hosts, you may use iperf. Planet CCRMA has iperf packets available for the Fedora Core So to install just issue the command (as root):

su
yum install iperf

You need remote access to the machine that you will connect to. Assuming that you have an account, you have to login remotely with ssh:

ssh -Y [remote-machine-IP]

Once you are login in the remote machine, you can test the connection using the Server-Client and Client-Server configurations.

Using the remote machine as server and the local machine as client, you may do the following.

On the remote machine (Server) type (this includes the output of your command):

iperf -u -s -p4464
     ------------------------------------------------------------
     Server listening on UDP port 4464
     Receiving 1470 byte datagrams
     UDP buffer size:   105 KByte (default)
     ------------------------------------------------------------

And on the local machine (client):

iperf -u -c [remote-machine-IP] -b20M -p4464
     ------------------------------------------------------------
     Client connecting to [remote-machine-IP], UDP port 4464
     Sending 1470 byte datagrams
     UDP buffer size:   105 KByte (default)
     ------------------------------------------------------------
     [  3] local [local-machine-IP] port 33090 connected with [remote-machine-IP] port 4464
     [  3]  0.0-10.0 sec  23.8 MBytes  20.0 Mbits/sec
     [  3] Sent 17004 datagrams
     [  3] Server Report:
     [  3]  0.0-10.0 sec  23.8 MBytes  20.0 Mbits/sec  0.002 ms    0/17004 (0%)

The previous example will have enough juice to run several audio channels. Depending on your connection, you may try different values for -b (for example, -b10M, -b5M).

---

Using JackTrip

Type jacktrip in a terminal window to display a help list with all the options. In the following example we will make an 8-channel connection between two hosts.

JackTrip uses Jack as its audio server. You have to make sure that the settings in Jack are the same in the local and remote machine. Login remotely with ssh, and open QjackCtl. The following steps apply for both the local and remote machine.

qjackctl &

Use the setup button to bring up the jack audio options. You should check in this setup:

• Server Path: jackd
• Driver: alsa (or freebob for example if you are using a firewire soundcard)
• Interface: check that this corresponds to your audio interface
• Frames/Period: this is the buffer size, the smaller the better to reduce audio latency. Both Client and Server should use the same value
• Sample Rate: again, Client and Server should use the same value

An example of this configuration is shown bellow:


Now start the jack server (Start button) in both the remote and local machine.

When jack is running in both machines, you are ready to connect. Jacktrip uses a server/client configuration. You have to set one machine as a server and the other as a client. It doesn't matter which one is which. In this example, we'll set the remote machine as the server. Type the following:

jacktrip -j -z 64 -b 2 -q 2 -a 8 -r

This will wait for an incoming connection from a client, using jack as audio server (-j) with a buffer size (-z) of 64 that should match the settings of jack, with 2 audio buffers of redundancy (-b), 2 packets on input queue (-q) and 8 channels (-a). Type jacktrip to see the options help.

The options -b and -q are used to tweak the connection. -b is the number of redundant buffer. If you have a lot of bandwidth, you can increase this number to make sure all the packets get there. All this is doing is sending duplicates of packets (-b 2 means sending 2 copies of each packet), so if the first one doesn't get there, jacktrip can use the second one. -q is the number of packets in the input queue. The longer the queue, the higher the latency, but if you have jitter on your connection, you may want to increase this number.

Once the server is waiting, you can tell the client to connect:

jacktrip -j -z 64 -b 2 -q 2 -a 8 -t [remote-machine-IP]

If everything is working, you should be connected now. Look at your Connect window in qjackctl. You'll see a jacktrip_1 client. The output is the signal coming from the remote machine, and the input is the signal that will be sent to the remote machine. Make the connections that you need to test and play with JackTrip!

Source Code

Jacktrip source code can be found here