Applet

Besides using SoundHelix as a standalone Java application or accessing the SoundHelix API from other Java software, SoundHelix can also be used as a JNLP-based applet or as an applet embedded into a webpage.

If your browser supports Java 6 applets and MIDI is available, you should already hear the applet playing. Note that it might take a while to load and initialize the applet (see below).

For integrating the SoundHelix applet into a webpage, you need the following files in your webspace:

  • SoundHelix.jar (part of the SoundHelix binary distribution)
  • log4j.jar (this JAR is even required if you use the applet in invisible mode; part of the SoundHelix binary distribution)
  • a SoundHelix XML file (including all files that the XML file references, if any)

Note that you will probably not be able to reference the JARs or the XML files on other domains. These files must be available on your webserver because of the usual Java applet security policy. Even though SoundHelix requires the external library GNU Getopt for compiling, it will not be required at runtime if you use the applet, as GNU Getopt will only be used if you run SoundHelix from the command-line.

Then, add the following HTML snippet to your webpage (adjust the paths to SoundHelix.jar and log4j in the "archive" attribute and the XML file to use in the "url" parameter as required):


<applet code="com.soundhelix.SoundHelixApplet.class" archive="SoundHelix.jar,log4j.jar" width="0" height="0">
  <param name="invisible" value="true"/>
  <param name="url" value="SoundHelix-Percussion.xml"/>
</applet>

This will create an invisible applet that uses the given XML file and starts playing. Note that the parameters "invisible" and "url" are available starting with version 0.3.

The following parameters are supported by the applet (all are optional):

Parameter Example value Description
invisible true If set to true, all applet UI controls and logging output are hidden. This is nice for embedding the applet into a webpage for playing in the background. Defaults to false. Make sure to use appropriate width and height values in the applet tag if the applet is visible.
url SoundHelix-MyMusic.xml Specifies the XML document to use. If a relative URL is given, the URL is relative to the embedding document (i.e., the HTML file). Defaults to "examples/SoundHelix-Piano.xml".
songName The tricky driver Specifies a song name to use for random initialization. This will only affect the first song played. All following songs will use the system clock for random initialization. Defaults to unspecified (which means that all songs will use the system clock for random initialization).

Note that the applet startup time might be pretty long. This is not a bug in SoundHelix, but a bug in Java 5/6 regarding the Java factory API, which is used by the XML parser. The factory loader code tries to load non-existing files from the META-INF folder on the webserver lots of times during XML parsing (whereas it should only inspect the downloaded JARs). You may or may not have the problem in your browser. For details, see this bug. According to the bug description, the bug is fixed in Java 5 and in Java 6 (b28).


Add new comment