JJack - Java framework API for the JACK Audio Connection Kit

JJack is a JACK audio driver for the Java Sound API and a framework for the Java programming language that allows Java applications to use the JACK Audio Connection Kit.

Copyright © Jens Gulden.
Licensed under the GNU Lesser General Public License (LGPL).

This software comes with NO WARRANTY. See file LICENSE for details.


CONTENTS

OVERVIEW
Features
Running JJack
Developing JJack clients
INSTALLATION

THE JJACK SHELL APPLICATION
Synopsis
Description
Options
Classpath
Usage Example
THE JJACK SYSTEM WRAPPER APPLICATION
Synopsis
Description
Options
Classpath
Usage Example
JJACK SYSTEM PROPERTIES
Synopsis
Description
ENVIRONMENT
JACK Audio Connection Kit
Java Virtual Machine
Classpath
Library Path
LIMITATIONS

SEE ALSO

OVERVIEW

Features

JJack is a JACK audio driver for the Java Sound API and a framework for the Java programming language that allows Java applications to use the JACK Audio Connection Kit.

Audio processor clients can be designed to:

Running JJack

There are 4 alternative ways to run JJack:

Developing JJack clients

The document Developing JJack Clients describes the basic steps to create new JJack clients.

For more details on the JJack API, refer to the Javadoc API documentation. To get a quick overview, see the UML class diagram.

INSTALLATION

JJack uses the Java Native Interface (JNI) to access the JACK daemon. Therefore, the native bridge library libjjack.so (on Linux systems) needs to be accessible by the Java Virtual Machine (JVM).
There are two ways to make sure the JVM can load the native bridge library:

Note: The current version includes a pre-compiled binary library for i386-Linux only. To run JJack on different platforms, the source files libjjack.c and libjjack.h need to be compiled on your system. Please send a copy of the binray and a description of your compilation process if you succeed in running JJack on different platforms.

THE JJACK SHELL APPLICATION

Synopsis

<jre-binary and classpath> [ jjack-system-properties ] JJack [ -i=import-packages ] client-chain | -help

with

client-chain  :=  client-class [ parameters ] { monitor-chain } [ client-chain ]

monitor-chain
:=  [ monitor
-chain-members ]

monitor-chain-members
  :=  client-class
[ parameters ]  monitor-chain-members  |  monitor-class [ parameters ]

import-packages  :=  package-name{,package-name}

parameters
  :=  (name=value{,
name=value})

client-class : Java class that implements de.gulden.framework.jjack.JJackAudioProducer

monitor-class
:
Java class that implements de.gulden.framework.jjack.JJackAudioConsumer


Mind the recursive definition of monitor-chain-members: behind each member of a monitor-chain which is a client-class (implementing JJackAudioProcuder), a new monitor chain can again be started. However, any monitor-class ends a monitor-chain: it is not possible to connect any more clients to a monitor-class, because it only is a JJackAudioConsumer.

(JJack is a Java class located in the 'default' package of the class tree, without any preceeding package qualifier. All it does is delegating the call to its main-method to de.gulden.application.jjack.JJack. JJack exists for shorter command line calls only.)

Description

JJack loads, displays and runs Java-based JACK audio processing clients. Such a client is any Java class that implements the interface de.gulden.framework.jjack.JJackAudioProcessor, as provided by the JJack framework API.

These steps are performed when the JJack shell application is run:

A usage example is given below.

Note that there are alternative ways to deploy JJack audio processors:

Options

-c <filename>
Load options, client-chain and monitor-chains from a file, instead of expecting them on the command line.
-i <package-name(s)>
Package name to search for client classes. This allows shorter and better-readable specification of the client-chain and monitor-chains. Multiple package names are to be seperated by commas, without whitespace between them.

Additionally, the behaviour of the underlying native bridge to JACK can be controlled by specifying JJack system properties.

Classpath

See below.

Usage Example

The following example runs the "Gain control" JJack client (the current directory is assumed to be the JJack install directory):

java -Djava.library.path=lib/i386/Linux -cp lib/jjack.jar:lib/jjack-clients.jar JJack de.gulden.application.jjack.clients.Gain

