Requirements

You need the following hardware/software components for installing and running SoundHelix:

• Java SE Development Kit or Runtime Edition 6 (JDK 6 or JRE 6) or later (http://www.oracle.com/technetwork/java/javase/downloads)
• Apache log4j 1.2.x or later (included)
• GNU Getopt 1.0.14 or later (included)
• a MIDI hardware playback device, MIDI-capable software or operation system's MIDI implementation
• some MIDI hub software a.k.a. virtual MIDI cable (optional)
• some audio recording software (optional)

Downloading, installing and starting SoundHelix

Download a binary package of SoundHelix and extract it somewhere. Then, open a console and go to that directory. Then on Windows simply run SoundHelix by typing

run.bat

You can also double-click on "run.bat" (or "run", depending on how it's displayed) using the Explorer.

On Linux or any other Unix variant type

./run.sh

(this requires the "x" flag of the script to be set; if it is not set, you can run "chmod a+x ./run.sh" upfront to set it).

Without parameters (like above), this will start SoundHelix with the XML file examples/SoundHelix-Piano.xml.

Run the script with the parameter "--help" to view the usage options:

Usage: java -jar SoundHelix.jar [options] xml-filename

Options:

   -h
   --help                 Show this help

   -v
   --version              Show the application version

   -s songname
   --song-name songname   Set the song name for seeding the random generator

   -m
   --show-midi-devices    Show available MIDI devices with MIDI IN port

Instead of using a local filename you can use a URL that contains SoundHelix XML data. E.g., run "run.bat http://www.soundhelix.com/applet/examples/SoundHelix-Piano.xml". Supported URL schemes are http, https, ftp and file.

During playback, SoundHelix provides a very simple command console. Type "help" in the console to view the possible commands.

Logging

SoundHelix uses Apache log4j for logging. You can configure the log level to use in the "log4j.properties" file found in the SoundHelix directory. For details about how to configure log4j, please refer to the log4j documentation.

Using a MIDI hub (a.k.a. virtual MIDI router or virtual MIDI cable)

Some MIDI software (like Propellerhead Reason) does not offer a MIDI device itself, but can connect to an existing MIDI device to receive MIDI messages. SoundHelix also does not make itself visible as a MIDI device, so neither can SoundHelix connect to the MIDI software nor can the MIDI software connect to SoundHelix. In this case, you must install some MIDI hub software as a man-in-the-middle, for example loopMIDI (available for Windows, other platforms offer similar MIDI hub software), where both SoundHelix and the MIDI software can connect to. This software simply sets up a MIDI device that is visible from both Java and from any other MIDI software and relays MIDI messages between SoundHelix and the MIDI software. SoundHelix must be configured to use the MIDI hub input port as the MIDI output device and the MIDI software must use MIDI hub output port as the MIDI input device. A nice side effect of this approach is that you can start SoundHelix and the MIDI software independently, because they can both successfully connect to the MIDI hub, even if the corresponding MIDI partner has not connected yet.

With loopMIDI, simply create a MIDI port with any name and use this port in your SoundHelix XML file as the MIDI output device. The MIDI software can then use the same port for input. If needed, you can create more than one MIDI port (every MIDI port can handle upto 16 MIDI channels) and configure these ports as separate MIDI devices in SoundHelix. Visit the loopMIDI website to download loopMIDI. loopMIDI will run on Windows XP, Windows Vista and Windows 7 (both on 32-bit and 64-bit).