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 (
  • 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


You can also double-click on "run.bat" (or "run", depending on how it's displayed) using the Explorer. If it doesn't work, make sure you have read and execute permission for "run.bat".

On Linux or any other Unix variant (also MacOS) type


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

Without parameters (like above), this will start SoundHelix with the XML file examples/SoundHelix-Popcorn.xml. You can also provide the SoundHelix XML file directly, e.g. by running "./ examples/SoundHelix-Percussion.xml").

Run the script (run.bat or with the parameter "--help" to view the usage options:

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


   --help                 Show this help

   --version              Show the application version

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

   --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". 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.


SoundHelix uses Apache log4j for logging. You can configure the log level to use in the "" file found in the SoundHelix directory. For more verbose logging, change the default log level "INFO" to "DEBUG" (more logging) or "TRACE" (most logging). Log levels can also be defined per Java class, if required. 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).


"With loopMIDI, simply create

"With loopMIDI, simply create a MIDI port with any name and use this port in your SoundHelix XML file as the MIDI output device."
Ok, but how i proceed to add a port in wich XML Sound Helix file please ?
Everybody are not programmers. I really beg you to give me some help, it will be very kind.
Thanks both of you for your creations.
Best regards.


I wish I could use this. Had to blow open my windows security to get the "test applet" to run. WOW it's fabulous!
So I download it, and have NO IDEA what this is or how to open it. Run.bat doesn't do anything. Very sad.
The installation instructions might as well be in Chinese. :(

Sorry, but i'm having big

Sorry, but i'm having big diffulties with soundhelix on Mac (Snow leopard 10.6.8) and the first question is: What do you mean with "Soundhelix XML file"? I can't find any file with this name in the pakage I dowloaded. When I start launching the program with ./ via Terminal, i got a message error "Could not find the midiplayer" so i immagine I have to set the one I created. Where and wich is the file I have to set before lounching the program with ./ Tahnks in advance.

Add new comment