Implement custom Java audio devices for AudioChain

Since AudioChain version 1.1.4, you can easily implement and integrate self made audio devices. Take a look at the following example classes which build a totally usable and complete audio device named 'Gain'. This device simply provides the feature to boost the whole audio level.

To build an audio device, there have to be implemented just two classes: the device and the reader. The device is a storable representation of the audio device. It holds all values and manages the creation of the reader. The reader makes the audio processing and implements the actual logic.

Class 1: the audio device

To build a very basic and generic audio device with no special user interface features, you can simply extend the AbstractChainableAudioDevice as stated below:

package org.audiochain.devices.gain;

import org.audiochain.io.AudioDataReader;
import org.audiochain.io.AudioDataReaderChainLink;
import org.audiochain.io.FrameObserver;
import org.audiochain.model.AbstractChainableAudioDevice;
import org.audiochain.model.AudioDevice;
import org.audiochain.model.AudioDeviceProperty;
import org.audiochain.model.UserInterfaceContext;
import org.audiochain.ui.gui.GenericUserInterfaceContext;

/**
 * This is a very simple audio device that has one property named 'Gain'.
 * 
 * To integrate this audio device into AudioChain, run the JVM with the following parameter:
 * 
 * <pre>-DadditionalAudioDeviceClasses=org.audiochain.devices.gain.GainAudioDevice</pre>
 * 
 */
public class GainAudioDevice extends AbstractChainableAudioDevice {
	private static final long serialVersionUID = 1L;

	/*
	 * This property is manipulatable by the user. It must have a name.
	 * Optionally it can have a min and max value which influences the UI
	 * validation and visible components or labels. The unit is a plain visible
	 * artefact and has no technical consequences. The symbol is displayed in
	 * the command line interface (CLI) and means a unicode character.
	 * 
	 * The audio device becomes stored (persisted) so the properties must not be
	 * transient.
	 */
	@AudioDeviceProperty(name = "Gain", max = 30, min = 0, unit = "dB", symbol = 9651)
	private float gain = 0F;
	/* The reader must be transient to not become saved. */
	private transient GainAudioDataReader reader;

	@Override
	public AudioDataReaderChainLink createAudioDataReaderChainLink(AudioDataReader source, float frameRate, int sampleSizeInBits, FrameObserver frameObserver) {
		/*
		 * Create a new reader and remember it in a transient (!!!) instance
		 * variable for manipulating the reader while it is in use (playback).
		 */
		reader = new GainAudioDataReader(source, gain);
		return reader;
	}

	/**
	 * This is the name, displayed to the user on the user interface (GUI or
	 * CLI).
	 */
	@Override
	public String getName() {
		return "Gain";
	}

	@Override
	protected UserInterfaceContext<? extends AudioDevice> createUserInterfaceContext() {
		/*
		 * The simplest way to provide a GUI and a CLI. If the UI has to be more
		 * complex, you can implement the UserInterfaceContext interface
		 * directly.
		 */
		return new GenericUserInterfaceContext<AudioDevice>();
	}

	/**
	 * Because the gain variable is annotated with the @AudioDeviceProperty,
	 * this setter is called 'by magic' when the user manipulates the property
	 * through the UI or through the sync process.
	 * 
	 * If the reader is available (this means, it is playing back at this
	 * moment), the property change should be promoted to the reader
	 * immediately, so the user can hear the changes directly.
	 * 
	 * @param gain
	 */
	public void setGain(float gain) {
		this.gain = gain;
		if (reader != null) {
			reader.setGain(gain);
		}
	}
}

Class 2: the audio data reader

The audio data reader makes all the work while audio data becomes processed. The simplest way is to extend the class AbstractAudioDataReaderChainLink which remains you to implement the read method only. Take a look at the following example implementation:

package org.audiochain.devices.gain;

import java.io.IOException;

import org.audiochain.io.AbstractAudioDataReaderChainLink;
import org.audiochain.io.AudioDataReader;

/**
 * This is a very simple example for an AudioDataReader. It manipulates the
 * audio data while it multiplies each sample by an adjustable factor.
 */
public class GainAudioDataReader extends AbstractAudioDataReaderChainLink {
	private float gainFactor;

	public GainAudioDataReader(AudioDataReader source, float gain) {
		super(source);
		setGain(gain);
	}

	@Override
	public int read(int[] data) throws IOException {
		/*
		 * Read the audio data from the implicitly visible source
		 * AudioDataReader. The data array is shared over the whole reader chain
		 * this means it is shared by all readers that are calling this read
		 * method. The source may be changed from external.
		 */
		int len = source.read(data);
		/*
		 * Modify the read data, here we simply multiply the samples with a
		 * factor. This algorithm must be coded very efficiently. As an example,
		 * this saves cpu resources if gain factor is exactly 1.
		 */
		if (gainFactor > 1) {
			for (int i = 0; i < len; i++) {
				data[i] *= gainFactor;
			}
		}
		// return the length of the read samples
		return len;
	}

	public void setGain(float gain) {
		/*
		 * Convert gain in dB (Decibel) to a factor to save cpu resources while
		 * reading and processing the audio data.
		 */
		float exp = gain / 20F;
		gainFactor = (float) Math.pow(10D, exp);
	}
}

Running the self made audio device

To run the self implemented audio device, it has to be compiled. For compilation you need to append the audiochain jar file to the classpath. One way to compile the classes is to copy the audiochain-x.x.x.jar and the audio device package (org/audiochain/devices/gain) to a single directory, then compile the classes on the command line as follows:

javac -d . -classpath audiochain-1.1.4.jar org/audiochain/devices/gain/*.java

The classes will be compiled into the current directory (as given by -d .). To integrate this compiled audio device into AudioChain, run the JVM with the parameter 'additionalAudioDeviceClasses'. For example:

java -DadditionalAudioDeviceClasses=org.audiochain.devices.gain.GainAudioDevice \
  -cp .:audiochain-1.1.4.jar org.audiochain.ui.gui.mixer.GuiAudioRecorder

Where the classpath (-cp) has to be set to the directory of the self compiled audio device classes. For this example this directory would contain the subdirectory 'org' where the class files belong. Find more detail information about this by searching the internet for "setting java classpath". The backslash means that the above displayed command has to be executed as one single line.

After the UI has started you can choose and add the custom device to any audio track. But notice: these new audio device classes form a dependency when the audio device is used and saved to a project file. The saved project cannot be opened, when the class files are not present on the classpath. If you want to work with the network synchronization, you have to distribute these classes to each AudioChain instance. If you accidentally have stored the project, you can remove the audio device entry from the file by editing it by hand. You may want to make a backup of your project file if you are unsure.

Audio Device Factory (since 1.1.5)

In some cases you might want to provide multiple different audio devices of the same implementation class. In this case you can implement the AudioDeviceFactory interface, that can create and return instances of distinct device types. The implemented factory must be stated by the runtime environment variable 'audioDeviceFactoryClasses'. The concrete AudioDevice implementation class can be kept encapsulated behind the factory and may not be stated additionally.