The next example deploys the delay effect JJack client. The client is configured to be a mono device, as set by the JJack system properties -Djjack...=... The delay's time-parameter and effects-intensity are specified in round brackets. After the delay-effect, a monitor chain is started, indicated by square brackets. The monitor-chain contains the oscilloscope client, which displays the generated waveform.

java -Djava.library.path=lib/i386/Linux -Djjack.ports=1 -cp lib/jjack.jar:lib/jjack-clients.jar JJack -i de.gulden.application.jjack.clients "Delay(time=660,mixFx=30)" [ Oscilloscope ]

(Mind the quotation marks around "Delay(..)". These are needed in a bash-shell to allow round brackets on the command line.)

The screenshot below shows the configuration of an interconnected JJack client invoked by

./jjack.sh -i de.gulden.application.jjack.clients "Gain [Oscilloscope(name=Oscilloscope-Client)] Delay [Oscilloscope(name=Delay-Oscilloscope)]"

The JJack client's input is connected to the xmms audio-player, using the qjackctl patchbay application:


THE JJACK SYSTEM WRAPPER APPLICATION

Synopsis

<jre-binary and classpath> [<jjack system properties>] JJackSystem <wrapped main application> <parameters of wrapped application> | -help

In other words: call any Java program as you would do without JJack, but insert JJackSystem right before the original main class.

