EARPLUG
A "Live Connected" Audio Plugin for Linux

by Jonathan S. Kinnersley

jsk@amath.washington.edu
jskinnersley@hotmail.com

Version 1.0 - 1st March 1999

  1. Features
  2. Downloading and installation
  3. Playing MIDI Files (timidity)
  4. Test Page
  5. Cool Links
  6. Embedding an EarPlug in your web page
  7. Controlling EarPlug from Java and JavaScript
  8. Problems?

Features

This Plug-in allows up to 30 sound files to be played simultaneously from a web page, and to be controlled from Java or JavaScript programs using many of the "Live-Audio" methods (and a few more).

The files can be any mixture of AU, AIFF, MIDI or WAV files.

It allows independent control of both stereo channels for some interesting 2D effects. Here is a snap-shot of EarPlug.

There are volume controls for both stereo channels and a display of the file being played. The state of the controls can also be controlled from Java and JavaScript for added visual feedback (for example, the "play" button will appear to be pressed when the plugin's "play" method is called from Java or JavaScript).

Download and Installation

First download the gzipped tar file, earplug-1.0.tar.gz, then expand it with the command
 tar xvfz earplug-1.0.tar.gz
or
 gunzip earplug-1.0.tar.gz
 tar xvf earplug-1.0.tar
This will make a directory called 'EarPlug-1.0'.
To install the plugin so Netscape can use it, first 'cd' into the directory called 'EarPlug-1.0'.
If you are the root user, typing
 make install 
will copy three files ( earPlug.so, EarPlug.class and FadeEarPlug.class ) into the directory
/usr/lib/netscape/plugins/
Alternatively, (if you are not the root user, or if you want EarPlug to be local to your Netscape) by changing 'INSTALL_DIR' in "Makefile" before typing 'make install' you can install them in
~/.netscape/plugins/
You will need to re-start netscape and hopefully everything should work perfectly! (Note that to play MIDI files you'll need timidity - see below). You can test out EarPlug on my test files.

If you have problems, look here first.

(Note - If you are using RedHat Linux version 5.x or 6.0 the binaries should work right away. I don't know if the binaries will work with other versions of Linux - if not, you'll need to re-compile the source code (see below) - sorry!).

Re-compiling the source

The source code is included in the gzipped tar file EarPlug.gz

Download, unzip and untar as above.

You'll need the Plugin SDK from Netscape, along with the Java Developers Kit from Sun.

You'll need to change the definitions of 'SDK' and 'JDK' in Makefile to point to your SDK and JDK directories, then just type 'make' and it should re-compile the Java and native C code.

If it does compile and run properly I would appreciate a copy of the binaries so I can include them here - thanks.

Timidity

In order to play midi files you'll need to have timidity installed - but don't worry! - you have already downloaded it!.

Timidity converts MIDI files to WAV format files which can then be played on almost any sound card. Timidity was originally written by Tuukka Toivonen and though his page is now not being maintained by him it still contains useful links.

I have included a version of timidity (which should run on RedHat Linux 5.x and 6.0) in the EarPlug.gz file you just downloaded. You can copy timidity into '/usr/local/bin' (as well as a cut-down sample of patch files into '/usr/local/lib/timidity/patch') by simply typing

 cd timidity 
and then
 make install
Read the README file if you want to put the files somewhere else.

When EarPlug is presented with a MIDI file it calls Timidity which converts the MIDI file to a WAV file, which EarPlug can then play and mix with other sounds. Timidity may take a while to convert a file, so you will notice a pause of a few seconds before EarPlug plays the converted MIDI file. Timidity needs a set of "patch" files which contain the wave shapes of all the instruments needed. This full set of patch files takes up about 7 MB (though the selection I have included is much shorter).

If the binary code I mentioned above doesn't work for you, you can get a version of timidity from Vincet Pagel's timidity page, or search the web a bit.

If you want the full set of patch files (I really recommend getting them), you need to put them in the directory '/usr/local/lib/timidity/patch'. I got my patch files from Fredrick Hubinette's Plugger page (which, by the way, I recommend if you want a general purpose plug-in to deal with lots of different kinds of files).

Links to pages with cool sound files


Embedding an EarPlug in your web page

In addition to the brief write-up here, you might want to take a look at the source of the page as an example of how to use EarPlug from JavaScript.

In order to play sounds on your web page you have to embed an EarPlug plugin in it. You do this with the command

< EMBED 
NAME="name"                    an optional name for the plugin 
                               so that you can refer to it from
SRC="URL or file"              (must have a suffix aif,aiff,mid,
                                midi,wav,au or snd)
TYPE="MIME type"               (eg. audio/basic - if SRC is not 
                                included you'll need this to get 
                                an EarPlug plugin).
COLOR="color"                  (eg. red - default is lightblue)
AUTOSTART="{true or false}"    (starts playing right after loading)
WIDTH="int"                    a number - 150 is good
HEIGHT="int"                   a number - 70 is good
DISABLED="{true or false}"     if true, console can be enabled later
                               using the method "enable()"
HIDDEN="{true or false}"       hides the plugin console
LOOP="{true or false or int}"  infinite loop, single play, or a certain
                               number of loops.
>
For example,
< EMBED SRC="sound.wav" color="blue" width=150 height=70
   autostart=false loop=true >
or
< EMBED src="http://www.noise.com/sounds/bang.au" autostart=true >
or
< EMBED type="audio/midi" width=120 height=70 >

Controlling an EarPlug from Java and JavaScript

EarPlug has a number of methods which can be called from JavaScript or Java, but in both cases you first have to embed an EarPlug plugin in your web page.

The methods are
play(loop,url) eg. play(true,"sound/boing.au") - loops endlessly
or play(false,"http://www.noise.com/tune.midi") - plays once
or play(3,"hey.wav") - plays 3 times.
play(loop) plays the sound file last loaded - 'loop' is as described above.
stop() stops the plugin playing.
pause() pauses the plugin
setvol(vol) where 'vol' is an integer from 0 to 100. Sets both stereo channels to 'vol'
setvol(leftvol,rightvol) sets volumes for left and right speakers, again from 0 to 100
fade_to(vol) fades left and right channels to 'vol' over a time of 3 seconds
fade_to(leftvol,rightvol) fades left channel to 'leftvol' and right channel to 'rightvol' over 3 seconds
fade_to(leftvol,rightvol,time) fades left channel to 'leftvol' and right channel to 'rightvol' over 'time' seconds
disableConsole() disables the console controls
enableConsole() enables the console controls
stopAll() stops all playing plugins
pauseAll() pauses all playing plugins
playAll() re-starts all plugins which have been paused
IsPlaying() returns true when plugin is playing
IsPaused() returns true when plugin has been paused
IsStopped() returns true when plugin has been stopped
IsReady() returns "true" when sound file has been uploaded
GetVolume() returns the average of left and right volumes

These methods are called by prefixing them with "document.embeds[n]." where 'n' is the number of the plugin in the web page (starting with 0).

eg. document.embeds[0].play(3,"sound.wav") would play "sound.wav" three times on the first plugin.

More detailed information on calling plugin methods from JavaScript and Java can be found on Netscape's Client-side JavaScript Guide, or you can take a look at the source for this page (hold "shift" down and click to download).

Problems

If you are using RedHat, you'll need a bug-free version 4.06 or higher of Netscape (the upgrades are available from RedHat). The earlier versions had problems with Java.
I've had problems when trying to refer to a plugin from JavaScript using its name (defined by the NAME attribute in the EMBED statement). Everything worked when instead of 'document.earPlug.play(1,"file.wave")' I used 'document.embeds[0].play(1,"file.wav")'

If EarPlug doesn't work, check that it is enabled for all the MIME-types AIFF, AU, MIDI and WAV. Do this by going to the "About Plugins" page under the "Help" menu on Netscape.

If EarPlug is not enabled, go to the Netscape Applications page by choosing "Edit" - "Preferences" - "Navigator" - "Applications". Then find the above MIME types and make sure the EarPlug plug-in is selected for them. Note that audio/wav and audio/x-wav both refer to files with the .wav suffix.

I also had problems because the ownership of my ~/.netscape/cache/index.db file had been inadvertently changed to 'root' - make sure that it is owned by you, by using chmod.

Afterward

I wrote this plug-in mainly out of frustration! I wanted noisy web pages to be available to Linux users - at first I thought Java was the answer, but I soon found out that the Java applet method "play" just didn't work!

Then when I read about the Netscape Live-Audio plug-in I thought NOW I could produce noisy web pages.... until I eventually realised it wasn't shipped with the Unix/Linux versions!


I would appreciate comments and bug reports - and if anyone makes binaries for a Linux system which uses libc5 and not glibc, please let me know.
You can mail me at jsk@amath.washington.edu
or jskinnersley@hotmail.com