Applications that originally use the -jar <archive-file> option of the Java runtime-environment (JRE) must be invoked using the classic mechanism instead, by naming the main class right after JJackSystem and including the jar-archive in the classpath. (The main-class is specified in the archive's MANIFEST entry.)

(JJackSystem is a Java class located in the default package of the class tree, without any preceeding package qualifier. All it does is delegating the call to its main-method to de.gulden.framework.jjack.JJackSystem. JJackSystem exists for shorter command line calls only.)

Description

The JJackSystem wrapper initializes the native parts of JJack and registers the underlying JACK client prior to running any other Java program. Depending on the system platform and configuration JJack is running on, such a wrapper is needed to access the native side and register a JJack client without thread collision, as early as possible, before the JVM's main thread exits.

E.g., this allows to run JJack clients as JavaBeans inside Sun's BeanBuilder, see Creating JJack clients with the BeanBuilder.

Note: Using the JJackSystem wrapper this way is supposed to be a workaround. Future versions of JJack / JACK should aim to make this obsolete.

These steps are performed when the JJackSystem wrapper application is run:

A usage example is given below.

Note that class de.gulden.framework.jjack.JJackSystem is not only an application wrapper, but implements the central native interface to the JACK daemon.

Options

None, except the general JJack system properties. (Internally, the wrapped application and its parameters are JJackSystem's options, but these are used to simulate the direct invocation of the wrapped application. )

Classpath

See below.

Usage Example

This example describes how to modify the original BeanBuilder startup script to enable JJack support. See Creating JJack clients with the BeanBuilder.

The BeanBuilder comes with a small default start script that looks like this:

#! /usr/bin/sh
# Shell script to run the Bean Builder Application on 1.4 (and beyond)
#
# Usage: JAVA_HOME=/usr/local/java/jdk1.3/solaris run.sh [-p palettefile] [-i] [filename.xml]
#
# -where [-i] is interpret mode. Execute filename.xml without starting the Builder.
# -where [filename.xml] load the archived xml file.
# -where [-p palettefile] use "palettefile" as the Bean Builder palette
#
# Note: the -i and -p flags cannot be used simultaneously

CPATH=builder.jar:${JAVA_HOME}/lib/dt.jar:lib/jlfgr-1_0.jar

${JAVA_HOME}/bin/java -cp ${CPATH} Main $1 $2 $3 $4 $5


To manually prepare the BeanBuilder for deploying JJack clients, the above script needs to be modified in 3 points.

1. adjust the classpath:

In order to use JJack clients inside the BeanBuilder, the JJack API classes must be present in the classpath. The script should be changed like this:
JJACK_HOME=<jjack-install-dir>
CPATH=builder.jar:${JAVA_HOME}/lib/dt.jar:lib/jlfgr-1_0.jar:${JJACK_HOME}/lib/jjack.jar

2. set native library path:

The JVM must be told where to look for native library files. If you did not install the JJack native library libjjack.so into your system's default library path (by copying or linking libjjack.so there), set the Java system property java.library.path to the desired directory:

${JAVA_HOME}/bin/java -cp ${CPATH} -Djava.library.path=${JJACK_HOME}/lib/i386/Linux Main $1 $2 $3 $4 $5

3. add the JJackSystem wrapper in front of the main-class call:

On some systems and configurations, it is necessary to make sure that JJack's native JACK client is allocated as early as possible, before program execution branches into child-threads. If you need this, place the wrapper application JJackSystem right before the original main class name in the command line:

${JAVA_HOME}/bin/java -cp ${CPATH} -Djava.library.path=${JJACK_HOME}/lib/i386/Linux JJackSystem Main $1 $2 $3 $4 $5
When the BeanBuilder has started, choose "Load Jar..." from the file menu and select <jjack-install-dir>/lib/jjack-beans.jar to make the JJack clients known to the BeanBuilder as JavaBeans. Then you can work with the JJack clients as with any other JavaBean. By using the add/remove-Monitor and add/remove-Chained event-listener methods, complex interactions of JJack clients can be constructed. See Creating JJack clients with the BeanBuilder for more details.

JJACK SYSTEM PROPERTIES

Synopsis

<jre-binary and options> -D<property>=<value> -D<property>=<value> ... <application-and-options> ...

The JJack system properties are passed to the Java virtual machine by using the -D flag on the command line. Mind that these options have to occur before the name of the Java class invoked.

Description

JJack system properties control the behaviour of the underlying JJack system. They take effect when the JJack system registers as a native JACK client at the JACK daemon jackd.

-Djjack.client.name=name Name of native JACK client to register.
-Djjack.ports=n Number of input and output ports to be used. Default: 2 (stereo)
-Djjack.ports.input=n Number of input ports to be used, if different from output ports.
-Djjack.ports.output=n Number of output ports to be used, if different from input ports.
-Djjack.ports.autoconnect=true|false Sets whether to connect both input and output ports to physical JACK ports.
-Djjack.ports.input.autoconnect=true|false Sets whether to connect the input ports to physical JACK ports.
-Djjack.ports.output.autoconnect=true|false Sets whether to connect the output ports to physical JACK ports.

ENVIRONMENT

JACK Audio Connection Kit

The current version of JJack has been tested with jackd version 0.9.4 on a Debian 3.0 Linux system (version 0.80.0 of libjack.so). Other versions or operating systems may or may not work. (Please send a mail about your experience with another OS, especially MacOS. Note that for use with platforms other than i386-Linux, the native bridge library libjjack.so needs to be compiled from the source files libjjack.c and libjjack.h first.)

The testing environment's JACK daemon had been started manually from an ordinary user account with access to the audio device by entering

jackd -v -d alsa -d hw:0 -r 44100 -s

There are many alternative ways for starting jackd, see the JACK user documentation for details.

Java Virtual Machine

Java Runtime Environment Version 1.4 (or higher) is required to run JJack. This version newly introduces the memory mapped direct java.nio.ByteBuffer class, which JJack makes intensive use of.

Classpath

In order to run JJack, the following components are needed in the classpath:

Library Path

The JVM must be told where to look for native library files. If you did not install the JJack native library libjjack.so into your system's default library path (by copying or linking libjjack.so there), set the Java system property java.library.path to the desired directory:
${JAVA_HOME}/bin/java ... -Djava.library.path=${JJACK_HOME}/lib/i386/Linux ...

LIMITATIONS

Some limitations and bugs apply to the current version:

SEE ALSO

JACK Audio Connection Kit

JACK user documentation

Java BeanBuilder

JavaBeans Specification

Java Native Interface Extensions introduced in Version 1.4 of the Java2 SDK

Class java.nio.FloatBuffer

Copyright © Jens Gulden and others 2004-2007
Licensed under the LGPL.